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

p LATIN SMALL LETTER P 3645 q LATIN SMALL LETTER Q 3646 r LATIN SMALL LETTER R 3647 s LATIN SMALL LETTER S 3648 t LATIN SMALL LETTER T 3649 u LATIN SMALL LETTER U 3650 v LATIN SMALL LETTER V 3651 w LATIN SMALL LETTER W 3652 x LATIN SMALL LETTER X 3653 y LATIN SMALL LETTER Y 3654 z LATIN SMALL LETTER Z 3655 { LEFT CURLY BRACKET 3656 { LEFT CURLY BRACKET 3657 | VERTICAL LINE 3658 } RIGHT CURLY BRACKET 3659 } RIGHT CURLY BRACKET 3660 _ ~ TILDE ____________________________________________________________________________ 3661 IEEE Std 1003.1-200x uses character names other than the above, but only in an informative way; 3662 for example, in examples to illustrate the use of characters beyond the portable character set 3663 with the facilities of IEEE Std 1003.1-200x. 3664 Table 6-1 (on page 111) defines the characters in the portable character set and the corresponding 3665 symbolic character names used to identify each character in a character set description file. The 3666 table contains more than one symbolic character name for characters whose traditional name 3667 differs from the chosen name. Characters defined in Table 6-2 (on page 116) may also be used in 3668 character set description files. 3669 IEEE Std 1003.1-200x places only the following requirements on the encoded values of the 3670 characters in the portable character set: 3671 * If the encoded values associated with each member of the portable character set are not 3672 invariant across all locales supported by the implementation, if an application accesses any 3673 pair of locales where the character encodings differ, or accesses data from an application 3674 running in a locale which has different encodings from the application's current locale, the 3675 results are unspecified. Base Definitions, Issue 6 113 Portable Character Set Character Set 3676 * The encoded values associated with the digits 0 to 9 shall be such that the value of each 3677 character after 0 shall be one greater than the value of the previous character. 3678 * A null character, NUL, which has all bits set to zero, shall be in the set of characters. 3679 * The encoded values associated with the members of the portable character set are each 3680 represented in a single byte. Moreover, if the value is stored in an object of C-language type 3681 char, it is guaranteed to be positive (except the NUL, which is always zero). 3682 Conforming implementations shall support certain character and character set attributes, as 3683 defined in Section 7.2 (on page 120). 3684 6.2 Character Encoding 3685 The POSIX locale contains the characters in Table 6-1 (on page 111), which have the properties 3686 listed in Section 7.3.1 (on page 122). In other locales, the presence, meaning, and representation 3687 of any additional characters is locale-specific. 3688 In locales other than the POSIX locale, a character may have a state-dependent encoding. There 3689 are two types of these encodings: 3690 * A single-shift encoding (where each character not in the initial shift state is preceded by a 3691 shift code) can be defined if each shift-code and character sequence is considered a multi- 3692 byte character. This is done using the concatenated-constant format in a character set 3693 description file, as described in Section 6.4 (on page 115). If the implementation supports a 3694 character encoding of this type, all of the standard utilities in the Shell and Utilities volume of | 3695 IEEE Std 1003.1-200x shall support it. Use of a single-shift encoding with any of the functions | 3696 in the System Interfaces volume of IEEE Std 1003.1-200x that do not specifically mention the 3697 effects of state-dependent encoding is implementation-defined. 3698 * A locking-shift encoding (where the state of the character is determined by a shift code that 3699 may affect more than the single character following it) cannot be defined with the current 3700 character set description file format. Use of a locking-shift encoding with any of the standard 3701 utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x or with any of the functions 3702 in the System Interfaces volume of IEEE Std 1003.1-200x that do not specifically mention the 3703 effects of state-dependent encoding is implementation-defined. 3704 While in the initial shift state, all characters in the portable character set shall retain their usual | 3705 interpretation and shall not alter the shift state. The interpretation for subsequent bytes in the | 3706 sequence shall be a function of the current shift state. A byte with all bits zero shall be | 3707 interpreted as the null character independent of shift state. Thus a byte with all bits zero shall | 3708 never occur in the second or subsequent bytes of a character. | 3709 The maximum allowable number of bytes in a character in the current locale shall be indicated | 3710 by {MB_CUR_MAX}, defined in the header and by the value in a | 3711 character set description file; see Section 6.4 (on page 115). The implementation's maximum | 3712 number of bytes in a character shall be defined by the C-language macro {MB_LEN_MAX}. | 114 Technical Standard (2001) (Draft April 13, 2001) Character Set C Language Wide-Character Codes 3713 6.3 C Language Wide-Character Codes 3714 In the shell, the standard utilities are written so that the encodings of characters are described by 3715 the locale's LC_CTYPE definition (see Section 7.3.1 (on page 122)) and there is no differentiation 3716 between characters consisting of single octets (8-bit bytes) or multiple bytes. However, in the C | 3717 language, a differentiation is made. To ease the handling of variable length characters, the C | 3718 language has introduced the concept of wide-character codes. | 3719 All wide-character codes in a given process consist of an equal number of bits. This is in contrast 3720 to characters, which can consist of a variable number of bytes. The byte or byte sequence that 3721 represents a character can also be represented as a wide-character code. Wide-character codes 3722 thus provide a uniform size for manipulating text data. A wide-character code having all bits 3723 zero is the null wide-character code (see Section 3.246 (on page 66)), and terminates wide- 3724 character strings (see Section 3.432 (on page 92)). The wide-character value for each member of | 3725 the portable character set shall equal its value when used as the lone character in an integer | 3726 character constant. Wide-character codes for other characters are locale and implementation- | 3727 defined. State shift bytes shall not have a wide-character code representation. | 3728 6.4 Character Set Description File 3729 Implementations shall provide a character set description file for at least one coded character set 3730 supported by the implementation. These files are referred to elsewhere in IEEE Std 1003.1-200x 3731 as charmap files. It is implementation-defined whether or not users or applications can provide 3732 additional character set description files. 3733 IEEE Std 1003.1-200x does not require that multiple character sets or codesets be supported. 3734 Although multiple charmap files are supported, it is the responsibility of the implementation to 3735 provide the file or files; if only one is provided, only that one is accessible using the localedef 3736 utility's -f option. 3737 Each character set description file, except those that use the ISO/IEC 10646-1: 2000 standard 3738 position values as the encoding values, shall define characteristics for the coded character set 3739 and the encoding for the characters specified in Table 6-1 (on page 111), and may define 3740 encoding for additional characters supported by the implementation. Other information about 3741 the coded character set may also be in the file. Coded character set character values shall be 3742 defined using symbolic character names followed by character encoding values. 3743 Each symbolic name specified in Table 6-1 (on page 111) shall be included in the file and shall be 3744 mapped to a unique coding value, except as noted below. The glyphs '{', '}', '_', '-', '/', 3745 '\', '.', and ' ' have more than one symbolic name; all symbolic names for each such glyph 3746 shall be included, each with identical encoding. If some or all of the control characters identified 3747 in Table 6-2 (on page 116) are supported by the implementation, the symbolic names and their 3748 corresponding encoding values shall be included in the file. Some of the encodings associated 3749 with the symbolic names in Table 6-2 (on page 116) may be the same as characters found in Table 3750 6-1 (on page 111); both names shall be provided for each encoding. Base Definitions, Issue 6 115 Character Set Description File Character Set 3751 Table 6-2 Control Character Set _________________________________________________________ 3752 3753 3754 3755 3756 3757 _ ________________________________________________________ 3758 The following declarations can precede the character definitions. Each shall consist of the | 3759 symbol shown in the following list, starting in column 1, including the surrounding brackets, | 3760 followed by one or more s, followed by the value to be assigned to the symbol. 3761 The name of the coded character set for which the character set 3762 description file is defined. The characters of the name shall be taken from 3763 the set of characters with visible glyphs defined in Table 6-1 (on page 3764 111). 3765 The maximum number of bytes in a multi-byte character. This shall | 3766 default to 1. | 3767 An unsigned positive integer value that defines the minimum number of 3768 XSI bytes in a character for the encoded character set. On XSI-conformant 3769 systems, shall always be 1. 3770 The character used to indicate that the characters following shall be | 3771 interpreted in a special way, as defined later in this section. This shall | 3772 default to backslash ('\'), which is the character used in all the following | 3773 text and examples, unless otherwise noted. 3774 The character that, when placed in column 1 of a charmap line, is used to | 3775 indicate that the line shall be ignored. The default character shall be the | 3776 number sign ('#'). | 3777 The character set mapping definitions shall be all the lines immediately following an identifier 3778 line containing the string "CHARMAP" starting in column 1, and preceding a trailer line 3779 containing the string "END CHARMAP" starting in column 1. Empty lines and lines containing a 3780 in the first column shall be ignored. Each non-comment line of the character 3781 set mapping definition (that is, between the "CHARMAP" and "END CHARMAP" lines of the file) 3782 shall be in either of two forms: 3783 "%s %s %s\n", , , 3784 or: 3785 "%s...%s %s %s\n", , , 3786 , 3787 In the first format, the line in the character set mapping definition shall define a single symbolic | 3788 name and a corresponding encoding. A symbolic name is one or more characters from the set | 3789 shown with visible glyphs in Table 6-1 (on page 111), enclosed between angle brackets. A | 3790 character following an escape character is interpreted as itself; for example, the sequence 3791 "<\\\>>" represents the symbolic name "\>" enclosed between angle brackets. 3792 In the second format, the line in the character set mapping definition shall define a range of one | 3793 or more symbolic names. In this form, the symbolic names shall consist of zero or more non- | 3794 numeric characters from the set shown with visible glyphs in Table 6-1 (on page 111), followed | 3795 by an integer formed by one or more decimal digits. Both integers shall contain the same number 3796 of digits. The characters preceding the integer shall be identical in the two symbolic names, and 116 Technical Standard (2001) (Draft April 13, 2001) Character Set Character Set Description File 3797 the integer formed by the digits in the second symbolic name shall be equal to or greater than the 3798 integer formed by the digits in the first name. This shall be interpreted as a series of symbolic 3799 names formed from the common part and each of the integers between the first and the second 3800 integer, inclusive. As an example, . . . is interpreted as the symbolic names 3801 , , , and , in that order. 3802 A character set mapping definition line shall exist for all symbolic names specified in Table 6-1 3803 (on page 111), and shall define the coded character value that corresponds to the character | 3804 indicated in the table, or the coded character value that corresponds to the control character 3805 symbolic name. If the control characters commonly associated with the symbolic names in Table 3806 6-2 (on page 116) are supported by the implementation, the symbolic name and the 3807 corresponding encoding value shall be included in the file. Additional unique symbolic names 3808 may be included. A coded character value can be represented by more than one symbolic name. 3809 The encoding part is expressed as one (for single-byte character values) or more concatenated 3810 decimal, octal, or hexadecimal constants in the following formats: 3811 "%cd%u", , 3812 "%cx%x", , 3813 "%c%o", , 3814 Decimal constants shall be represented by two or three decimal digits, preceded by the escape | 3815 character and the lowercase letter 'd'; for example, "\d05", "\d97", or "\d143". | 3816 Hexadecimal constants shall be represented by two hexadecimal digits, preceded by the escape | 3817 character and the lowercase letter 'x'; for example, "\x05", "\x61", or "\x8f". Octal | 3818 constants shall be represented by two or three octal digits, preceded by the escape character; for | 3819 example, "\05", "\141", or "\217". In a portable charmap file, each constant represents an 8- 3820 bit byte. When constants are concatenated for multi-byte character values, they shall be of the | 3821 same type, and interpreted in byte order from first to last with the least significant byte of the | 3822 multi-byte character specified by the last constant. The manner in which these constants are | 3823 represented in the character stored in the system is implementation-defined. (This notation was | 3824 chosen for reasons of portability. There is no requirement that the internal representation in the | 3825 computer memory be in this same order.) Omitting bytes from a multi-byte character definition | 3826 produces undefined results. | 3827 In lines defining ranges of symbolic names, the encoded value shall be the value for the first | 3828 symbolic name in the range (the symbolic name preceding the ellipsis). Subsequent symbolic | 3829 names defined by the range shall have encoding values in increasing order. Bytes shall be treated | 3830 as unsigned octets, and carry shall be propagated between the bytes as necessary to represent | 3831 the range. For example, the line: | 3832 ... \d129\d254 3833 is interpreted as: 3834 \d129\d254 3835 \d129\d255 3836 \d130\d0 3837 \d130\d1 3838 Note that this line is interpreted as the example even on systems with bytes larger than 8 bits. | 3839 The comment is optional. | 3840 The following declarations can follow the character set mapping definitions (after the "END 3841 CHARMAP" statement). Each shall consist of the keyword shown in the following list, starting in 3842 column 1, followed by the value(s) to be associated to the keyword, as defined below. Base Definitions, Issue 6 117 Character Set Description File Character Set 3843 WIDTH An unsigned positive integer value defining the column width (see Section 3.103 3844 (on page 47)) for the printable characters in the coded character set specified in 3845 Table 6-1 (on page 111) and Table 6-2 (on page 116). Coded character set character | 3846 values shall be defined using symbolic character names followed by column width 3847 values. Defining a character with more than one WIDTH produces undefined 3848 results. The END WIDTH keyword shall be used to terminate the WIDTH 3849 definitions. Specifying the width of a non-printable character in a WIDTH 3850 declaration produces undefined results. 3851 WIDTH_DEFAULT 3852 An unsigned positive integer value defining the default column width for any 3853 printable character not listed by one of the WIDTH keywords. If no 3854 WIDTH_DEFAULT keyword is included in the charmap, the default character 3855 width shall be 1. 3856 Example 3857 After the "END CHARMAP" statement, a syntax for a width definition would be: 3858 WIDTH 3859 1 3860 1 3861 ... 1 3862 ... 2 3863 END WIDTH 3864 In this example, the numerical code point values represented by the symbols and are 3865 assigned a width of 1. The code point values to inclusive (, , , and so on) 3866 are also assigned a width of 1. Using . . . would have required fewer lines, but the 3867 alternative was shown to demonstrate flexibility. The keyword WIDTH_DEFAULT could have 3868 been added as appropriate. 3869 6.4.1 State-Dependent Character Encodings 3870 This section addresses the use of state-dependent character encodings (that is, those in which the 3871 encoding of a character is dependent on one or more shift codes that may precede it). 3872 A single-shift encoding (where each character not in the initial shift state is preceded by a shift 3873 code) can be defined in the charmap format if each shift-code/character sequence is considered a 3874 multi-byte character, defined using the concatenated-constant format described in Section 6.4 3875 (on page 115). If the implementation supports a character encoding of this type, all of the 3876 standard utilities shall support it. A locking-shift encoding (where the state of the character is 3877 determined by a shift code that may affect more than the single character following it) could be 3878 defined with an extension to the charmap format described in Section 6.4 (on page 115). If the 3879 implementation supports a character encoding of this type, any of the standard utilities that 3880 describe character (versus byte) or text-file manipulation shall have the following characteristics: 3881 1. The utility shall process the statefully encoded data as a concatenation of state- 3882 independent characters. The presence of redundant locking shifts shall not affect the 3883 comparison of two statefully encoded strings. 3884 2. A utility that divides, truncates, or extracts substrings from statefully encoded data shall 3885 produce output that contains locking shifts at the beginning or end of the resulting data, if 3886 appropriate, to retain correct state information. | 118 Technical Standard (2001) (Draft April 13, 2001) Chapter 7 Locale 3887 3888 7.1 General 3889 A locale is the definition of the subset of a user's environment that depends on language and 3890 cultural conventions. It is made up from one or more categories. Each category is identified by 3891 its name and controls specific aspects of the behavior of components of the system. Category 3892 names correspond to the following environment variable names: 3893 LC_CTYPE Character classification and case conversion. 3894 LC_COLLATE Collation order. 3895 LC_MONETARY Monetary formatting. 3896 LC_NUMERIC Numeric, non-monetary formatting. 3897 LC_TIME Date and time formats. 3898 LC_MESSAGES Formats of informative and diagnostic messages and interactive responses. 3899 The standard utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x shall base their 3900 behavior on the current locale, as defined in the ENVIRONMENT VARIABLES section for each 3901 utility. The behavior of some of the C-language functions defined in the System Interfaces 3902 volume of IEEE Std 1003.1-200x shall also be modified based on the current locale, as defined by 3903 the last call to setlocale( ). 3904 Locales other than those supplied by the implementation can be created via the localedef utility, 3905 provided that the _POSIX2_LOCALEDEF symbol is defined on the system. Even if localedef is not 3906 provided, all implementations conforming to the System Interfaces volume of 3907 IEEE Std 1003.1-200x shall provide one or more locales that behave as described in this chapter. 3908 The input to the utility is described in Section 7.3 (on page 120). The value that is used to specify 3909 a locale when using environment variables shall be the string specified as the name operand to 3910 the localedef utility when the locale was created. The strings "C" and "POSIX" are reserved as 3911 identifiers for the POSIX locale (see Section 7.2 (on page 120)). When the value of a locale 3912 environment variable begins with a slash ('/'), it shall be interpreted as the pathname of the 3913 locale definition; the type of file (regular, directory, and so on) used to store the locale definition 3914 is implementation-defined. If the value does not begin with a slash, the mechanism used to 3915 locate the locale is implementation-defined. 3916 If different character sets are used by the locale categories, the results achieved by an application 3917 utilizing these categories are undefined. Likewise, if different codesets are used for the data 3918 being processed by interfaces whose behavior is dependent on the current locale, or the codeset 3919 is different from the codeset assumed when the locale was created, the result is also undefined. 3920 Applications can select the desired locale by invoking the setlocale( ) function (or equivalent) 3921 with the appropriate value. If the function is invoked with an empty string, such as: 3922 setlocale(LC_ALL, ""); 3923 the value of the corresponding environment variable is used. If the environment variable is 3924 unset or is set to the empty string, the implementation shall set the appropriate environment as 3925 defined in Chapter 8 (on page 157). Base Definitions, Issue 6 119 POSIX Locale Locale 3926 7.2 POSIX Locale 3927 Conforming systems shall provide a POSIX locale, also known as the C locale. The behavior of 3928 standard utilities and functions in the POSIX locale shall be as if the locale was defined via the 3929 localedef utility with input data from the POSIX locale tables in Section 7.3. 3930 The tables in Section 7.3 describe the characteristics and behavior of the POSIX locale for data 3931 consisting entirely of characters from the portable character set and the control character set. For 3932 other characters, the behavior is unspecified. For C-language programs, the POSIX locale shall be | 3933 the default locale when the setlocale( ) function is not called. | 3934 The POSIX locale can be specified by assigning to the appropriate environment variables the 3935 values "C" or "POSIX". 3936 All implementations shall define a locale as the default locale, to be invoked when no 3937 environment variables are set, or set to the empty string. This default locale can be the POSIX 3938 locale or any other implementation-defined locale. Some implementations may provide facilities 3939 for local installation administrators to set the default locale, customizing it for each location. 3940 IEEE Std 1003.1-200x does not require such a facility. 3941 7.3 Locale Definition 3942 The capability to specify additional locales to those provided by an implementation is optional, 3943 denoted by the _POSIX2_LOCALEDEF symbol. If the option is not supported, only 3944 implementation-supplied locales are available. Such locales shall be documented using the 3945 format specified in this section. 3946 Locales can be described with the file format presented in this section. The file format is that 3947 accepted by the localedef utility. For the purposes of this section, the file is referred to as the locale 3948 definition file, but no locales shall be affected by this file unless it is processed by localedef or some 3949 similar mechanism. Any requirements in this section imposed upon the utility shall apply to 3950 localedef or to any other similar utility used to install locale information using the locale 3951 definition file format described here. 3952 The locale definition file shall contain one or more locale category source definitions, and shall 3953 not contain more than one definition for the same locale category. If the file contains source 3954 definitions for more than one category, implementation-defined categories, if present, shall 3955 appear after the categories defined by Section 7.1 (on page 119). A category source definition 3956 contains either the definition of a category or a copy directive. For a description of the copy 3957 directive, see localedef. In the event that some of the information for a locale category, as 3958 specified in this volume of IEEE Std 1003.1-200x, is missing from the locale source definition, the 3959 behavior of that category, if it is referenced, is unspecified. 3960 A category source definition shall consist of a category header, a category body, and a category 3961 trailer. A category header shall consist of the character string naming of the category, beginning 3962 with the characters LC_. The category trailer shall consist of the string "END", followed by one 3963 or more s and the string used in the corresponding category header. 3964 The category body shall consist of one or more lines of text. Each line shall contain an identifier, 3965 optionally followed by one or more operands. Identifiers shall be either keywords, identifying a 3966 particular locale element, or collating elements. In addition to the keywords defined in this 3967 volume of IEEE Std 1003.1-200x, the source can contain implementation-defined keywords. Each 3968 keyword within a locale shall have a unique name (that is, two categories cannot have a 3969 commonly-named keyword); no keyword shall start with the characters LC_. Identifiers shall be 3970 separated from the operands by one or more s. 120 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 3971 Operands shall be characters, collating elements, or strings of characters. Strings shall be 3972 enclosed in double-quotes. Literal double-quotes within strings shall be preceded by the , described below. When a keyword is followed by more than one operand, the 3974 operands shall be separated by semicolons; s shall be allowed both before and after a 3975 semicolon. 3976 The first category header in the file can be preceded by a line modifying the comment character. 3977 It shall have the following format, starting in column 1: 3978 "comment_char %c\n", 3979 The comment character shall default to the number sign ('#'). Blank lines and lines containing 3980 the in the first position shall be ignored. 3981 The first category header in the file can be preceded by a line modifying the escape character to 3982 be used in the file. It shall have the following format, starting in column 1: 3983 "escape_char %c\n", 3984 The escape character shall default to backslash, which is the character used in all examples 3985 shown in this volume of IEEE Std 1003.1-200x. 3986 A line can be continued by placing an escape character as the last character on the line; this 3987 continuation character shall be discarded from the input. Although the implementation need not 3988 accept any one portion of a continued line with a length exceeding {LINE_MAX} bytes, it shall 3989 place no limits on the accumulated length of the continued line. Comment lines shall not be 3990 continued on a subsequent line using an escaped newline character. 3991 Individual characters, characters in strings, and collating elements shall be represented using 3992 symbolic names, as defined below. In addition, characters can be represented using the 3993 characters themselves or as octal, hexadecimal, or decimal constants. When non-symbolic 3994 notation is used, the resultant locale definitions are in many cases not portable between systems. 3995 The left angle bracket ('<') is a reserved symbol, denoting the start of a symbolic name; when 3996 used to represent itself it shall be preceded by the escape character. The following rules apply to 3997 character representation: 3998 1. A character can be represented via a symbolic name, enclosed within angle brackets '<' 3999 and '>'. The symbolic name, including the angle brackets, shall exactly match a symbolic 4000 name defined in the charmap file specified via the localedef -f option, and it shall be 4001 replaced by a character value determined from the value associated with the symbolic 4002 name in the charmap file. The use of a symbolic name not found in the charmap file shall 4003 constitute an error, unless the category is LC_CTYPE or LC_COLLATE, in which case it 4004 shall constitute a warning condition (see localedef for a description of actions resulting from 4005 errors and warnings). The specification of a symbolic name in a collating-element or 4006 collating-symbol section that duplicates a symbolic name in the charmap file (if present) 4007 shall be an error. Use of the escape character or a right angle bracket within a symbolic 4008 name is invalid unless the character is preceded by the escape character. 4009 For example: 4010 ; "" 4011 2. A character in the portable character set can be represented by the character itself, in which 4012 case the value of the character is implementation-defined. (Implementations may allow 4013 other characters to be represented as themselves, but such locale definitions are not 4014 portable.) Within a string, the double-quote character, the escape character, and the right 4015 angle bracket character shall be escaped (preceded by the escape character) to be 4016 interpreted as the character itself. Outside strings, the characters: Base Definitions, Issue 6 121 Locale Definition Locale 4017 , ; < > escape_char 4018 shall be escaped to be interpreted as the character itself. 4019 For example: 4020 c "May" 4021 3. A character can be represented as an octal constant. An octal constant shall be specified as 4022 the escape character followed by two or three octal digits. Each constant shall represent a 4023 byte value. Multi-byte values can be represented by concatenated constants specified in 4024 byte order with the last constant specifying the least significant byte of the character. 4025 For example: 4026 \143;\347;\143\150 "\115\141\171" 4027 4. A character can be represented as a hexadecimal constant. A hexadecimal constant shall be 4028 specified as the escape character followed by an 'x' followed by two hexadecimal digits. 4029 Each constant shall represent a byte value. Multi-byte values can be represented by 4030 concatenated constants specified in byte order with the last constant specifying the least 4031 significant byte of the character. 4032 For example: 4033 \x63;\xe7;\x63\x68 "\x4d\x61\x79" 4034 5. A character can be represented as a decimal constant. A decimal constant shall be specified 4035 as the escape character followed by a 'd' followed by two or three decimal digits. Each 4036 constant represents a byte value. Multi-byte values can be represented by concatenated 4037 constants specified in byte order with the last constant specifying the least significant byte 4038 of the character. 4039 For example: 4040 \d99;\d231;\d99\d104 "\d77\d97\d121" 4041 Implementations may accept single-digit octal, decimal, or hexadecimal constants following the | 4042 escape character. Only characters existing in the character set for which the locale definition is 4043 created shall be specified, whether using symbolic names, the characters themselves, or octal, 4044 decimal, or hexadecimal constants. If a charmap file is present, only characters defined in the 4045 charmap can be specified using octal, decimal, or hexadecimal constants. Symbolic names not 4046 present in the charmap file can be specified and shall be ignored, as specified under item 1 4047 above. 4048 7.3.1 LC_CTYPE 4049 The LC_CTYPE category shall define character classification, case conversion, and other 4050 character attributes. In addition, a series of characters can be represented by three adjacent 4051 periods representing an ellipsis symbol ("..."). The ellipsis specification shall be interpreted as 4052 meaning that all values between the values preceding and following it represent valid 4053 characters. The ellipsis specification shall be valid only within a single encoded character set; 4054 that is, within a group of characters of the same size. An ellipsis shall be interpreted as including 4055 in the list all characters with an encoded value higher than the encoded value of the character 4056 preceding the ellipsis and lower than the encoded value of the character following the ellipsis. 4057 For example: 4058 \x30;...;\x39; 122 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4059 includes in the character class all characters with encoded values between the endpoints. 4060 The following keywords shall be recognized. In the descriptions, the term ``automatically 4061 included'' means that it shall not be an error either to include or omit any of the referenced 4062 characters; the implementation provides them if missing (even if the entire keyword is missing) 4063 and accepts them silently if present. When the implementation automatically includes a missing 4064 character, it shall have an encoded value dependent on the charmap file in effect (see the 4065 description of the localedef -f option); otherwise, it shall have a value derived from an 4066 implementation-defined character mapping. 4067 The character classes digit, xdigit, lower, upper, and space have a set of automatically included 4068 characters. These only need to be specified if the character values (that is, encoding) differ from 4069 the implementation default values. It is not possible to define a locale without these 4070 automatically included characters unless some implementation extension is used to prevent 4071 their inclusion. Such a definition would not be a proper superset of the C or POSIX locale and 4072 thus, it might not be possible for conforming applications to work properly. 4073 copy Specify the name of an existing locale which shall be used as the definition of | 4074 this category. If this keyword is specified, no other keyword shall be specified. | 4075 upper Define characters to be classified as uppercase letters. 4076 In the POSIX locale, the 26 uppercase letters shall be included: | 4077 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 4078 In a locale definition file, no character specified for the keywords cntrl, digit, 4079 punct, or space shall be specified. The uppercase letters to , as 4080 defined in Section 6.4 (on page 115) (the portable character set), are 4081 automatically included in this class. 4082 lower Define characters to be classified as lowercase letters. 4083 In the POSIX locale, the 26 lowercase letters shall be included: | 4084 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 4085 In a locale definition file, no character specified for the keywords cntrl, digit, 4086 punct, or space shall be specified. The lowercase letters to of the 4087 portable character set are automatically included in this class. 4088 alpha Define characters to be classified as letters. 4089 In the POSIX locale, all characters in the classes upper and lower shall be | 4090 included. | 4091 In a locale definition file, no character specified for the keywords cntrl, digit, 4092 punct, or space shall be specified. Characters classified as either upper or 4093 lower are automatically included in this class. 4094 digit Define the characters to be classified as numeric digits. 4095 In the POSIX locale, only: 4096 0 1 2 3 4 5 6 7 8 9 4097 shall be included. | 4098 In a locale definition file, only the digits , , , , 4099 , , , , , and shall be specified, and in 4100 contiguous ascending sequence by numerical value. The digits to 4101 of the portable character set are automatically included in this class. Base Definitions, Issue 6 123 Locale Definition Locale 4102 alnum Define characters to be classified as letters and numeric digits. Only the 4103 characters specified for the alpha and digit keywords shall be specified. 4104 Characters specified for the keywords alpha and digit are automatically 4105 included in this class. 4106 space Define characters to be classified as white-space characters. 4107 In the POSIX locale, at a minimum, the , , , 4108 , , and shall be included. | 4109 In a locale definition file, no character specified for the keywords upper, 4110 lower, alpha, digit, graph, or xdigit shall be specified. The , , , , , and of the portable 4112 character set, and any characters included in the class blank are automatically 4113 included in this class. 4114 cntrl Define characters to be classified as control characters. 4115 In the POSIX locale, no characters in classes alpha or print shall be included. | 4116 In a locale definition file, no character specified for the keywords upper, 4117 lower, alpha, digit, punct, graph, print, or xdigit shall be specified. 4118 punct Define characters to be classified as punctuation characters. 4119 In the POSIX locale, neither the nor any characters in classes alpha, 4120 digit, or cntrl shall be included. | 4121 In a locale definition file, no character specified for the keywords upper, 4122 lower, alpha, digit, cntrl, xdigit, or as the shall be specified. 4123 graph Define characters to be classified as printable characters, not including the 4124 . 4125 In the POSIX locale, all characters in classes alpha, digit, and punct shall be | 4126 included; no characters in class cntrl shall be included. | 4127 In a locale definition file, characters specified for the keywords upper, lower, 4128 alpha, digit, xdigit, and punct are automatically included in this class. No 4129 character specified for the keyword cntrl shall be specified. 4130 print Define characters to be classified as printable characters, including the 4131 . 4132 In the POSIX locale, all characters in class graph shall be included; no | 4133 characters in class cntrl shall be included. | 4134 In a locale definition file, characters specified for the keywords upper, lower, 4135 alpha, digit, xdigit, punct, graph, and the are automatically included 4136 in this class. No character specified for the keyword cntrl shall be specified. 4137 xdigit Define the characters to be classified as hexadecimal digits. 4138 In the POSIX locale, only: 4139 0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f 4140 shall be included. | 4141 In a locale definition file, only the characters defined for the class digit shall be 4142 specified, in contiguous ascending sequence by numerical value, followed by 4143 one or more sets of six characters representing the hexadecimal digits 10 to 15 124 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4144 inclusive, with each set in ascending order (for example, , , , , 4145 , , , , , , , ). The digits to , the 4146 uppercase letters to , and the lowercase letters to of the 4147 portable character set are automatically included in this class. 4148 blank Define characters to be classified as s. 4149 In the POSIX locale, only the and shall be included. | 4150 In a locale definition file, the and are automatically included in 4151 this class. LI charclass Define one or more locale-specific character class | 4152 names as strings separated by semicolons. Each named character class can 4153 then be defined subsequently in the LC_CTYPE definition. A character class | 4154 name shall consist of at least one and at most {CHARCLASS_NAME_MAX} | 4155 bytes of alphanumeric characters from the portable filename character set. The | 4156 first character of a character class name shall not be a digit. The name shall not | 4157 match any of the LC_CTYPE keywords defined in this volume of | 4158 IEEE Std 1003.1-200x. Future revisions of IEEE Std 1003.1-200x will not specify 4159 any LC_CTYPE keywords containing uppercase letters. 4160 charclass-name Define characters to be classified as belonging to the named locale-specific 4161 character class. In the POSIX locale, locale-specific named character classes 4162 need not exist. 4163 If a class name is defined by a charclass keyword, but no characters are 4164 subsequently assigned to it, this is not an error; it represents a class without 4165 any characters belonging to it. 4166 The charclass-name can be used as the property argument to the wctype( ) 4167 function, in regular expression and shell pattern-matching bracket 4168 expressions, and by the tr command. 4169 toupper Define the mapping of lowercase letters to uppercase letters. 4170 In the POSIX locale, at a minimum, the 26 lowercase characters: 4171 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 4172 shall be mapped to the corresponding 26 uppercase characters: | 4173 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 4174 In a locale definition file, the operand shall consist of character pairs, | 4175 separated by semicolons. The characters in each character pair shall be | 4176 separated by a comma and the pair enclosed by parentheses. The first | 4177 character in each pair is the lowercase letter, the second the corresponding | 4178 uppercase letter. Only characters specified for the keywords lower and upper 4179 shall be specified. The lowercase letters to , and their corresponding 4180 uppercase letters to , of the portable character set are automatically 4181 included in this mapping, but only when the toupper keyword is omitted 4182 from the locale definition. 4183 tolower Define the mapping of uppercase letters to lowercase letters. 4184 In the POSIX locale, at a minimum, the 26 uppercase characters: 4185 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 4186 shall be mapped to the corresponding 26 lowercase characters: | Base Definitions, Issue 6 125 Locale Definition Locale 4187 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 4188 In a locale definition file, the operand shall consist of character pairs, | 4189 separated by semicolons. The characters in each character pair shall be | 4190 separated by a comma and the pair enclosed by parentheses. The first | 4191 character in each pair is the uppercase letter, the second the corresponding | 4192 lowercase letter. Only characters specified for the keywords lower and upper 4193 shall be specified. If the tolower keyword is omitted from the locale definition, 4194 the mapping is the reverse mapping of the one specified for toupper. 4195 The following table shows the character class combinations allowed: 4196 Table 7-1 Valid Character Class Combinations _____________________________________________________________________________ 4197 _ Can Also Belong To __________________________________________________________________ 4198 _In Class upper lower alpha digit space cntrl punct graph print xdigit blank ____________________________________________________________________________ 4199 upper - A x x x x A A - x 4200 lower - A x x x x A A - x 4201 alpha - - x x x x A A - x 4202 digit x x x x x x A A A x 4203 space x x x x - * * * x - 4204 cntrl x x x x - x x x x - 4205 punct x x x x - x A A x - 4206 graph - - - - - x - A - - 4207 print - - - - - x - - - - 4208 xdigit - - - - x x x A A x 4209 _ blank x x x x A - * * * x ____________________________________________________________________________ 4210 Notes: 4211 1. Explanation of codes: 4212 A Automatically included; see text. 4213 - Permitted. 4214 x Mutually-exclusive. 4215 * See note 2. 4216 2. The , which is part of the space and blank classes, cannot belong to punct or 4217 graph, but shall automatically belong to the print class. Other space or blank characters 4218 can be classified as any of punct, graph, or print. 4219 7.3.1.1 LC_CTYPE Category in the POSIX Locale 4220 The character classifications for the POSIX locale follow; the code listing depicts the localedef 4221 input, the table represents the same information, sorted by character. 4222 LC_CTYPE 4223 # The following is the POSIX locale LC_CTYPE. 4224 # "alpha" is by default "upper" and "lower" 4225 # "alnum" is by definition "alpha" and "digit" 4226 # "print" is by default "alnum", "punct" and the 4227 # "graph" is by default "alnum" and "punct" 4228 # 4229 upper ;;;;;;;;;;;;;\ 4230 ;;

;;;;;;;;;; 4231 # 126 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4232 lower ;;;;;;;;;;;;;\ 4233 ;;

;;;;;;;;;; 4234 # 4235 digit ;;;;;;;\ 4236 ;; 4237 # 4238 space ;;;;\ 4239 ; 4240 # 4241 cntrl ;;;;;\ 4242 ;;\ 4243 ;;;;;;;;\ 4244 ;;;;;;;;\ 4245 ;;;;;;;;\ 4246 ; 4247 # 4248 punct ;;;\ 4249 ;;;;\ 4250 ;;;\ 4251 ;;;;;\ 4252 ;;;;\ 4253 ;;;\ 4254 ;;;\ 4255 ;;;;\ 4256 ;; 4257 # 4258 xdigit ;;;;;;;;\ 4259 ;;;;;;;;;;;;; 4260 # 4261 blank ; 4262 # 4263 toupper (,);(,);(,);(,);(,);\ 4264 (,);(,);(,);(,);(,);\ 4265 (,);(,);(,);(,);(,);\ 4266 (

,

);(,);(,);(,);(,);\ 4267 (,);(,);(,);(,);(,);(,) 4268 # 4269 tolower (,);(,);(,);(,);(,);\ 4270 (,);(,);(,);(,);(,);\ 4271 (,);(,);(,);(,);(,);\ 4272 (

,

);(,);(,);(,);(,);\ 4273 (,);(,);(,);(,);(,);(,) 4274 END LC_CTYPE Base Definitions, Issue 6 127 Locale Definition Locale 4275 ____________________________________________________________________ 4276 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4277 cntrl 4278 cntrl 4279 cntrl 4280 cntrl 4281 cntrl 4282 cntrl 4283 cntrl 4284 cntrl 4285 cntrl 4286 cntrl, space, blank 4287 cntrl, space 4288 cntrl, space 4289 cntrl, space 4290 cntrl, space 4291 cntrl 4292 cntrl 4293 cntrl 4294 cntrl 4295 cntrl 4296 cntrl 4297 cntrl 4298 cntrl 4299 cntrl 4300 cntrl 4301 cntrl 4302 cntrl 4303 cntrl 4304 cntrl 4305 cntrl 4306 cntrl 4307 cntrl 4308 cntrl 4309 space, print, blank 4310 punct, print, graph 4311 punct, print, graph 4312 punct, print, graph 4313 punct, print, graph 4314 punct, print, graph 4315 punct, print, graph 4316 punct, print, graph 4317 punct, print, graph 4318 punct, print, graph 4319 punct, print, graph 4320 punct, print, graph 4321 punct, print, graph 4322 punct, print, graph 4323 _ punct, print, graph ___________________________________________________________________ 128 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4324 ____________________________________________________________________ 4325 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4326 punct, print, graph 4327 digit, xdigit, print, graph 4328 digit, xdigit, print, graph 4329 digit, xdigit, print, graph 4330 digit, xdigit, print, graph 4331 digit, xdigit, print, graph 4332 digit, xdigit, print, graph 4333 digit, xdigit, print, graph 4334 digit, xdigit, print, graph 4335 digit, xdigit, print, graph 4336 digit, xdigit, print, graph 4337 punct, print, graph 4338 punct, print, graph 4339 punct, print, graph 4340 punct, print, graph 4341 punct, print, graph 4342 punct, print, graph 4343 punct, print, graph 4344 upper, xdigit, alpha, print, graph 4345 upper, xdigit, alpha, print, graph 4346 upper, xdigit, alpha, print, graph 4347 upper, xdigit, alpha, print, graph 4348 upper, xdigit, alpha, print, graph 4349 upper, xdigit, alpha, print, graph 4350 upper, alpha, print, graph 4351 upper, alpha, print, graph 4352 upper, alpha, print, graph 4353 upper, alpha, print, graph 4354 upper, alpha, print, graph 4355 upper, alpha, print, graph 4356 upper, alpha, print, graph 4357 upper, alpha, print, graph 4358 upper, alpha, print, graph 4359

upper, alpha, print, graph 4360 upper, alpha, print, graph 4361 upper, alpha, print, graph 4362 upper, alpha, print, graph 4363 upper, alpha, print, graph 4364 upper, alpha, print, graph 4365 upper, alpha, print, graph 4366 upper, alpha, print, graph 4367 upper, alpha, print, graph 4368 upper, alpha, print, graph 4369 upper, alpha, print, graph 4370 punct, print, graph 4371 punct, print, graph 4372 _ punct, print, graph ___________________________________________________________________ Base Definitions, Issue 6 129 Locale Definition Locale 4373 ____________________________________________________________________ 4374 _ Symbolic Name Other Case Character Classes ___________________________________________________________________ 4375 punct, print, graph 4376 punct, print, graph 4377 punct, print, graph 4378 lower, xdigit, alpha, print, graph 4379 lower, xdigit, alpha, print, graph 4380 lower, xdigit, alpha, print, graph 4381 lower, xdigit, alpha, print, graph 4382 lower, xdigit, alpha, print, graph 4383 lower, xdigit, alpha, print, graph 4384 lower, alpha, print, graph 4385 lower, alpha, print, graph 4386 lower, alpha, print, graph 4387 lower, alpha, print, graph 4388 lower, alpha, print, graph 4389 lower, alpha, print, graph 4390 lower, alpha, print, graph 4391 lower, alpha, print, graph 4392 lower, alpha, print, graph 4393

lower, alpha, print, graph 4394 lower, alpha, print, graph 4395 lower, alpha, print, graph 4396 lower, alpha, print, graph 4397 lower, alpha, print, graph 4398 lower, alpha, print, graph 4399 lower, alpha, print, graph 4400 lower, alpha, print, graph 4401 lower, alpha, print, graph 4402 lower, alpha, print, graph 4403 lower, alpha, print, graph 4404 punct, print, graph 4405 punct, print, graph 4406 punct, print, graph 4407 punct, print, graph 4408 _ cntrl ___________________________________________________________________ 4409 7.3.2 LC_COLLATE 4410 The LC_COLLATE category provides a collation sequence definition for numerous utilities in the 4411 Shell and Utilities volume of IEEE Std 1003.1-200x (sort, uniq, and so on), regular expression 4412 matching (see Chapter 9 (on page 165)) and the strcoll( ), strxfrm( ), wcscoll( ), and wcsxfrm( ) 4413 functions in the System Interfaces volume of IEEE Std 1003.1-200x. 4414 A collation sequence definition shall define the relative order between collating elements 4415 (characters and multi-character collating elements) in the locale. This order is expressed in terms 4416 of collation values; that is, by assigning each element one or more collation values (also known 4417 as collation weights). This does not imply that implementations shall assign such values, but 4418 that ordering of strings using the resultant collation definition in the locale behaves as if such 4419 assignment is done and used in the collation process. At least the following capabilities are 4420 provided: 4421 1. Multi-character collating elements. Specification of multi-character collating elements 4422 (that is, sequences of two or more characters to be collated as an entity). 130 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4423 2. User-defined ordering of collating elements. Each collating element shall be assigned a 4424 collation value defining its order in the character (or basic) collation sequence. This 4425 ordering is used by regular expressions and pattern matching and, unless collation weights 4426 are explicitly specified, also as the collation weight to be used in sorting. 4427 3. Multiple weights and equivalence classes. Collating elements can be assigned one or 4428 more (up to the limit {COLL_WEIGHTS_MAX}, as defined in ) collating weights 4429 for use in sorting. The first weight is hereafter referred to as the primary weight. 4430 4. One-to-many mapping. A single character is mapped into a string of collating elements. 4431 5. Equivalence class definition. Two or more collating elements have the same collation 4432 value (primary weight). 4433 6. Ordering by weights. When two strings are compared to determine their relative order, 4434 the two strings are first broken up into a series of collating elements; the elements in each 4435 successive pair of elements are then compared according to the relative primary weights 4436 for the elements. If equal, and more than one weight has been assigned, then the pairs of 4437 collating elements are recompared according to the relative subsequent weights, until 4438 either a pair of collating elements compare unequal or the weights are exhausted. 4439 The following keywords shall be recognized in a collation sequence definition. They are 4440 described in detail in the following sections. 4441 copy Specify the name of an existing locale which shall be used as the | 4442 definition of this category. If this keyword is specified, no other keyword | 4443 shall be specified. | 4444 collating-element Define a collating-element symbol representing a multi-character 4445 collating element. This keyword is optional. 4446 collating-symbol Define a collating symbol for use in collation order statements. This 4447 keyword is optional. 4448 order_start Define collation rules. This statement shall be followed by one or more | 4449 collation order statements, assigning character collation values and 4450 collation weights to collating elements. 4451 order_end Specify the end of the collation-order statements. 4452 7.3.2.1 The collating-element Keyword 4453 In addition to the collating elements in the character set, the collating-element keyword can be 4454 used to define multi-character collating elements. The syntax is as follows: 4455 "collating-element %s from \"%s\"\n", , 4456 The operand shall be a symbolic name, enclosed between angle brackets ('<' 4457 and '>'), and shall not duplicate any symbolic name in the current charmap file (if any), or any 4458 other symbolic name defined in this collation definition. The string operand is a string of two or 4459 more characters that collates as an entity. A defined via this keyword is only 4460 recognized with the LC_COLLATE category. 4461 For example: 4462 collating-element from "" 4463 collating-element from "" 4464 collating-element from "ll" Base Definitions, Issue 6 131 Locale Definition Locale 4465 7.3.2.2 The collating-symbol Keyword 4466 This keyword shall be used to define symbols for use in collation sequence statements; that is, 4467 between the order_start and the order_end keywords. The syntax is as follows: 4468 "collating-symbol %s\n", 4469 The shall be a symbolic name, enclosed between angle brackets ('<' and 4470 '>'), and shall not duplicate any symbolic name in the current charmap file (if any), or any 4471 other symbolic name defined in this collation definition. A defined via this 4472 keyword is only recognized within the LC_COLLATE category. 4473 For example: 4474 collating-symbol 4475 collating-symbol 4476 The collating-symbol keyword defines a symbolic name that can be associated with a relative 4477 position in the character order sequence. While such a symbolic name does not represent any 4478 collating element, it can be used as a weight. 4479 7.3.2.3 The order_start Keyword 4480 The order_start keyword shall precede collation order entries and also define the number of 4481 weights for this collation sequence definition and other collation rules. The syntax is as follows: 4482 "order_start %s;%s;...;%s\n", , ... 4483 The operands to the order_start keyword are optional. If present, the operands define rules to be 4484 applied when strings are compared. The number of operands define how many weights each 4485 element is assigned; if no operands are present, one forward operand is assumed. If present, the 4486 first operand defines rules to be applied when comparing strings using the first (primary) 4487 weight; the second when comparing strings using the second weight, and so on. Operands shall 4488 be separated by semicolons (';'). Each operand shall consist of one or more collation 4489 directives, separated by commas (','). If the number of operands exceeds the 4490 {COLL_WEIGHTS_MAX} limit, the utility shall issue a warning message. The following 4491 directives shall be supported: 4492 forward Specifies that comparison operations for the weight level shall proceed from start 4493 of string towards the end of string. 4494 backward Specifies that comparison operations for the weight level shall proceed from end of 4495 string towards the beginning of string. 4496 position Specifies that comparison operations for the weight level shall consider the relative 4497 position of elements in the strings not subject to IGNORE. The string containing 4498 an element not subject to IGNORE after the fewest collating elements subject to 4499 IGNORE from the start of the compare shall collate first. If both strings contain a 4500 character not subject to IGNORE in the same relative position, the collating values 4501 assigned to the elements shall determine the ordering. In case of equality, 4502 subsequent characters not subject to IGNORE shall be considered in the same 4503 manner. 4504 The directives forward and backward are mutually-exclusive. 4505 If no operands are specified, a single forward operand shall be assumed. 4506 For example: 132 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4507 order_start forward;backward 4508 7.3.2.4 Collation Order 4509 The order_start keyword shall be followed by collating identifier entries. The syntax for the 4510 collating element entries is as follows: 4511 "%s %s;%s;...;%s\n", , , , ... 4512 Each collating-identifier shall consist of either a character (in any of the forms defined in Section 4513 7.3 (on page 120)), a , a , an ellipsis, or the special symbol 4514 UNDEFINED. The order in which collating elements are specified determines the character 4515 order sequence, such that each collating element shall compare less than the elements following 4516 it. 4517 A shall be used to specify multi-character collating elements, and indicates 4518 that the character sequence specified via the is to be collated as a unit and in 4519 the relative order specified by its place. 4520 A can be used to define a position in the relative order for use in weights. No 4521 weights shall be specified with a . 4522 The ellipsis symbol specifies that a sequence of characters shall collate according to their 4523 encoded character values. It shall be interpreted as indicating that all characters with a coded 4524 character set value higher than the value of the character in the preceding line, and lower than 4525 the coded character set value for the character in the following line, in the current coded 4526 character set, shall be placed in the character collation order between the previous and the 4527 following character in ascending order according to their coded character set values. An initial 4528 ellipsis shall be interpreted as if the preceding line specified the NUL character, and a trailing 4529 ellipsis as if the following line specified the highest coded character set value in the current 4530 coded character set. An ellipsis shall be treated as invalid if the preceding or following lines do 4531 not specify characters in the current coded character set. The use of the ellipsis symbol ties the 4532 definition to a specific coded character set and may preclude the definition from being portable 4533 between implementations. 4534 The symbol UNDEFINED shall be interpreted as including all coded character set values not 4535 specified explicitly or via the ellipsis symbol. Such characters shall be inserted in the character 4536 collation order at the point indicated by the symbol, and in ascending order according to their 4537 coded character set values. If no UNDEFINED symbol is specified, and the current coded 4538 character set contains characters not specified in this section, the utility shall issue a warning 4539 message and place such characters at the end of the character collation order. 4540 The optional operands for each collation-element shall be used to define the primary, secondary, 4541 or subsequent weights for the collating element. The first operand specifies the relative primary 4542 weight, the second the relative secondary weight, and so on. Two or more collation-elements can 4543 be assigned the same weight; they belong to the same equivalence class if they have the same 4544 primary weight. Collation shall behave as if, for each weight level, elements subject to IGNORE 4545 are removed, unless the position collation directive is specified for the corresponding level with 4546 the order_start keyword. Then each successive pair of elements shall be compared according to 4547 the relative weights for the elements. If the two strings compare equal, the process shall be 4548 repeated for the next weight level, up to the limit {COLL_WEIGHTS_MAX}. 4549 Weights shall be expressed as characters (in any of the forms specified in Section 7.3 (on page 4550 120)), s, s, an ellipsis, or the special symbol IGNORE. A 4551 single character, a , or a shall represent the relative position 4552 in the character collating sequence of the character or symbol, rather than the character or 4553 characters themselves. Thus, rather than assigning absolute values to weights, a particular Base Definitions, Issue 6 133 Locale Definition Locale 4554 weight is expressed using the relative order value assigned to a collating element based on its 4555 order in the character collation sequence. 4556 One-to-many mapping is indicated by specifying two or more concatenated characters or 4557 symbolic names. For example, if the is given the string "" as a weight, 4558 comparisons are performed as if all occurrences of the are replaced by "" 4559 (assuming that "" has the collating weight ""). If it is necessary to define and 4560 "" as an equivalence class, then a collating element must be defined for the string "ss". 4561 All characters specified via an ellipsis shall by default be assigned unique weights, equal to the 4562 relative order of characters. Characters specified via an explicit or implicit UNDEFINED special 4563 symbol shall by default be assigned the same primary weight (that is, they belong to the same 4564 equivalence class). An ellipsis symbol as a weight shall be interpreted to mean that each 4565 character in the sequence shall have unique weights, equal to the relative order of their character 4566 in the character collation sequence. The use of the ellipsis as a weight shall be treated as an error 4567 if the collating element is neither an ellipsis nor the special symbol UNDEFINED. 4568 The special keyword IGNORE as a weight shall indicate that when strings are compared using 4569 the weights at the level where IGNORE is specified, the collating element shall be ignored; that 4570 is, as if the string did not contain the collating element. In regular expressions and pattern 4571 matching, all characters that are subject to IGNORE in their primary weight form an 4572 equivalence class. 4573 An empty operand shall be interpreted as the collating element itself. 4574 For example, the order statement: 4575 ; 4576 is equal to: 4577 4578 An ellipsis can be used as an operand if the collating element was an ellipsis, and shall be 4579 interpreted as the value of each character defined by the ellipsis. 4580 The collation order as defined in this section affects the interpretation of bracket expressions in 4581 regular expressions (see Section 9.3.5 (on page 168)). 4582 For example: 4583 order_start forward;backward 4584 UNDEFINED IGNORE;IGNORE 4585 4586 ; 4587 ... ;... 4588 ; 4589 ; 4590 ; 4591 ; 4592 ; 4593 ; 4594 ; 4595 ; 4596 ; 4597 "";"" 4598 order_end 134 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4599 This example is interpreted as follows: 4600 1. The UNDEFINED means that all characters not specified in this definition (explicitly or 4601 via the ellipsis) shall be ignored for collation purposes. 4602 2. All characters between and 'a' shall have the same primary equivalence class 4603 and individual secondary weights based on their ordinal encoded values. 4604 3. All characters based on the uppercase or lowercase character 'a' belong to the same 4605 primary equivalence class. 4606 4. The multi-character collating element is represented by the collating symbol 4607 and belongs to the same primary equivalence class as the multi-character collating element 4608 . 4609 7.3.2.5 The order_end Keyword 4610 The collating order entries shall be terminated with an order_end keyword. 4611 7.3.2.6 LC_COLLATE Category in the POSIX Locale 4612 The collation sequence definition of the POSIX locale follows; the code listing depicts the 4613 localedef input. 4614 LC_COLLATE 4615 # This is the POSIX locale definition for the LC_COLLATE category. 4616 # The order is the same as in the ASCII codeset. 4617 order_start forward 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 Base Definitions, Issue 6 135 Locale Definition Locale 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 136 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4698

4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730

4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 order_end 4747 # 4748 END LC_COLLATE Base Definitions, Issue 6 137 Locale Definition Locale 4749 7.3.3 LC_MONETARY 4750 The LC_MONETARY category shall define the rules and symbols that are used to format 4751 XSI monetary numeric information. This information is available through the localeconv( ) function 4752 and is used by the strfmon( ) function. 4753 XSI Some of the information is also available in an alternative form via the nl_langinfo ( ) function 4754 (see CRNCYSTR in ). 4755 The following items are defined in this category of the locale. The item names are the keywords 4756 recognized by the localedef utility when defining a locale. They are also similar to the member 4757 names of the lconv structure defined in ; see for the exact symbols in the 4758 header. The localeconv( ) function returns {CHAR_MAX} for unspecified integer items and the 4759 empty string ("") for unspecified or size zero string items. 4760 In a locale definition file, the operands are strings, formatted as indicated by the grammar in 4761 Section 7.4 (on page 149). For some keywords, the strings can contain only integers. Keywords 4762 that are not provided, string values set to the empty string (""), or integer keywords set to -1, 4763 are used to indicate that the value is not available in the locale. The following keywords shall be 4764 recognized: 4765 copy Specify the name of an existing locale which shall be used as the | 4766 definition of this category. If this keyword is specified, no other keyword | 4767 shall be specified. | 4768 Note: This is a localedef utility keyword, unavailable through localeconv( ). 4769 int_curr_symbol The international currency symbol. The operand shall be a four-character 4770 string, with the first three characters containing the alphabetic 4771 international currency symbol in accordance with those specified in the 4772 ISO 4217: 1995 standard. The fourth character shall be the character used 4773 to separate the international currency symbol from the monetary 4774 quantity. 4775 currency_symbol The string that shall be used as the local currency symbol. 4776 mon_decimal_point The operand is a string containing the symbol that shall be used as the 4777 decimal delimiter (radix character) in monetary formatted quantities. | 4778 mon_thousands_sep The operand is a string containing the symbol that shall be used as a 4779 separator for groups of digits to the left of the decimal delimiter in | 4780 formatted monetary quantities. | 4781 mon_grouping Define the size of each group of digits in formatted monetary quantities. 4782 The operand is a sequence of integers separated by semicolons. Each 4783 integer specifies the number of digits in each group, with the initial 4784 integer defining the size of the group immediately preceding the decimal 4785 delimiter, and the following integers defining the preceding groups. If the 4786 last integer is not -1, then the size of the previous group (if any) shall be 4787 repeatedly used for the remainder of the digits. If the last integer is -1, 4788 then no further grouping shall be performed. 4789 positive_sign A string that shall be used to indicate a non-negative-valued formatted 4790 monetary quantity. 4791 negative_sign A string that shall be used to indicate a negative-valued formatted 4792 monetary quantity. 4793 int_frac_digits An integer representing the number of fractional digits (those to the right 4794 of the decimal delimiter) to be written in a formatted monetary quantity 138 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4795 using int_curr_symbol. 4796 frac_digits An integer representing the number of fractional digits (those to the right 4797 of the decimal delimiter) to be written in a formatted monetary quantity 4798 using currency_symbol. 4799 p_cs_precedes An integer set to 1 if the currency_symbol precedes the value for a | 4800 monetary quantity with a non-negative value, and set to 0 if the symbol 4801 succeeds the value. 4802 p_sep_by_space An integer set to 0 if no space separates the currency_symbol from the | 4803 value for a monetary quantity with a non-negative value, set to 1 if a 4804 space separates the symbol from the value, and set to 2 if a space 4805 separates the symbol and the sign string, if adjacent. 4806 n_cs_precedes An integer set to 1 if the currency_symbol precedes the value for a | 4807 monetary quantity with a negative value, and set to 0 if the symbol 4808 succeeds the value. 4809 n_sep_by_space An integer set to 0 if no space separates the currency_symbol from the | 4810 value for a monetary quantity with a negative value, set to 1 if a space 4811 separates the symbol from the value, and set to 2 if a space separates the 4812 symbol and the sign string, if adjacent. 4813 p_sign_posn An integer set to a value indicating the positioning of the positive_sign 4814 for a monetary quantity with a non-negative value. The following integer | 4815 values shall be recognized for int_n_sign_posn, int_p_sign_posn, | 4816 n_sign_posn, and p_sign_posn: | 4817 0 Parentheses enclose the quantity and the currency_symbol. | 4818 1 The sign string precedes the quantity and the currency_symbol. | 4819 2 The sign string succeeds the quantity and the currency_symbol. | 4820 3 The sign string precedes the currency_symbol. | 4821 4 The sign string succeeds the currency_symbol. | 4822 n_sign_posn An integer set to a value indicating the positioning of the negative_sign 4823 for a negative formatted monetary quantity. | 4824 int_p_cs_precedes An integer set to 1 if the int_curr_symbol precedes the value for a | 4825 monetary quantity with a non-negative value, and set to 0 if the symbol | 4826 succeeds the value. | 4827 int_n_cs_precedes An integer set to 1 if the int_curr_symbol precedes the value for a | 4828 monetary quantity with a negative value, and set to 0 if the symbol | 4829 succeeds the value. | 4830 int_p_sep_by_space An integer to set 0 if no space separates the int_curr_symbol from the | 4831 value for a monetary quantity with a non-negative value, set to 1 if a | 4832 space separates the symbol from the value, and set to 2 if a space | 4833 separates the symbol and the sign string, if adjacent. | 4834 int_n_sep_by_space An integer set to 0 if no space separates the int_curr_symbol from the | 4835 value for a monetary quantity with a negative value, set to 1 if a space | 4836 separates the symbol from the value, and set to 2 if a space separates the | 4837 symbol and the sign string, if adjacent. | Base Definitions, Issue 6 139 Locale Definition Locale 4838 int_p_sign_posn An integer set to a value indicating the positioning of the positive_sign | 4839 for a positive monetary quantity formatted with the international format. | 4840 int_n_sign_posn An integer set to a value indicating the positioning of the negative_sign | 4841 for a negative monetary quantity formatted with the international format. | 4842 7.3.3.1 LC_MONETARY Category in the POSIX Locale 4843 The monetary formatting definitions for the POSIX locale follow; the code listing depicting the 4844 XSI localedef input, the table representing the same information with the addition of localeconv( ) and 4845 nl_langinfo ( )formats. All values are unspecified in the POSIX locale. 4846 LC_MONETARY 4847 # This is the POSIX locale definition for 4848 # the LC_MONETARY category. 4849 # 4850 int_curr_symbol "" 4851 currency_symbol "" 4852 mon_decimal_point "" 4853 mon_thousands_sep "" 4854 mon_grouping -1 4855 positive_sign "" 4856 negative_sign "" 4857 int_frac_digits -1 4858 frac_digits -1 4859 p_cs_precedes -1 4860 p_sep_by_space -1 4861 n_cs_precedes -1 4862 n_sep_by_space -1 4863 p_sign_posn -1 4864 n_sign_posn -1 4865 # 4866 END LC_MONETARY ______________________________________________________________________________ 4867 langinfo POSIX Locale localeconv( ) localedef 4868 _ Item Constant Value Value Value _____________________________________________________________________________ 4869 int_curr_symbol - N/A " " " " 4870 currency_symbol CRNCYSTR N/A " " " " 4871 mon_decimal_point - N/A " " " " 4872 mon_thousands_sep - N/A " " " " 4873 mon_grouping - N/A " " " " 4874 positive_sign - N/A " " " " 4875 negative_sign - N/A " " " " 4876 int_frac_digits - N/A {CHAR_MAX} -1 4877 frac_digits - N/A {CHAR_MAX} -1 4878 p_cs_precedes CRNCYSTR N/A {CHAR_MAX} -1 4879 p_sep_by_space - N/A {CHAR_MAX} -1 4880 n_cs_precedes CRNCYSTR N/A {CHAR_MAX} -1 4881 n_sep_by_space - N/A {CHAR_MAX} -1 4882 p_sign_posn - N/A {CHAR_MAX} -1 4883 _ n_sign_posn - N/A {CHAR_MAX} -1 _____________________________________________________________________________ 4884 XSI In the preceding table, the langinfo Constant column represents an XSI-conformant extension. 4885 The entry N/A indicates that the value is not available in the POSIX locale. 140 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4886 7.3.4 LC_NUMERIC 4887 The LC_NUMERIC category shall define the rules and symbols that are used to format non- 4888 XSI monetary numeric information. This information is available through the localeconv( ) function. 4889 Some of the information is also available in an alternative form via the nl_langinfo ( ) function. 4890 The following items are defined in this category of the locale. The item names are the keywords 4891 recognized by the localedef utility when defining a locale. They are also similar to the member 4892 names of the lconv structure defined in ; see for the exact symbols in the 4893 header. The localeconv( ) function returns {CHAR_MAX} for unspecified integer items and the 4894 empty string ("") for unspecified or size zero string items. 4895 In a locale definition file, the operands are strings, formatted as indicated by the grammar in 4896 Section 7.4 (on page 149). For some keywords, the strings can only contain integers. Keywords 4897 that are not provided, string values set to the empty string (""), or integer keywords set to -1, 4898 shall be used to indicate that the value is not available in the locale. The following keywords 4899 shall be recognized: 4900 copy Specify the name of an existing locale which shall be used as the definition of | 4901 this category. If this keyword is specified, no other keyword shall be specified. | 4902 Note: This is a localedef utility keyword, unavailable through localeconv( ). 4903 decimal_point The operand is a string containing the symbol that shall be used as the 4904 decimal delimiter (radix character) in numeric, non-monetary formatted 4905 quantities. This keyword cannot be omitted and cannot be set to the empty 4906 string. In contexts where standards limit the decimal_point to a single byte, 4907 the result of specifying a multi-byte operand shall be unspecified. 4908 thousands_sep The operand is a string containing the symbol that shall be used as a separator 4909 for groups of digits to the left of the decimal delimiter in numeric, non- 4910 monetary formatted monetary quantities. In contexts where standards limit 4911 the thousands_sep to a single byte, the result of specifying a multi-byte 4912 operand shall be unspecified. 4913 grouping Define the size of each group of digits in formatted non-monetary quantities. 4914 The operand is a sequence of integers separated by semicolons. Each integer 4915 specifies the number of digits in each group, with the initial integer defining 4916 the size of the group immediately preceding the decimal delimiter, and the 4917 following integers defining the preceding groups. If the last integer is not -1, 4918 then the size of the previous group (if any) shall be repeatedly used for the 4919 remainder of the digits. If the last integer is -1, then no further grouping shall 4920 be performed. 4921 7.3.4.1 LC_NUMERIC Category in the POSIX Locale 4922 The non-monetary numeric formatting definitions for the POSIX locale follow; the code listing 4923 depicting the localedef input, the table representing the same information with the addition of 4924 XSI localeconv( ) values, and nl_langinfo ( ) constants. 4925 LC_NUMERIC 4926 # This is the POSIX locale definition for 4927 # the LC_NUMERIC category. 4928 # 4929 decimal_point "" 4930 thousands_sep "" 4931 grouping -1 4932 # Base Definitions, Issue 6 141 Locale Definition Locale 4933 END LC_NUMERIC ________________________________________________________________________ 4934 langinfo POSIX Locale localeconv( ) localedef 4935 _ Item Constant Value Value Value _______________________________________________________________________ 4936 decimal_point RADIXCHAR "." "." . 4937 thousands_sep THOUSEP N/A " " " " 4938 _ grouping - N/A " " -1 _______________________________________________________________________ 4939 XSI In the preceding table, the langinfo Constant column represents an XSI-conforming extension. 4940 The entry N/A indicates that the value is not available in the POSIX locale. 4941 7.3.5 LC_TIME 4942 The LC_TIME category shall define the interpretation of the conversion specifications supported 4943 XSI by the date utility and shall affect the behavior of the strftime( ), wcsftime( ), strptime( ), and 4944 nl_langinfo ( ) functions. Since the interfaces for C-language access and locale definition differ | 4945 significantly, they are described separately. 4946 7.3.5.1 LC_TIME Locale Definition 4947 For locale definition, the following mandatory keywords shall be recognized: 4948 copy Specify the name of an existing locale which shall be used as the definition of | 4949 this category. If this keyword is specified, no other keyword shall be specified. | 4950 abday Define the abbreviated weekday names, corresponding to the %a conversion 4951 specification (conversion specification in the strftime( ), wcsftime( ), and 4952 strptime( ) functions). The operand shall consist of seven semicolon-separated 4953 strings, each surrounded by double-quotes. The first string shall be the 4954 abbreviated name of the day corresponding to Sunday, the second the 4955 abbreviated name of the day corresponding to Monday, and so on. 4956 day Define the full weekday names, corresponding to the %A conversion 4957 specification. The operand shall consist of seven semicolon-separated strings, 4958 each surrounded by double-quotes. The first string is the full name of the day 4959 corresponding to Sunday, the second the full name of the day corresponding 4960 to Monday, and so on. 4961 abmon Define the abbreviated month names, corresponding to the %b conversion 4962 specification. The operand shall consist of twelve semicolon-separated strings, 4963 each surrounded by double-quotes. The first string shall be the abbreviated 4964 name of the first month of the year (January), the second the abbreviated 4965 name of the second month, and so on. 4966 mon Define the full month names, corresponding to the %B conversion 4967 specification. The operand shall consist of twelve semicolon-separated strings, 4968 each surrounded by double-quotes. The first string shall be the full name of 4969 the first month of the year (January), the second the full name of the second 4970 month, and so on. 4971 d_t_fmt Define the appropriate date and time representation, corresponding to the %c 4972 conversion specification. The operand shall consist of a string containing any 4973 combination of characters and conversion specifications. In addition, the 4974 string can contain escape sequences defined in the table in Table 5-1 (on page 4975 108) ('\\', '\a', '\b', '\f', '\n', '\r', '\t', '\v'). 142 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 4976 d_fmt Define the appropriate date representation, corresponding to the %x 4977 conversion specification. The operand shall consist of a string containing any 4978 combination of characters and conversion specifications. In addition, the 4979 string can contain escape sequences defined in the table in Table 5-1 (on page 4980 108). 4981 t_fmt Define the appropriate time representation, corresponding to the %X 4982 conversion specification. The operand shall consist of a string containing any 4983 combination of characters and conversion specifications. In addition, the 4984 string can contain escape sequences defined in the table in Table 5-1 (on page 4985 108). 4986 am_pm Define the appropriate representation of the ante meridiem and post meridiem 4987 strings, corresponding to the %p conversion specification. The operand shall 4988 consist of two strings, separated by a semicolon, each surrounded by double- 4989 quotes. The first string shall represent the ante meridiem designation, the last 4990 string the post meridiem designation. 4991 t_fmt_ampm Define the appropriate time representation in the 12-hour clock format with 4992 am_pm, corresponding to the %r conversion specification. The operand shall 4993 consist of a string and can contain any combination of characters and 4994 conversion specifications. If the string is empty, the 12-hour format is not 4995 supported in the locale. 4996 era Define how years are counted and displayed for each era in a locale. The 4997 operand shall consist of semicolon-separated strings. Each string shall be an 4998 era description segment with the format: 4999 direction:offset:start_date:end_date:era_name:era_format 5000 according to the definitions below. There can be as many era description 5001 segments as are necessary to describe the different eras. 5002 Note: The start of an era might not be the earliest point in the era-it may be the 5003 latest. For example, the Christian era BC starts on the day before January 1, 5004 AD 1, and increases with earlier time. 5005 direction Either a '+' or a '-' character. The '+' character shall indicate 5006 that years closer to the start_date have lower numbers than those 5007 closer to the end_date. The '-' character shall indicate that 5008 years closer to the start_date have higher numbers than those 5009 closer to the end_date. 5010 offset The number of the year closest to the start_date in the era, 5011 corresponding to the %Ey conversion specification. 5012 start_date A date in the form yyyy/mm/dd, where yyyy, mm, and dd are the 5013 year, month, and day numbers respectively of the start of the 5014 era. Years prior to AD 1 shall be represented as negative 5015 numbers. 5016 end_date The ending date of the era, in the same format as the start_date, 5017 or one of the two special values "-*" or "+*". The value "-*" 5018 shall indicate that the ending date is the beginning of time. The 5019 value "+*" shall indicate that the ending date is the end of time. 5020 era_name A string representing the name of the era, corresponding to the 5021 %EC conversion specification. Base Definitions, Issue 6 143 Locale Definition Locale 5022 era_format A string for formatting the year in the era, corresponding to the 5023 %EY conversion specification. 5024 era_d_fmt Define the format of the date in alternative era notation, corresponding to the 5025 %Ex conversion specification. 5026 era_t_fmt Define the locale's appropriate alternative time format, corresponding to the 5027 %EX conversion specification. 5028 era_d_t_fmt Define the locale's appropriate alternative date and time format, 5029 corresponding to the %Ec conversion specification. 5030 alt_digits Define alternative symbols for digits, corresponding to the %O modified 5031 conversion specification. The operand shall consist of semicolon-separated 5032 strings, each surrounded by double-quotes. The first string shall be the 5033 alternative symbol corresponding with zero, the second string the symbol 5034 corresponding with one, and so on. Up to 100 alternative symbol strings can 5035 be specified. The %O modifier shall indicate that the string corresponding to 5036 the value specified via the conversion specification shall be used instead of the 5037 value. 5038 7.3.5.2 LC_TIME C-Language Access 5039 XSI This section describes extensions to access information in the LC_TIME category using the 5040 nl_langinfo ( ) function. This functionality is dependent on support of the XSI extension (and the 5041 rest of this section is not further shaded for this option). 5042 The following constants used to identify items of langinfo data can be used as arguments to the 5043 nl_langinfo ( ) function to access information in the LC_TIME category. These constants are 5044 defined in the header. 5045 ABDAY_x The abbreviated weekday names (for example Sun), where x is a number from 5046 1 to 7. 5047 DAY_x The full weekday names (for example Sunday), where x is a number from 1 to 5048 7. 5049 ABMON_x The abbreviated month names (for example Jan), where x is a number from 1 5050 to 12. 5051 MON_x The full month names (for example January), where x is a number from 1 to 5052 12. 5053 D_T_FMT The appropriate date and time representation. 5054 D_FMT The appropriate date representation. 5055 T_FMT The appropriate time representation. 5056 AM_STR The appropriate ante-meridiem affix. 5057 PM_STR The appropriate post-meridiem affix. 5058 T_FMT_AMPM The appropriate time representation in the 12-hour clock format with 5059 AM_STR and PM_STR. 5060 ERA The era description segments, which describe how years are counted and 5061 displayed for each era in a locale. Each era description segment shall have the 5062 format: 144 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 5063 direction:offset:start_date:end_date:era_name:era_format 5064 according to the definitions below. There can be as many era description 5065 segments as are necessary to describe the different eras. Era description 5066 segments are separated by semicolons. 5067 direction Either a '+' or a '-' character. The '+' character shall indicate 5068 that years closer to the start_date have lower numbers than those 5069 closer to the end_date. The '-' character shall indicate that 5070 years closer to the start_date have higher numbers than those 5071 closer to the end_date. 5072 offset The number of the year closest to the start_date in the era. 5073 start_date A date in the form yyyy/mm/dd, where yyyy, mm, and dd are the 5074 year, month, and day numbers respectively of the start of the 5075 era. Years prior to AD 1 shall be represented as negative 5076 numbers. 5077 end_date The ending date of the era, in the same format as the start_date, 5078 or one of the two special values "-*" or "+*". The value "-*" 5079 shall indicate that the ending date is the beginning of time. The 5080 value "+*" shall indicate that the ending date is the end of time. 5081 era_name The era, corresponding to the %EC conversion specification. 5082 era_format The format of the year in the era, corresponding to the %EY 5083 conversion specification. 5084 ERA_D_FMT The era date format. 5085 ERA_T_FMT The locale's appropriate alternative time format, corresponding to the %EX 5086 conversion specification. 5087 ERA_D_T_FMT The locale's appropriate alternative date and time format, corresponding to 5088 the %Ec conversion specification. 5089 ALT_DIGITS The alternative symbols for digits, corresponding to the %O conversion 5090 specification modifier. The value consists of semicolon-separated symbols. 5091 The first is the alternative symbol corresponding to zero, the second is the 5092 symbol corresponding to one, and so on. Up to 100 alternative symbols may 5093 be specified. 5094 7.3.5.3 LC_TIME Category in the POSIX Locale 5095 The LC_TIME category definition of the POSIX locale follows; the code listing depicts the 5096 localedef input; the table represents the same information with the addition of localedef keywords, 5097 conversion specifiers used by the date utility and the strftime( ), wcsftime( ), and strptime( ) 5098 XSI functions, and nl_langinfo ( ) constants. 5099 LC_TIME 5100 # This is the POSIX locale definition for 5101 # the LC_TIME category. 5102 # 5103 # Abbreviated weekday names (%a) 5104 abday "";"";"";"";\ 5105 "";"";"" 5106 # 5107 # Full weekday names (%A) Base Definitions, Issue 6 145 Locale Definition Locale 5108 day "";"";\ 5109 "";"";\ 5110 "";"";\ 5111 "" 5112 # 5113 # Abbreviated month names (%b) 5114 abmon "";"";"";\ 5115 "

";"";"";\ 5116 "";"";"

";\ 5117 "";"";"" 5118 # 5119 # Full month names (%B) 5120 mon "";"";\ 5121 "";"

";\ 5122 "";"";\ 5123 "";"";\ 5124 "

";"";\ 5125 "";"" 5126 # 5127 # Equivalent of AM/PM (%p) "AM";"PM" 5128 am_pm "";"

" 5129 # 5130 # Appropriate date and time representation (%c) 5131 # "%a %b %e %H:%M:%S %Y" 5132 d_t_fmt "\ 5133 \ 5134 \ 5135 " 5136 # 5137 # Appropriate date representation (%x) "%m/%d/%y" 5138 d_fmt "\ 5139 " 5140 # 5141 # Appropriate time representation (%X) "%H:%M:%S" 5142 t_fmt "\ 5143 " 5144 # 5145 # Appropriate 12-hour time representation (%r) "%I:%M:%S %p" 5146 t_fmt_ampm "\ 5147

" 5148 # 5149 END LC_TIME 5150 _______________________________________________________________________________ 5151 localedef langinfo Conversion POSIX 5152 _ Keyword Constant Specification Locale Value ______________________________________________________________________________ 5153 d_t_fmt D_T_FMT %c "%a %b %e %H:%M:%S %Y" 5154 d_fmt D_FMT %x "%m/%d/%y" 5155 _ t_fmt T_FMT %X "%H:%M:%S" ______________________________________________________________________________ 146 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition 5156 _______________________________________________________________________________ 5157 localedef langinfo Conversion POSIX 5158 _ Keyword Constant Specification Locale Value ______________________________________________________________________________ 5159 am_pm AM_STR %p "AM" 5160 am_pm PM_STR %p "PM" 5161 t_fmt_ampm T_FMT_AMPM %r "%I:%M:%S %p" 5162 day DAY_1 %A "Sunday" 5163 day DAY_2 %A "Monday" 5164 day DAY_3 %A "Tuesday" 5165 day DAY_4 %A "Wednesday" 5166 day DAY_5 %A "Thursday" 5167 day DAY_6 %A "Friday" 5168 day DAY_7 %A "Saturday" 5169 abday ABDAY_1 %a "Sun" 5170 abday ABDAY_2 %a "Mon" 5171 abday ABDAY_3 %a "Tue" 5172 abday ABDAY_4 %a "Wed" 5173 abday ABDAY_5 %a "Thu" 5174 abday ABDAY_6 %a "Fri" 5175 abday ABDAY_7 %a "Sat" 5176 mon MON_1 %B "January" 5177 mon MON_2 %B "February" 5178 mon MON_3 %B "March" 5179 mon MON_4 %B "April" 5180 mon MON_5 %B "May" 5181 mon MON_6 %B "June" 5182 mon MON_7 %B "July" 5183 mon MON_8 %B "August" 5184 mon MON_9 %B "September" 5185 mon MON_10 %B "October" 5186 mon MON_11 %B "November" 5187 mon MON_12 %B "December" 5188 abmon ABMON_1 %b "Jan" 5189 abmon ABMON_2 %b "Feb" 5190 abmon ABMON_3 %b "Mar" 5191 abmon ABMON_4 %b "Apr" 5192 abmon ABMON_5 %b "May" 5193 abmon ABMON_6 %b "Jun" 5194 abmon ABMON_7 %b "Jul" 5195 abmon ABMON_8 %b "Aug" 5196 abmon ABMON_9 %b "Sep" 5197 abmon ABMON_10 %b "Oct" 5198 abmon ABMON_11 %b "Nov" 5199 abmon ABMON_12 %b "Dec" 5200 era ERA %EC, %Ey, %EY N/A 5201 era_d_fmt ERA_D_FMT %Ex N/A 5202 era_t_fmt ERA_T_FMT %EX N/A 5203 era_d_t_fmt ERA_D_T_FMT %Ec N/A 5204 _ alt_digits ALT_DIGITS %O N/A ______________________________________________________________________________ 5205 XSI In the preceding table, the langinfo Constant column represents an XSI-conformant extension. Base Definitions, Issue 6 147 Locale Definition Locale 5206 The entry ``N/A'' indicates the value is not available in the POSIX locale. 5207 7.3.6 LC_MESSAGES 5208 The LC_MESSAGES category shall define the format and values used by various utilities for 5209 XSI affirmative and negative responses. This information is available through the nl_langinfo ( ) 5210 function. 5211 XSI The message catalog used by the standard utilities and selected by the catopen( ) function shall be 5212 determined by the setting of NLSPATH; see Chapter 8 (on page 157). The LC_MESSAGES 5213 category can be specified as part of an NLSPATH substitution field. 5214 The following keywords shall be recognized as part of the locale definition file. 5215 copy Specify the name of an existing locale which shall be used as the definition of this | 5216 category. If this keyword is specified, no other keyword shall be specified. | 5217 Note: This is a localedef keyword, unavailable through nl_langinfo ( ). 5218 yesexpr The operand consists of an extended regular expression (see Section 9.4 (on page 5219 171)) that describes the acceptable affirmative response to a question expecting an 5220 affirmative or negative response. 5221 noexpr The operand consists of an extended regular expression that describes the 5222 acceptable negative response to a question expecting an affirmative or negative 5223 response. 5224 7.3.6.1 LC_MESSAGES Category for the POSIX Locale 5225 The format and values for affirmative and negative responses of the POSIX locale follow; the 5226 XSI code listing depicting the localedef input, the table representing the same information with the 5227 addition of nl_langinfo ( ) constants. 5228 LC_MESSAGES 5229 # This is the POSIX locale definition for 5230 # the LC_MESSAGES category. 5231 # 5232 yesexpr "" 5233 # 5234 noexpr "" 5235 # 5236 END LC_MESSAGES ____________________________________________________________ 5237 _localedef Keyword langinfo Constant POSIX Locale Value ___________________________________________________________ 5238 yesexpr YESEXPR " [yY]" 5239 _ noexpr NOEXPR " [nN]" ___________________________________________________________ 5240 XSI In the preceding table, the langinfo Constant column represents an XSI-conformant extension. 148 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition Grammar 5241 7.4 Locale Definition Grammar 5242 The grammar and lexical conventions in this section shall together describe the syntax for the 5243 locale definition source. The general conventions for this style of grammar are described in the 5244 Shell and Utilities volume of IEEE Std 1003.1-200x, Section 1.10, Grammar Conventions. The 5245 grammar shall take precedence over the text in this chapter. 5246 7.4.1 Locale Lexical Conventions 5247 The lexical conventions for the locale definition grammar are described in this section. 5248 The following tokens shall be processed (in addition to those string constants shown in the 5249 grammar): 5250 LOC_NAME A string of characters representing the name of a locale. 5251 CHAR Any single character. 5252 NUMBER A decimal number, represented by one or more decimal digits. 5253 COLLSYMBOL A symbolic name, enclosed between angle brackets. The string 5254 cannot duplicate any charmap symbol defined in the current 5255 charmap (if any), or a COLLELEMENT symbol. 5256 COLLELEMENT A symbolic name, enclosed between angle brackets, which cannot 5257 duplicate either any charmap symbol or a COLLSYMBOL symbol. 5258 CHARCLASS A string of alphanumeric characters from the portable character set, 5259 the first of which is not a digit, consisting of at least one and at most 5260 {CHARCLASS_NAME_MAX} bytes, and optionally surrounded by 5261 double-quotes. 5262 CHARSYMBOL A symbolic name, enclosed between angle brackets, from the current 5263 charmap (if any). 5264 OCTAL_CHAR One or more octal representations of the encoding of each byte in a 5265 single character. The octal representation consists of an escape 5266 character (normally a backslash) followed by two or more octal 5267 digits. 5268 HEX_CHAR One or more hexadecimal representations of the encoding of each 5269 byte in a single character. The hexadecimal representation consists of 5270 an escape character followed by the constant x and two or more 5271 hexadecimal digits. 5272 DECIMAL_CHAR One or more decimal representations of the encoding of each byte in 5273 a single character. The decimal representation consists of an escape 5274 character followed by a character 'd' and two or more decimal 5275 digits. 5276 ELLIPSIS The string "...". 5277 EXTENDED_REG_EXP An extended regular expression as defined in the grammar in Section 5278 9.5 (on page 175). 5279 EOL The line termination character newline. Base Definitions, Issue 6 149 Locale Definition Grammar Locale 5280 7.4.2 Locale Grammar 5281 This section presents the grammar for the locale definition. 5282 %token LOC_NAME 5283 %token CHAR 5284 %token NUMBER 5285 %token COLLSYMBOL COLLELEMENT 5286 %token CHARSYMBOL OCTAL_CHAR HEX_CHAR DECIMAL_CHAR 5287 %token ELLIPSIS 5288 %token EXTENDED_REG_EXP 5289 %token EOL 5290 %start locale_definition 5291 %% 5292 locale_definition : global_statements locale_categories 5293 | locale_categories 5294 ; 5295 global_statements : global_statements symbol_redefine 5296 | symbol_redefine 5297 ; 5298 symbol_redefine : 'escape_char' CHAR EOL 5299 | 'comment_char' CHAR EOL 5300 ; 5301 locale_categories : locale_categories locale_category 5302 | locale_category 5303 ; 5304 locale_category : lc_ctype | lc_collate | lc_messages 5305 | lc_monetary | lc_numeric | lc_time 5306 ; 5307 /* The following grammar rules are common to all categories */ 5308 char_list : char_list char_symbol 5309 | char_symbol 5310 ; 5311 char_symbol : CHAR | CHARSYMBOL 5312 | OCTAL_CHAR | HEX_CHAR | DECIMAL_CHAR 5313 ; 5314 elem_list : elem_list char_symbol 5315 | elem_list COLLSYMBOL 5316 | elem_list COLLELEMENT 5317 | char_symbol 5318 | COLLSYMBOL 5319 | COLLELEMENT 5320 ; 5321 symb_list : symb_list COLLSYMBOL 5322 | COLLSYMBOL 5323 ; 150 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition Grammar 5324 locale_name : LOC_NAME 5325 | '"' LOC_NAME '"' 5326 ; 5327 /* The following is the LC_CTYPE category grammar */ 5328 lc_ctype : ctype_hdr ctype_keywords ctype_tlr 5329 | ctype_hdr 'copy' locale_name EOL ctype_tlr 5330 ; 5331 ctype_hdr : 'LC_CTYPE' EOL 5332 ; 5333 ctype_keywords : ctype_keywords ctype_keyword 5334 | ctype_keyword 5335 ; 5336 ctype_keyword : charclass_keyword charclass_list EOL 5337 | charconv_keyword charconv_list EOL 5338 | 'charclass' charclass_namelist EOL 5339 ; 5340 charclass_namelist : charclass_namelist ';' CHARCLASS 5341 | CHARCLASS 5342 ; 5343 charclass_keyword : 'upper' | 'lower' | 'alpha' | 'digit' 5344 | 'punct' | 'xdigit' | 'space' | 'print' 5345 | 'graph' | 'blank' | 'cntrl' | 'alnum' 5346 | CHARCLASS 5347 ; 5348 charclass_list : charclass_list ';' char_symbol 5349 | charclass_list ';' ELLIPSIS ';' char_symbol 5350 | char_symbol 5351 ; 5352 charconv_keyword : 'toupper' 5353 | 'tolower' 5354 ; 5355 charconv_list : charconv_list ';' charconv_entry 5356 | charconv_entry 5357 ; 5358 charconv_entry : '(' char_symbol ',' char_symbol ')' 5359 ; 5360 ctype_tlr : 'END' 'LC_CTYPE' EOL 5361 ; 5362 /* The following is the LC_COLLATE category grammar */ 5363 lc_collate : collate_hdr collate_keywords collate_tlr 5364 | collate_hdr 'copy' locale_name EOL collate_tlr 5365 ; 5366 collate_hdr : 'LC_COLLATE' EOL 5367 ; Base Definitions, Issue 6 151 Locale Definition Grammar Locale 5368 collate_keywords : order_statements 5369 | opt_statements order_statements 5370 ; 5371 opt_statements : opt_statements collating_symbols 5372 | opt_statements collating_elements 5373 | collating_symbols 5374 | collating_elements 5375 ; 5376 collating_symbols : 'collating-symbol' COLLSYMBOL EOL 5377 ; 5378 collating_elements : 'collating-element' COLLELEMENT 5379 | 'from' '"' elem_list '"' EOL 5380 ; 5381 order_statements : order_start collation_order order_end 5382 ; 5383 order_start : 'order_start' EOL 5384 | 'order_start' order_opts EOL 5385 ; 5386 order_opts : order_opts ';' order_opt 5387 | order_opt 5388 ; 5389 order_opt : order_opt ',' opt_word 5390 | opt_word 5391 ; 5392 opt_word : 'forward' | 'backward' | 'position' 5393 ; 5394 collation_order : collation_order collation_entry 5395 | collation_entry 5396 ; 5397 collation_entry : COLLSYMBOL EOL 5398 | collation_element weight_list EOL 5399 | collation_element EOL 5400 ; 5401 collation_element : char_symbol 5402 | COLLELEMENT 5403 | ELLIPSIS 5404 | 'UNDEFINED' 5405 ; 5406 weight_list : weight_list ';' weight_symbol 5407 | weight_list ';' 5408 | weight_symbol 5409 ; 5410 weight_symbol : /* empty */ 5411 | char_symbol 5412 | COLLSYMBOL 5413 | '"' elem_list '"' 152 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition Grammar 5414 | '"' symb_list '"' 5415 | ELLIPSIS 5416 | 'IGNORE' 5417 ; 5418 order_end : 'order_end' EOL 5419 ; 5420 collate_tlr : 'END' 'LC_COLLATE' EOL 5421 ; 5422 /* The following is the LC_MESSAGES category grammar */ 5423 lc_messages : messages_hdr messages_keywords messages_tlr 5424 | messages_hdr 'copy' locale_name EOL messages_tlr 5425 ; 5426 messages_hdr : 'LC_MESSAGES' EOL 5427 ; 5428 messages_keywords : messages_keywords messages_keyword 5429 | messages_keyword 5430 ; 5431 messages_keyword : 'yesexpr' '"' EXTENDED_REG_EXP '"' EOL 5432 | 'noexpr' '"' EXTENDED_REG_EXP '"' EOL 5433 ; | 5434 messages_tlr : 'END' 'LC_MESSAGES' EOL 5435 ; 5436 /* The following is the LC_MONETARY category grammar */ 5437 lc_monetary : monetary_hdr monetary_keywords monetary_tlr 5438 | monetary_hdr 'copy' locale_name EOL monetary_tlr 5439 ; 5440 monetary_hdr : 'LC_MONETARY' EOL 5441 ; 5442 monetary_keywords : monetary_keywords monetary_keyword 5443 | monetary_keyword 5444 ; 5445 monetary_keyword : mon_keyword_string mon_string EOL 5446 | mon_keyword_char NUMBER EOL 5447 | mon_keyword_char '-1' EOL 5448 | mon_keyword_grouping mon_group_list EOL 5449 ; 5450 mon_keyword_string : 'int_curr_symbol' | 'currency_symbol' 5451 | 'mon_decimal_point' | 'mon_thousands_sep' 5452 | 'positive_sign' | 'negative_sign' 5453 ; 5454 mon_string : '"' char_list '"' 5455 | '""' 5456 ; Base Definitions, Issue 6 153 Locale Definition Grammar Locale 5457 mon_keyword_char : 'int_frac_digits' | 'frac_digits' 5458 | 'p_cs_precedes' | 'p_sep_by_space' 5459 | 'n_cs_precedes' | 'n_sep_by_space' 5460 | 'p_sign_posn' | 'n_sign_posn' 5461 ; 5462 mon_keyword_grouping : 'mon_grouping' 5463 ; 5464 mon_group_list : NUMBER 5465 | mon_group_list ';' NUMBER 5466 ; 5467 monetary_tlr : 'END' 'LC_MONETARY' EOL 5468 ; 5469 /* The following is the LC_NUMERIC category grammar */ 5470 lc_numeric : numeric_hdr numeric_keywords numeric_tlr 5471 | numeric_hdr 'copy' locale_name EOL numeric_tlr 5472 ; 5473 numeric_hdr : 'LC_NUMERIC' EOL 5474 ; 5475 numeric_keywords : numeric_keywords numeric_keyword 5476 | numeric_keyword 5477 ; 5478 numeric_keyword : num_keyword_string num_string EOL 5479 | num_keyword_grouping num_group_list EOL 5480 ; 5481 num_keyword_string : 'decimal_point' 5482 | 'thousands_sep' 5483 ; 5484 num_string : '"' char_list '"' 5485 | '""' 5486 ; 5487 num_keyword_grouping: 'grouping' 5488 ; 5489 num_group_list : NUMBER 5490 | num_group_list ';' NUMBER 5491 ; 5492 numeric_tlr : 'END' 'LC_NUMERIC' EOL 5493 ; 5494 /* The following is the LC_TIME category grammar */ 5495 lc_time : time_hdr time_keywords time_tlr 5496 | time_hdr 'copy' locale_name EOL time_tlr 5497 ; 5498 time_hdr : 'LC_TIME' EOL 5499 ; 154 Technical Standard (2001) (Draft April 13, 2001) Locale Locale Definition Grammar 5500 time_keywords : time_keywords time_keyword 5501 | time_keyword 5502 ; 5503 time_keyword : time_keyword_name time_list EOL 5504 | time_keyword_fmt time_string EOL 5505 | time_keyword_opt time_list EOL 5506 ; 5507 time_keyword_name : 'abday' | 'day' | 'abmon' | 'mon' 5508 ; 5509 time_keyword_fmt : 'd_t_fmt' | 'd_fmt' | 't_fmt' 5510 | 'am_pm' | 't_fmt_ampm' 5511 ; 5512 time_keyword_opt : 'era' | 'era_d_fmt' | 'era_t_fmt' 5513 | 'era_d_t_fmt' | 'alt_digits' 5514 ; 5515 time_list : time_list ';' time_string 5516 | time_string 5517 ; 5518 time_string : '"' char_list '"' 5519 ; 5520 time_tlr : 'END' 'LC_TIME' EOL 5521 ; Base Definitions, Issue 6 155 Locale 5522 | 156 Technical Standard (2001) (Draft April 13, 2001) Chapter 8 Environment Variables 5523 5524 8.1 Environment Variable Definition 5525 Environment variables defined in this chapter affect the operation of multiple utilities, functions, 5526 and applications. There are other environment variables that are of interest only to specific 5527 utilities. Environment variables that apply to a single utility only are defined as part of the 5528 utility description. See the ENVIRONMENT VARIABLES section of the utility descriptions in 5529 the Shell and Utilities volume of IEEE Std 1003.1-200x for information on environment variable 5530 usage. 5531 The value of an environment variable is a string of characters. For a C-language program, an 5532 array of strings called the environment shall be made available when a process begins. The array 5533 is pointed to by the external variable environ, which is defined as: 5534 extern char **environ; 5535 These strings have the form name=value; names shall not contain the character '='. For values to | 5536 be portable across systems conforming to IEEE Std 1003.1-200x, the value shall be composed of 5537 characters from the portable character set (except NUL and as indicated below). There is no 5538 meaning associated with the order of strings in the environment. If more than one string in a 5539 process' environment has the same name, the consequences are undefined. 5540 Environment variable names used by the utilities in the Shell and Utilities volume of | 5541 IEEE Std 1003.1-200x consist solely of uppercase letters, digits, and the '_' (underscore) from | 5542 the characters defined in Table 6-1 (on page 111) and do not begin with a digit. Other characters | 5543 may be permitted by an implementation; applications shall tolerate the presence of such names. | 5544 Uppercase and lowercase letters shall retain their unique identities and shall not be folded | 5545 together. The name space of environment variable names containing lowercase letters is | 5546 reserved for applications. Applications can define any environment variables with names from | 5547 this name space without modifying the behavior of the standard utilities. | 5548 Note: Other applications may have difficulty dealing with environment variable names that start | 5549 with a digit. For this reason, use of such names is not recommended anywhere. 5550 The values that the environment variables may be assigned are not restricted except that they are 5551 considered to end with a null byte and the total space used to store the environment and the 5552 arguments to the process is limited to {ARG_MAX} bytes. 5553 Other name=value pairs may be placed in the environment by, for example, calling any of the 5554 XSI setenv( ), unsetenv( ), or putenv( ) functions, manipulating the environ variable, or by using envp 5555 arguments when creating a process; see exec in the System Interfaces volume of 5556 IEEE Std 1003.1-200x. 5557 It is unwise to conflict with certain variables that are frequently exported by widely used 5558 command interpreters and applications: Base Definitions, Issue 6 157 Environment Variable Definition Environment Variables 5559 __________________________________________________________ 5560 ARFLAGS IFS MAILPATH PS1 5561 CC LANG MAILRC PS2 5562 CDPATH LC_ALL MAKEFLAGS PS3 5563 CFLAGS LC_COLLATE MAKESHELL PS4 5564 CHARSET LC_CTYPE MANPATH PWD 5565 COLUMNS LC_MESSAGES MBOX RANDOM 5566 DATEMSK LC_MONETARY MORE SECONDS 5567 DEAD LC_NUMERIC MSGVERB SHELL 5568 EDITOR LC_TIME NLSPATH TERM 5569 ENV LDFLAGS NPROC TERMCAP 5570 EXINIT LEX OLDPWD TERMINFO 5571 FC LFLAGS OPTARG TMPDIR 5572 FCEDIT LINENO OPTERR TZ 5573 FFLAGS LINES OPTIND USER 5574 GET LISTER PAGER VISUAL 5575 GFLAGS LOGNAME PATH YACC 5576 HISTFILE LPDEST PPID YFLAGS 5577 HISTORY MAIL PRINTER 5578 HISTSIZE MAILCHECK PROCLANG 5579 _ HOME MAILER PROJECTDIR _________________________________________________________ 5580 If the variables in the following two sections are present in the environment during the | 5581 execution of an application or utility, they shall be given the meaning described below. Some are | 5582 placed into the environment by the implementation at the time the user logs in; all can be added | 5583 or changed by the user or any ancestor of the current process. The implementation adds or | 5584 changes environment variables named in IEEE Std 1003.1-200x only as specified in | 5585 IEEE Std 1003.1-200x. If they are defined in the application's environment, the utilities in the 5586 Shell and Utilities volume of IEEE Std 1003.1-200x and the functions in the System Interfaces 5587 volume of IEEE Std 1003.1-200x assume they have the specified meaning. Conforming 5588 applications shall not set these environment variables to have meanings other than as described. 5589 See getenv( ) and the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 2.12, Shell 5590 Execution Environment for methods of accessing these variables. 5591 8.2 Internationalization Variables 5592 This section describes environment variables that are relevant to the operation of 5593 internationalized interfaces described in IEEE Std 1003.1-200x. 5594 Users may use the following environment variables to announce specific localization 5595 requirements to applications. Applications can retrieve this information using the setlocale( ) 5596 function to initialize the correct behavior of the internationalized interfaces. The descriptions of 5597 the internationalization environment variables describe the resulting behavior only when the 5598 application locale is initialized in this way. The use of the internationalization variables by 5599 utilities described in the Shell and Utilities volume of IEEE Std 1003.1-200x are described in the 5600 ENVIRONMENT VARIABLES section for those utilities in addition to the global effects 5601 described in this section. 5602 LANG This variable shall determine the locale category for native language, local 5603 customs, and coded character set in the absence of the LC_ALL and other LC_* 5604 (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, 5605 LC_TIME) environment variables. This can be used by applications to 5606 determine the language to use for error messages and instructions, collating 5607 sequences, date formats, and so on. 158 Technical Standard (2001) (Draft April 13, 2001) Environment Variables Internationalization Variables 5608 LC_ALL This variable shall determine the values for all locale categories. The value of 5609 the LC_ALL environment variable has precedence over any of the other 5610 environment variables starting with LC_(LC_COLLATE, LC_CTYPE, 5611 LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) and the LANG 5612 environment variable. 5613 LC_COLLATE This variable shall determine the locale category for character collation. It 5614 determines collation information for regular expressions and sorting, 5615 including equivalence classes and multi-character collating elements, in 5616 various utilities and the strcoll( ) and strxfrm( ) functions. Additional semantics 5617 of this variable, if any, are implementation-defined. 5618 LC_CTYPE This variable shall determine the locale category for character handling 5619 functions, such as tolower( ), toupper( ), and isalpha( ). This environment 5620 variable determines the interpretation of sequences of bytes of text data as 5621 characters (for example, single as opposed to multi-byte characters), the 5622 classification of characters (for example, alpha, digit, graph), and the behavior 5623 of character classes. Additional semantics of this variable, if any, are 5624 implementation-defined. 5625 LC_MESSAGES This variable shall determine the locale category for processing affirmative 5626 and negative responses and the language and cultural conventions in which 5627 XSI messages should be written. It also affects the behavior of the catopen( ) 5628 function in determining the message catalog. Additional semantics of this 5629 variable, if any, are implementation-defined. The language and cultural 5630 conventions of diagnostic and informative messages whose format is 5631 unspecified by IEEE Std 1003.1-200x should be affected by the setting of 5632 LC_MESSAGES. 5633 LC_MONETARY This variable shall determine the locale category for monetary-related numeric 5634 formatting information. Additional semantics of this variable, if any, are 5635 implementation-defined. 5636 LC_NUMERIC This variable shall determine the locale category for numeric formatting (for 5637 example, thousands separator and radix character) information in various 5638 utilities as well as the formatted I/O operations in printf( ) and scanf( ) and the 5639 string conversion functions in strtod( ). Additional semantics of this variable, 5640 if any, are implementation-defined. 5641 LC_TIME This variable shall determine the locale category for date and time formatting 5642 information. It affects the behavior of the time functions in strftime( ). 5643 Additional semantics of this variable, if any, are implementation-defined. 5644 XSI NLSPATH This variable shall contain a sequence of templates that the catopen( ) function 5645 uses when attempting to locate message catalogs. Each template consists of an 5646 optional prefix, one or more conversion specifications, a filename, and an 5647 optional suffix. 5648 For example: 5649 NLSPATH="/system/nlslib/%N.cat" 5650 defines that catopen( ) should look for all message catalogs in the directory 5651 /system/nlslib, where the catalog name should be constructed from the name 5652 parameter passed to catopen( ) (%N), with the suffix .cat. 5653 Conversion specifications consist of a '%' symbol, followed by a single-letter 5654 keyword. The following keywords are currently defined: Base Definitions, Issue 6 159 Internationalization Variables Environment Variables 5655 %N The value of the name parameter passed to catopen( ). 5656 %L The value of the LC_MESSAGES category. 5657 %l The language element from the LC_MESSAGES category. 5658 %t The territory element from the LC_MESSAGES category. 5659 %c The codeset element from the LC_MESSAGES category. 5660 %% A single '%' character. 5661 An empty string is substituted if the specified value is not currently defined. 5662 The separators underscore ('_') and period ('.') are not included in the %t 5663 and %c conversion specifications. 5664 Templates defined in NLSPATH are separated by colons (':'). A leading or 5665 two adjacent colons "::" is equivalent to specifying %N. For example: 5666 NLSPATH=":%N.cat:/nlslib/%L/%N.cat" 5667 indicates to catopen( ) that it should look for the requested message catalog in 5668 name, name.cat, and /nlslib/category/name.cat, where category is the value of the 5669 LC_MESSAGES category of the current locale. 5670 Users should not set the NLSPATH variable unless they have a specific reason 5671 to override the default system path. Setting NLSPATH to override the default 5672 system path produces undefined results in the standard utilities and in 5673 applications with appropriate privileges. 5674 The environment variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, 5675 XSI LC_MONETARY, LC_NUMERIC, LC_TIME, and NLSPATH provide for the support of 5676 internationalized applications. The standard utilities shall make use of these environment 5677 variables as described in this section and the individual ENVIRONMENT VARIABLES sections 5678 for the utilities. If these variables specify locale categories that are not based upon the same 5679 underlying codeset, the results are unspecified. 5680 The values of locale categories shall be determined by a precedence order; the first condition met 5681 below determines the value: 5682 1. If the LC_ALL environment variable is defined and is not null, the value of LC_ALL shall be 5683 used. 5684 2. If the LC_* environment variable (LC_COLLATE, LC_CTYPE, LC_MESSAGES, 5685 LC_MONETARY, LC_NUMERIC, LC_TIME) is defined and is not null, the value of the 5686 environment variable shall be used to initialize the category that corresponds to the 5687 environment variable. 5688 3. If the LANG environment variable is defined and is not null, the value of the LANG 5689 environment variable shall be used. 5690 4. If the LANG environment variable is not set or is set to the empty string, the 5691 implementation-defined default locale shall be used. 5692 If the locale value is "C" or "POSIX", the POSIX locale shall be used and the standard utilities 5693 behave in accordance with the rules in Section 7.2 (on page 120) for the associated category. 5694 If the locale value begins with a slash, it shall be interpreted as the pathname of a file that was 5695 created in the output format used by the localedef utility; see OUTPUT FILES under localedef. 5696 Referencing such a pathname shall result in that locale being used for the indicated category. 160 Technical Standard (2001) (Draft April 13, 2001) Environment Variables Internationalization Variables 5697 XSI If the locale value has the form: 5698 language[_territory][.codeset] 5699 it refers to an implementation-provided locale, where settings of language, territory, and codeset 5700 are implementation-defined. 5701 LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME are 5702 defined to accept an additional field @modifier, which allows the user to select a specific instance 5703 of localization data within a single category (for example, for selecting the dictionary as opposed 5704 to the character ordering of data). The syntax for these environment variables is thus defined as: 5705 [language[_territory][.codeset][@modifier]] 5706 For example, if a user wanted to interact with the system in French, but required to sort German 5707 text files, LANG and LC_COLLATE could be defined as: 5708 LANG=Fr_FR 5709 LC_COLLATE=De_DE 5710 This could be extended to select dictionary collation (say) by use of the @modifier field; for 5711 example: 5712 LC_COLLATE=De_DE@dict 5713 5714 An implementation may support other formats. 5715 If the locale value is not recognized by the implementation, the behavior is unspecified. 5716 At runtime, these values are bound to a program's locale by calling the setlocale( ) function. 5717 Additional criteria for determining a valid locale name are implementation-defined. 5718 8.3 Other Environment Variables 5719 COLUMNS This variable shall represent a decimal integer >0 used to indicate the user's 5720 preferred width in column positions for the terminal screen or window; see 5721 Section 3.103 (on page 47). If this variable is unset or null, the implementation 5722 determines the number of columns, appropriate for the terminal or window, 5723 in an unspecified manner. When COLUMNS is set, any terminal-width 5724 information implied by TERM is overridden. Users and conforming | 5725 applications should not set COLUMNS unless they wish to override the | 5726 system selection and produce output unrelated to the terminal characteristics. 5727 Users should not need to set this variable in the environment unless there is a 5728 specific reason to override the implementation's default behavior, such as to 5729 display data in an area arbitrarily smaller than the terminal or window. 5730 XSI DATEMSK Indicates the pathname of the template file used by getdate( ). 5731 HOME The system shall initialize this variable at the time of login to be a pathname of 5732 the user's home directory. See . 5733 LINES This variable shall represent a decimal integer >0 used to indicate the user's 5734 preferred number of lines on a page or the vertical screen or window size in 5735 lines. A line in this case is a vertical measure large enough to hold the tallest 5736 character in the character set being displayed. If this variable is unset or null, 5737 the implementation determines the number of lines, appropriate for the Base Definitions, Issue 6 161 Other Environment Variables Environment Variables 5738 terminal or window (size, terminal baud rate, and so on), in an unspecified 5739 manner. When LINES is set, any terminal-height information implied by 5740 TERM is overridden. Users and conforming applications should not set LINES | 5741 unless they wish to override the system selection and produce output 5742 unrelated to the terminal characteristics. 5743 Users should not need to set this variable in the environment unless there is a 5744 specific reason to override the implementation's default behavior, such as to 5745 display data in an area arbitrarily smaller than the terminal or window. 5746 LOGNAME The system shall initialize this variable at the time of login to be the user's 5747 login name. See . For a value of LOGNAME to be portable across 5748 implementations of IEEE Std 1003.1-200x, the value should be composed of 5749 characters from the portable filename character set. 5750 XSI MSGVERB Describes which message components shall be used in writing messages by 5751 fmtmsg( ). 5752 PATH This variable shall represent the sequence of path prefixes that certain 5753 functions and utilities apply in searching for an executable file known only by | 5754 a filename. The prefixes shall be separated by a colon (':'). When a non- | 5755 zero-length prefix is applied to this filename, a slash shall be inserted between | 5756 the prefix and the filename. A zero-length prefix is a legacy feature that | 5757 indicates the current working directory. It appears as two adjacent colons | 5758 ("::"), as an initial colon preceding the rest of the list, or as a trailing colon 5759 following the rest of the list. A strictly conforming application shall use an 5760 actual pathname (such as .) to represent the current working directory in 5761 PATH. The list shall be searched from beginning to end, applying the filename | 5762 to each prefix, until an executable file with the specified name and appropriate | 5763 execution permissions is found. If the pathname being sought contains a slash, | 5764 the search through the path prefixes shall not be performed. If the pathname | 5765 begins with a slash, the specified path is resolved (see Section 4.11 (on page | 5766 98)). If PATH is unset or is set to null, the path search is implementation- 5767 defined. 5768 PWD This variable shall represent an absolute pathname of the current working 5769 directory. It shall not contain any filename components of dot or dot-dot. The 5770 value is set by the cd utility. 5771 SHELL This variable shall represent a pathname of the user's preferred command 5772 language interpreter. If this interpreter does not conform to the Shell 5773 Command Language in the Shell and Utilities volume of IEEE Std 1003.1-200x, 5774 Chapter 2, Shell Command Language, utilities may behave differently from 5775 those described in IEEE Std 1003.1-200x. 5776 TMPDIR This variable shall represent a pathname of a directory made available for 5777 programs that need a place to create temporary files. 5778 TERM This variable shall represent the terminal type for which output is to be 5779 prepared. This information is used by utilities and application programs 5780 wishing to exploit special capabilities specific to a terminal. The format and 5781 allowable values of this environment variable are unspecified. 5782 TZ This variable shall represent timezone information. The contents of the 5783 environment variable named TZ shall be used by the ctime( ), localtime( ), 5784 strftime( ), and mktime( ) functions, and by various utilities, to override the 5785 default timezone. The value of TZ has one of the two forms (spaces inserted 162 Technical Standard (2001) (Draft April 13, 2001) Environment Variables Other Environment Variables 5786 for clarity): 5787 :characters 5788 or: 5789 std offset dst offset, rule 5790 If TZ is of the first format (that is, if the first character is a colon), the 5791 characters following the colon are handled in an implementation-defined 5792 manner. 5793 The expanded format (for all TZs whose value does not have a colon as the 5794 first character) is as follows: 5795 stdoffset[dst[offset][,start[/time],end[/time]]] 5796 Where: 5797 std and dst Indicate no less than three, nor more than {TZNAME_MAX}, 5798 bytes that are the designation for the standard (std) or the 5799 alternative (dst-such as Daylight Savings Time) timezone. Only 5800 std is required; if dst is missing, then the alternative time does 5801 not apply in this locale. 5802 Each of these fields may occur in either of two formats quoted or 5803 unquoted: 5804 - In the quoted form, the first character shall be the less-than 5805 ('<') character and the last character shall be the greater- 5806 than ('>') character. All characters between these quoting 5807 characters shall be alphanumeric characters in the current 5808 locale, the plus-sign ('+') character, or the minus-sign ('-') 5809 character. The std and dst fields in this case shall not include | 5810 the quoting characters. | 5811 - In the unquoted form, all characters in these fields shall be 5812 alphabetic characters in the current locale. 5813 The interpretation of these fields is unspecified if either field is 5814 less than three bytes (except for the case when dst is missing), 5815 more than {TZNAME_MAX} bytes, or if they contain characters 5816 other than those specified. 5817 offset Indicates the value added to the local time to arrive at 5818 Coordinated Universal Time. The offset has the form: 5819 hh[:mm[:ss]] 5820 The minutes (mm) and seconds (ss) are optional. The hour (hh) 5821 shall be required and may be a single digit. The offset following 5822 std shall be required. If no offset follows dst, the alternative time 5823 is assumed to be one hour ahead of standard time. One or more 5824 digits may be used; the value is always interpreted as a decimal 5825 number. The hour shall be between zero and 24, and the minutes 5826 (and seconds)-if present-between zero and 59. The result of 5827 using values outside of this range is unspecified. If preceded by 5828 a '-', the timezone shall be east of the Prime Meridian; 5829 otherwise, it shall be west (which may be indicated by an 5830 optional preceding '+'). Base Definitions, Issue 6 163 Other Environment Variables Environment Variables 5831 rule Indicates when to change to and back from the alternative time. 5832 The rule has the form: 5833 date[/time],date[/time] 5834 where the first date describes when the change from standard to 5835 alternative time occurs and the second date describes when the 5836 change back happens. Each time field describes when, in current 5837 local time, the change to the other time is made. 5838 The format of date is one of the following: 5839 Jn The Julian day n (1 n 365). Leap days shall not be 5840 counted. That is, in all years-including leap years- 5841 February 28 is day 59 and March 1 is day 60. It is 5842 impossible to refer explicitly to the occasional February 5843 29. 5844 n The zero-based Julian day (0 n 365). Leap days shall 5845 be counted, and it is possible to refer to February 29. 5846 Mm.n.d The d'th day (0 d 6) of week n of month m of the 5847 year (1 n 5, 1 m 12, where week 5 means ``the 5848 last d day in month m'' which may occur in either the 5849 fourth or the fifth week). Week 1 is the first week in 5850 which the d'th day occurs. Day zero is Sunday. 5851 The time has the same format as offset except that no leading sign 5852 ('-' or '+') is allowed. The default, if time is not given, shall be 5853 02:00:00. | 164 Technical Standard (2001) (Draft April 13, 2001) Chapter 9 Regular Expressions 5854 5855 Regular Expressions (REs) provide a mechanism to select specific strings from a set of character 5856 strings. 5857 Regular expressions are a context-independent syntax that can represent a wide variety of 5858 character sets and character set orderings, where these character sets are interpreted according 5859 to the current locale. While many regular expressions can be interpreted differently depending 5860 on the current locale, many features, such as character class expressions, provide for contextual 5861 invariance across locales. 5862 The Basic Regular Expression (BRE) notation and construction rules in Section 9.3 (on page 167) 5863 shall apply to most utilities supporting regular expressions. Some utilities, instead, support the 5864 Extended Regular Expressions (ERE) described in Section 9.4 (on page 171); any exceptions for 5865 both cases are noted in the descriptions of the specific utilities using regular expressions. Both 5866 BREs and EREs are supported by the Regular Expression Matching interface in the System 5867 Interfaces volume of IEEE Std 1003.1-200x under regcomp( ), regexec( ), and related functions. 5868 9.1 Regular Expression Definitions 5869 For the purposes of this section, the following definitions shall apply: 5870 entire regular expression 5871 The concatenated set of one or more BREs or EREs that make up the pattern specified for 5872 string selection. 5873 matched 5874 A sequence of zero or more characters shall be said to be matched by a BRE or ERE when 5875 the characters in the sequence correspond to a sequence of characters defined by the 5876 pattern. 5877 Matching shall be based on the bit pattern used for encoding the character, not on the 5878 graphic representation of the character. This means that if a character set contains two or 5879 more encodings for a graphic symbol, or if the strings searched contain text encoded in 5880 more than one codeset, no attempt is made to search for any other representation of the 5881 encoded symbol. If that is required, the user can specify equivalence classes containing all 5882 variations of the desired graphic symbol. 5883 The search for a matching sequence starts at the beginning of a string and stops when the 5884 first sequence matching the expression is found, where first is defined to mean ``begins 5885 earliest in the string''. If the pattern permits a variable number of matching characters and 5886 thus there is more than one such sequence starting at that point, the longest such sequence 5887 is matched. For example: the BRE "bb*" matches the second to fourth characters of abbbc, 5888 and the ERE (wee|week)(knights|night) matches all ten characters of weeknights. 5889 Consistent with the whole match being the longest of the leftmost matches, each subpattern, 5890 from left to right, shall match the longest possible string. For this purpose, a null string shall 5891 be considered to be longer than no match at all. For example, matching the BRE 5892 "\(.*\).*" against "abcdef", the subexpression "(\1)" is "abcdef", and matching 5893 the BRE "\(a*\)*" against "bc", the subexpression "(\1)" is the null string. 5894 When a multi-character collating element in a bracket expression (see Section 9.3.5 (on page 5895 168)) is involved, the longest sequence shall be measured in characters consumed from the Base Definitions, Issue 6 165 Regular Expression Definitions Regular Expressions 5896 string to be matched; that is, the collating element counts not as one element, but as the 5897 number of characters it matches. 5898 BRE (ERE) matching a single character 5899 A BRE or ERE that shall match either a single character or a single collating element. 5900 Only a BRE or ERE of this type that includes a bracket expression (see Section 9.3.5 (on page 5901 168)) can match a collating element. 5902 BRE (ERE) matching multiple characters 5903 A BRE or ERE that shall match a concatenation of single characters or collating elements. 5904 Such a BRE or ERE is made up from a BRE (ERE) matching a single character and BRE (ERE) 5905 special characters. 5906 invalid 5907 This section uses the term invalid for certain constructs or conditions. Invalid REs shall 5908 cause the utility or function using the RE to generate an error condition. When invalid is not 5909 used, violations of the specified syntax or semantics for REs produce undefined results: this 5910 may entail an error, enabling an extended syntax for that RE, or using the construct in error 5911 as literal characters to be matched. For example, the BRE construct "\{1,2,3\}" does not | 5912 comply with the grammar. A conforming application cannot rely on it producing an error | 5913 nor matching the literal characters "\{1,2,3\}". 5914 9.2 Regular Expression General Requirements 5915 The requirements in this section shall apply to both basic and extended regular expressions. 5916 The use of regular expressions is generally associated with text processing. REs (BREs and EREs) 5917 operate on text strings; that is, zero or more characters followed by an end-of-string delimiter 5918 (typically NUL). Some utilities employing regular expressions limit the processing to lines; that 5919 is, zero or more characters followed by a . In the regular expression processing 5920 described in IEEE Std 1003.1-200x, the is regarded as an ordinary character and both a 5921 period and a non-matching list can match one. The Shell and Utilities volume of 5922 IEEE Std 1003.1-200x specifies within the individual descriptions of those standard utilities 5923 employing regular expressions whether they permit matching of s; if not stated 5924 otherwise, the use of literal s or any escape sequence equivalent produces undefined 5925 results. Those utilities (like grep) that do not allow s to match are responsible for 5926 eliminating any from strings before matching against the RE. The regcomp( ) function 5927 in the System Interfaces volume of IEEE Std 1003.1-200x, however, can provide support for such 5928 processing without violating the rules of this section. 5929 The interfaces specified in IEEE Std 1003.1-200x do not permit the inclusion of a NUL character 5930 in an RE or in the string to be matched. If during the operation of a standard utility a NUL is 5931 included in the text designated to be matched, that NUL may designate the end of the text string 5932 for the purposes of matching. 5933 When a standard utility or function that uses regular expressions specifies that pattern matching 5934 shall be performed without regard to the case (uppercase or lowercase) of either data or 5935 patterns, then when each character in the string is matched against the pattern, not only the 5936 character, but also its case counterpart (if any), shall be matched. This definition of case- 5937 insensitive processing is intended to allow matching of multi-character collating elements as 5938 well as characters, as each character in the string is matched using both its cases. For example, in 5939 a locale where "Ch" is a multi-character collating element and where a matching list expression 5940 matches such elements, the RE "[[.Ch.]]" when matched against the string "char", is in 166 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Regular Expression General Requirements 5941 reality matched against "ch", "Ch", "cH", and "CH". 5942 The implementation shall support any regular expression that does not exceed 256 bytes in 5943 length. 5944 9.3 Basic Regular Expressions 5945 9.3.1 BREs Matching a Single Character or Collating Element 5946 A BRE ordinary character, a special character preceded by a backslash or a period, shall match a 5947 single character. A bracket expression shall match a single character or a single collating 5948 element. 5949 9.3.2 BRE Ordinary Characters 5950 An ordinary character is a BRE that matches itself: any character in the supported character set, 5951 except for the BRE special characters listed in Section 9.3.3. 5952 The interpretation of an ordinary character preceded by a backslash ('\') is undefined, except 5953 for: 5954 * The characters ')', '(', '{', and '}' 5955 * The digits 1 to 9 inclusive (see Section 9.3.6 (on page 170)) 5956 * A character inside a bracket expression 5957 9.3.3 BRE Special Characters 5958 A BRE special character has special properties in certain contexts. Outside those contexts, or when 5959 preceded by a backslash, such a character is a BRE that matches the special character itself. The 5960 BRE special characters and the contexts in which they have their special meaning are as follows: 5961 . [ \ The period, left-bracket, and backslash shall be special except when used in a bracket 5962 expression (see Section 9.3.5 (on page 168)). An expression containing a '[' that is not 5963 preceded by a backslash and is not part of a bracket expression produces undefined 5964 results. 5965 * The asterisk shall be special except when used: 5966 * In a bracket expression 5967 * As the first character of an entire BRE (after an initial ' ', if any) 5968 * As the first character of a subexpression (after an initial ' ', if any); see Section 5969 9.3.6 (on page 170) 5970 ^ The circumflex shall be special when used as: 5971 * An anchor (see Section 9.3.8 (on page 171)) 5972 * The first character of a bracket expression (see Section 9.3.5 (on page 168)) 5973 $ The dollar sign shall be special when used as an anchor. Base Definitions, Issue 6 167 Basic Regular Expressions Regular Expressions 5974 9.3.4 Periods in BREs 5975 A period ('.'), when used outside a bracket expression, is a BRE that shall match any character 5976 in the supported character set except NUL. 5977 9.3.5 RE Bracket Expression 5978 A bracket expression (an expression enclosed in square brackets, "[ ]") is an RE that shall match | 5979 a single collating element contained in the non-empty set of collating elements represented by | 5980 the bracket expression. 5981 The following rules and definitions apply to bracket expressions: 5982 1. A bracket expression is either a matching list expression or a non-matching list expression. It 5983 consists of one or more expressions: collating elements, collating symbols, equivalence 5984 classes, character classes, or range expressions. The right-bracket (']') shall lose its special 5985 meaning and represents itself in a bracket expression if it occurs first in the list (after an 5986 initial circumflex (' '), if any). Otherwise, it shall terminate the bracket expression, unless 5987 it appears in a collating symbol (such as "[.].]") or is the ending right-bracket for a 5988 collating symbol, equivalence class, or character class. The special characters '.', '*', 5989 '[', and '\' (period, asterisk, left-bracket, and backslash, respectively) shall lose their 5990 special meaning within a bracket expression. 5991 The character sequences "[.", "[=", and "[:" (left-bracket followed by a period, equals- 5992 sign, or colon) shall be special inside a bracket expression and are used to delimit collating 5993 symbols, equivalence class expressions, and character class expressions. These symbols 5994 shall be followed by a valid expression and the matching terminating sequence ".]", 5995 "=]", or ":]", as described in the following items. 5996 2. A matching list expression specifies a list that shall match any single-character collating | 5997 element in any of the expressions represented in the list. The first character in the list shall | 5998 not be the circumflex; for example, "[abc]" is an RE that matches any of the characters | 5999 'a', 'b', or 'c'. It is unspecified whether a matching list expression matches a multi- 6000 character collating element that is matched by one of the expressions. 6001 3. A non-matching list expression begins with a circumflex (' '), and specifies a list that shall | 6002 match any single-character collating element except for the expressions represented in the | 6003 list after the leading circumflex. For example, "[ abc]" is an RE that matches any | 6004 character except the characters 'a', 'b', or 'c'. It is unspecified whether a non-matching 6005 list expression matches a multi-character collating element that is not matched by any of 6006 the expressions. The circumflex shall have this special meaning only when it occurs first in 6007 the list, immediately following the left-bracket. 6008 4. A collating symbol is a collating element enclosed within bracket-period ("[." and ".]") 6009 delimiters. Collating elements are defined as described in Section 7.3.2.4 (on page 133). | 6010 Conforming applications shall represent multi-character collating elements as collating | 6011 symbols when it is necessary to distinguish them from a list of the individual characters 6012 that make up the multi-character collating element. For example, if the string "ch" is a 6013 collating element defined using the line: 6014 collating-element from "" 6015 in the locale definition, the expression "[[.ch.]]" shall be treated as an RE containing 6016 the collating symbol 'ch', while "[ch]" shall be treated as an RE matching 'c' or 'h'. 6017 Collating symbols are recognized only inside bracket expressions. If the string is not a 6018 collating element in the current locale, the expression is invalid. 168 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Basic Regular Expressions 6019 5. An equivalence class expression shall represent the set of collating elements belonging to an 6020 equivalence class, as described in Section 7.3.2.4 (on page 133). Only primary equivalence 6021 classes shall be recognized. The class shall be expressed by enclosing any one of the 6022 collating elements in the equivalence class within bracket-equal ("[=" and "=]") 6023 delimiters. For example, if 'a', 'à', and 'â' belong to the same equivalence class, then 6024 "[[=a=]b]", "[[=à=]b]", and "[[=â=]b]" are each equivalent to "[aàâb]". If the 6025 collating element does not belong to an equivalence class, the equivalence class expression 6026 shall be treated as a collating symbol. 6027 6. A character class expression shall represent the union of two sets: | 6028 a. The set of single-character collating elements whose characters belong to the | 6029 character class, as defined in the LC_CTYPE category in the current locale. | 6030 b. An unspecified set of multi-character collating elements. | 6031 All character classes specified in the current locale shall be recognized. A character class | 6032 expression is expressed as a character class name enclosed within bracket-colon ("[:" and | 6033 ":]") delimiters. 6034 The following character class expressions shall be supported in all locales: 6035 [:alnum:] [:cntrl:] [:lower:] [:space:] 6036 [:alpha:] [:digit:] [:print:] [:upper:] 6037 [:blank:] [:graph:] [:punct:] [:xdigit:] 6038 XSI In addition, character class expressions of the form: 6039 [:name:] 6040 are recognized in those locales where the name keyword has been given a charclass 6041 definition in the LC_CTYPE category. 6042 7. In the POSIX locale, a range expression represents the set of collating elements that fall 6043 between two elements in the collation sequence, inclusive. In other locales, a range 6044 expression has unspecified behavior: strictly conforming applications shall not rely on 6045 whether the range expression is valid, or on the set of collating elements matched. A range 6046 expression shall be expressed as the starting point and the ending point separated by a 6047 hyphen ('-'). 6048 In the following, all examples assume the POSIX locale. 6049 The starting range point and the ending range point shall be a collating element or 6050 collating symbol. An equivalence class expression used as a starting or ending point of a 6051 range expression produces unspecified results. An equivalence class can be used portably 6052 within a bracket expression, but only outside the range. If the represented set of collating 6053 elements is empty, it is unspecified whether the expression matches nothing, or is treated 6054 as invalid. 6055 The interpretation of range expressions where the ending range point is also the starting 6056 range point of a subsequent range expression (for example, "[a-m-o]") is undefined. 6057 The hyphen character shall be treated as itself if it occurs first (after an initial ' ', if any) 6058 or last in the list, or as an ending range point in a range expression. As examples, the 6059 expressions "[-ac]" and "[ac-]" are equivalent and match any of the characters 'a', 6060 'c', or '-'; "[ -ac]" and "[ ac-]" are equivalent and match any characters except 6061 'a', 'c', or '-'; the expression "[%- -]" matches any of the characters between '%' and 6062 '-' inclusive; the expression "[- -@]" matches any of the characters between '-' and 6063 '@' inclusive; and the expression "[a- -@]" is either invalid or equivalent to '@', Base Definitions, Issue 6 169 Basic Regular Expressions Regular Expressions 6064 because the letter 'a' follows the symbol '-' in the POSIX locale. To use a hyphen as the 6065 starting range point, it shall either come first in the bracket expression or be specified as a 6066 collating symbol; for example, "[][.-.]-0]", which matches either a right bracket or 6067 any character or collating element that collates between hyphen and 0, inclusive. 6068 If a bracket expression specifies both '-' and ']', the ']' shall be placed first (after the 6069 ' ', if any) and the '-' last within the bracket expression. 6070 9.3.6 BREs Matching Multiple Characters 6071 The following rules can be used to construct BREs matching multiple characters from BREs 6072 matching a single character: 6073 1. The concatenation of BREs shall match the concatenation of the strings matched by each 6074 component of the BRE. 6075 2. A subexpression can be defined within a BRE by enclosing it between the character pairs 6076 "\(" and "\)". Such a subexpression shall match whatever it would have matched 6077 without the "\(" and "\)", except that anchoring within subexpressions is optional 6078 behavior; see Section 9.3.8 (on page 171). Subexpressions can be arbitrarily nested. 6079 3. The back-reference expression '\n' shall match the same (possibly empty) string of | 6080 characters as was matched by a subexpression enclosed between "\(" and "\)" 6081 preceding the '\n'. The character 'n' shall be a digit from 1 through 9, specifying the 6082 nth subexpression (the one that begins with the nth "\(" from the beginning of the 6083 pattern and ends with the corresponding paired "\)"). The expression is invalid if less 6084 than n subexpressions precede the '\n'. For example, the expression "\(.*\)\1$" 6085 matches a line consisting of two adjacent appearances of the same string, and the 6086 expression "\(a\)*\1" fails to match 'a'. When the referenced subexpression matched 6087 more than one string, the back-referenced expression shall refer to the last matched string. 6088 If the subexpression referenced by the back-reference matches more than one string 6089 because of an asterisk ('*') or an interval expression (see item (5)), the back-reference 6090 shall match the last (rightmost) of these strings. 6091 4. When a BRE matching a single character, a subexpression, or a back-reference is followed 6092 by the special character asterisk ('*'), together with that asterisk it shall match what zero 6093 or more consecutive occurrences of the BRE would match. For example, "[ab]*" and 6094 "[ab][ab]" are equivalent when matching the string "ab". 6095 5. When a BRE matching a single character, a subexpression, or a back-reference is followed 6096 by an interval expression of the format "\{m\}", "\{m,\}", or "\{m,n\}", together with 6097 that interval expression it shall match what repeated consecutive occurrences of the BRE 6098 would match. The values of m and n are decimal integers in the range 0 6099 m n {RE_DUP_MAX}, where m specifies the exact or minimum number of occurrences 6100 and n specifies the maximum number of occurrences. The expression "\{m\}" shall match 6101 exactly m occurrences of the preceding BRE, "\{m,\}" shall match at least m occurrences, 6102 and "\{m,n\}" shall match any number of occurrences between m and n, inclusive. 6103 For example, in the string "abababccccccd" the BRE "c\{3\}" is matched by 6104 characters '7' to '9', the BRE "\(ab\)\{4,\}" is not matched at all, and the BRE 6105 "c\{1,3\}d" is matched by characters ten to thirteen. 6106 The behavior of multiple adjacent duplication symbols ('*' and intervals) produces undefined 6107 results. 6108 A subexpression repeated by an asterisk ('*') or an interval expression shall not match a null 6109 expression unless this is the only match for the repetition or it is necessary to satisfy the exact or 170 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Basic Regular Expressions 6110 minimum number of occurrences for the interval expression. 6111 9.3.7 BRE Precedence 6112 The order of precedence shall be as shown in the following table: ___________________________________________________________ 6113 _ BRE Precedence (from high to low) __________________________________________________________ 6114 Collation-related bracket symbols [==] [::] [..] 6115 Escaped characters \ 6116 Bracket expression [] 6117 Subexpressions/back-references \(\) \n 6118 Single-character-BRE duplication * \{m,n\} 6119 Concatenation 6120 _ Anchoring ^ $ __________________________________________________________ 6121 9.3.8 BRE Expression Anchoring 6122 A BRE can be limited to matching strings that begin or end a line; this is called anchoring. The 6123 circumflex and dollar sign special characters shall be considered BRE anchors in the following 6124 contexts: 6125 1. A circumflex (' ') shall be an anchor when used as the first character of an entire BRE. 6126 The implementation may treat the circumflex as an anchor when used as the first character 6127 of a subexpression. The circumflex shall anchor the expression (or optionally 6128 subexpression) to the beginning of a string; only sequences starting at the first character of 6129 a string shall be matched by the BRE. For example, the BRE " ab" matches "ab" in the 6130 string "abcdef", but fails to match in the string "cdefab". The BRE "\( ab\)" may 6131 match the former string. A portable BRE shall escape a leading circumflex in a 6132 subexpression to match a literal circumflex. 6133 2. A dollar sign ('$') shall be an anchor when used as the last character of an entire BRE. 6134 The implementation may treat a dollar sign as an anchor when used as the last character of 6135 a subexpression. The dollar sign shall anchor the expression (or optionally subexpression) 6136 to the end of the string being matched; the dollar sign can be said to match the end-of- 6137 string following the last character. 6138 3. A BRE anchored by both ' ' and '$' shall match only an entire string. For example, the 6139 BRE " abcdef$" matches strings consisting only of "abcdef". 6140 9.4 Extended Regular Expressions 6141 The extended regular expression (ERE) notation and construction rules shall apply to utilities 6142 defined as using extended regular expressions; any exceptions to the following rules are noted in 6143 the descriptions of the specific utilities using EREs. Base Definitions, Issue 6 171 Extended Regular Expressions Regular Expressions 6144 9.4.1 EREs Matching a Single Character or Collating Element 6145 An ERE ordinary character, a special character preceded by a backslash, or a period shall match 6146 a single character. A bracket expression shall match a single character or a single collating 6147 element. An ERE matching a single character enclosed in parentheses shall match the same as the 6148 ERE without parentheses would have matched. 6149 9.4.2 ERE Ordinary Characters 6150 An ordinary character is an ERE that matches itself. An ordinary character is any character in the 6151 supported character set, except for the ERE special characters listed in Section 9.4.3. The 6152 interpretation of an ordinary character preceded by a backslash ('\') is undefined. 6153 9.4.3 ERE Special Characters 6154 An ERE special character has special properties in certain contexts. Outside those contexts, or 6155 when preceded by a backslash, such a character shall be an ERE that matches the special 6156 character itself. The extended regular expression special characters and the contexts in which 6157 they shall have their special meaning are as follows: 6158 . [ \ ( The period, left-bracket, backslash, and left-parenthesis shall be special except when 6159 used in a bracket expression (see Section 9.3.5 (on page 168)). Outside a bracket 6160 expression, a left-parenthesis immediately followed by a right-parenthesis produces 6161 undefined results. 6162 ) The right-parenthesis shall be special when matched with a preceding left-parenthesis, 6163 both outside a bracket expression. 6164 * + ? { The asterisk, plus-sign, question-mark, and left-brace shall be special except when used 6165 in a bracket expression (see Section 9.3.5 (on page 168)). Any of the following uses 6166 produce undefined results: 6167 * If these characters appear first in an ERE, or immediately following a vertical-line, 6168 circumflex, or left-parenthesis 6169 * If a left-brace is not part of a valid interval expression (see Section 9.4.6 (on page 6170 173)) 6171 | The vertical-line is special except when used in a bracket expression (see Section 9.3.5 6172 (on page 168)). A vertical-line appearing first or last in an ERE, or immediately 6173 following a vertical-line or a left-parenthesis, or immediately preceding a right- 6174 parenthesis, produces undefined results. 6175 ^ The circumflex shall be special when used as: 6176 * An anchor (see Section 9.4.9 (on page 174)) 6177 * The first character of a bracket expression (see Section 9.3.5 (on page 168)) 6178 $ The dollar sign shall be special when used as an anchor. 172 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Extended Regular Expressions 6179 9.4.4 Periods in EREs 6180 A period ('.'), when used outside a bracket expression, is an ERE that shall match any 6181 character in the supported character set except NUL. 6182 9.4.5 ERE Bracket Expression 6183 The rules for ERE Bracket Expressions are the same as for Basic Regular Expressions; see Section 6184 9.3.5 (on page 168). 6185 9.4.6 EREs Matching Multiple Characters 6186 The following rules shall be used to construct EREs matching multiple characters from EREs 6187 matching a single character: 6188 1. A concatenation of EREs shall match the concatenation of the character sequences matched 6189 by each component of the ERE. A concatenation of EREs enclosed in parentheses shall 6190 match whatever the concatenation without the parentheses matches. For example, both the 6191 ERE "cd" and the ERE "(cd)" are matched by the third and fourth character of the string 6192 "abcdefabcdef". 6193 2. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6194 the special character plus-sign ('+'), together with that plus-sign it shall match what one 6195 or more consecutive occurrences of the ERE would match. For example, the ERE 6196 "b+(bc)" matches the fourth to seventh characters in the string "acabbbcde". And, 6197 "[ab]+" and "[ab][ab]*" are equivalent. 6198 3. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6199 the special character asterisk ('*'), together with that asterisk it shall match what zero or 6200 more consecutive occurrences of the ERE would match. For example, the ERE "b*c" 6201 matches the first character in the string "cabbbcde", and the ERE "b*cd" matches the 6202 third to seventh characters in the string "cabbbcdebbbbbbcdbc". And, "[ab]*" and 6203 [ab][ab] are equivalent when matching the string "ab". 6204 4. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6205 the special character question-mark ('?'), together with that question-mark it shall match 6206 what zero or one consecutive occurrences of the ERE would match. For example, the ERE 6207 "b?c" matches the second character in the string "acabbbcde". 6208 5. When an ERE matching a single character or an ERE enclosed in parentheses is followed by 6209 an interval expression of the format "{m}", "{m,}", or "{m,n}", together with that 6210 interval expression it shall match what repeated consecutive occurrences of the ERE would 6211 match. The values of m and n are decimal integers in the range 0 m n {RE_DUP_MAX}, 6212 where m specifies the exact or minimum number of occurrences and n specifies the 6213 maximum number of occurrences. The expression "{m}" matches exactly m occurrences 6214 of the preceding ERE, "{m,}" matches at least m occurrences, and "{m,n}" matches any 6215 number of occurrences between m and n, inclusive. 6216 For example, in the string "abababccccccd" the ERE "c{3}" is matched by characters 6217 '7' to '9' and the ERE "(ab){2,}" is matched by characters one to six. 6218 The behavior of multiple adjacent duplication symbols ('+', '*', '?', and intervals) produces 6219 undefined results. 6220 An ERE matching a single character repeated by an '*', '?', or an interval expression shall not 6221 match a null expression unless this is the only match for the repetition or it is necessary to satisfy 6222 the exact or minimum number of occurrences for the interval expression. Base Definitions, Issue 6 173 Extended Regular Expressions Regular Expressions 6223 9.4.7 ERE Alternation 6224 Two EREs separated by the special character vertical-line ('|') shall match a string that is 6225 matched by either. For example, the ERE "a((bc)|d)" matches the string "abc" and the string 6226 "ad". Single characters, or expressions matching single characters, separated by the vertical bar 6227 and enclosed in parentheses, shall be treated as an ERE matching a single character. 6228 9.4.8 ERE Precedence 6229 The order of precedence shall be as shown in the following table: ___________________________________________________________ 6230 _ ERE Precedence (from high to low) __________________________________________________________ 6231 Collation-related bracket symbols [==] [::] [..] 6232 Escaped characters \ 6233 Bracket expression [] 6234 Grouping () 6235 Single-character-ERE duplication * + ? {m,n} 6236 Concatenation 6237 Anchoring ^ $ 6238 _ Alternation | __________________________________________________________ 6239 For example, the ERE "abba|cde" matches either the string "abba" or the string "cde" 6240 (rather than the string "abbade" or "abbcde", because concatenation has a higher order of 6241 precedence than alternation). 6242 9.4.9 ERE Expression Anchoring 6243 An ERE can be limited to matching strings that begin or end a line; this is called anchoring. The 6244 circumflex and dollar sign special characters shall be considered ERE anchors when used 6245 anywhere outside a bracket expression. This shall have the following effects: 6246 1. A circumflex (' ') outside a bracket expression shall anchor the expression or 6247 subexpression it begins to the beginning of a string; such an expression or subexpression 6248 can match only a sequence starting at the first character of a string. For example, the EREs 6249 " ab" and "( ab)" match "ab" in the string "abcdef", but fail to match in the string 6250 "cdefab", and the ERE "a b" is valid, but can never match because the 'a' prevents the 6251 expression " b" from matching starting at the first character. 6252 2. A dollar sign ('$') outside a bracket expression shall anchor the expression or 6253 subexpression it ends to the end of a string; such an expression or subexpression can 6254 match only a sequence ending at the last character of a string. For example, the EREs 6255 "ef$" and "(ef$)" match "ef" in the string "abcdef", but fail to match in the string 6256 "cdefab", and the ERE "e$f" is valid, but can never match because the 'f' prevents the 6257 expression "e$" from matching ending at the last character. 174 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Regular Expression Grammar 6258 9.5 Regular Expression Grammar 6259 Grammars describing the syntax of both basic and extended regular expressions are presented in 6260 this section. The grammar takes precedence over the text. See the Shell and Utilities volume of 6261 IEEE Std 1003.1-200x, Section 1.10, Grammar Conventions. 6262 9.5.1 BRE/ERE Grammar Lexical Conventions 6263 The lexical conventions for regular expressions are as described in this section. 6264 Except as noted, the longest possible token or delimiter beginning at a given point is recognized. 6265 The following tokens are processed (in addition to those string constants shown in the 6266 grammar): 6267 COLL_ELEM_SINGLE | 6268 Any single-character collating element, unless it is a META_CHAR. | 6269 COLL_ELEM_MULTI Any multi-character collating element. 6270 BACKREF Applicable only to basic regular expressions. The character string 6271 consisting of '\' followed by a single-digit numeral, '1' to '9'. 6272 DUP_COUNT Represents a numeric constant. It shall be an integer in the range 0 6273 DUP_COUNT {RE_DUP_MAX}. This token is only recognized when 6274 the context of the grammar requires it. At all other times, digits not 6275 preceded by '\' are treated as ORD_CHAR. 6276 META_CHAR One of the characters: 6277 ^ When found first in a bracket expression 6278 - When found anywhere but first (after an initial ' ', if any) or 6279 last in a bracket expression, or as the ending range point in a 6280 range expression 6281 ] When found anywhere but first (after an initial ' ', if any) in a 6282 bracket expression 6283 L_ANCHOR Applicable only to basic regular expressions. The character ' ' when it 6284 appears as the first character of a basic regular expression and when not 6285 QUOTED_CHAR. The ' ' may be recognized as an anchor elsewhere; 6286 see Section 9.3.8 (on page 171). 6287 ORD_CHAR A character, other than one of the special characters in SPEC_CHAR. 6288 QUOTED_CHAR In a BRE, one of the character sequences: 6289 \ \. \* \[ \$ \\ 6290 In an ERE, one of the character sequences: 6291 \ \. \[ \$ \( \) \| 6292 \* \+ \? \{ \\ 6293 R_ANCHOR (Applicable only to basic regular expressions.) The character '$' when it 6294 appears as the last character of a basic regular expression and when not 6295 QUOTED_CHAR. The '$' may be recognized as an anchor elsewhere; 6296 see Section 9.3.8 (on page 171). 6297 SPEC_CHAR For basic regular expressions, one of the following special characters: Base Definitions, Issue 6 175 Regular Expression Grammar Regular Expressions 6298 . Anywhere outside bracket expressions 6299 \ Anywhere outside bracket expressions 6300 [ Anywhere outside bracket expressions 6301 ^ When used as an anchor (see Section 9.3.8 (on page 171)) or 6302 when first in a bracket expression 6303 $ When used as an anchor 6304 * Anywhere except first in an entire RE, anywhere in a bracket 6305 expression, directly following "\(", directly following an 6306 anchoring ' ' 6307 For extended regular expressions, shall be one of the following special 6308 characters found anywhere outside bracket expressions: 6309 ^ . [ $ ( ) | 6310 * + ? { \ 6311 (The close-parenthesis shall be considered special in this context only if 6312 matched with a preceding open-parenthesis.) 6313 9.5.2 RE and Bracket Expression Grammar 6314 This section presents the grammar for basic regular expressions, including the bracket 6315 expression grammar that is common to both BREs and EREs. 6316 %token ORD_CHAR QUOTED_CHAR DUP_COUNT 6317 %token BACKREF L_ANCHOR R_ANCHOR 6318 %token Back_open_paren Back_close_paren 6319 /* '\(' '\)' */ 6320 %token Back_open_brace Back_close_brace 6321 /* '\{' '\}' */ 6322 /* The following tokens are for the Bracket Expression 6323 grammar common to both REs and EREs. */ 6324 %token COLL_ELEM_SINGLE COLL_ELEM_MULTI META_CHAR 6325 %token Open_equal Equal_close Open_dot Dot_close Open_colon Colon_close 6326 /* '[=' '=]' '[.' '.]' '[:' ':]' */ 6327 %token class_name 6328 /* class_name is a keyword to the LC_CTYPE locale category */ 6329 /* (representing a character class) in the current locale */ 6330 /* and is only recognized between [: and :] */ 6331 %start basic_reg_exp 6332 %% 6333 /* -------------------------------------------- 6334 Basic Regular Expression 6335 -------------------------------------------- 6336 */ 6337 basic_reg_exp : RE_expression 6338 | L_ANCHOR 6339 | R_ANCHOR 176 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Regular Expression Grammar 6340 | L_ANCHOR R_ANCHOR 6341 | L_ANCHOR RE_expression 6342 | RE_expression R_ANCHOR 6343 | L_ANCHOR RE_expression R_ANCHOR 6344 ; 6345 RE_expression : simple_RE 6346 | RE_expression simple_RE 6347 ; 6348 simple_RE : nondupl_RE 6349 | nondupl_RE RE_dupl_symbol 6350 ; 6351 nondupl_RE : one_char_or_coll_elem_RE 6352 | Back_open_paren RE_expression Back_close_paren 6353 | BACKREF 6354 ; 6355 one_char_or_coll_elem_RE : ORD_CHAR 6356 | QUOTED_CHAR 6357 | '.' 6358 | bracket_expression 6359 ; 6360 RE_dupl_symbol : '*' 6361 | Back_open_brace DUP_COUNT Back_close_brace 6362 | Back_open_brace DUP_COUNT ',' Back_close_brace 6363 | Back_open_brace DUP_COUNT ',' DUP_COUNT Back_close_brace 6364 ; 6365 /* -------------------------------------------- 6366 Bracket Expression 6367 ------------------------------------------- 6368 */ 6369 bracket_expression : '[' matching_list ']' 6370 | '[' nonmatching_list ']' 6371 ; 6372 matching_list : bracket_list 6373 ; 6374 nonmatching_list : ' ' bracket_list 6375 ; 6376 bracket_list : follow_list 6377 | follow_list '-' 6378 ; 6379 follow_list : expression_term 6380 | follow_list expression_term 6381 ; 6382 expression_term : single_expression 6383 | range_expression 6384 ; 6385 single_expression : end_range 6386 | character_class 6387 | equivalence_class 6388 ; 6389 range_expression : start_range end_range 6390 | start_range '-' 6391 ; Base Definitions, Issue 6 177 Regular Expression Grammar Regular Expressions 6392 start_range : end_range '-' 6393 ; 6394 end_range : COLL_ELEM_SINGLE 6395 | collating_symbol 6396 ; 6397 collating_symbol : Open_dot COLL_ELEM_SINGLE Dot_close 6398 | Open_dot COLL_ELEM_MULTI Dot_close 6399 | Open_dot META_CHAR Dot_close 6400 ; 6401 equivalence_class : Open_equal COLL_ELEM_SINGLE Equal_close 6402 | Open_equal COLL_ELEM_MULTI Equal_close 6403 ; 6404 character_class : Open_colon class_name Colon_close 6405 ; 6406 The BRE grammar does not permit L_ANCHOR or R_ANCHOR inside "\(" and "\)" (which 6407 implies that ' ' and '$' are ordinary characters). This reflects the semantic limits on the 6408 application, as noted in Section 9.3.8 (on page 171). Implementations are permitted to extend the 6409 language to interpret ' ' and '$' as anchors in these locations, and as such, conforming | 6410 applications cannot use unescaped ' ' and '$' in positions inside "\(" and "\)" that might | 6411 be interpreted as anchors. 6412 9.5.3 ERE Grammar 6413 This section presents the grammar for extended regular expressions, excluding the bracket 6414 expression grammar. 6415 Note: The bracket expression grammar and the associated %token lines are identical between BREs 6416 and EREs. It has been omitted from the ERE section to avoid unnecessary editorial duplication. 6417 %token ORD_CHAR QUOTED_CHAR DUP_COUNT 6418 %start extended_reg_exp 6419 %% 6420 /* -------------------------------------------- 6421 Extended Regular Expression 6422 -------------------------------------------- 6423 */ 6424 extended_reg_exp : ERE_branch 6425 | extended_reg_exp '|' ERE_branch 6426 ; 6427 ERE_branch : ERE_expression 6428 | ERE_branch ERE_expression 6429 ; 6430 ERE_expression : one_char_or_coll_elem_ERE 6431 | ' ' 6432 | '$' 6433 | '(' extended_reg_exp ')' 6434 | ERE_expression ERE_dupl_symbol 6435 ; 6436 one_char_or_coll_elem_ERE : ORD_CHAR 6437 | QUOTED_CHAR 6438 | '.' 6439 | bracket_expression 6440 ; 178 Technical Standard (2001) (Draft April 13, 2001) Regular Expressions Regular Expression Grammar 6441 ERE_dupl_symbol : '*' 6442 | '+' 6443 | '?' 6444 | '{' DUP_COUNT '}' 6445 | '{' DUP_COUNT ',' '}' 6446 | '{' DUP_COUNT ',' DUP_COUNT '}' 6447 ; 6448 The ERE grammar does not permit several constructs that previous sections specify as having 6449 undefined results: 6450 * ORD_CHAR preceded by '\' 6451 * One or more ERE_dupl_symbols appearing first in an ERE, or immediately following '|', 6452 ' ', or '(' 6453 * '{' not part of a valid ERE_dupl_symbol 6454 * '|' appearing first or last in an ERE, or immediately following '|' or '(', or immediately 6455 preceding ')' 6456 Implementations are permitted to extend the language to allow these. Conforming applications | 6457 cannot use such constructs. | Base Definitions, Issue 6 179 Regular Expressions 6458 | 180 Technical Standard (2001) (Draft April 13, 2001) Chapter 10 Directory Structure and Devices 6459 6460 10.1 Directory Structure and Files 6461 The following directories shall exist on conforming systems and conforming applications shall | 6462 make use of them only as described. Strictly conforming applications shall not assume the | 6463 ability to create files in any of these directories, unless specified below. 6464 / The root directory. 6465 /dev Contains /dev/console, /dev/null, and /dev/tty, described below. 6466 The following directory shall exist on conforming systems and shall be used as described. 6467 /tmp A directory made available for programs that need a place to create temporary | 6468 files. Applications shall be allowed to create files in this directory, but shall not | 6469 assume that such files are preserved between invocations of the application. 6470 The following files shall exist on conforming systems and shall be both readable and writable. 6471 /dev/null An infinite data source and data sink. Data written to /dev/null shall be discarded. 6472 Reads from /dev/null shall always return end-of-file (EOF). 6473 /dev/tty In each process, a synonym for the controlling terminal associated with the process 6474 group of that process, if any. It is useful for programs or shell procedures that wish 6475 to be sure of writing messages to or reading data from the terminal no matter how 6476 output has been redirected. It can also be used for programs that demand the name 6477 of a file for output, when typed output is desired and it is tiresome to find out 6478 what terminal is currently in use. 6479 The following file shall exist on conforming systems and need not be readable or writable: 6480 /dev/console The /dev/console file is a generic name given to the system console (see Section | 6481 3.382 (on page 85)). It is usually linked to an implementation-defined special file. It | 6482 shall provide an interface to the system console conforming to the requirements of | 6483 the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal | 6484 Interface. | 6485 10.2 Output Devices and Terminal Types 6486 The utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x historically have been 6487 implemented on a wide range of terminal types, but a conforming implementation need not 6488 support all features of all utilities on every conceivable terminal. IEEE Std 1003.1-200x states 6489 which features are optional for certain classes of terminals in the individual utility description 6490 sections. The implementation shall document which terminal types it supports and which of 6491 these features and utilities are not supported by each terminal. 6492 When a feature or utility is not supported on a specific terminal type, as allowed by 6493 IEEE Std 1003.1-200x, and the implementation considers such a condition to be an error 6494 preventing use of the feature or utility, the implementation shall indicate such conditions 6495 through diagnostic messages or exit status values or both (as appropriate to the specific utility 6496 description) that inform the user that the terminal type lacks the appropriate capability. Base Definitions, Issue 6 181 Output Devices and Terminal Types Directory Structure and Devices 6497 IEEE Std 1003.1-200x uses a notational convention based on historical practice that identifies 6498 some of the control characters defined in Section 7.3.1 (on page 122) in a manner easily 6499 remembered by users on many terminals. The correspondence between this ``-char'' 6500 notation and the actual control characters is shown in the following table. When 6501 IEEE Std 1003.1-200x refers to a character by its - name, it is referring to the actual 6502 control character shown in the Value column of the table, which is not necessarily the exact 6503 control key sequence on all terminals. Some terminals have keyboards that do not allow the 6504 direct transmission of all the non-alphanumeric characters shown. In such cases, the system 6505 documentation shall describe which data sequences transmitted by the terminal are interpreted 6506 by the system as representing the special characters. 6507 Table 10-1 Control Character Names ____________________________________________________________________________________ 6508 _ Name Value Symbolic Name Name Value Symbolic Name ___________________________________________________________________________________ 6509 -A -Q 6510 -B -R 6511 -C -S 6512 -D -T 6513 -E -U 6514 -F -V 6515 -G -W 6516 -H -X 6517 -I -Y 6518 -J -Z 6519 -K -[ 6520 -L -\ 6521 -M -] 6522 -N - 6523 -O -_ 6524 _ -P -? ___________________________________________________________________________________ 6525 Note: The notation uses uppercase letters for arbitrary editorial reasons. There is no implication that 6526 the keystrokes represent control-shift-letter sequences. | 182 Technical Standard (2001) (Draft April 13, 2001) Chapter 11 General Terminal Interface 6527 6528 This chapter describes a general terminal interface that shall be provided. It shall be supported 6529 on any asynchronous communications ports if the implementation provides them. It is 6530 implementation-defined whether it supports network connections or synchronous ports, or 6531 both. 6532 11.1 Interface Characteristics 6533 11.1.1 Opening a Terminal Device File 6534 When a terminal device file is opened, it normally causes the thread to wait until a connection is 6535 established. In practice, application programs seldom open these files; they are opened by 6536 special programs and become an application's standard input, output, and error files. 6537 As described in open( ), opening a terminal device file with the O_NONBLOCK flag clear shall 6538 cause the thread to block until the terminal device is ready and available. If CLOCAL mode is 6539 not set, this means blocking until a connection is established. If CLOCAL mode is set in the 6540 terminal, or the O_NONBLOCK flag is specified in the open( ), the open( ) function shall return a 6541 file descriptor without waiting for a connection to be established. 6542 11.1.2 Process Groups 6543 A terminal may have a foreground process group associated with it. This foreground process 6544 group plays a special role in handling signal-generating input characters, as discussed in Section 6545 11.1.9 (on page 187). 6546 A command interpreter process supporting job control can allocate the terminal to different jobs, 6547 or process groups, by placing related processes in a single process group and associating this 6548 process group with the terminal. A terminal's foreground process group may be set or examined 6549 by a process, assuming the permission requirements are met; see tcgetpgrp( ) and tcsetpgrp( ). The 6550 terminal interface aids in this allocation by restricting access to the terminal by processes that are 6551 not in the current process group; see Section 11.1.4 (on page 184). 6552 When there is no longer any process whose process ID or process group ID matches the process 6553 group ID of the foreground process group, the terminal shall have no foreground process group. 6554 It is unspecified whether the terminal has a foreground process group when there is a process 6555 whose process ID matches the foreground process ID, but whose process group ID does not. No 6556 actions defined in IEEE Std 1003.1-200x, other than allocation of a controlling terminal or a 6557 successful call to tcsetpgrp( ), cause a process group to become the foreground process group of 6558 the terminal. Base Definitions, Issue 6 183 Interface Characteristics General Terminal Interface 6559 11.1.3 The Controlling Terminal 6560 A terminal may belong to a process as its controlling terminal. Each process of a session that has 6561 a controlling terminal has the same controlling terminal. A terminal may be the controlling 6562 terminal for at most one session. The controlling terminal for a session is allocated by the session 6563 leader in an implementation-defined manner. If a session leader has no controlling terminal, and 6564 opens a terminal device file that is not already associated with a session without using the 6565 O_NOCTTY option (see open( )), it is implementation-defined whether the terminal becomes the 6566 controlling terminal of the session leader. If a process which is not a session leader opens a 6567 terminal file, or the O_NOCTTY option is used on open( ), then that terminal shall not become 6568 the controlling terminal of the calling process. When a controlling terminal becomes associated 6569 with a session, its foreground process group shall be set to the process group of the session 6570 leader. 6571 The controlling terminal is inherited by a child process during a fork( ) function call. A process 6572 relinquishes its controlling terminal when it creates a new session with the setsid( ) function; 6573 other processes remaining in the old session that had this terminal as their controlling terminal 6574 continue to have it. Upon the close of the last file descriptor in the system (whether or not it is in 6575 the current session) associated with the controlling terminal, it is unspecified whether all 6576 processes that had that terminal as their controlling terminal cease to have any controlling 6577 terminal. Whether and how a session leader can reacquire a controlling terminal after the 6578 controlling terminal has been relinquished in this fashion is unspecified. A process does not 6579 relinquish its controlling terminal simply by closing all of its file descriptors associated with the 6580 controlling terminal if other processes continue to have it open. 6581 When a controlling process terminates, the controlling terminal is dissociated from the current 6582 session, allowing it to be acquired by a new session leader. Subsequent access to the terminal by 6583 other processes in the earlier session may be denied, with attempts to access the terminal treated 6584 as if a modem disconnect had been sensed. 6585 11.1.4 Terminal Access Control 6586 If a process is in the foreground process group of its controlling terminal, read operations shall 6587 be allowed, as described in Section 11.1.5 (on page 185). Any attempts by a process in a 6588 background process group to read from its controlling terminal cause its process group to be 6589 sent a SIGTTIN signal unless one of the following special cases applies: if the reading process is 6590 ignoring or blocking the SIGTTIN signal, or if the process group of the reading process is 6591 orphaned, the read( ) shall return -1, with errno set to [EIO] and no signal shall be sent. The 6592 default action of the SIGTTIN signal shall be to stop the process to which it is sent. See 6593 . 6594 If a process is in the foreground process group of its controlling terminal, write operations shall 6595 be allowed as described in Section 11.1.8 (on page 187). Attempts by a process in a background 6596 process group to write to its controlling terminal shall cause the process group to be sent a 6597 SIGTTOU signal unless one of the following special cases applies: if TOSTOP is not set, or if 6598 TOSTOP is set and the process is ignoring or blocking the SIGTTOU signal, the process is 6599 allowed to write to the terminal and the SIGTTOU signal is not sent. If TOSTOP is set, and the 6600 process group of the writing process is orphaned, and the writing process is not ignoring or 6601 blocking the SIGTTOU signal, the write( ) shall return -1, with errno set to [EIO] and no signal 6602 shall be sent. 6603 Certain calls that set terminal parameters are treated in the same fashion as write( ), except that 6604 TOSTOP is ignored; that is, the effect is identical to that of terminal writes when TOSTOP is set 6605 (see Section 11.2.5 (on page 193), tcdrain( ), tcflow( ), tcflush( ), tcsendbreak( ), tcsetattr( ), and 6606 tcsetpgrp( )). 184 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Interface Characteristics 6607 11.1.5 Input Processing and Reading Data 6608 A terminal device associated with a terminal device file may operate in full-duplex mode, so that 6609 data may arrive even while output is occurring. Each terminal device file has an input queue, 6610 associated with it, into which incoming data is stored by the system before being read by a 6611 process. The system may impose a limit, {MAX_INPUT}, on the number of bytes that may be 6612 stored in the input queue. The behavior of the system when this limit is exceeded is 6613 implementation-defined. 6614 Two general kinds of input processing are available, determined by whether the terminal device 6615 file is in canonical mode or non-canonical mode. These modes are described in Section 11.1.6 and 6616 Section 11.1.7 (on page 186). Additionally, input characters are processed according to the 6617 c_iflag (see Section 11.2.2 (on page 189)) and c_lflag (see Section 11.2.5 (on page 193)) fields. 6618 Such processing can include echoing, which in general means transmitting input characters 6619 immediately back to the terminal when they are received from the terminal. This is useful for 6620 terminals that can operate in full-duplex mode. 6621 The manner in which data is provided to a process reading from a terminal device file is 6622 dependent on whether the terminal file is in canonical or non-canonical mode, and on whether 6623 or not the O_NONBLOCK flag is set by open( ) or fcntl( ). 6624 If the O_NONBLOCK flag is clear, then the read request shall be blocked until data is available 6625 or a signal has been received. If the O_NONBLOCK flag is set, then the read request shall be 6626 completed, without blocking, in one of three ways: 6627 1. If there is enough data available to satisfy the entire request, the read( ) shall complete 6628 successfully and shall return the number of bytes read. 6629 2. If there is not enough data available to satisfy the entire request, the read( ) shall complete 6630 successfully, having read as much data as possible, and shall return the number of bytes it 6631 was able to read. 6632 3. If there is no data available, the read( ) shall return -1, with errno set to [EAGAIN]. 6633 When data is available depends on whether the input processing mode is canonical or non- 6634 canonical. The following sections, Section 11.1.6 and Section 11.1.7 (on page 186), describe each 6635 of these input processing modes. 6636 11.1.6 Canonical Mode Input Processing 6637 In canonical mode input processing, terminal input is processed in units of lines. A line is 6638 delimited by a newline character (NL), an end-of-file character (EOF), or an end-of-line (EOL) 6639 character. See Section 11.1.9 (on page 187) for more information on EOF and EOL. This means 6640 that a read request shall not return until an entire line has been typed or a signal has been 6641 received. Also, no matter how many bytes are requested in the read( ) call, at most one line shall 6642 be returned. It is not, however, necessary to read a whole line at once; any number of bytes, even 6643 one, may be requested in a read( ) without losing information. 6644 If {MAX_CANON} is defined for this terminal device, it shall be a limit on the number of bytes | 6645 in a line. The behavior of the system when this limit is exceeded is implementation-defined. If | 6646 {MAX_CANON} is not defined, there shall be no such limit; see pathconf( ). | 6647 Erase and kill processing occur when either of two special characters, the ERASE and KILL 6648 characters (see Section 11.1.9 (on page 187)), is received. This processing shall affect data in the | 6649 input queue that has not yet been delimited by a newline (NL), EOF, or EOL character. This un- | 6650 delimited data makes up the current line. The ERASE character shall delete the last character in | 6651 the current line, if there is one. The KILL character shall delete all data in the current line, if there | 6652 are any. The ERASE and KILL characters shall have no effect if there is no data in the current | Base Definitions, Issue 6 185 Interface Characteristics General Terminal Interface 6653 line. The ERASE and KILL characters themselves shall not be placed in the input queue. | 6654 11.1.7 Non-Canonical Mode Input Processing 6655 In non-canonical mode input processing, input bytes are not assembled into lines, and erase and | 6656 kill processing shall not occur. The values of the MIN and TIME members of the c_cc array are | 6657 used to determine how to process the bytes received. The IEEE Std 1003.1-200x does not specify 6658 whether the setting of O_NONBLOCK takes precedence over MIN or TIME settings. Therefore, 6659 if O_NONBLOCK is set, read( ) may return immediately, regardless of the setting of MIN or 6660 TIME. Also, if no data is available, read( ) may either return 0, or return -1 with errno set to 6661 [EAGAIN]. 6662 MIN represents the minimum number of bytes that should be received when the read( ) function 6663 returns successfully. TIME is a timer of 0.1 second granularity that is used to time out bursty and 6664 short-term data transmissions. If MIN is greater than {MAX_INPUT}, the response to the request 6665 is undefined. The four possible values for MIN and TIME and their interactions are described 6666 below. 6667 Case A: MIN>0, TIME>0 6668 In case A, TIME serves as an inter-byte timer which shall be activated after the first byte is | 6669 received. Since it is an inter-byte timer, it shall be reset after a byte is received. The interaction | 6670 between MIN and TIME is as follows. As soon as one byte is received, the inter-byte timer shall | 6671 be started. If MIN bytes are received before the inter-byte timer expires (remember that the timer | 6672 is reset upon receipt of each byte), the read shall be satisfied. If the timer expires before MIN | 6673 bytes are received, the characters received to that point shall be returned to the user. Note that if | 6674 TIME expires at least one byte shall be returned because the timer would not have been enabled | 6675 unless a byte was received. In this case (MIN>0, TIME>0) the read shall block until the MIN and | 6676 TIME mechanisms are activated by the receipt of the first byte, or a signal is received. If data is in | 6677 the buffer at the time of the read( ), the result shall be as if data has been received immediately | 6678 after the read( ). | 6679 Case B: MIN>0, TIME=0 6680 In case B, since the value of TIME is zero, the timer plays no role and only MIN is significant. A | 6681 pending read shall not be satisfied until MIN bytes are received (that is, the pending read shall | 6682 block until MIN bytes are received), or a signal is received. A program that uses case B to read | 6683 record-based terminal I/O may block indefinitely in the read operation. 6684 Case C: MIN=0, TIME>0 6685 In case C, since MIN=0, TIME no longer represents an inter-byte timer. It now serves as a read | 6686 timer that shall be activated as soon as the read( ) function is processed. A read shall be satisfied | 6687 as soon as a single byte is received or the read timer expires. Note that in case C if the timer | 6688 expires, no bytes shall be returned. If the timer does not expire, the only way the read can be | 6689 satisfied is if a byte is received. If bytes are not received, the read shall not block indefinitely | 6690 waiting for a byte; if no byte is received within TIME*0.1 seconds after the read is initiated, the | 6691 read( ) shall return a value of zero, having read no data. If data is in the buffer at the time of the | 6692 read( ), the timer shall be started as if data has been received immediately after the read( ). | 186 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Interface Characteristics 6693 Case D: MIN=0, TIME=0 6694 The minimum of either the number of bytes requested or the number of bytes currently available 6695 shall be returned without waiting for more bytes to be input. If no characters are available, read( ) 6696 shall return a value of zero, having read no data. 6697 11.1.8 Writing Data and Output Processing 6698 When a process writes one or more bytes to a terminal device file, they are processed according 6699 to the c_oflag field (see Section 11.2.3 (on page 190)). The implementation may provide a 6700 buffering mechanism; as such, when a call to write( ) completes, all of the bytes written have 6701 been scheduled for transmission to the device, but the transmission has not necessarily 6702 completed. See write( ) for the effects of O_NONBLOCK on write( ). 6703 11.1.9 Special Characters 6704 Certain characters have special functions on input or output or both. These functions are 6705 summarized as follows: 6706 INTR Special character on input, which is recognized if the ISIG flag is set. Generates a 6707 SIGINT signal which is sent to all processes in the foreground process group for which 6708 the terminal is the controlling terminal. If ISIG is set, the INTR character shall be | 6709 discarded when processed. | 6710 QUIT Special character on input, which is recognized if the ISIG flag is set. Generates a 6711 SIGQUIT signal which is sent to all processes in the foreground process group for 6712 which the terminal is the controlling terminal. If ISIG is set, the QUIT character shall be | 6713 discarded when processed. | 6714 ERASE Special character on input, which is recognized if the ICANON flag is set. Erases the 6715 last character in the current line; see Section 11.1.6 (on page 185). It shall not erase 6716 beyond the start of a line, as delimited by an NL, EOF, or EOL character. If ICANON is | 6717 set, the ERASE character shall be discarded when processed. | 6718 KILL Special character on input, which is recognized if the ICANON flag is set. Deletes the 6719 entire line, as delimited by an NL, EOF, or EOL character. If ICANON is set, the KILL | 6720 character shall be discarded when processed. | 6721 EOF Special character on input, which is recognized if the ICANON flag is set. When 6722 received, all the bytes waiting to be read are immediately passed to the process without 6723 waiting for a newline, and the EOF is discarded. Thus, if there are no bytes waiting 6724 (that is, the EOF occurred at the beginning of a line), a byte count of zero shall be 6725 returned from the read( ), representing an end-of-file indication. If ICANON is set, the 6726 EOF character shall be discarded when processed. | 6727 NL Special character on input, which is recognized if the ICANON flag is set. It is the line 6728 delimiter newline. It cannot be changed. 6729 EOL Special character on input, which is recognized if the ICANON flag is set. It is an 6730 additional line delimiter, like NL. 6731 SUSP If the ISIG flag is set, receipt of the SUSP character shall cause a SIGTSTP signal to be | 6732 sent to all processes in the foreground process group for which the terminal is the | 6733 controlling terminal, and the SUSP character shall be discarded when processed. | 6734 STOP Special character on both input and output, which is recognized if the IXON (output 6735 control) or IXOFF (input control) flag is set. Can be used to suspend output 6736 temporarily. It is useful with CRT terminals to prevent output from disappearing Base Definitions, Issue 6 187 Interface Characteristics General Terminal Interface 6737 before it can be read. If IXON is set, the STOP character shall be discarded when | 6738 processed. | 6739 START Special character on both input and output, which is recognized if the IXON (output 6740 control) or IXOFF (input control) flag is set. Can be used to resume output that has 6741 been suspended by a STOP character. If IXON is set, the START character shall be | 6742 discarded when processed. | 6743 CR Special character on input, which is recognized if the ICANON flag is set; it is the | 6744 carriage-return character. When ICANON and ICRNL are set and IGNCR is not set, | 6745 this character shall be translated into an NL, and shall have the same effect as an NL | 6746 character. | 6747 The NL and CR characters cannot be changed. It is implementation-defined whether the START 6748 and STOP characters can be changed. The values for INTR, QUIT, ERASE, KILL, EOF, EOL, and 6749 SUSP shall be changeable to suit individual tastes. Special character functions associated with 6750 changeable special control characters can be disabled individually. 6751 If two or more special characters have the same value, the function performed when that 6752 character is received is undefined. 6753 A special character is recognized not only by its value, but also by its context; for example, an 6754 implementation may support multi-byte sequences that have a meaning different from the 6755 meaning of the bytes when considered individually. Implementations may also support 6756 additional single-byte functions. These implementation-defined multi-byte or single-byte | 6757 functions shall be recognized only if the IEXTEN flag is set; otherwise, data is received without | 6758 interpretation, except as required to recognize the special characters defined in this section. | 6759 XSI If IEXTEN is set, the ERASE, KILL, and EOF characters can be escaped by a preceding '\' | 6760 character, in which case no special function shall occur. | 6761 11.1.10 Modem Disconnect 6762 If a modem disconnect is detected by the terminal interface for a controlling terminal, and if 6763 CLOCAL is not set in the c_cflag field for the terminal (see Section 11.2.4 (on page 192)), the | 6764 SIGHUP signal shall be sent to the controlling process for which the terminal is the controlling | 6765 terminal. Unless other arrangements have been made, this shall cause the controlling process to | 6766 terminate (see exit( )). Any subsequent read from the terminal device shall return the value of | 6767 zero, indicating end-of-file; see read( ). Thus, processes that read a terminal file and test for end- 6768 of-file can terminate appropriately after a disconnect. If the EIO condition as specified in read( ) 6769 also exists, it is unspecified whether on EOF condition or the [EIO] is returned. Any subsequent 6770 write( ) to the terminal device shall return -1, with errno set to [EIO], until the device is closed. 6771 11.1.11 Closing a Terminal Device File 6772 The last process to close a terminal device file shall cause any output to be sent to the device and 6773 any input to be discarded. If HUPCL is set in the control modes and the communications port 6774 supports a disconnect function, the terminal device shall perform a disconnect. 188 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Parameters that Can be Set 6775 11.2 Parameters that Can be Set 6776 11.2.1 The termios Structure 6777 Routines that need to control certain terminal I/O characteristics shall do so by using the 6778 termios structure as defined in the header. The members of this structure include 6779 (but are not limited to): _________________________________________________ 6780 Member Array Member 6781 _ Type Size Name Description ________________________________________________ 6782 tcflag_t c_iflag Input modes. 6783 tcflag_t c_oflag Output modes. 6784 tcflag_t c_cflag Control modes. 6785 tcflag_t c_lflag Local modes. 6786 _ cc_t NCCS c_cc[ ] Control characters. ________________________________________________ 6787 The types tcflag_t and cc_t are defined in the header. They shall be unsigned 6788 integer types. 6789 11.2.2 Input Modes 6790 Values of the c_iflag field describe the basic terminal input control, and are composed of the 6791 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name | 6792 symbols in this table are defined in : | 6793 ___________________________________________________ 6794 _ Mask Name Description __________________________________________________ 6795 BRKINT Signal interrupt on break. 6796 ICRNL Map CR to NL on input. 6797 IGNBRK Ignore break condition. 6798 IGNCR Ignore CR. 6799 IGNPAR Ignore characters with parity errors. 6800 INLCR Map NL to CR on input. 6801 INPCK Enable input parity check. 6802 ISTRIP Strip character. 6803 XSI IXANY Enable any character to restart output. 6804 IXOFF Enable start/stop input control. 6805 IXON Enable start/stop output control. 6806 _ PARMRK Mark parity errors. __________________________________________________ 6807 In the context of asynchronous serial data transmission, a break condition shall be defined as a 6808 sequence of zero-valued bits that continues for more than the time to send one byte. The entire 6809 sequence of zero-valued bits is interpreted as a single break condition, even if it continues for a 6810 time equivalent to more than one byte. In contexts other than asynchronous serial data 6811 transmission, the definition of a break condition is implementation-defined. 6812 If IGNBRK is set, a break condition detected on input shall be ignored; that is, not put on the 6813 input queue and therefore not read by any process. If IGNBRK is not set and BRKINT is set, the 6814 break condition shall flush the input and output queues, and if the terminal is the controlling 6815 terminal of a foreground process group, the break condition shall generate a single SIGINT 6816 signal to that foreground process group. If neither IGNBRK nor BRKINT is set, a break 6817 condition shall be read as a single 0x00, or if PARMRK is set, as 0xff 0x00 0x00. 6818 If IGNPAR is set, a byte with a framing or parity error (other than break) shall be ignored. Base Definitions, Issue 6 189 Parameters that Can be Set General Terminal Interface 6819 If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity error (other than | 6820 break) shall be given to the application as the three-byte sequence 0xff 0x00 X, where 0xff 0x00 is | 6821 a two-byte flag preceding each sequence and X is the data of the byte received in error. To avoid | 6822 ambiguity in this case, if ISTRIP is not set, a valid byte of 0xff is given to the application as 0xff 6823 0xff. If neither PARMRK nor IGNPAR is set, a framing or parity error (other than break) shall be | 6824 given to the application as a single byte 0x00. | 6825 If INPCK is set, input parity checking shall be enabled. If INPCK is not set, input parity checking 6826 shall be disabled, allowing output parity generation without input parity errors. Note that 6827 whether input parity checking is enabled or disabled is independent of whether parity detection 6828 is enabled or disabled (see Section 11.2.4 (on page 192)). If parity detection is enabled but input 6829 parity checking is disabled, the hardware to which the terminal is connected shall recognize the 6830 parity bit, but the terminal special file shall not check whether or not this bit is correctly set. 6831 If ISTRIP is set, valid input bytes shall first be stripped to seven bits; otherwise, all eight bits 6832 shall be processed. 6833 If INLCR is set, a received NL character shall be translated into a CR character. If IGNCR is set, a 6834 received CR character shall be ignored (not read). If IGNCR is not set and ICRNL is set, a 6835 received CR character shall be translated into an NL character. 6836 XSI If IXANY is set, any input character shall restart output that has been suspended. 6837 If IXON is set, start/stop output control shall be enabled. A received STOP character shall 6838 suspend output and a received START character shall restart output. When IXON is set, START 6839 and STOP characters are not read, but merely perform flow control functions. When IXON is not 6840 set, the START and STOP characters shall be read. 6841 If IXOFF is set, start/stop input control shall be enabled. The system shall transmit STOP 6842 characters, which are intended to cause the terminal device to stop transmitting data, as needed 6843 to prevent the input queue from overflowing and causing implementation-defined behavior, and 6844 shall transmit START characters, which are intended to cause the terminal device to resume 6845 transmitting data, as soon as the device can continue transmitting data without risk of 6846 overflowing the input queue. The precise conditions under which STOP and START characters 6847 are transmitted are implementation-defined. 6848 The initial input control value after open( ) is implementation-defined. 6849 11.2.3 Output Modes 6850 The c_oflag field specifies the terminal interface's treatment of output, and is composed of the 6851 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name 6852 symbols in this table are defined in : 190 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Parameters that Can be Set 6853 ______________________________________________________________________________________ 6854 _ Mask Name Description _____________________________________________________________________________________ 6855 OPOST Perform output processing. 6856 XSI ONLCR Map NL to CR-NL on output. 6857 OCRNL Map CR to NL on output. 6858 ONOCR No CR output at column 0. 6859 ONLRET NL performs CR function. 6860 OFILL Use fill characters for delay. 6861 OFDEL Fill is DEL, else NUL. 6862 NLDLY Select newline delays: 6863 NL0 Newline character type 0. 6864 NL1 Newline character type 1. 6865 CRDLY Select carriage-return delays: 6866 CR0 Carriage-return delay type 0. 6867 CR1 Carriage-return delay type 1. 6868 CR2 Carriage-return delay type 2. 6869 CR3 Carriage-return delay type 3. 6870 TABDLY Select horizontal-tab delays: 6871 TAB0 Horizontal-tab delay type 0. 6872 TAB1 Horizontal-tab delay type 1. 6873 TAB2 Horizontal-tab delay type 2. 6874 TAB3 Expand tabs to spaces. 6875 BSDLY Select backspace delays: 6876 BS0 Backspace-delay type 0. 6877 BS1 Backspace-delay type 1. 6878 VTDLY Select vertical-tab delays: 6879 VT0 Vertical-tab delay type 0. 6880 VT1 Vertical-tab delay type 1. 6881 FFDLY Select form-feed delays: 6882 FF0 Form-feed delay type 0. 6883 _ FF1 Form-feed delay type 1. _____________________________________________________________________________________ 6884 If OPOST is set, output data shall be post-processed as described below, so that lines of text are 6885 modified to appear appropriately on the terminal device; otherwise, characters shall be 6886 transmitted without change. 6887 XSI If ONLCR is set, the NL character shall be transmitted as the CR-NL character pair. If OCRNL is 6888 set, the CR character shall be transmitted as the NL character. If ONOCR is set, no CR character 6889 shall be transmitted when at column 0 (first position). If ONLRET is set, the NL character is 6890 assumed to do the carriage-return function; the column pointer shall be set to 0 and the delays 6891 specified for CR shall be used. Otherwise, the NL character is assumed to do just the line-feed 6892 function; the column pointer remains unchanged. The column pointer shall also be set to 0 if the 6893 CR character is actually transmitted. 6894 The delay bits specify how long transmission stops to allow for mechanical or other movement 6895 when certain characters are sent to the terminal. In all cases a value of 0 shall indicate no delay. If | 6896 OFILL is set, fill characters shall be transmitted for delay instead of a timed delay. This is useful | 6897 for high baud rate terminals which need only a minimal delay. If OFDEL is set, the fill character | 6898 shall be DEL; otherwise, NUL. | 6899 If a form-feed or vertical-tab delay is specified, it shall last for about 2 seconds. | 6900 New-line delay shall last about 0.10 seconds. If ONLRET is set, the carriage-return delays shall | 6901 be used instead of the newline delays. If OFILL is set, two fill characters shall be transmitted. | Base Definitions, Issue 6 191 Parameters that Can be Set General Terminal Interface 6902 Carriage-return delay type 1 shall be dependent on the current column position, type 2 shall be | 6903 about 0.10 seconds, and type 3 shall be about 0.15 seconds. If OFILL is set, delay type 1 shall | 6904 transmit two fill characters, and type 2, four fill characters. | 6905 Horizontal-tab delay type 1 shall be dependent on the current column position. Type 2 shall be | 6906 about 0.10 seconds. Type 3 specifies that tabs shall be expanded into spaces. If OFILL is set, two | 6907 fill characters shall be transmitted for any delay. | 6908 Backspace delay shall last about 0.05 seconds. If OFILL is set, one fill character shall be | 6909 transmitted. | 6910 The actual delays depend on line speed and system load. 6911 The initial output control value after open( ) is implementation-defined. 6912 11.2.4 Control Modes 6913 The c_cflag field describes the hardware control of the terminal, and is composed of the 6914 bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name | 6915 symbols in this table are defined in ; not all values specified are required to be | 6916 supported by the underlying hardware: ___________________________________________________________ 6917 _ Mask Name Description __________________________________________________________ 6918 CLOCAL Ignore modem status lines. 6919 CREAD Enable receiver. 6920 CSIZE Number of bits transmitted or received per byte: 6921 CS5 5 bits 6922 CS6 6 bits 6923 CS7 7 bits 6924 CS8 8 bits. 6925 CSTOPB Send two stop bits, else one. 6926 HUPCL Hang up on last close. 6927 PARENB Parity enable. 6928 _ PARODD Odd parity, else even. __________________________________________________________ 6929 In addition, the input and output baud rates are stored in the termios structure. The symbols in | 6930 the following table are defined in . Not all values specified are required to be | 6931 supported by the underlying hardware. | ________________________________________________ 6932 _ Name Description Name Description _______________________________________________ 6933 B0 Hang up B600 600 baud 6934 B50 50 baud B1200 1200 baud 6935 B75 75 baud B1800 1800 baud 6936 B110 110 baud B2400 2400 baud 6937 B134 134.5 baud B4800 4800 baud 6938 B150 150 baud B9600 9600 baud 6939 B200 200 baud B19200 19200 baud 6940 _ B300 300 baud B38400 38400 baud _______________________________________________ 6941 The following functions are provided for getting and setting the values of the input and output 6942 baud rates in the termios structure: cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), and cfsetospeed( ). | 6943 The effects on the terminal device shall not become effective and not all errors need be detected | 6944 until the tcsetattr( ) function is successfully called. | 6945 The CSIZE bits shall specify the number of transmitted or received bits per byte. If ISTRIP is not | 6946 set, the value of all the other bits is unspecified. If ISTRIP is set, the value of all but the 7 low- 192 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Parameters that Can be Set 6947 order bits shall be zero, but the value of any other bits beyond CSIZE is unspecified when read. | 6948 CSIZE shall not include the parity bit, if any. If CSTOPB is set, two stop bits shall be used; | 6949 otherwise, one stop bit. For example, at 110 baud, two stop bits are normally used. 6950 If CREAD is set, the receiver shall be enabled; otherwise, no characters shall be received. 6951 If PARENB is set, parity generation and detection shall be enabled and a parity bit is added to 6952 each byte. If parity is enabled, PARODD shall specify odd parity if set; otherwise, even parity | 6953 shall be used. | 6954 If HUPCL is set, the modem control lines for the port shall be lowered when the last process 6955 with the port open closes the port or the process terminates. The modem connection shall be 6956 broken. 6957 If CLOCAL is set, a connection shall not depend on the state of the modem status lines. If | 6958 CLOCAL is clear, the modem status lines shall be monitored. 6959 Under normal circumstances, a call to the open( ) function shall wait for the modem connection 6960 to complete. However, if the O_NONBLOCK flag is set (see open( )) or if CLOCAL has been set, 6961 the open( ) function shall return immediately without waiting for the connection. 6962 If the object for which the control modes are set is not an asynchronous serial connection, some 6963 of the modes may be ignored; for example, if an attempt is made to set the baud rate on a 6964 network connection to a terminal on another host, the baud rate need not be set on the | 6965 connection between that terminal and the machine to which it is directly connected. | 6966 The initial hardware control value after open( ) is implementation-defined. 6967 11.2.5 Local Modes 6968 The c_lflag field of the argument structure is used to control various functions. It is composed 6969 of the bitwise-inclusive OR of the masks shown, which shall be bitwise-distinct. The mask name | 6970 symbols in this table are defined in ; not all values specified are required to be | 6971 supported by the underlying hardware: 6972 _______________________________________________________________ 6973 _ Mask Name Description ______________________________________________________________ 6974 ECHO Enable echo. 6975 ECHOE Echo ERASE as an error correcting backspace. 6976 ECHOK Echo KILL. 6977 ECHONL Echo . 6978 ICANON Canonical input (erase and kill processing). 6979 IEXTEN Enable extended (implementation-defined) functions. 6980 ISIG Enable signals. 6981 NOFLSH Disable flush after interrupt, quit or suspend. 6982 _ TOSTOP Send SIGTTOU for background output. ______________________________________________________________ 6983 If ECHO is set, input characters shall be echoed back to the terminal. If ECHO is clear, input 6984 characters shall not be echoed. 6985 If ECHOE and ICANON are set, the ERASE character shall cause the terminal to erase, if 6986 possible, the last character in the current line from the display. If there is no character to erase, an | 6987 implementation may echo an indication that this was the case, or do nothing. | 6988 If ECHOK and ICANON are set, the KILL character shall either cause the terminal to erase the 6989 line from the display or shall echo the newline character after the KILL character. Base Definitions, Issue 6 193 Parameters that Can be Set General Terminal Interface 6990 If ECHONL and ICANON are set, the newline character shall be echoed even if ECHO is not set. 6991 If ICANON is set, canonical processing shall be enabled. This enables the erase and kill edit 6992 functions, and the assembly of input characters into lines delimited by NL, EOF, and EOL, as 6993 described in Section 11.1.6 (on page 185). 6994 If ICANON is not set, read requests shall be satisfied directly from the input queue. A read shall 6995 not be satisfied until at least MIN bytes have been received or the timeout value TIME expired 6996 between bytes. The time value represents tenths of a second. See Section 11.1.7 (on page 186) for 6997 more details. 6998 If IEXTEN is set, implementation-defined functions shall be recognized from the input data. It is | 6999 implementation-defined how IEXTEN being set interacts with ICANON, ISIG, IXON, or IXOFF. 7000 If IEXTEN is not set, implementation-defined functions shall not be recognized and the 7001 corresponding input characters are processed as described for ICANON, ISIG, IXON, and 7002 IXOFF. 7003 If ISIG is set, each input character shall be checked against the special control characters INTR, 7004 QUIT, and SUSP. If an input character matches one of these control characters, the function 7005 associated with that character shall be performed. If ISIG is not set, no checking shall be done. 7006 Thus these special input functions are possible only if ISIG is set. 7007 If NOFLSH is set, the normal flush of the input and output queues associated with the INTR, 7008 QUIT, and SUSP characters shall not be done. 7009 If TOSTOP is set, the signal SIGTTOU shall be sent to the process group of a process that tries to 7010 write to its controlling terminal if it is not in the foreground process group for that terminal. This 7011 signal, by default, stops the members of the process group. Otherwise, the output generated by | 7012 that process shall be output to the current output stream. Processes that are blocking or ignoring | 7013 SIGTTOU signals are excepted and allowed to produce output, and the SIGTTOU signal shall | 7014 not be sent. | 7015 The initial local control value after open( ) is implementation-defined. 7016 11.2.6 Special Control Characters 7017 The special control character values shall be defined by the array c_cc. The subscript name and | 7018 description for each element in both canonical and non-canonical modes are as follows: 194 Technical Standard (2001) (Draft April 13, 2001) General Terminal Interface Parameters that Can be Set 7019 ______________________________________________ 7020 _ Subscript Usage ____________________________ 7021 Canonical Non-Canonical 7022 _ Mode Mode Description _____________________________________________ 7023 VEOF EOF character 7024 VEOL EOL character 7025 VERASE ERASE character 7026 VINTR VINTR INTR character 7027 VKILL KILL character 7028 VMIN MIN value 7029 VQUIT VQUIT QUIT character 7030 VSUSP VSUSP SUSP character 7031 VTIME TIME value 7032 VSTART VSTART START character 7033 _ VSTOP VSTOP STOP character _____________________________________________ 7034 The subscript values are unique, except that the VMIN and VTIME subscripts may have the 7035 same values as the VEOF and VEOL subscripts, respectively. 7036 Implementations that do not support changing the START and STOP characters may ignore the 7037 character values in the c_cc array indexed by the VSTART and VSTOP subscripts when 7038 tcsetattr( ) is called, but shall return the value in use when tcgetattr( ) is called. 7039 The initial values of all control characters are implementation-defined. 7040 If the value of one of the changeable special control characters (see Section 11.1.9 (on page 187)) 7041 is _POSIX_VDISABLE, that function shall be disabled; that is, no input data is recognized as the 7042 disabled special character. If ICANON is not set, the value of _POSIX_VDISABLE has no special 7043 meaning for the VMIN and VTIME entries of the c_cc array. Base Definitions, Issue 6 195 General Terminal Interface 7044 | 196 Technical Standard (2001) (Draft April 13, 2001) Chapter 12 Utility Conventions 7045 7046 12.1 Utility Argument Syntax 7047 This section describes the argument syntax of the standard utilities and introduces terminology 7048 used throughout IEEE Std 1003.1-200x for describing the arguments processed by the utilities. 7049 Within IEEE Std 1003.1-200x, a special notation is used for describing the syntax of a utility's 7050 arguments. Unless otherwise noted, all utility descriptions use this notation, which is illustrated 7051 by this example (see the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 2.9.1, Simple 7052 Commands): 7053 utility_name[-a][-b][-c option_argument] 7054 [-d|-e][-foption_argument][operand...] 7055 The notation used for the SYNOPSIS sections imposes requirements on the implementors of the 7056 standard utilities and provides a simple reference for the application developer or system user. 7057 1. The utility in the example is named utility_name. It is followed by options, option- 7058 arguments, and operands. The arguments that consist of hyphens and single letters or 7059 digits, such as 'a', are known as options (or, historically, flags). Certain options are 7060 followed by an option-argument, as shown with [-c option_argument]. The arguments 7061 following the last options and option-arguments are named operands. 7062 2. Option-arguments are sometimes shown separated from their options by s, 7063 sometimes directly adjacent. This reflects the situation that in some cases an option- 7064 argument is included within the same argument string as the option; in most cases it is the 7065 next argument. The Utility Syntax Guidelines in Section 12.2 (on page 199) require that the 7066 option be a separate argument from its option-argument, but there are some exceptions in 7067 IEEE Std 1003.1-200x to ensure continued operation of historical applications: 7068 a. If the SYNOPSIS of a standard utility shows a space character between an option and 7069 option-argument (as with [-c option_argument] in the example), a conforming | 7070 application shall use separate arguments for that option and its option-argument. | 7071 b. If a space character is not shown (as with [-foption_argument] in the example), a | 7072 conforming application shall place an option and its option-argument directly | 7073 adjacent in the same argument string, without intervening s. 7074 c. Notwithstanding the preceding requirements on conforming applications, a | 7075 conforming system shall permit, but shall not require, an application to specify 7076 options and option-arguments as separate arguments whether or not a space 7077 XSI character is shown on the synopsis line, except in those cases (marked with the XSI 7078 portability warning) where an option-argument is optional and no separation can be 7079 used. 7080 d. A standard utility may also be implemented to operate correctly when the required 7081 separation into multiple arguments is violated by a non-conforming application. | 7082 In summary, the following table shows allowable combinations: Base Definitions, Issue 6 197 Utility Argument Syntax Utility Conventions 7083 ____________________________________________________________________ 7084 _ SYNOPSIS Shows: __________________________________ 7085 _ -a arg -barg -c[arg] ___________________________________________________________________ 7086 _Conforming application shall use: -a arg -barg N/A ___________________________________________________________________ | | 7087 _ System shall support: -a arg -barg -carg or -c ___________________________________________________________________ 7088 _ System may support: -aarg -b arg ___________________________________________________________________ 7089 3. Options are usually listed in alphabetical order unless this would make the utility 7090 description more confusing. There are no implied relationships between the options based 7091 upon the order in which they appear, unless otherwise stated in the OPTIONS section, or 7092 unless the exception in Guideline 11 of Section 12.2 (on page 199) applies. If an option that 7093 does not have option-arguments is repeated, the results are undefined, unless otherwise 7094 stated. 7095 4. Frequently, names of parameters that require substitution by actual values are shown with 7096 embedded underscores. Alternatively, parameters are shown as follows: 7097 7098 The angle brackets are used for the symbolic grouping of a phrase representing a single | 7099 parameter and conforming applications shall not include them in data submitted to the | 7100 utility. 7101 5. When a utility has only a few permissible options, they are sometimes shown individually, 7102 as in the example. Utilities with many flags generally show all of the individual flags (that 7103 do not take option-arguments) grouped, as in: 7104 utility_name [-abcDxyz][-p arg][operand] 7105 Utilities with very complex arguments may be shown as follows: 7106 utility_name [options][operands] 7107 6. Unless otherwise specified, whenever an operand or option-argument is, or contains, a 7108 numeric value: 7109 * The number is interpreted as a decimal integer. 7110 * Numerals in the range 0 to 2 147 483 647 are syntactically recognized as numeric values. 7111 * When the utility description states that it accepts negative numbers as operands or 7112 option-arguments, numerals in the range -2 147 483 647 to 2 147 483 647 are 7113 syntactically recognized as numeric values. 7114 * Ranges greater than those listed here are allowed. 7115 This does not mean that all numbers within the allowable range are necessarily 7116 semantically correct. A standard utility that accepts an option-argument or operand that is 7117 to be interpreted as a number, and for which a range of values smaller than that shown 7118 above is permitted by the IEEE Std 1003.1-200x, describes that smaller range along with the 7119 description of the option-argument or operand. If an error is generated, the utility's 7120 diagnostic message shall indicate that the value is out of the supported range, not that it is 7121 syntactically incorrect. 7122 7. Arguments or option-arguments enclosed in the '[' and ']' notation are optional and | 7123 can be omitted. Conforming applications shall not include the '[' and ']' symbols in | 7124 data submitted to the utility. 7125 8. Arguments separated by the '|' vertical bar notation are mutually-exclusive. Conforming | 7126 applications shall not include the '|' symbol in data submitted to the utility. | 198 Technical Standard (2001) (Draft April 13, 2001) Utility Conventions Utility Argument Syntax 7127 Alternatively, mutually-exclusive options and operands may be listed with multiple 7128 synopsis lines. For example: 7129 utility_name -d[-a][-c option_argument][operand...] 7130 utility_name[-a][-b][operand...] 7131 When multiple synopsis lines are given for a utility, it is an indication that the utility has 7132 mutually-exclusive arguments. These mutually-exclusive arguments alter the functionality 7133 of the utility so that only certain other arguments are valid in combination with one of the 7134 mutually-exclusive arguments. Only one of the mutually-exclusive arguments is allowed 7135 for invocation of the utility. Unless otherwise stated in an accompanying OPTIONS 7136 section, the relationships between arguments depicted in the SYNOPSIS sections are 7137 mandatory requirements placed on conforming applications. The use of conflicting | 7138 mutually-exclusive arguments produces undefined results, unless a utility description 7139 specifies otherwise. When an option is shown without the '[' and ']' brackets, it means 7140 that option is required for that version of the SYNOPSIS. However, it is not required to be 7141 the first argument, as shown in the example above, unless otherwise stated. 7142 9. Ellipses ("...") are used to denote that one or more occurrences of an option or operand 7143 are allowed. When an option or an operand followed by ellipses is enclosed in brackets, 7144 zero or more options or operands can be specified. The forms: 7145 utility_name -f option_argument...[operand...] 7146 utility_name [-g option_argument]...[operand...] 7147 indicate that multiple occurrences of the option and its option-argument preceding the 7148 ellipses are valid, with semantics as indicated in the OPTIONS section of the utility. (See 7149 also Guideline 11 in Section 12.2.) In the first example, each option-argument requires a 7150 preceding -f and at least one -f option_argument must be given. 7151 10. When the synopsis line is too long to be printed on a single line in the Shell and Utilities 7152 volume of IEEE Std 1003.1-200x, the indented lines following the initial line are 7153 continuation lines. An actual use of the command would appear on a single logical line. 7154 12.2 Utility Syntax Guidelines 7155 The following guidelines are established for the naming of utilities and for the specification of 7156 options, option-arguments, and operands. The getopt( ) function in the System Interfaces volume 7157 of IEEE Std 1003.1-200x assists utilities in handling options and operands that conform to these 7158 guidelines. 7159 Operands and option-arguments can contain characters not specified in the portable character 7160 set. 7161 The guidelines are intended to provide guidance to the authors of future utilities, such as those 7162 written specific to a local system or that are components of a larger application. Some of the 7163 standard utilities do not conform to all of these guidelines; in those cases, the OPTIONS sections 7164 describe the deviations. 7165 Guideline 1: Utility names should be between two and nine characters, inclusive. 7166 Guideline 2: Utility names should include lowercase letters (the lower character 7167 classification) and digits only from the portable character set. 7168 Guideline 3: Each option name should be a single alphanumeric character (the alnum 7169 character classification) from the portable character set. The -W (capital-W) 7170 option shall be reserved for vendor options. Base Definitions, Issue 6 199 Utility Syntax Guidelines Utility Conventions 7171 Multi-digit options should not be allowed. | 7172 Guideline 4: All options should be preceded by the '-' delimiter character. 7173 Guideline 5: Options without option-arguments should be accepted when grouped behind 7174 one '-' delimiter. 7175 Guideline 6: Each option and option-argument should be a separate argument, except as 7176 noted in Section 12.1 (on page 197), item (2). 7177 Guideline 7: Option-arguments should not be optional. 7178 Guideline 8: When multiple option-arguments are specified to follow a single option, they 7179 should be presented as a single argument, using commas within that 7180 argument or s within that argument to separate them. 7181 Guideline 9: All options should precede operands on the command line. 7182 Guideline 10: The argument - - should be accepted as a delimiter indicating the end of 7183 options. Any following arguments should be treated as operands, even if they 7184 begin with the '-' character. The - - argument should not be used as an 7185 option or as an operand. 7186 Guideline 11: The order of different options relative to one another should not matter, 7187 unless the options are documented as mutually-exclusive and such an option 7188 is documented to override any incompatible options preceding it. If an option 7189 that has option-arguments is repeated, the option and option-argument 7190 combinations should be interpreted in the order specified on the command 7191 line. 7192 Guideline 12: The order of operands may matter and position-related interpretations should 7193 be determined on a utility-specific basis. 7194 Guideline 13: For utilities that use operands to represent files to be opened for either reading 7195 or writing, the '-' operand should be used only to mean standard input (or 7196 standard output when it is clear from context that an output file is being 7197 specified). 7198 The utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x that claim conformance to 7199 these guidelines shall conform completely to these guidelines as if these guidelines contained the | 7200 term ``shall'' instead of ``should''. On some implementations, the utilities accept usage in | 7201 violation of these guidelines for backward compatibility as well as accepting the required form. | 7202 It is recommended that all future utilities and applications use these guidelines to enhance user 7203 portability. The fact that some historical utilities could not be changed (to avoid breaking | 7204 existing applications) should not deter this future goal. 200 Technical Standard (2001) (Draft April 13, 2001) Chapter 13 Headers 7205 7206 This chapter describes the contents of headers. 7207 Headers contain function prototypes, the definition of symbolic constants, common structures, 7208 preprocessor macros, and defined types. Each function in the System Interfaces volume of 7209 IEEE Std 1003.1-200x specifies the headers that an application shall include in order to use that 7210 function. In most cases, only one header is required. These headers are present on an application 7211 development system; they need not be present on the target execution system. 7212 13.1 Format of Entries 7213 The entries in this chapter are based on a common format as follows. The only sections relating 7214 to conformance are the SYNOPSIS and DESCRIPTION. 7215 NAME 7216 This section gives the name or names of the entry and briefly states its purpose. 7217 SYNOPSIS 7218 This section summarizes the use of the entry being described. 7219 DESCRIPTION 7220 This section describes the functionality of the header. 7221 APPLICATION USAGE 7222 This section is non-normative. 7223 This section gives warnings and advice to application writers about the entry. In the 7224 event of conflict between warnings and advice and a normative part of this volume of 7225 IEEE Std 1003.1-200x, the normative material is to be taken as correct. 7226 RATIONALE 7227 This section is non-normative. 7228 This section contains historical information concerning the contents of this volume of 7229 IEEE Std 1003.1-200x and why features were included or discarded by the standard 7230 developers. 7231 FUTURE DIRECTIONS 7232 This section is non-normative. 7233 This section provides comments which should be used as a guide to current thinking; 7234 there is not necessarily a commitment to adopt these future directions. 7235 SEE ALSO 7236 This section is non-normative. 7237 This section gives references to related information. 7238 CHANGE HISTORY 7239 This section is non-normative. 7240 This section shows the derivation of the entry and any significant changes that have 7241 been made to it. Base Definitions, Issue 6 201 Headers 7242 NAME 7243 aio.h - asynchronous input and output (REALTIME) 7244 SYNOPSIS 7245 AIO #include 7246 7247 DESCRIPTION 7248 The header shall define the aiocb structure which shall include at least the following 7249 members: 7250 int aio_fildes File descriptor. 7251 off_t aio_offset File offset. 7252 volatile void *aio_buf Location of buffer. 7253 size_t aio_nbytes Length of transfer. 7254 int aio_reqprio Request priority offset. 7255 struct sigevent aio_sigevent Signal number and value. 7256 int aio_lio_opcode Operation to be performed. 7257 This header shall also include the following constants: 7258 AIO_CANCELED A return value indicating that all requested operations have been 7259 canceled. 7260 AIO_NOTCANCELED 7261 A return value indicating that some of the requested operations could not 7262 be canceled since they are in progress. 7263 AIO_ALLDONE A return value indicating that none of the requested operations could be 7264 canceled since they are already complete. 7265 LIO_WAIT A lio_listio ( ) synchronization operation indicating that the calling thread 7266 is to suspend until the lio_listio ( ) operation is complete. 7267 LIO_NOWAIT A lio_listio ( ) synchronization operation indicating that the calling thread 7268 is to continue execution while the lio_listio ( ) operation is being 7269 performed, and no notification is given when the operation is complete. 7270 LIO_READ A lio_listio ( ) element operation option requesting a read. 7271 LIO_WRITE A lio_listio ( ) element operation option requesting a write. 7272 LIO_NOP A lio_listio ( ) element operation option indicating that no transfer is 7273 requested. 7274 The following shall be declared as functions and may also be defined as macros. Function | 7275 prototypes shall be provided. | 7276 int aio_cancel(int, struct aiocb *); 7277 int aio_error(const struct aiocb *); 7278 int aio_fsync(int, struct aiocb *); 7279 int aio_read(struct aiocb *); 7280 ssize_t aio_return(struct aiocb *); 7281 int aio_suspend(const struct aiocb *const[], int, 7282 const struct timespec *); 7283 int aio_write(struct aiocb *); 7284 int lio_listio(int, struct aiocb *restrict const[restrict], int, 7285 struct sigevent *restrict); 202 Technical Standard (2001) (Draft April 13, 2001) Headers 7286 Inclusion of the header may make visible symbols defined in the headers , 7287 , , and . 7288 APPLICATION USAGE 7289 None. 7290 RATIONALE 7291 None. 7292 FUTURE DIRECTIONS 7293 None. 7294 SEE ALSO 7295 , , , , the System Interfaces volume of 7296 IEEE Std 1003.1-200x, fsync( ), lseek( ), read( ), write( ) 7297 CHANGE HISTORY 7298 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 7299 Issue 6 7300 The header is marked as part of the Asynchronous Input and Output option. 7301 The description of the constants is expanded. 7302 The restrict keyword is added to the prototype for lio_listio ( ). Base Definitions, Issue 6 203 Headers 7303 NAME 7304 arpa/inet.h - definitions for internet operations 7305 SYNOPSIS 7306 #include 7307 DESCRIPTION 7308 The in_port_t and in_addr_t types shall be defined as described in . 7309 The in_addr structure shall be defined as described in . 7310 IP6 The INET_ADDRSTRLEN and INET6_ADDRSTRLEN macros shall be defined as described in | 7311 . 7312 The following shall either be declared as functions, defined as macros, or both. If functions are 7313 declared, function prototypes shall be provided. | 7314 uint32_t htonl(uint32_t); 7315 uint16_t htons(uint16_t); 7316 uint32_t ntohl(uint32_t); 7317 uint16_t ntohs(uint16_t); 7318 The uint32_t and uint16_t types shall be defined as described in . 7319 The following shall be declared as functions and may also be defined as macros. Function | 7320 prototypes shall be provided. | 7321 in_addr_t inet_addr(const char *); 7322 char *inet_ntoa(struct in_addr); 7323 const char *inet_ntop(int, const void *restrict, char *restrict, 7324 socklen_t); 7325 int inet_pton(int, const char *restrict, void *restrict); 7326 Inclusion of the header may also make visible all symbols from 7327 and . 7328 APPLICATION USAGE 7329 None. 7330 RATIONALE 7331 None. 7332 FUTURE DIRECTIONS 7333 None. 7334 SEE ALSO 7335 , , the System Interfaces volume of IEEE Std 1003.1-200x, htonl( ), 7336 inet_addr( ) 7337 CHANGE HISTORY 7338 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 7339 The restrict keyword is added to the prototypes for inet_ntop( ) and inet_pton( ). 204 Technical Standard (2001) (Draft April 13, 2001) Headers 7340 NAME 7341 assert.h - verify program assertion 7342 SYNOPSIS 7343 #include 7344 DESCRIPTION 7345 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7346 conflict between the requirements described here and the ISO C standard is unintentional. This 7347 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7348 The header shall define the assert( ) macro. It refers to the macro NDEBUG which is 7349 not defined in the header. If NDEBUG is defined as a macro name before the inclusion of this 7350 header, the assert( ) macro shall be defined simply as: 7351 #define assert(ignore)((void) 0) 7352 Otherwise, the macro behaves as described in assert( ). 7353 The assert( ) macro shall be redefined according to the current state of NDEBUG each time 7354 is included. 7355 The assert( ) macro shall be implemented as a macro, not as a function. If the macro definition is 7356 suppressed in order to access an actual function, the behavior is undefined. 7357 APPLICATION USAGE 7358 None. 7359 RATIONALE 7360 None. 7361 FUTURE DIRECTIONS 7362 None. 7363 SEE ALSO 7364 The System Interfaces volume of IEEE Std 1003.1-200x, assert( ) 7365 CHANGE HISTORY 7366 First released in Issue 1. Derived from Issue 1 of the SVID. 7367 Issue 6 7368 The definition of the assert( ) macro is changed for alignment with the ISO/IEC 9899: 1999 7369 standard. Base Definitions, Issue 6 205 Headers 7370 NAME 7371 complex.h - complex arithmetic 7372 SYNOPSIS 7373 #include 7374 DESCRIPTION 7375 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7376 conflict between the requirements described here and the ISO C standard is unintentional. This 7377 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7378 The header shall define the following macros: 7379 complex Expands to _Complex. 7380 _Complex_I Expands to a constant expression of type const float _Complex, with the 7381 value of the imaginary unit (that is, a number such that i2=-1). 7382 imaginary Expands to _Imaginary. 7383 _Imaginary_I Expands to a constant expression of type const float _Imaginary with the 7384 value of the imaginary unit. 7385 I Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not defined, 7386 I expands to _Complex_I. 7387 The macros imaginary and _Imaginary_I shall be defined if and only if the implementation 7388 supports imaginary types. 7389 An application may undefine and then, perhaps, redefine the complex, imaginary, and I macros. 7390 The following shall be declared as functions and may also be defined as macros. Function | 7391 prototypes shall be provided. | 7392 double cabs(double complex); 7393 float cabsf(float complex); 7394 long double cabsl(long double complex); 7395 double complex cacos(double complex); 7396 float complex cacosf(float complex); 7397 double complex cacosh(double complex); 7398 float complex cacoshf(float complex); 7399 long double complex cacoshl(long double complex); 7400 long double complex cacosl(long double complex); 7401 double carg(double complex); 7402 float cargf(float complex); 7403 long double cargl(long double complex); 7404 double complex casin(double complex); 7405 float complex casinf(float complex); 7406 double complex casinh(double complex); 7407 float complex casinhf(float complex); 7408 long double complex casinhl(long double complex); 7409 long double complex casinl(long double complex); 7410 double complex catan(double complex); 7411 float complex catanf(float complex); 7412 double complex catanh(double complex); 7413 float complex catanhf(float complex); 7414 long double complex catanhl(long double complex); 7415 long double complex catanl(long double complex); 206 Technical Standard (2001) (Draft April 13, 2001) Headers 7416 double complex ccos(double complex); 7417 float complex ccosf(float complex); 7418 double complex ccosh(double complex); 7419 float complex ccoshf(float complex); 7420 long double complex ccoshl(long double complex); 7421 long double complex ccosl(long double complex); 7422 double complex cexp(double complex); 7423 float complex cexpf(float complex); 7424 long double complex cexpl(long double complex); 7425 double cimag(double complex); 7426 float cimagf(float complex); 7427 long double cimagl(long double complex); 7428 double complex clog(double complex); 7429 float complex clogf(float complex); 7430 long double complex clogl(long double complex); 7431 double complex conj(double complex); 7432 float complex conjf(float complex); 7433 long double complex conjl(long double complex); 7434 double complex cpow(double complex, double complex); 7435 float complex cpowf(float complex, float complex); 7436 long double complex cpowl(long double complex, long double complex); 7437 double complex cproj(double complex); 7438 float complex cprojf(float complex); 7439 long double complex cprojl(long double complex); 7440 double creal(double complex); 7441 float crealf(float complex); 7442 long double creall(long double complex); 7443 double complex csin(double complex); 7444 float complex csinf(float complex); 7445 double complex csinh(double complex); 7446 float complex csinhf(float complex); 7447 long double complex csinhl(long double complex); 7448 long double complex csinl(long double complex); 7449 double complex csqrt(double complex); 7450 float complex csqrtf(float complex); 7451 long double complex csqrtl(long double complex); 7452 double complex ctan(double complex); 7453 float complex ctanf(float complex); 7454 double complex ctanh(double complex); 7455 float complex ctanhf(float complex); 7456 long double complex ctanhl(long double complex); 7457 long double complex ctanl(long double complex); 7458 APPLICATION USAGE 7459 Values are interpreted as radians, not degrees. 7460 RATIONALE 7461 The choice of I instead of i for the imaginary unit concedes to the widespread use of the 7462 identifier i for other purposes. The application can use a different identifier, say j, for the 7463 imaginary unit by following the inclusion of the header with: 7464 #undef I 7465 #define j _Imaginary_I Base Definitions, Issue 6 207 Headers 7466 An I suffix to designate imaginary constants is not required, as multiplication by I provides a 7467 sufficiently convenient and more generally useful notation for imaginary terms. The 7468 corresponding real type for the imaginary unit is float, so that use of I for algorithmic or 7469 notational convenience will not result in widening types. 7470 On systems with imaginary types, the application has the ability to control whether use of the 7471 macro I introduces an imaginary type, by explicitly defining I to be _Imaginary_I or _Complex_I. 7472 Disallowing imaginary types is useful for some applications intended to run on implementations 7473 without support for such types. 7474 The macro _Imaginary_I provides a test for whether imaginary types are supported. 7475 The cis( ) function (cos(x) + I*sin(x)) was considered but rejected because its implementation is 7476 easy and straightforward, even though some implementations could compute sine and cosine 7477 more efficiently in tandem. 7478 FUTURE DIRECTIONS 7479 The following function names and the same names suffixed with f or l are reserved for future 7480 use, and may be added to the declarations in the header. 7481 cerf( ) cexpm1( ) clog2( ) 7482 cerfc( ) clog10( ) clgamma( ) 7483 cexp2( ) clog1p( ) ctgamma( ) 7484 SEE ALSO 7485 The System Interfaces volume of IEEE Std 1003.1-200x, cabs( ), cacos( ), cacosh( ), carg( ), casin( ), 7486 casinh( ), catan( ), catanh( ), ccos( ), ccosh( ), cexp( ), cimag( ), clog( ), conj( ), cpow( ), cproj( ), creal( ), 7487 csin( ), csinh( ), csqrt( ), ctan( ), ctanh( ) 7488 CHANGE HISTORY 7489 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. 208 Technical Standard (2001) (Draft April 13, 2001) Headers 7490 NAME 7491 cpio.h - cpio archive values 7492 SYNOPSIS 7493 XSI #include 7494 7495 DESCRIPTION 7496 Values needed by the c_mode field of the cpio archive format are described as follows: 7497 ________________________________________________________________ 7498 _ Name Description Value (Octal) _______________________________________________________________ 7499 C_IRUSR Read by owner. 0000400 7500 C_IWUSR Write by owner. 0000200 7501 C_IXUSR Execute by owner. 0000100 7502 C_IRGRP Read by group. 0000040 7503 C_IWGRP Write by group. 0000020 7504 C_IXGRP Execute by group. 0000010 7505 C_IROTH Read by others. 0000004 7506 C_IWOTH Write by others. 0000002 7507 C_IXOTH Execute by others. 0000001 7508 C_ISUID Set user ID. 0004000 7509 C_ISGID Set group ID. 0002000 7510 C_ISVTX On directories, restricted deletion flag. 0001000 7511 C_ISDIR Directory. 0040000 7512 C_ISFIFO FIFO. 0010000 7513 C_ISREG Regular file. 0100000 7514 C_ISBLK Block special. 0060000 7515 C_ISCHR Character special. 0020000 7516 C_ISCTG Reserved. 0110000 7517 C_ISLNK Symbolic link. 0120000 7518 _ C_ISSOCK Socket. 0140000 _______________________________________________________________ 7519 The header shall define the symbolic constant: 7520 MAGIC "070707" 7521 APPLICATION USAGE 7522 None. 7523 RATIONALE 7524 None. 7525 FUTURE DIRECTIONS 7526 None. 7527 SEE ALSO 7528 The Shell and Utilities volume of IEEE Std 1003.1-200x, pax 7529 CHANGE HISTORY 7530 First released in Issue 3 of the Headers Interface, Issue 3 specification. Derived from the 7531 POSIX.1-1988 standard. 7532 Issue 6 7533 The SEE ALSO is updated to refer to pax, since the cpio utility is not included in the Shell and 7534 Utilities volume of IEEE Std 1003.1-200x. Base Definitions, Issue 6 209 Headers 7535 NAME 7536 ctype.h - character types 7537 SYNOPSIS 7538 #include 7539 DESCRIPTION 7540 CX Some of the functionality described on this reference page extends the ISO C standard. 7541 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 7542 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 7543 symbols in this header. 7544 The following shall be declared as functions and may also be defined as macros. Function | 7545 prototypes shall be provided. | 7546 int isalnum(int); 7547 int isalpha(int); 7548 XSI int isascii(int); 7549 int isblank(int); 7550 int iscntrl(int); 7551 int isdigit(int); 7552 int isgraph(int); 7553 int islower(int); 7554 int isprint(int); 7555 int ispunct(int); 7556 int isspace(int); 7557 int isupper(int); 7558 int isxdigit(int); 7559 XSI int toascii(int); 7560 int tolower(int); 7561 int toupper(int); 7562 The following are defined as macros: 7563 XSI int _toupper(int); 7564 int _tolower(int); 7565 7566 APPLICATION USAGE 7567 None. 7568 RATIONALE 7569 None. 7570 FUTURE DIRECTIONS 7571 None. 7572 SEE ALSO 7573 , the System Interfaces volume of IEEE Std 1003.1-200x, isalnum( ), isalpha( ), isascii( ), 7574 iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), mblen( ), 7575 mbstowcs( ), mbtowc( ), setlocale( ), toascii( ), tolower( ), _tolower( ), toupper( ), _toupper( ), wcstombs( ), 7576 wctomb( ) 7577 CHANGE HISTORY 7578 First released in Issue 1. Derived from Issue 1 of the SVID. 210 Technical Standard (2001) (Draft April 13, 2001) Headers 7579 Issue 6 7580 Extensions beyond the ISO C standard are now marked. Base Definitions, Issue 6 211 Headers 7581 NAME 7582 dirent.h - format of directory entries 7583 SYNOPSIS 7584 #include 7585 DESCRIPTION 7586 The internal format of directories is unspecified. 7587 The header shall define the following type: 7588 DIR A type representing a directory stream. 7589 It shall also define the structure dirent which shall include the following members: 7590 XSI ino_t d_ino File serial number. 7591 char d_name[] Name of entry. 7592 XSI The type ino_t shall be defined as described in . 7593 The character array d_name is of unspecified size, but the number of bytes preceding the 7594 terminating null byte shall not exceed {NAME_MAX}. 7595 The following shall be declared as functions and may also be defined as macros. Function | 7596 prototypes shall be provided. | 7597 int closedir(DIR *); 7598 DIR *opendir(const char *); 7599 struct dirent *readdir(DIR *); 7600 TSF int readdir_r(DIR *restrict, struct dirent *restrict, 7601 struct dirent **restrict); 7602 void rewinddir(DIR *); 7603 XSI void seekdir(DIR *, long); 7604 long telldir(DIR *); 7605 7606 APPLICATION USAGE 7607 None. 7608 RATIONALE 7609 Information similar to that in the header is contained in a file in 4.2 BSD 7610 and 4.3 BSD. The equivalent in these implementations of struct dirent from this volume of 7611 IEEE Std 1003.1-200x is struct direct. The filename was changed because the name 7612 was also used in earlier implementations to refer to definitions related to the older access 7613 method; this produced name conflicts. The name of the structure was changed because this 7614 volume of IEEE Std 1003.1-200x does not completely define what is in the structure, so it could 7615 be different on some implementations from struct direct. 7616 The name of an array of char of an unspecified size should not be used as an lvalue. Use of: | 7617 sizeof(d_name) 7618 is incorrect; use: 7619 strlen(d_name) 7620 instead. 7621 The array of char d_name is not a fixed size. Implementations may need to declare struct dirent 7622 with an array size for d_name of 1, but the actual number of characters provided matches (or 7623 only slightly exceeds) the length of the filename. 212 Technical Standard (2001) (Draft April 13, 2001) Headers 7624 FUTURE DIRECTIONS 7625 None. 7626 SEE ALSO 7627 , the System Interfaces volume of IEEE Std 1003.1-200x, closedir( ), opendir( ), 7628 readdir( ), readdir_r( ), rewinddir( ), seekdir( ), telldir( ) 7629 CHANGE HISTORY 7630 First released in Issue 2. 7631 Issue 5 7632 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 7633 Issue 6 7634 The Open Group Corrigendum U026/7 is applied, correcting the prototype for readdir_r( ). 7635 The restrict keyword is added to the prototype for readdir_r( ). Base Definitions, Issue 6 213 Headers 7636 NAME 7637 dlfcn.h - dynamic linking 7638 SYNOPSIS 7639 XSI #include 7640 7641 DESCRIPTION 7642 The header shall define at least the following macros for use in the construction of a 7643 dlopen( ) mode argument: 7644 RTLD_LAZY Relocations are performed at an implementation-defined time. 7645 RTLD_NOW Relocations are performed when the object is loaded. 7646 RTLD_GLOBAL All symbols are available for relocation processing of other modules. 7647 RTLD_LOCAL All symbols are not made available for relocation processing by other 7648 modules. 7649 The following shall be declared as functions and may also be defined as macros. Function | 7650 prototypes shall be provided. | 7651 int dlclose(void *); 7652 char *dlerror(void); 7653 void *dlopen(const char *, int); 7654 void *dlsym(void *restrict, const char *restrict); 7655 APPLICATION USAGE 7656 None. 7657 RATIONALE 7658 None. 7659 FUTURE DIRECTIONS 7660 None. 7661 SEE ALSO 7662 The System Interfaces volume of IEEE Std 1003.1-200x, dlopen( ), dlclose( ), dlsym( ), dlerror( ) 7663 CHANGE HISTORY 7664 First released in Issue 5. 7665 Issue 6 7666 The restrict keyword is added to the prototype for dlsym( ). 214 Technical Standard (2001) (Draft April 13, 2001) Headers 7667 NAME 7668 errno.h - system error numbers 7669 SYNOPSIS 7670 #include 7671 DESCRIPTION 7672 CX Some of the functionality described on this reference page extends the ISO C standard. Any 7673 conflict between the requirements described here and the ISO C standard is unintentional. This 7674 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7675 CX The ISO C standard only requires the symbols [EDOM], [EILSEQ], and [ERANGE] to be defined. 7676 The header shall provide a declaration for errno and give positive values for the 7677 following symbolic constants. Their values shall be unique except as noted below: 7678 [E2BIG] Argument list too long. 7679 [EACCES] Permission denied. 7680 [EADDRINUSE] Address in use. 7681 [EADDRNOTAVAIL] Address not available. 7682 [EAFNOSUPPORT] Address family not supported. 7683 [EAGAIN] Resource unavailable, try again (may be the same value as 7684 [EWOULDBLOCK]). 7685 [EALREADY] Connection already in progress. 7686 [EBADF] Bad file descriptor. 7687 [EBADMSG] Bad message. 7688 [EBUSY] Device or resource busy. 7689 [ECANCELED] Operation canceled. 7690 [ECHILD] No child processes. 7691 [ECONNABORTED] Connection aborted. 7692 [ECONNREFUSED] Connection refused. 7693 [ECONNRESET] Connection reset. 7694 [EDEADLK] Resource deadlock would occur. 7695 [EDESTADDRREQ] Destination address required. 7696 [EDOM] Mathematics argument out of domain of function. 7697 [EDQUOT] Reserved. 7698 [EEXIST] File exists. 7699 [EFAULT] Bad address. 7700 [EFBIG] File too large. 7701 [EHOSTUNREACH] Host is unreachable. 7702 [EIDRM] Identifier removed. 7703 [EILSEQ] Illegal byte sequence. Base Definitions, Issue 6 215 Headers 7704 [EINPROGRESS] Operation in progress. 7705 [EINTR] Interrupted function. 7706 [EINVAL] Invalid argument. 7707 [EIO] I/O error. 7708 [EISCONN] Socket is connected. 7709 [EISDIR] Is a directory. 7710 [ELOOP] Too many levels of symbolic links. 7711 [EMFILE] Too many open files. 7712 [EMLINK] Too many links. 7713 [EMSGSIZE] Message too large. 7714 [EMULTIHOP] Reserved. 7715 [ENAMETOOLONG] Filename too long. 7716 [ENETDOWN] Network is down. 7717 [ENETUNREACH] Network unreachable. 7718 [ENFILE] Too many files open in system. 7719 [ENOBUFS] No buffer space available. 7720 XSR [ENODATA] No message is available on the STREAM head read queue. 7721 [ENODEV] No such device. 7722 [ENOENT] No such file or directory. 7723 [ENOEXEC] Executable file format error. 7724 [ENOLCK] No locks available. 7725 [ENOLINK] Reserved. 7726 [ENOMEM] Not enough space. 7727 [ENOMSG] No message of the desired type. 7728 [ENOPROTOOPT] Protocol not available. 7729 [ENOSPC] No space left on device. 7730 XSR [ENOSR] No STREAM resources. 7731 XSR [ENOSTR] Not a STREAM. 7732 [ENOSYS] Function not supported. 7733 [ENOTCONN] The socket is not connected. 7734 [ENOTDIR] Not a directory. 7735 [ENOTEMPTY] Directory not empty. 7736 [ENOTSOCK] Not a socket. 7737 [ENOTSUP] Not supported. 216 Technical Standard (2001) (Draft April 13, 2001) Headers 7738 [ENOTTY] Inappropriate I/O control operation. 7739 [ENXIO] No such device or address. 7740 [EOPNOTSUPP] Operation not supported on socket. 7741 [EOVERFLOW] Value too large to be stored in data type. 7742 [EPERM] Operation not permitted. 7743 [EPIPE] Broken pipe. 7744 [EPROTO] Protocol error. 7745 [EPROTONOSUPPORT] 7746 Protocol not supported. 7747 [EPROTOTYPE] Protocol wrong type for socket. 7748 [ERANGE] Result too large. 7749 [EROFS] Read-only file system. 7750 [ESPIPE] Invalid seek. 7751 [ESRCH] No such process. 7752 [ESTALE] Reserved. 7753 XSR [ETIME] Stream ioctl( ) timeout. 7754 [ETIMEDOUT] Connection timed out. 7755 [ETXTBSY] Text file busy. 7756 [EWOULDBLOCK] Operation would block (may be the same value as [EAGAIN]). 7757 [EXDEV] Cross-device link. 7758 APPLICATION USAGE 7759 Additional error numbers may be defined on conforming systems; see the System Interfaces 7760 volume of IEEE Std 1003.1-200x. 7761 RATIONALE 7762 None. 7763 FUTURE DIRECTIONS 7764 None. 7765 SEE ALSO 7766 The System Interfaces volume of IEEE Std 1003.1-200x, Section 2.3, Error Numbers 7767 CHANGE HISTORY 7768 First released in Issue 1. Derived from Issue 1 of the SVID. 7769 Issue 5 7770 Updated for alignment with the POSIX Realtime Extension. 7771 Issue 6 7772 The following new requirements on POSIX implementations derive from alignment with the 7773 Single UNIX Specification: 7774 * The majority of the error conditions previously marked as extensions are now mandatory, 7775 except for the STREAMS-related error conditions. Base Definitions, Issue 6 217 Headers 7776 Values for errno are now required to be distinct positive values rather than non-zero values. This 7777 change is for alignment with the ISO/IEC 9899: 1999 standard. 218 Technical Standard (2001) (Draft April 13, 2001) Headers 7778 NAME 7779 fcntl.h - file control options 7780 SYNOPSIS 7781 #include 7782 DESCRIPTION 7783 The header shall define the following requests and arguments for use by the functions 7784 fcntl( ) and open( ). 7785 Values for cmd used by fcntl( ) (the following values are unique) are as follows: 7786 F_DUPFD Duplicate file descriptor. 7787 F_GETFD Get file descriptor flags. 7788 F_SETFD Set file descriptor flags. 7789 F_GETFL Get file status flags and file access modes. 7790 F_SETFL Set file status flags. 7791 F_GETLK Get record locking information. 7792 F_SETLK Set record locking information. 7793 F_SETLKW Set record locking information; wait if blocked. 7794 F_GETOWN Get process or process group ID to receive SIGURG signals. 7795 F_SETOWN Set process or process group ID to receive SIGURG signals. 7796 File descriptor flags used for fcntl( ) are as follows: 7797 FD_CLOEXEC Close the file descriptor upon execution of an exec family function. 7798 Values for l_type used for record locking with fcntl( ) (the following values are unique) are as 7799 follows: 7800 F_RDLCK Shared or read lock. 7801 F_UNLCK Unlock. 7802 F_WRLCK Exclusive or write lock. 7803 XSI The values used for l_whence, SEEK_SET, SEEK_CUR, and SEEK_END shall be defined as 7804 described in . 7805 The following values are file creation flags and are used in the oflag value to open( ). They shall | 7806 be bitwise-distinct. | 7807 O_CREAT Create file if it does not exist. 7808 O_EXCL Exclusive use flag. 7809 O_NOCTTY Do not assign controlling terminal. 7810 O_TRUNC Truncate flag. 7811 File status flags used for open( ) and fcntl( ) are as follows: 7812 O_APPEND Set append mode. 7813 SIO O_DSYNC Write according to synchronized I/O data integrity completion. 7814 O_NONBLOCK Non-blocking mode. Base Definitions, Issue 6 219 Headers 7815 SIO O_RSYNC Synchronized read I/O operations. 7816 O_SYNC Write according to synchronized I/O file integrity completion. 7817 Mask for use with file access modes is as follows: 7818 O_ACCMODE Mask for file access modes. 7819 File access modes used for open( ) and fcntl( ) are as follows: 7820 O_RDONLY Open for reading only. 7821 O_RDWR Open for reading and writing. 7822 O_WRONLY Open for writing only. 7823 XSI The symbolic names for file modes for use as values of mode_t shall be defined as described in 7824 . 7825 ADV Values for advice used by posix_fadvise( ) are as follows: 7826 POSIX_FADV_NORMAL 7827 The application has no advice to give on its behavior with respect to the specified data. It is 7828 the default characteristic if no advice is given for an open file. 7829 POSIX_FADV_SEQUENTIAL 7830 The application expects to access the specified data sequentially from lower offsets to 7831 higher offsets. 7832 POSIX_FADV_RANDOM 7833 The application expects to access the specified data in a random order. 7834 POSIX_FADV_WILLNEED 7835 The application expects to access the specified data in the near future. 7836 POSIX_FADV_DONTNEED 7837 The application expects that it will not access the specified data in the near future. 7838 POSIX_FADV_NOREUSE 7839 The application expects to access the specified data once and then not reuse it thereafter. 7840 7841 The structure flock describes a file lock. It shall include the following members: 7842 short l_type Type of lock; F_RDLCK, F_WRLCK, F_UNLCK. 7843 short l_whence Flag for starting offset. 7844 off_t l_start Relative offset in bytes. 7845 off_t l_len Size; if 0 then until EOF. 7846 pid_t l_pid Process ID of the process holding the lock; returned with F_GETLK. 7847 The mode_t, off_t, and pid_t types shall be defined as described in . 7848 The following shall be declared as functions and may also be defined as macros. Function | 7849 prototypes shall be provided. | 7850 int creat(const char *, mode_t); 7851 int fcntl(int, int, ...); 7852 int open(const char *, int, ...); 7853 ADV int posix_fadvise(int, off_t, size_t, int); 7854 int posix_fallocate(int, off_t, size_t); 7855 220 Technical Standard (2001) (Draft April 13, 2001) Headers 7856 XSI Inclusion of the header may also make visible all symbols from and 7857 . 7858 APPLICATION USAGE 7859 None. 7860 RATIONALE 7861 None. 7862 FUTURE DIRECTIONS 7863 None. 7864 SEE ALSO 7865 , , , the System Interfaces volume of IEEE Std 1003.1-200x, 7866 creat( ), exec( ), fcntl( ), open( ), posix_fadvise( ), posix_fallocate( ), posix_madvise( ) 7867 CHANGE HISTORY 7868 First released in Issue 1. Derived from Issue 1 of the SVID. 7869 Issue 5 7870 The DESCRIPTION is updated for alignment with POSIX Realtime Extension. 7871 Issue 6 7872 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 7873 * O_DSYNC and O_RSYNC are marked as part of the Synchronized Input and Output option. 7874 The following new requirements on POSIX implementations derive from alignment with the 7875 Single UNIX Specification: 7876 * The definition of the mode_t, off_t, and pid_t types is mandated. 7877 The F_GETOWN and F_SETOWN values are added for sockets. 7878 The posix_fadvise( ), posix_fallocate( ), and posix_madvise( ) functions are added for alignment with 7879 IEEE Std 1003.1d-1999. 7880 IEEE PASC Interpretation 1003.1 #102 is applied moving the prototype for posix_madvise( ) to | 7881 . | Base Definitions, Issue 6 221 Headers 7882 NAME 7883 fenv.h - floating-point environment 7884 SYNOPSIS 7885 #include 7886 DESCRIPTION 7887 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7888 conflict between the requirements described here and the ISO C standard is unintentional. This 7889 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7890 The header shall define the following data types through typedef: 7891 fenv_t Represents the entire floating-point environment. The floating-point environment 7892 refers collectively to any floating-point status flags and control modes supported 7893 by the implementation. 7894 fexcept_t Represents the floating-point status flags collectively, including any status the 7895 implementation associates with the flags. A floating-point status flag is a system 7896 variable whose value is set (but never cleared) when a floating-point exception is 7897 raised, which occurs as a side effect of exceptional floating-point arithmetic to 7898 provide auxiliary information. A floating-point control mode is a system variable 7899 whose value may be set by the user to affect the subsequent behavior of floating- 7900 point arithmetic. 7901 The header shall define the following constants if and only if the implementation 7902 supports the floating-point exception by means of the floating-point functions fwclearexcept( ), 7903 fegetexceptflag( ), feraiseexcept( ), fesetexceptflag( ), and fetestexcept( ). Each expands to an integer 7904 constant expression with values such that bitwise-inclusive ORs of all combinations of the 7905 constants result in distinct values. 7906 FE_DIVBYZERO 7907 FE_INEXACT 7908 FE_INVALID 7909 FE_OVERFLOW 7910 FE_UNDERFLOW 7911 The header shall define the following constant, which is simply the bitwise-inclusive 7912 OR of all floating-point exception constants defined above: 7913 FE_ALL_EXCEPT 7914 The header shall define the following constants if and only if the implementation 7915 supports getting and setting the represented rounding direction by means of the fegetround( ) 7916 and fesetround( ) functions. Each expands to an integer constant expression whose values are 7917 distinct non-negative vales. 7918 FE_DOWNWARD 7919 FE_TONEAREST 7920 FE_TOWARDZERO 7921 FE_UPWARD 7922 The header shall define the following constant, which represents the default floating- 7923 point environment (that is, the one installed at program startup) and has type pointer to const- 7924 qualified fenv_t. It can be used as an argument to the functions within the header that 7925 manage the floating-point environment. 7926 FE_DFL_ENV 222 Technical Standard (2001) (Draft April 13, 2001) Headers 7927 The following shall be declared as functions and may also be defined as macros. Function | 7928 prototypes shall be provided. | 7929 int feclearexcept(int); 7930 int fegetexceptflag(fexcept_t *, int); 7931 int feraiseexcept(int); 7932 int fesetexceptflag(const fexcept_t *, int); 7933 int fetestexcept(int); 7934 int fegetround(void); 7935 int fesetround(int); 7936 int fegetenv(fenv_t *); 7937 int feholdexcept(fenv_t *); 7938 int fesetenv(const fenv_t *); 7939 int feupdateenv(const fenv_t *); 7940 The FENV_ACCESS pragma provides a means to inform the implementation when an 7941 application might access the floating-point environment to test floating-point status flags or run 7942 under non-default floating-point control modes. The pragma shall occur either outside external 7943 declarations or preceding all explicit declarations and statements inside a compound statement. 7944 When outside external declarations, the pragma takes effect from its occurrence until another 7945 FENV_ACCESS pragma is encountered, or until the end of the translation unit. When inside a 7946 compound statement, the pragma takes effect from its occurrence until another FENV_ACCESS 7947 pragma is encountered (including within a nested compound statement), or until the end of the 7948 compound statement; at the end of a compound statement the state for the pragma is restored to 7949 its condition just before the compound statement. If this pragma is used in any other context, the 7950 behavior is undefined. If part of an application tests floating-point status flags, sets floating- 7951 point control modes, or runs under non-default mode settings, but was translated with the state 7952 for the FENV_ACCESS pragma off, the behavior is undefined. The default state (on or off) for 7953 the pragma is implementation-defined. (When execution passes from a part of the application 7954 translated with FENV_ACCESS off to a part translated with FENV_ACCESS on, the state of the 7955 floating-point status flags is unspecified and the floating-point control modes have their default 7956 settings.) 7957 APPLICATION USAGE 7958 This header is designed to support the floating-point exception status flags and directed- 7959 rounding control modes required by the IEC 60559: 1989 standard, and other similar floating- 7960 point state information. Also it is designed to facilitate code portability among all systems. 7961 Certain application programming conventions support the intended model of use for the 7962 floating-point environment: 7963 * A function call does not alter its caller's floating-point control modes, clear its caller's 7964 floating-point status flags, nor depend on the state of its caller's floating-point status flags 7965 unless the function is so documented. 7966 * A function call is assumed to require default floating-point control modes, unless its 7967 documentation promises otherwise. 7968 * A function call is assumed to have the potential for raising floating-point exceptions, unless 7969 its documentation promises otherwise. 7970 With these conventions, an application can safely assume default floating-point control modes 7971 (or be unaware of them). The responsibilities associated with accessing the floating-point 7972 environment fall on the application that does so explicitly. 7973 Even though the rounding direction macros may expand to constants corresponding to the 7974 values of FLT_ROUNDS, they are not required to do so. Base Definitions, Issue 6 223 Headers 7975 For example: 7976 #include 7977 void f(double x) 7978 { 7979 #pragma STDC FENV_ACCESS ON 7980 void g(double); 7981 void h(double); 7982 /* ... */ 7983 g(x + 1); 7984 h(x + 1); 7985 /* ... */ 7986 } 7987 If the function g( ) might depend on status flags set as a side effect of the first x+1, or if the 7988 second x+1 might depend on control modes set as a side effect of the call to function g( ), then 7989 the application shall contain an appropriately placed invocation as follows: 7990 #pragma STDC FENV_ACCESS ON 7991 RATIONALE 7992 The fexcept_t Type 7993 fexcept_t does not have to be an integer type. Its values must be obtained by a call to 7994 fegetexceptflag( ), and cannot be created by logical operations from the exception macros. An 7995 implementation might simply implement fexcept_t as an int and use the representations 7996 reflected by the exception macros, but is not required to; other representations might contain 7997 extra information about the exceptions. fexcept_t might be a struct with a member for each 7998 exception (that might hold the address of the first or last floating-point instruction that caused 7999 that exception). The ISO/IEC 9899: 1999 standard makes no claims about the internals of an 8000 fexcept_t, and so the user cannot inspect it. 8001 Exception and Rounding Macros 8002 Macros corresponding to unsupported modes and rounding directions are not defined by the | 8003 implementation and must not be defined by the application. An application might use #ifdef to | 8004 test for this. | 8005 FUTURE DIRECTIONS 8006 None. 8007 SEE ALSO 8008 The System Interfaces volume of IEEE Std 1003.1-200x, feclearexcept( ), fegetenv( ), fegetexceptflag( ), 8009 fegetround( ), feholdexcept( ), feraiseexcept( ), fesetenv( ), fesetexceptflag( ), fesetround( ), fetestexcept( ), 8010 feupdateenv( ) 8011 CHANGE HISTORY 8012 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. 8013 The return types for feclearexcept( ), fegetexcepflag( ), feraiseexcept( ), fesetexceptflag( ), fegetenv( ), 8014 fesetenv( ), and feupdateenv( ) are changed from void to int for alignment with the 8015 ISO/IEC 9899: 1999 standard, Defect Report 202. 224 Technical Standard (2001) (Draft April 13, 2001) Headers 8016 NAME 8017 float.h - floating types 8018 SYNOPSIS 8019 #include 8020 DESCRIPTION 8021 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8022 conflict between the requirements described here and the ISO C standard is unintentional. This 8023 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 8024 The characteristics of floating types are defined in terms of a model that describes a 8025 representation of floating-point numbers and values that provide information about an 8026 implementation's floating-point arithmetic. 8027 The following parameters are used to define the model for each floating-point type: 8028 s Sign (±1). 8029 b Base or radix of exponent representation (an integer >1). 8030 e Exponent (an integer between a minimum emin and a maximum emax). 8031 p Precision (the number of base-b digits in the significand). 8032 fk Non-negative integers less than b (the significand digits). 8033 A floating-point number x is defined by the following model: p 8034 x = sbe fk b-k, emin e emax k =1 8035 In addition to normalized floating-point numbers (f1>0 if x 0), floating types may be able to 8036 contain other kinds of floating-point numbers, such as subnormal floating-point numbers (x 0, 8037 e=emin, f1=0) and unnormalized floating-point numbers (x 0, e>emin, f1=0), and values that are 8038 not floating-point numbers, such as infinities and NaNs. A NaN is an encoding signifying Not- 8039 a-Number. A quiet NaN propagates through almost every arithmetic operation without raising a 8040 floating-point exception; a signaling NaN generally raises a floating-point exception when 8041 occurring as an arithmetic operand. 8042 The accuracy of the floating-point operations ('+', '-', '*', '/') and of the library functions 8043 in and that return floating-point results is implementation-defined. The 8044 implementation may state that the accuracy is unknown. 8045 All integer values in the header, except FLT_ROUNDS, shall be constant expressions 8046 suitable for use in #if preprocessing directives; all floating values shall be constant expressions. 8047 All except DECIMAL_DIG, FLT_EVAL_METHOD, FLT_RADIX, and FLT_ROUNDS have 8048 separate names for all three floating-point types. The floating-point model representation is 8049 provided for all values except FLT_EVAL_METHOD and FLT_ROUNDS. 8050 The rounding mode for floating-point addition is characterized by the implementation-defined 8051 value of FLT_ROUNDS: 8052 -1 Indeterminable. 8053 0 Toward zero. 8054 1 To nearest. 8055 2 Toward positive infinity. Base Definitions, Issue 6 225 Headers 8056 3 Toward negative infinity. 8057 All other values for FLT_ROUNDS characterize implementation-defined rounding behavior. 8058 The values of operations with floating operands and values subject to the usual arithmetic 8059 conversions and of floating constants are evaluated to a format whose range and precision may 8060 be greater than required by the type. The use of evaluation formats is characterized by the 8061 implementation-defined value of FLT_EVAL_METHOD: 8062 -1 Indeterminable. 8063 0 Evaluate all operations and constants just to the range and precision of the type. 8064 1 Evaluate operations and constants of type float and double to the range and precision of the 8065 double type, evaluate long double operations and constants to the range and precision of 8066 the long double type. 8067 2 Evaluate all operations and constants to the range and precision of the long double type. 8068 All other negative values for FLT_EVAL_METHOD characterize implementation-defined 8069 behavior. 8070 The values given in the following list shall be defined as constant expressions with 8071 implementation-defined values that are greater or equal in magnitude (absolute value) to those 8072 shown, with the same sign. 8073 * Radix of exponent representation, b. 8074 FLT_RADIX 2 8075 * Number of base-FLT_RADIX digits in the floating-point significand, p. 8076 FLT_MANT_DIG 8077 DBL_MANT_DIG 8078 LDBL_MANT_DIG 8079 * Number of decimal digits, n, such that any floating-point number in the widest supported 8080 floating type with pmax radix b digits can be rounded to a floating-point number with n 8081 decimal digits and back again without change to the value. 8082 p max log10 b if b is a power of 10 otherwise 1 + pmax log10 b 8083 DECIMAL_DIG 10 8084 * Number of decimal digits, q, such that any floating-point number with q decimal digits can 8085 be rounded into a floating-point number with p radix b digits and back again without change 8086 to the q decimal digits. 8087 p log 10 b if b is a power of 10 otherwise (p - 1) log10 b 8088 FLT_DIG 6 8089 DBL_DIG 10 226 Technical Standard (2001) (Draft April 13, 2001) Headers 8090 LDBL_DIG 10 8091 * Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a 8092 normalized floating-point number, emin. 8093 FLT_MIN_EXP 8094 DBL_MIN_EXP 8095 LDBL_MIN_EXP 8096 * Minimum negative integer such that 10 raised to that power is in the range of normalized 8097 floating-point numbers. 8098 log10 bemin -1 8099 FLT_MIN_10_EXP -37 8100 DBL_MIN_10_EXP -37 8101 LDBL_MIN_10_EXP -37 8102 * Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable 8103 finite floating-point number, emax. 8104 FLT_MAX_EXP 8105 DBL_MAX_EXP 8106 LDBL_MAX_EXP 8107 * Maximum integer such that 10 raised to that power is in the range of representable finite 8108 floating-point numbers. 8109 log10((1 - b-p) bemax ) 8110 FLT_MAX_10_EXP +37 8111 DBL_MAX_10_EXP +37 8112 LDBL_MAX_10_EXP +37 8113 The values given in the following list shall be defined as constant expressions with 8114 implementation-defined values that are greater than or equal to those shown: 8115 * Maximum representable finite floating-point number. 8116 (1 - b-p ) bemax 8117 FLT_MAX 1E+37 8118 DBL_MAX 1E+37 8119 LDBL_MAX 1E+37 8120 The values given in the following list shall be defined as constant expressions with 8121 implementation-defined (positive) values that are less than or equal to those shown: 8122 * The difference between 1 and the least value greater that 1 that is representable in the given 8123 floating-point type, b1 - p. 8124 FLT_EPSILON 1E-5 8125 DBL_EPSILON 1E-9 Base Definitions, Issue 6 227 Headers 8126 LDBL_EPSILON 1E-9 8127 * Minimum normalized positive floating-point number, bemin -1 . 8128 FLT_MIN 1E-37 8129 DBL_MIN 1E-37 8130 LDBL_MIN 1E-37 8131 APPLICATION USAGE 8132 None. 8133 RATIONALE 8134 None. 8135 FUTURE DIRECTIONS 8136 None. 8137 SEE ALSO 8138 , 8139 CHANGE HISTORY 8140 First released in Issue 4. Derived from the ISO C standard. 8141 Issue 6 8142 The description of the operations with floating-point values is updated for alignment with the 8143 ISO/IEC 9899: 1999 standard. 228 Technical Standard (2001) (Draft April 13, 2001) Headers 8144 NAME 8145 fmtmsg.h - message display structures 8146 SYNOPSIS 8147 XSI #include 8148 8149 DESCRIPTION 8150 The header shall define the following macros, which expand to constant integer 8151 expressions: 8152 MM_HARD Source of the condition is hardware. 8153 MM_SOFT Source of the condition is software. 8154 MM_FIRM Source of the condition is firmware. 8155 MM_APPL Condition detected by application. 8156 MM_UTIL Condition detected by utility. 8157 MM_OPSYS Condition detected by operating system. 8158 MM_RECOVER Recoverable error. 8159 MM_NRECOV Non-recoverable error. 8160 MM_HALT Error causing application to halt. 8161 MM_ERROR Application has encountered a non-fatal fault. 8162 MM_WARNING Application has detected unusual non-error condition. 8163 MM_INFO Informative message. 8164 MM_NOSEV No severity level provided for the message. 8165 MM_PRINT Display message on standard error. 8166 MM_CONSOLE Display message on system console. 8167 The table below indicates the null values and identifiers for fmtmsg( ) arguments. The 8168 header shall define the macros in the Identifier column, which expand to constant 8169 expressions that expand to expressions of the type indicated in the Type column: 8170 __________________________________________________ 8171 _ Argument Type Null-Value Identifier _________________________________________________ 8172 label char * (char*)0 MM_NULLLBL 8173 severity int 0 MM_NULLSEV 8174 class long 0L MM_NULLMC 8175 text char * (char*)0 MM_NULLTXT 8176 action char * (char*)0 MM_NULLACT 8177 _ tag char * (char*)0 MM_NULLTAG _________________________________________________ 8178 The header shall also define the following macros for use as return values for 8179 fmtmsg( ): 8180 MM_OK The function succeeded. 8181 MM_NOTOK The function failed completely. 8182 MM_NOMSG The function was unable to generate a message on standard error, but 8183 otherwise succeeded. Base Definitions, Issue 6 229 Headers 8184 MM_NOCON The function was unable to generate a console message, but otherwise 8185 succeeded. 8186 The following shall be declared as a function and may also be defined as a macro. A function | 8187 prototype shall be provided. | 8188 int fmtmsg(long, const char *, int, 8189 const char *, const char *, const char *); 8190 APPLICATION USAGE 8191 None. 8192 RATIONALE 8193 None. 8194 FUTURE DIRECTIONS 8195 None. 8196 SEE ALSO 8197 The System Interfaces volume of IEEE Std 1003.1-200x, fmtmsg( ) 8198 CHANGE HISTORY 8199 First released in Issue 4, Version 2. 230 Technical Standard (2001) (Draft April 13, 2001) Headers 8200 NAME 8201 fnmatch.h - filename-matching types 8202 SYNOPSIS 8203 #include 8204 DESCRIPTION 8205 The header shall define the following constants: 8206 FNM_NOMATCH The string does not match the specified pattern. 8207 FNM_PATHNAME Slash in string only matches slash in pattern. 8208 FNM_PERIOD Leading period in string must be exactly matched by period in pattern. 8209 FNM_NOESCAPE Disable backslash escaping. 8210 OB XSI FNM_NOSYS Reserved. 8211 The following shall be declared as a function and may also be defined as a macro. A function | 8212 prototype shall be provided. | 8213 int fnmatch(const char *, const char *, int); 8214 APPLICATION USAGE 8215 None. 8216 RATIONALE 8217 None. 8218 FUTURE DIRECTIONS 8219 None. 8220 SEE ALSO 8221 The System Interfaces volume of IEEE Std 1003.1-200x, fnmatch( ), the Shell and Utilities volume 8222 of IEEE Std 1003.1-200x 8223 CHANGE HISTORY 8224 First released in Issue 4. Derived from the ISO POSIX-2 standard. 8225 Issue 6 8226 The constant FNM_NOSYS is marked obsolescent. Base Definitions, Issue 6 231 Headers 8227 NAME 8228 ftw.h - file tree traversal 8229 SYNOPSIS 8230 XSI #include 8231 8232 DESCRIPTION 8233 The header shall define the FTW structure that includes at least the following members: 8234 int base 8235 int level 8236 The header shall define macros for use as values of the third argument to the 8237 application-supplied function that is passed as the second argument to ftw( ) and nftw( ): 8238 FTW_F File. 8239 FTW_D Directory. 8240 FTW_DNR Directory without read permission. 8241 FTW_DP Directory with subdirectories visited. 8242 FTW_NS Unknown type; stat( ) failed. 8243 FTW_SL Symbolic link. 8244 FTW_SLN Symbolic link that names a nonexistent file. 8245 The header shall define macros for use as values of the fourth argument to nftw( ): 8246 FTW_PHYS Physical walk, does not follow symbolic links. Otherwise, nftw( ) follows 8247 links but does not walk down any path that crosses itself. 8248 FTW_MOUNT The walk does not cross a mount point. 8249 FTW_DEPTH All subdirectories are visited before the directory itself. 8250 FTW_CHDIR The walk changes to each directory before reading it. 8251 The following shall be declared as functions and may also be defined as macros. Function | 8252 prototypes shall be provided. | 8253 int ftw(const char *, 8254 int (*)(const char *, const struct stat *, int), int); 8255 int nftw(const char *, int (*) 8256 (const char *, const struct stat *, int, struct FTW*), 8257 int, int); 8258 The header shall define the stat structure and the symbolic names for st_mode and the 8259 file type test macros as described in . 8260 Inclusion of the header may also make visible all symbols from . 232 Technical Standard (2001) (Draft April 13, 2001) Headers 8261 APPLICATION USAGE 8262 None. 8263 RATIONALE 8264 None. 8265 FUTURE DIRECTIONS 8266 None. 8267 SEE ALSO 8268 , the System Interfaces volume of IEEE Std 1003.1-200x, ftw( ), nftw( ) 8269 CHANGE HISTORY 8270 First released in Issue 1. Derived from Issue 1 of the SVID. 8271 Issue 5 8272 A description of FTW_DP is added. Base Definitions, Issue 6 233 Headers 8273 NAME 8274 glob.h - pathname pattern-matching types | 8275 SYNOPSIS 8276 #include 8277 DESCRIPTION 8278 The header shall define the structures and symbolic constants used by the glob( ) 8279 function. 8280 The structure type glob_t shall contain at least the following members: 8281 size_t gl_pathc Count of paths matched by pattern. 8282 char **gl_pathv Pointer to a list of matched pathnames. | 8283 size_t gl_offs Slots to reserve at the beginning of gl_pathv. | 8284 The following constants shall be provided as values for the flags argument: 8285 GLOB_APPEND Append generated pathnames to those previously obtained. | 8286 GLOB_DOOFFS Specify how many null pointers to add to the beginning of pglob- 8287 >gl_pathv. 8288 GLOB_ERR Cause glob( ) to return on error. 8289 GLOB_MARK Each pathname that is a directory that matches pattern has a slash | 8290 appended. 8291 GLOB_NOCHECK If pattern does not match any pathname, then return a list consisting of | 8292 only pattern. | 8293 GLOB_NOESCAPE Disable backslash escaping. 8294 GLOB_NOSORT Do not sort the pathnames returned. | 8295 The following constants shall be defined as error return values: 8296 GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*errfunc)( ) 8297 returned non-zero. 8298 GLOB_NOMATCH The pattern does not match any existing pathname, and | 8299 GLOB_NOCHECK was not set in flags. | 8300 GLOB_NOSPACE An attempt to allocate memory failed. 8301 OB XSI GLOB_NOSYS Reserved. 8302 The following shall be declared as functions and may also be defined as macros. Function | 8303 prototypes shall be provided. | 8304 int glob(const char *restrict, int, int (*restrict)(const char *, int), 8305 glob_t *restrict); 8306 void globfree (glob_t *); 8307 The implementation may define additional macros or constants using names beginning with 8308 GLOB_. 234 Technical Standard (2001) (Draft April 13, 2001) Headers 8309 APPLICATION USAGE 8310 None. 8311 RATIONALE 8312 None. 8313 FUTURE DIRECTIONS 8314 None. 8315 SEE ALSO 8316 The System Interfaces volume of IEEE Std 1003.1-200x, glob( ), the Shell and Utilities volume of 8317 IEEE Std 1003.1-200x 8318 CHANGE HISTORY 8319 First released in Issue 4. Derived from the ISO POSIX-2 standard. 8320 Issue 6 8321 The restrict keyword is added to the prototype for glob( ). 8322 The constant GLOB_NOSYS is marked obsolescent. Base Definitions, Issue 6 235 Headers 8323 NAME 8324 grp.h - group structure 8325 SYNOPSIS 8326 #include 8327 DESCRIPTION 8328 The header shall declare the structure group which shall include the following 8329 members: 8330 char *gr_name The name of the group. 8331 gid_t gr_gid Numerical group ID. 8332 char **gr_mem Pointer to a null-terminated array of character 8333 pointers to member names. 8334 The gid_t type shall be defined as described in . 8335 The following shall be declared as functions and may also be defined as macros. Function | 8336 prototypes shall be provided. | 8337 struct group *getgrgid(gid_t); 8338 struct group *getgrnam(const char *); 8339 TSF int getgrgid_r(gid_t, struct group *, char *, 8340 size_t, struct group **); 8341 int getgrnam_r(const char *, struct group *, char *, 8342 size_t , struct group **); 8343 XSI struct group *getgrent(void); 8344 void endgrent(void); 8345 void setgrent(void); 8346 8347 APPLICATION USAGE 8348 None. 8349 RATIONALE 8350 None. 8351 FUTURE DIRECTIONS 8352 None. 8353 SEE ALSO 8354 , the System Interfaces volume of IEEE Std 1003.1-200x, endgrent( ), getgrgid( ), 8355 getgrnam( ) 8356 CHANGE HISTORY 8357 First released in Issue 1. 8358 Issue 5 8359 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 8360 Issue 6 8361 The following new requirements on POSIX implementations derive from alignment with the 8362 Single UNIX Specification: 8363 * The definition of gid_t is mandated. 8364 * The getgrgid_r( ) and getgrnam_r( ) functions are marked as part of the Thread-Safe Functions 8365 option. 236 Technical Standard (2001) (Draft April 13, 2001) Headers 8366 NAME 8367 iconv.h - codeset conversion facility 8368 SYNOPSIS 8369 XSI #include 8370 8371 DESCRIPTION 8372 The header shall define the following type: 8373 iconv_t Identifies the conversion from one codeset to another. 8374 The following shall be declared as functions and may also be defined as macros. Function | 8375 prototypes shall be provided. | 8376 iconv_t iconv_open(const char *, const char *); 8377 size_t iconv(iconv_t, char **restrict, size_t *restrict, char **restrict, 8378 size_t *restrict); 8379 int iconv_close(iconv_t); 8380 APPLICATION USAGE 8381 None. 8382 RATIONALE 8383 None. 8384 FUTURE DIRECTIONS 8385 None. 8386 SEE ALSO 8387 The System Interfaces volume of IEEE Std 1003.1-200x, iconv( ), iconv_close( ), iconv_open( ) 8388 CHANGE HISTORY 8389 First released in Issue 4. 8390 Issue 6 8391 The restrict keyword is added to the prototype for iconv( ). Base Definitions, Issue 6 237 Headers 8392 NAME 8393 inttypes.h - fixed size integer types 8394 SYNOPSIS 8395 #include 8396 DESCRIPTION 8397 CX Some of the functionality described on this reference page extends the ISO C standard. 8398 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 8399 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 8400 symbols in this header. 8401 The header shall include the header. 8402 The header shall include a definition of at least the following type: 8403 imaxdiv_t Structure type that is the type of the value returned by the imaxdiv( ) function. 8404 The following macros shall be defined. Each expands to a character string literal containing a 8405 conversion specifier, possibly modified by a length modifier, suitable for use within the format 8406 argument of a formatted input/output function when converting the corresponding integer 8407 type. These macros have the general form of PRI (character string literals for the fprintf( ) and 8408 fwprintf( ) family of functions) or SCN (character string literals for the fscanf( ) and fwscanf( ) 8409 family of functions), followed by the conversion specifier, followed by a name corresponding to 8410 a similar type name in . In these names, N represents the width of the type as 8411 described in . For example, PRIdFAST32 can be used in a format string to print the 8412 value of an integer of type int_fast32_t. 8413 The fprintf( ) macros for signed integers are: 8414 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR 8415 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR 8416 The fprintf( ) macros for unsigned integers are: 8417 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR 8418 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR 8419 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR 8420 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR 8421 The fscanf( ) macros for signed integers are: 8422 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR 8423 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR 8424 The fscanf( ) macros for unsigned integers are: 8425 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR 8426 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR 8427 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR 8428 For each type that the implementation provides in , the corresponding fprintf( ) 8429 macros shall be defined and the corresponding fscanf( ) macros shall be defined unless the 8430 implementation does not have a suitable fscanf length modifier for the type. 8431 The following shall be declared as functions and may also be defined as macros. Function | 8432 prototypes shall be provided. | 8433 intmax_t imaxabs(intmax_t); 8434 imaxdiv_t imaxdiv(intmax_t, intmax_t); 8435 intmax_t strtoimax(const char *restrict, char **restrict, int); 238 Technical Standard (2001) (Draft April 13, 2001) Headers 8436 uintmax_t strtoumax(const char *restrict, char **restrict, int); 8437 intmax_t wcstoimax(const wchar_t *restrict, wchar_t **restrict, int); 8438 uintmax_t wcstoumax(const wchar_t *restrict, wchar_t **restrict, int); 8439 EXAMPLES 8440 #include 8441 #include 8442 int main(void) 8443 { 8444 uintmax_t i = UINTMAX_MAX; // This type always exists. 8445 wprintf(L"The largest integer value is %020" 8446 PRIxMAX "\n", i); 8447 return 0; 8448 } 8449 APPLICATION USAGE 8450 None. 8451 RATIONALE 8452 The ISO/IEC 9899: 1990 standard specifies that the language should support four signed and 8453 unsigned integer data types-char, short, int, and long-but places very little requirement on 8454 their size other than that int and short be at least 16 bits and long be at least as long as int and 8455 not smaller than 32 bits. For 16-bit systems, most implementations assign 8, 16, 16, and 32 bits to 8456 char, short, int, and long, respectively. For 32-bit systems, the common practice is to assign 8, 16, 8457 32, and 32 bits to these types. This difference in int size can create some problems for users who 8458 migrate from one system to another which assigns different sizes to integer types, because the 8459 ISO C standard integer promotion rule can produce silent changes unexpectedly. The need for 8460 defining an extended integer type increased with the introduction of 64-bit systems. 8461 The purpose of is to provide a set of integer types whose definitions are consistent 8462 across machines and independent of operating systems and other implementation 8463 idiosyncrasies. It defines, via typedef, integer types of various sizes. Implementations are free to 8464 typedef them as ISO C standard integer types or extensions that they support. Consistent use of 8465 this header will greatly increase the portability of a users program across platforms. 8466 FUTURE DIRECTIONS 8467 Macro names beginning with PRI or SCN followed by any lowercase letter or 'X' may be added 8468 to the macros defined in the header. 8469 SEE ALSO 8470 The System Interfaces volume of IEEE Std 1003.1-200x, imaxdiv( ) 8471 CHANGE HISTORY 8472 First released in Issue 5. 8473 Issue 6 8474 The Open Group Base Resolution bwg97-006 is applied. 8475 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. Base Definitions, Issue 6 239 Headers 8476 NAME 8477 iso646.h - alternative spellings 8478 SYNOPSIS 8479 #include 8480 DESCRIPTION 8481 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8482 conflict between the requirements described here and the ISO C standard is unintentional. This 8483 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 8484 The header shall define the following eleven macros (on the left) that expand to the 8485 corresponding tokens (on the right): 8486 and && 8487 and_eq &= 8488 bitand & 8489 bitor | 8490 compl ~ 8491 not ! 8492 not_eq != 8493 or || 8494 or_eq |= 8495 xor ^ 8496 xor_eq ^= 8497 APPLICATION USAGE 8498 None. 8499 RATIONALE 8500 None. 8501 FUTURE DIRECTIONS 8502 None. 8503 SEE ALSO 8504 None. 8505 CHANGE HISTORY 8506 First released in Issue 5. Derived from ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 240 Technical Standard (2001) (Draft April 13, 2001) Headers 8507 NAME 8508 langinfo.h - language information constants 8509 SYNOPSIS 8510 XSI #include 8511 8512 DESCRIPTION 8513 The header contains the constants used to identify items of langinfo data (see 8514 nl_langinfo ( )). The type of the constant, nl_item, shall be defined as described in . 8515 The following constants shall be defined. The entries under Category indicate in which 8516 setlocale( ) category each item is defined. 8517 ______________________________________________________________________________________ 8518 _ Constant Category Meaning _____________________________________________________________________________________ 8519 CODESET LC_CTYPE Codeset name. 8520 D_T_FMT LC_TIME String for formatting date and time. 8521 D_FMT LC_TIME Date format string. 8522 T_FMT LC_TIME Time format string. 8523 T_FMT_AMPM LC_TIME a.m. or p.m. time format string. 8524 AM_STR LC_TIME Ante Meridian affix. 8525 PM_STR LC_TIME Post Meridian affix. 8526 DAY_1 LC_TIME Name of the first day of the week (for example, Sunday). 8527 DAY_2 LC_TIME Name of the second day of the week (for example, Monday). 8528 DAY_3 LC_TIME Name of the third day of the week (for example, Tuesday). 8529 DAY_4 LC_TIME Name of the fourth day of the week 8530 (for example, Wednesday). 8531 DAY_5 LC_TIME Name of the fifth day of the week (for example, Thursday). 8532 DAY_6 LC_TIME Name of the sixth day of the week (for example, Friday). 8533 DAY_7 LC_TIME Name of the seventh day of the week 8534 (for example, Saturday). 8535 ABDAY_1 LC_TIME Abbreviated name of the first day of the week. 8536 ABDAY_2 LC_TIME Abbreviated name of the second day of the week. 8537 ABDAY_3 LC_TIME Abbreviated name of the third day of the week. 8538 ABDAY_4 LC_TIME Abbreviated name of the fourth day of the week. 8539 ABDAY_5 LC_TIME Abbreviated name of the fifth day of the week. 8540 ABDAY_6 LC_TIME Abbreviated name of the sixth day of the week. 8541 ABDAY_7 LC_TIME Abbreviated name of the seventh day of the week. 8542 MON_1 LC_TIME Name of the first month of the year. 8543 MON_2 LC_TIME Name of the second month. 8544 MON_3 LC_TIME Name of the third month. 8545 MON_4 LC_TIME Name of the fourth month. 8546 MON_5 LC_TIME Name of the fifth month. 8547 MON_6 LC_TIME Name of the sixth month. 8548 MON_7 LC_TIME Name of the seventh month. 8549 MON_8 LC_TIME Name of the eighth month. 8550 MON_9 LC_TIME Name of the ninth month. 8551 MON_10 LC_TIME Name of the tenth month. 8552 MON_11 LC_TIME Name of the eleventh month. 8553 _ MON_12 LC_TIME Name of the twelfth month. _____________________________________________________________________________________ Base Definitions, Issue 6 241 Headers 8554 ______________________________________________________________________________________ 8555 _ Constant Category Meaning _____________________________________________________________________________________ 8556 ABMON_1 LC_TIME Abbreviated name of the first month. 8557 ABMON_2 LC_TIME Abbreviated name of the second month. 8558 ABMON_3 LC_TIME Abbreviated name of the third month. 8559 ABMON_4 LC_TIME Abbreviated name of the fourth month. 8560 ABMON_5 LC_TIME Abbreviated name of the fifth month. 8561 ABMON_6 LC_TIME Abbreviated name of the sixth month. 8562 ABMON_7 LC_TIME Abbreviated name of the seventh month. 8563 ABMON_8 LC_TIME Abbreviated name of the eighth month. 8564 ABMON_9 LC_TIME Abbreviated name of the ninth month. 8565 ABMON_10 LC_TIME Abbreviated name of the tenth month. 8566 ABMON_11 LC_TIME Abbreviated name of the eleventh month. 8567 ABMON_12 LC_TIME Abbreviated name of the twelfth month. 8568 ERA LC_TIME Era description segments. 8569 ERA_D_FMT LC_TIME Era date format string. 8570 ERA_D_T_FMT LC_TIME Era date and time format string. 8571 ERA_T_FMT LC_TIME Era time format string. 8572 ALT_DIGITS LC_TIME Alternative symbols for digits. 8573 RADIXCHAR LC_NUMERIC Radix character. 8574 THOUSEP LC_NUMERIC Separator for thousands. 8575 YESEXPR LC_MESSAGES Affirmative response expression. 8576 NOEXPR LC_MESSAGES Negative response expression. 8577 CRNCYSTR LC_MONETARY Currency symbol, preceded by '-' if the symbol should 8578 appear before the value, '+' if the symbol should appear 8579 after the value, or '.' if the symbol should replace the 8580 radix character. _ _____________________________________________________________________________________ 8581 If the locale's values for p_cs_precedes and n_cs_precedes do not match, the value of | 8582 nl_langinfo(CRNCYSTR) is unspecified. | 8583 The following shall be declared as a function and may also be defined as a macro. A function | 8584 prototype shall be provided. | 8585 char *nl_langinfo(nl_item); 8586 Inclusion of the header may also make visible all symbols from . 8587 APPLICATION USAGE 8588 Wherever possible, users are advised to use functions compatible with those in the ISO C 8589 standard to access items of langinfo data. In particular, the strftime( ) function should be used to 8590 access date and time information defined in category LC_TIME. The localeconv( ) function 8591 should be used to access information corresponding to RADIXCHAR, THOUSEP, and 8592 CRNCYSTR. 8593 RATIONALE 8594 None. 8595 FUTURE DIRECTIONS 8596 None. 8597 SEE ALSO 8598 The System Interfaces volume of IEEE Std 1003.1-200x, nl_langinfo ( ), localeconv( ), strfmon( ), 8599 strftime( ), Chapter 7 (on page 119) 242 Technical Standard (2001) (Draft April 13, 2001) Headers 8600 CHANGE HISTORY 8601 First released in Issue 2. 8602 Issue 5 8603 The constants YESSTR and NOSTR are marked LEGACY. 8604 Issue 6 8605 The constants YESSTR and NOSTR are removed. Base Definitions, Issue 6 243 Headers 8606 NAME 8607 libgen.h - definitions for pattern matching functions 8608 SYNOPSIS 8609 XSI #include 8610 8611 DESCRIPTION 8612 The following shall be declared as functions and may also be defined as macros. Function | 8613 prototypes shall be provided. | 8614 char *basename(char *); 8615 char *dirname(char *); 8616 APPLICATION USAGE 8617 None. 8618 RATIONALE 8619 None. 8620 FUTURE DIRECTIONS 8621 None. 8622 SEE ALSO 8623 The System Interfaces volume of IEEE Std 1003.1-200x, basename( ), dirname( ) 8624 CHANGE HISTORY 8625 First released in Issue 4, Version 2. 8626 Issue 5 8627 The function prototypes for basename( ) and dirname( ) are changed to indicate that the first 8628 argument is of type char * rather than const char *. 8629 Issue 6 8630 The _ _loc1 symbol and the regcmp( ) and regex( ) functions are removed. 244 Technical Standard (2001) (Draft April 13, 2001) Headers 8631 NAME 8632 limits.h - implementation-defined constants 8633 SYNOPSIS 8634 #include 8635 DESCRIPTION 8636 CX Some of the functionality described on this reference page extends the ISO C standard. 8637 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 8638 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 8639 symbols in this header. 8640 CX Many of the symbols listed here are not defined by the ISO/IEC 9899: 1999 standard. Such 8641 symbols are not shown as CX shaded. 8642 The header shall define various symbolic names. Different categories of names are 8643 described below. 8644 The names represent various limits on resources that the implementation imposes on 8645 applications. 8646 Implementations may choose any appropriate value for each limit, provided it is not more 8647 restrictive than the Minimum Acceptable Values listed below. Symbolic constant names 8648 beginning with _POSIX may be found in . 8649 Applications should not assume any particular value for a limit. To achieve maximum 8650 portability, an application should not require more resource than the Minimum Acceptable 8651 Value quantity. However, an application wishing to avail itself of the full amount of a resource 8652 available on an implementation may make use of the value given in on that 8653 particular implementation, by using the symbolic names listed below. It should be noted, 8654 however, that many of the listed limits are not invariant, and at runtime, the value of the limit 8655 may differ from those given in this header, for the following reasons: 8656 * The limit is pathname-dependent. | 8657 * The limit differs between the compile and runtime machines. 8658 For these reasons, an application may use the fpathconf( ), pathconf( ), and sysconf( ) functions to 8659 determine the actual value of a limit at runtime. 8660 The items in the list ending in _MIN give the most negative values that the mathematical types 8661 are guaranteed to be capable of representing. Numbers of a more negative value may be 8662 supported on some implementations, as indicated by the header on the 8663 implementation, but applications requiring such numbers are not guaranteed to be portable to 8664 all implementations. For positive constants ending in _MIN, this indicates the minimum 8665 acceptable value. 8666 The Minimum Acceptable Value symbol '*' indicates that there is no guaranteed value across 8667 all conforming implementations. Base Definitions, Issue 6 245 Headers 8668 Runtime Invariant Values (Possibly Indeterminate) 8669 A definition of one of the symbolic names in the following list shall be omitted from 8670 on specific implementations where the corresponding value is equal to or greater than the stated | 8671 minimum, but is unspecified. | 8672 This indetermination might depend on the amount of available memory space on a specific 8673 instance of a specific implementation. The actual value supported by a specific instance shall be 8674 provided by the sysconf( ) function. 8675 AIO {AIO_LISTIO_MAX} 8676 Maximum number of I/O operations in a single list I/O call supported by the 8677 implementation. 8678 Minimum Acceptable Value: {_POSIX_AIO_LISTIO_MAX} 8679 AIO {AIO_MAX} 8680 Maximum number of outstanding asynchronous I/O operations supported by the 8681 implementation. 8682 Minimum Acceptable Value: {_POSIX_AIO_MAX} 8683 AIO {AIO_PRIO_DELTA_MAX} 8684 The maximum amount by which a process can decrease its asynchronous I/O priority level 8685 from its own scheduling priority. 8686 Minimum Acceptable Value: 0 8687 {ARG_MAX} 8688 Maximum length of argument to the exec functions including environment data. 8689 Minimum Acceptable Value: {_POSIX_ARG_MAX} 8690 XSI {ATEXIT_MAX} 8691 Maximum number of functions that may be registered with atexit( ). 8692 Minimum Acceptable Value: 32 8693 {CHILD_MAX} 8694 Maximum number of simultaneous processes per real user ID. 8695 Minimum Acceptable Value: {_POSIX_CHILD_MAX} 8696 TMR {DELAYTIMER_MAX} 8697 Maximum number of timer expiration overruns. 8698 Minimum Acceptable Value: {_POSIX_DELAYTIMER_MAX} | 8699 {HOST_NAME_MAX} | 8700 Maximum length of a host name (not including the terminating null) as returned from the | 8701 gethostname( ) function. | 8702 Minimum Acceptable Value: {_POSIX_HOST_NAME_MAX} | 8703 XSI {IOV_MAX} 8704 Maximum number of iovec structures that one process has available for use with readv( ) or 8705 writev( ). 8706 Minimum Acceptable Value: {_XOPEN_IOV_MAX} 8707 {LOGIN_NAME_MAX} 8708 Maximum length of a login name. 8709 Minimum Acceptable Value: {_POSIX_LOGIN_NAME_MAX} 8710 MSG {MQ_OPEN_MAX} 8711 The maximum number of open message queue descriptors a process may hold. 8712 Minimum Acceptable Value: {_POSIX_MQ_OPEN_MAX} 246 Technical Standard (2001) (Draft April 13, 2001) Headers 8713 MSG {MQ_PRIO_MAX} 8714 The maximum number of message priorities supported by the implementation. 8715 Minimum Acceptable Value: {_POSIX_MQ_PRIO_MAX} 8716 {OPEN_MAX} 8717 Maximum number of files that one process can have open at any one time. 8718 Minimum Acceptable Value: {_POSIX_OPEN_MAX} 8719 {PAGESIZE} 8720 Size in bytes of a page. 8721 Minimum Acceptable Value: 1 8722 XSI {PAGE_SIZE} 8723 Equivalent to {PAGESIZE}. If either {PAGESIZE} or {PAGE_SIZE} is defined, the other is | 8724 defined with the same value. 8725 THR {PTHREAD_DESTRUCTOR_ITERATIONS} 8726 Maximum number of attempts made to destroy a thread's thread-specific data values on 8727 thread exit. 8728 Minimum Acceptable Value: {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} 8729 THR {PTHREAD_KEYS_MAX} 8730 Maximum number of data keys that can be created by a process. 8731 Minimum Acceptable Value: {_POSIX_THREAD_KEYS_MAX} 8732 THR {PTHREAD_STACK_MIN} 8733 Minimum size in bytes of thread stack storage. 8734 Minimum Acceptable Value: 0 8735 THR {PTHREAD_THREADS_MAX} 8736 Maximum number of threads that can be created per process. 8737 Minimum Acceptable Value: {_POSIX_THREAD_THREADS_MAX} 8738 {RE_DUP_MAX} 8739 The number of repeated occurrences of a BRE permitted by the regexec( ) and regcomp( ) 8740 functions when using the interval notation {\(m,n\}; see Section 9.3.6 (on page 170). 8741 Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} 8742 RTS {RTSIG_MAX} 8743 Maximum number of realtime signals reserved for application use in this implementation. 8744 Minimum Acceptable Value: {_POSIX_RTSIG_MAX} 8745 SEM {SEM_NSEMS_MAX} 8746 Maximum number of semaphores that a process may have. 8747 Minimum Acceptable Value: {_POSIX_SEM_NSEMS_MAX} 8748 SEM {SEM_VALUE_MAX} 8749 The maximum value a semaphore may have. 8750 Minimum Acceptable Value: {_POSIX_SEM_VALUE_MAX} 8751 RTS {SIGQUEUE_MAX} 8752 Maximum number of queued signals that a process may send and have pending at the 8753 receiver(s) at any time. 8754 Minimum Acceptable Value: {_POSIX_SIGQUEUE_MAX} 8755 SS|TSP {SS_REPL_MAX} 8756 The maximum number of replenishment operations that may be simultaneously pending 8757 for a particular sporadic server scheduler. 8758 Minimum Acceptable Value: {_POSIX_SS_REPL_MAX} Base Definitions, Issue 6 247 Headers 8759 {STREAM_MAX} 8760 The number of streams that one process can have open at one time. If defined, it has the 8761 same value as {FOPEN_MAX} (see ). 8762 Minimum Acceptable Value: {_POSIX_STREAM_MAX} 8763 {SYMLOOP_MAX} 8764 Maximum number of symbolic links that can be reliably traversed in the resolution of a | 8765 pathname in the absence of a loop. | 8766 Minimum Acceptable Value: {_POSIX_SYMLOOP_MAX} 8767 TMR {TIMER_MAX} 8768 Maximum number of timers per-process supported by the implementation. 8769 Minimum Acceptable Value: {_POSIX_TIMER_MAX} 8770 TRC {TRACE_EVENT_NAME_MAX} 8771 Maximum length of the trace event name. 8772 Minimum Acceptable Value: {_POSIX_TRACE_EVENT_NAME_MAX} 8773 TRC {TRACE_NAME_MAX} 8774 Maximum length of the trace generation version string or of the trace stream name. 8775 Minimum Acceptable Value: {_POSIX_TRACE_NAME_MAX} 8776 TRC {TRACE_SYS_MAX} 8777 Maximum number of trace streams that may simultaneously exist in the system. 8778 Minimum Acceptable Value: {_POSIX_TRACE_SYS_MAX} 8779 TRC {TRACE_USER_EVENT_MAX} 8780 Maximum number of user trace event type identifiers that may simultaneously exist in a 8781 traced process, including the predefined user trace event 8782 POSIX_TRACE_UNNAMED_USER_EVENT. 8783 Minimum Acceptable Value: {_POSIX_TRACE_USER_EVENT_MAX} 8784 {TTY_NAME_MAX} 8785 Maximum length of terminal device name. 8786 Minimum Acceptable Value: {_POSIX_TTY_NAME_MAX} 8787 {TZNAME_MAX} 8788 Maximum number of bytes supported for the name of a timezone (not of the TZ variable). 8789 Minimum Acceptable Value: {_POSIX_TZNAME_MAX} 8790 Note: The length given by {TZNAME_MAX} does not include the quoting characters mentioned in 8791 Section 8.3 (on page 161). 8792 Pathname Variable Values | 8793 The values in the following list may be constants within an implementation or may vary from | 8794 one pathname to another. For example, file systems or directories may have different | 8795 characteristics. 8796 A definition of one of the values shall be omitted from the header on specific 8797 implementations where the corresponding value is equal to or greater than the stated minimum, 8798 but where the value can vary depending on the file to which it is applied. The actual value | 8799 supported for a specific pathname shall be provided by the pathconf( ) function. | 8800 {FILESIZEBITS} 8801 Minimum number of bits needed to represent, as a signed integer value, the maximum size 8802 of a regular file allowed in the specified directory. 8803 Minimum Acceptable Value: 32 248 Technical Standard (2001) (Draft April 13, 2001) Headers 8804 {LINK_MAX} 8805 Maximum number of links to a single file. 8806 Minimum Acceptable Value: {_POSIX_LINK_MAX} 8807 {MAX_CANON} 8808 Maximum number of bytes in a terminal canonical input line. 8809 Minimum Acceptable Value: {_POSIX_MAX_CANON} 8810 {MAX_INPUT} 8811 Minimum number of bytes for which space is available in a terminal input queue; therefore, | 8812 the maximum number of bytes a conforming application may require to be typed as input | 8813 before reading them. 8814 Minimum Acceptable Value: {_POSIX_MAX_INPUT} 8815 {NAME_MAX} 8816 Maximum number of bytes in a filename (not including terminating null). 8817 Minimum Acceptable Value: {_POSIX_NAME_MAX} 8818 XSI Minimum Acceptable Value: {_XOPEN_NAME_MAX} 8819 {PATH_MAX} 8820 Maximum number of bytes in a pathname, including the terminating null character. | 8821 Minimum Acceptable Value: {_POSIX_PATH_MAX} 8822 XSI Minimum Acceptable Value: {_XOPEN_PATH_MAX} 8823 {PIPE_BUF} 8824 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. 8825 Minimum Acceptable Value: {_POSIX_PIPE_BUF} 8826 ADV {POSIX_ALLOC_SIZE_MIN} 8827 Minimum number of bytes of storage actually allocated for any portion of a file. 8828 Minimum Acceptable Value: Not specified. 8829 ADV {POSIX_REC_INCR_XFER_SIZE} 8830 Recommended increment for file transfer sizes between the 8831 {POSIX_REC_MIN_XFER_SIZE} and {POSIX_REC_MAX_XFER_SIZE} values. 8832 Minimum Acceptable Value: Not specified. 8833 ADV {POSIX_REC_MAX_XFER_SIZE} 8834 Maximum recommended file transfer size. 8835 Minimum Acceptable Value: Not specified. 8836 ADV {POSIX_REC_MIN_XFER_SIZE} 8837 Minimum recommended file transfer size. 8838 Minimum Acceptable Value: Not specified. 8839 ADV {POSIX_REC_XFER_ALIGN} 8840 Recommended file transfer buffer alignment. 8841 Minimum Acceptable Value: Not specified. 8842 {SYMLINK_MAX} 8843 Maximum number of bytes in a symbolic link. 8844 Minimum Acceptable Value: {_POSIX_SYMLINK_MAX} Base Definitions, Issue 6 249 Headers 8845 Runtime Increasable Values 8846 The magnitude limitations in the following list shall be fixed by specific implementations. An 8847 application should assume that the value supplied by in a specific implementation is 8848 the minimum that pertains whenever the application is run under that implementation. A 8849 specific instance of a specific implementation may increase the value relative to that supplied by 8850 for that implementation. The actual value supported by a specific instance shall be 8851 provided by the sysconf( ) function. 8852 {BC_BASE_MAX} 8853 Maximum obase values allowed by the bc utility. 8854 Minimum Acceptable Value: {_POSIX2_BC_BASE_MAX} 8855 {BC_DIM_MAX} 8856 Maximum number of elements permitted in an array by the bc utility. 8857 Minimum Acceptable Value: {_POSIX2_BC_DIM_MAX} 8858 {BC_SCALE_MAX} 8859 Maximum scale value allowed by the bc utility. 8860 Minimum Acceptable Value: {_POSIX2_BC_SCALE_MAX} 8861 {BC_STRING_MAX} 8862 Maximum length of a string constant accepted by the bc utility. 8863 Minimum Acceptable Value: {_POSIX2_BC_STRING_MAX} 8864 {CHARCLASS_NAME_MAX} 8865 Maximum number of bytes in a character class name. 8866 Minimum Acceptable Value: {_POSIX2_CHARCLASS_NAME_MAX} 8867 {COLL_WEIGHTS_MAX} 8868 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order 8869 keyword in the locale definition file; see Chapter 7 (on page 119). 8870 Minimum Acceptable Value: {_POSIX2_COLL_WEIGHTS_MAX} 8871 {EXPR_NEST_MAX} 8872 Maximum number of expressions that can be nested within parentheses by the expr utility. 8873 Minimum Acceptable Value: {_POSIX2_EXPR_NEST_MAX} 8874 {LINE_MAX} 8875 Unless otherwise noted, the maximum length, in bytes, of a utility's input line (either 8876 standard input or another file), when the utility is described as processing text files. The 8877 length includes room for the trailing newline. 8878 Minimum Acceptable Value: {_POSIX2_LINE_MAX} 8879 {NGROUPS_MAX} 8880 Maximum number of simultaneous supplementary group IDs per process. 8881 Minimum Acceptable Value: {_POSIX_NGROUPS_MAX} 8882 {RE_DUP_MAX} 8883 Maximum number of repeated occurrences of a regular expression permitted when using 8884 the interval notation \{m,n\}; see Chapter 9 (on page 165). 8885 Minimum Acceptable Value: {_POSIX2_RE_DUP_MAX} 250 Technical Standard (2001) (Draft April 13, 2001) Headers 8886 Maximum Values 8887 TMR The symbolic constants in the following list shall be defined in with the values 8888 shown. These are symbolic names for the most restrictive value for certain features on an 8889 implementation supporting the Timers option. A conforming implementation shall provide | 8890 values no larger than these values. A conforming application must not require a smaller value | 8891 for correct operation. 8892 TMR {_POSIX_CLOCKRES_MIN} 8893 The resolution of the CLOCK_REALTIME clock, in nanoseconds. 8894 Value: 20 000 000 8895 MON If the Monotonic Clock option is supported, the resolution of the CLOCK_MONOTONIC 8896 clock, in nanoseconds, is represented by {_POSIX_CLOCKRES_MIN}. 8897 Minimum Values 8898 The symbolic constants in the following list shall be defined in with the values 8899 shown. These are symbolic names for the most restrictive value for certain features on an 8900 implementation conforming to this volume of IEEE Std 1003.1-200x. Related symbolic constants 8901 are defined elsewhere in this volume of IEEE Std 1003.1-200x which reflect the actual 8902 implementation and which need not be as restrictive. A conforming implementation shall 8903 provide values at least this large. A strictly conforming application must not require a larger 8904 value for correct operation. 8905 AIO {_POSIX_AIO_LISTIO_MAX} 8906 The number of I/O operations that can be specified in a list I/O call. 8907 Value: 2 8908 AIO {_POSIX_AIO_MAX} 8909 The number of outstanding asynchronous I/O operations. 8910 Value: 1 8911 {_POSIX_ARG_MAX} 8912 Maximum length of argument to the exec functions including environment data. 8913 Value: 4 096 8914 {_POSIX_CHILD_MAX} 8915 Maximum number of simultaneous processes per real user ID. 8916 Value: 6 8917 TMR {_POSIX_DELAYTIMER_MAX} 8918 The number of timer expiration overruns. 8919 Value: 32 | 8920 {_POSIX_HOST_NAME_MAX} | 8921 Maximum length of a host name (not including the terminating null) as returned from the | 8922 gethostname( ) function. | 8923 Value: 255 | 8924 {_POSIX_LINK_MAX} 8925 Maximum number of links to a single file. 8926 Value: 8 8927 {_POSIX_LOGIN_NAME_MAX} 8928 The size of the storage required for a login name, in bytes, including the terminating null. 8929 Value: 9 Base Definitions, Issue 6 251 Headers 8930 {_POSIX_MAX_CANON} 8931 Maximum number of bytes in a terminal canonical input queue. 8932 Value: 255 8933 {_POSIX_MAX_INPUT} 8934 Maximum number of bytes allowed in a terminal input queue. 8935 Value: 255 8936 MSG {_POSIX_MQ_OPEN_MAX} 8937 The number of message queues that can be open for a single process. 8938 Value: 8 8939 MSG {_POSIX_MQ_PRIO_MAX} 8940 The maximum number of message priorities supported by the implementation. 8941 Value: 32 8942 {_POSIX_NAME_MAX} 8943 Maximum number of bytes in a filename (not including terminating null). 8944 Value: 14 8945 {_POSIX_NGROUPS_MAX} 8946 Maximum number of simultaneous supplementary group IDs per process. 8947 Value: 8 8948 {_POSIX_OPEN_MAX} 8949 Maximum number of files that one process can have open at any one time. 8950 Value: 20 8951 {_POSIX_PATH_MAX} 8952 Maximum number of bytes in a pathname. | 8953 Value: 256 8954 {_POSIX_PIPE_BUF} 8955 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. 8956 Value: 512 8957 {_POSIX_RE_DUP_MAX} 8958 The number of repeated occurrences of a BRE permitted by the regexec( ) and regcomp( ) 8959 functions when using the interval notation {\(m,n\}; see Section 9.3.6 (on page 170). 8960 Value: 255 8961 RTS {_POSIX_RTSIG_MAX} 8962 The number of realtime signal numbers reserved for application use. 8963 Value: 8 8964 SEM {_POSIX_SEM_NSEMS_MAX} 8965 The number of semaphores that a process may have. 8966 Value: 256 8967 SEM {_POSIX_SEM_VALUE_MAX} 8968 The maximum value a semaphore may have. 8969 Value: 32 767 8970 RTS {_POSIX_SIGQUEUE_MAX} 8971 The number of queued signals that a process may send and have pending at the receiver(s) 8972 at any time. 8973 Value: 32 252 Technical Standard (2001) (Draft April 13, 2001) Headers 8974 {_POSIX_SSIZE_MAX} 8975 The value that can be stored in an object of type ssize_t. 8976 Value: 32 767 8977 {_POSIX_STREAM_MAX} 8978 The number of streams that one process can have open at one time. 8979 Value: 8 8980 SS|TSP {_POSIX_SS_REPL_MAX} 8981 The number of replenishment operations that may be simultaneously pending for a 8982 particular sporadic server scheduler. 8983 Value: 4 8984 {_POSIX_SYMLINK_MAX} 8985 The number of bytes in a symbolic link. 8986 Value: 255 8987 {_POSIX_SYMLOOP_MAX} 8988 The number of symbolic links that can be traversed in the resolution of a pathname in the | 8989 absence of a loop. | 8990 Value: 8 8991 THR {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} 8992 The number of attempts made to destroy a thread's thread-specific data values on thread 8993 exit. 8994 Value: 4 8995 THR {_POSIX_THREAD_KEYS_MAX} 8996 The number of data keys per process. 8997 Value: 128 8998 THR {_POSIX_THREAD_THREADS_MAX} 8999 The number of threads per process. 9000 Value: 64 9001 TMR {_POSIX_TIMER_MAX} 9002 The per process number of timers. 9003 Value: 32 9004 TRC {_POSIX_TRACE_EVENT_NAME_MAX} 9005 The length in bytes of a trace event name. 9006 Value: 30 9007 TRC {_POSIX_TRACE_NAME_MAX} 9008 The length in bytes of a trace generation version string or a trace stream name. 9009 Value: 8 9010 TRC {_POSIX_TRACE_SYS_MAX} 9011 The number of trace streams that may simultaneously exist in the system. 9012 Value: 8 9013 TRC {_POSIX_TRACE_USER_EVENT_MAX} 9014 The number of user trace event type identifiers that may simultaneously exist in a traced 9015 process, including the predefined user trace event 9016 POSIX_TRACE_UNNAMED_USER_EVENT. 9017 Value: 32 9018 {_POSIX_TTY_NAME_MAX} 9019 The size of the storage required for a terminal device name, in bytes, including the Base Definitions, Issue 6 253 Headers 9020 terminating null. 9021 Value: 9 9022 {_POSIX_TZNAME_MAX} 9023 Maximum number of bytes supported for the name of a timezone (not of the TZ variable). 9024 Value: 6 9025 Note: The length given by {_POSIX_TZNAME_MAX} does not include the quoting characters 9026 mentioned in Section 8.3 (on page 161). 9027 {_POSIX2_BC_BASE_MAX} 9028 Maximum obase values allowed by the bc utility. 9029 Value: 99 9030 {_POSIX2_BC_DIM_MAX} 9031 Maximum number of elements permitted in an array by the bc utility. 9032 Value: 2 048 9033 {_POSIX2_BC_SCALE_MAX} 9034 Maximum scale value allowed by the bc utility. 9035 Value: 99 9036 {_POSIX2_BC_STRING_MAX} 9037 Maximum length of a string constant accepted by the bc utility. 9038 Value: 1 000 9039 {_POSIX2_CHARCLASS_NAME_MAX} 9040 Maximum number of bytes in a character class name. 9041 Value: 14 9042 {_POSIX2_COLL_WEIGHTS_MAX} 9043 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order 9044 keyword in the locale definition file; see Chapter 7 (on page 119). 9045 Value: 2 9046 {_POSIX2_EXPR_NEST_MAX} 9047 Maximum number of expressions that can be nested within parentheses by the expr utility. 9048 Value: 32 9049 {_POSIX2_LINE_MAX} 9050 Unless otherwise noted, the maximum length, in bytes, of a utility's input line (either 9051 standard input or another file), when the utility is described as processing text files. The 9052 length includes room for the trailing newline. 9053 Value: 2 048 9054 {_POSIX2_RE_DUP_MAX] 9055 Maximum number of repeated occurrences of a regular expression permitted when using 9056 the interval notation \{m,n\}; see Chapter 9 (on page 165). 9057 Value: 255 9058 XSI {_XOPEN_IOV_MAX} 9059 Maximum number of iovec structures that one process has available for use with readv( ) or 9060 writev( ). 9061 Value: 16 9062 XSI {_XOPEN_NAME_MAX} 9063 Maximum number of bytes in a filename (not including terminating null). 9064 Value: 255 254 Technical Standard (2001) (Draft April 13, 2001) Headers 9065 XSI {_XOPEN_PATH_MAX} 9066 Maximum number of bytes in a pathname. | 9067 Value: 1 024 9068 Numerical Limits 9069 The values in the following lists shall be defined in and are constant expressions 9070 XSI suitable for use in #if preprocessing directives. Moreover, except for {CHAR_BIT}, {DBL_DIG}, 9071 {DBL_MAX}, {FLT_DIG}, {FLT_MAX}, {LONG_BIT}, {WORD_BIT}, and {MB_LEN_MAX}, the 9072 symbolic names are defined as expressions of the correct type. 9073 If the value of an object of type char is treated as a signed integer when used in an expression, 9074 the value of {CHAR_MIN} is the same as that of {SCHAR_MIN} and the value of {CHAR_MAX} 9075 is the same as that of {SCHAR_MAX}. Otherwise, the value of {CHAR_MIN} is 0 and the value 9076 of {CHAR_MAX} is the same as that of {UCHAR_MAX}. 9077 {CHAR_BIT} 9078 Number of bits in a type char. 9079 CX Value: 8 | 9080 {CHAR_MAX} 9081 Maximum value of type char. 9082 Minimum Acceptable Value: {UCHAR_MAX} or {SCHAR_MAX} 9083 {INT_MAX} 9084 Maximum value of an int. 9085 Minimum Acceptable Value: 2 147 483 647 9086 XSI {LONG_BIT} 9087 Number of bits in a long. 9088 Minimum Acceptable Value: 32 9089 {LONG_MAX} 9090 Maximum value of a long. 9091 Minimum Acceptable Value: +2 147 483 647 9092 {MB_LEN_MAX} 9093 Maximum number of bytes in a character, for any supported locale. 9094 Minimum Acceptable Value: 1 9095 {SCHAR_MAX} 9096 Maximum value of type signed char. 9097 CX Value: +127 | 9098 {SHRT_MAX} 9099 Maximum value of type short. 9100 Minimum Acceptable Value: +32 767 9101 {SSIZE_MAX} 9102 Maximum value of an object of type ssize_t. 9103 Minimum Acceptable Value: {_POSIX_SSIZE_MAX} 9104 {UCHAR_MAX} 9105 Maximum value of type unsigned char. 9106 CX Value: 255 | 9107 {UINT_MAX} 9108 Maximum value of type unsigned. 9109 Minimum Acceptable Value: 4 294 967 295 Base Definitions, Issue 6 255 Headers 9110 {ULONG_MAX} 9111 Maximum value of type unsigned long. 9112 Minimum Acceptable Value: 4 294 967 295 9113 {USHRT_MAX} 9114 Maximum value for a type unsigned short. 9115 Minimum Acceptable Value: 65 535 9116 XSI {WORD_BIT} 9117 Number of bits in a word or type int. 9118 Minimum Acceptable Value: 16 9119 {CHAR_MIN} 9120 Minimum value of type char. 9121 Maximum Acceptable Value: {SCHAR_MIN} or 0 9122 {INT_MIN} 9123 Minimum value of type int. 9124 Maximum Acceptable Value: -2 147 483 647 9125 {LONG_MIN} 9126 Minimum value of type long. 9127 Maximum Acceptable Value: -2 147 483 647 9128 {SCHAR_MIN} 9129 Minimum value of type signed char. 9130 CX Value: -128 | 9131 {SHRT_MIN} 9132 Minimum value of type short. 9133 Maximum Acceptable Value: -32 767 9134 {LLONG_MIN} 9135 Minimum value of type long long. 9136 Maximum Acceptable Value: -9223372036854775807 9137 {LLONG_MAX} 9138 Maximum value of type long long. 9139 Minimum Acceptable Value: +9223372036854775807 9140 {ULLONG_MAX} 9141 Maximum value of type unsigned long long. 9142 Minimum Acceptable Value: 18446744073709551615 9143 Other Invariant Values 9144 XSI The following constants shall be defined on all implementations in : 9145 XSI {CHARCLASS_NAME_MAX} 9146 Maximum number of bytes in a character class name. 9147 Minimum Acceptable Value: 14 9148 XSI {NL_ARGMAX} 9149 Maximum value of digit in calls to the printf( ) and scanf( ) functions. 9150 Minimum Acceptable Value: 9 9151 XSI {NL_LANGMAX} 9152 Maximum number of bytes in a LANG name. 9153 Minimum Acceptable Value: 14 256 Technical Standard (2001) (Draft April 13, 2001) Headers 9154 XSI {NL_MSGMAX} 9155 Maximum message number. 9156 Minimum Acceptable Value: 32 767 9157 XSI {NL_NMAX} 9158 Maximum number of bytes in an N-to-1 collation mapping. 9159 Minimum Acceptable Value: '*' 9160 XSI {NL_SETMAX} 9161 Maximum set number. 9162 Minimum Acceptable Value: 255 9163 XSI {NL_TEXTMAX} 9164 Maximum number of bytes in a message string. 9165 Minimum Acceptable Value: {_POSIX2_LINE_MAX} 9166 XSI {NZERO} 9167 Default process priority. 9168 Minimum Acceptable Value: 20 9169 APPLICATION USAGE 9170 None. 9171 RATIONALE 9172 A request was made to reduce the value of {_POSIX_LINK_MAX} from the value of 8 specified 9173 for it in the POSIX.1-1990 standard to 2. The standard developers decided to deny this request 9174 for several reasons. 9175 * They wanted to avoid making any changes to the standard that could break conforming 9176 applications, and the requested change could have that effect. 9177 * The use of multiple hard links to a file cannot always be replaced with use of symbolic links. 9178 Symbolic links are semantically different from hard links in that they associate a pathname | 9179 with another pathname rather than a pathname with a file. This has implications for access | 9180 control, file permanence, and transparency. 9181 * The original standard developers had considered the issue of allowing for implementations 9182 that did not in general support hard links, and decided that this would reduce consensus on 9183 the standard. 9184 Systems that support historical versions of the development option of the ISO POSIX-2 standard 9185 retain the name {_POSIX2_RE_DUP_MAX} as an alias for {_POSIX_RE_DUP_MAX}. 9186 {PATH_MAX} 9187 IEEE PASC Interpretation 1003.1 #15 addressed the inconsistency in the standard with the | 9188 definition of pathname and the description of {PATH_MAX}, allowing application writers to | 9189 allocate either {PATH_MAX} or {PATH_MAX}+1 bytes. The inconsistency has been 9190 removed by correction to the {PATH_MAX} definition to include the null character. With 9191 this change, applications that previously allocated {PATH_MAX} bytes will continue to 9192 succeed. 9193 {SYMLINK_MAX} 9194 This symbol refers to space for data that is stored in the file system, as opposed to 9195 {PATH_MAX} which is the length of a name that can be passed to a function. In some 9196 existing implementations, the filenames pointed to by symbolic links are stored in the 9197 inodes of the links, so it is important that {SYMLINK_MAX} not be constrained to be as 9198 large as {PATH_MAX}. Base Definitions, Issue 6 257 Headers 9199 FUTURE DIRECTIONS 9200 None. 9201 SEE ALSO 9202 The System Interfaces volume of IEEE Std 1003.1-200x, fpathconf( ), pathconf( ), sysconf( ) 9203 CHANGE HISTORY 9204 First released in Issue 1. 9205 Issue 5 9206 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 9207 Threads Extension. 9208 {FILESIZEBITS} added for the Large File Summit extensions. 9209 The minimum acceptable values for {INT_MAX}, {INT_MIN}, and {UINT_MAX} are changed to 9210 make 32-bit values the minimum requirement. 9211 The entry is restructured to improve readability. 9212 Issue 6 9213 The Open Group Corrigendum U033/4 is applied. The wording is made clear for {CHAR_MIN}, 9214 {INT_MIN}, {LONG_MIN}, {SCHAR_MIN}, and {SHRT_MIN} that these are maximum 9215 acceptable values. 9216 The following new requirements on POSIX implementations derive from alignment with the 9217 Single UNIX Specification: 9218 * The minimum value for {CHILD_MAX} is 25. This is a FIPS requirement. 9219 * The minimum value for {OPEN_MAX} is 20. This is a FIPS requirement. 9220 * The minimum value for {NGROUPS_MAX} is 8. This is also a FIPS requirement. 9221 Symbolic constants are added for {_POSIX_SYMLINK_MAX}, {_POSIX_SYMLOOP_MAX}, 9222 {_POSIX_RE_DUP_MAX}, {RE_DUP_MAX}, {SYMLOOP_MAX}, and {SYMLINK_MAX}. 9223 The following values are added for alignment with IEEE Std 1003.1d-1999: 9224 {_POSIX_SS_REPL_MAX} 9225 {SS_REPL_MAX} 9226 {POSIX_ALLOC_SIZE_MIN} 9227 {POSIX_REC_INCR_XFER_SIZE} 9228 {POSIX_REC_MAX_XFER_SIZE} 9229 {POSIX_REC_MIN_XFER_SIZE} 9230 {POSIX_REC_XFER_ALIGN} 9231 Reference to CLOCK_MONOTONIC is added in the description of {_POSIX_CLOCKRES_MIN} 9232 for alignment with IEEE Std 1003.1j-2000. 9233 The constants {LLONG_MIN}, {LLONG_MAX}, and {ULLONG_MAX} are added for alignment 9234 with the ISO/IEC 9899: 1999 standard. 9235 The following values are added for alignment with IEEE Std 1003.1q-2000: | 258 Technical Standard (2001) (Draft April 13, 2001) Headers 9236 {_POSIX_TRACE_EVENT_NAME_MAX} || 9237 {_POSIX_TRACE_NAME_MAX} || 9238 {_POSIX_TRACE_SYS_MAX} || 9239 {_POSIX_TRACE_USER_EVENT_MAX} || 9240 {TRACE_EVENT_NAME_MAX} || 9241 {TRACE_NAME_MAX} || 9242 {TRACE_SYS_MAX} || 9243 {TRACE_USER_EVENT_MAX} || 9244 The new limits {_XOPEN_NAME_MAX} and {_XOPEN_PATH_MAX} are added as minimum | 9245 values for {PATH_MAX} and {NAME_MAX} limits on XSI-conformant systems. 9246 The legacy symbols {PASS_MAX} and {TMP_MAX} are removed. | 9247 The values for the limits {CHAR_BIT}, {CHAR_MAX}, {SCHAR_MAX}, and {UCHAR_MAX} are | 9248 now required to be 8, +127, 255, and -128, respectively. | Base Definitions, Issue 6 259 Headers 9249 NAME 9250 locale.h - category macros 9251 SYNOPSIS 9252 #include 9253 DESCRIPTION 9254 CX Some of the functionality described on this reference page extends the ISO C standard. Any | 9255 conflict between the requirements described here and the ISO C standard is unintentional. This | 9256 volume of IEEE Std 1003.1-200x defers to the ISO C standard. | 9257 The header shall provide a definition for structure lconv, which shall include at least 9258 the following members. (See the definitions of LC_MONETARY in the Section 7.3.3 (on page 9259 138), and Section 7.3.4 (on page 141).) 9260 char *currency_symbol 9261 char *decimal_point 9262 char frac_digits 9263 char *grouping 9264 char *int_curr_symbol 9265 char int_frac_digits 9266 char int_n_cs_precedes 9267 char int_n_sep_by_space 9268 char int_n_sign_posn 9269 char int_p_cs_precedes 9270 char int_p_sep_by_space 9271 char int_p_sign_posn 9272 char *mon_decimal_point 9273 char *mon_grouping 9274 char *mon_thousands_sep 9275 char *negative_sign 9276 char n_cs_precedes 9277 char n_sep_by_space 9278 char n_sign_posn 9279 char *positive_sign 9280 char p_cs_precedes 9281 char p_sep_by_space 9282 char p_sign_posn 9283 char *thousands_sep 9284 The header shall define NULL (as defined in ) and at least the following as 9285 macros: 9286 LC_ALL 9287 LC_COLLATE 9288 LC_CTYPE 9289 CX LC_MESSAGES 9290 LC_MONETARY 9291 LC_NUMERIC 9292 LC_TIME 9293 which shall expand to distinct integer constant expressions, for use as the first argument to the 9294 setlocale( ) function. 9295 Additional macro definitions, beginning with the characters LC_ and an uppercase letter, may 9296 also be given here. 260 Technical Standard (2001) (Draft April 13, 2001) Headers 9297 The following shall be declared as functions and may also be defined as macros. Function | 9298 prototypes shall be provided. | 9299 struct lconv *localeconv (void); 9300 char *setlocale(int, const char *); | 9301 APPLICATION USAGE | 9302 None. 9303 RATIONALE 9304 None. 9305 FUTURE DIRECTIONS 9306 None. 9307 SEE ALSO 9308 The System Interfaces volume of IEEE Std 1003.1-200x, localeconv( ), setlocale( ), Chapter 8 (on 9309 page 157) 9310 CHANGE HISTORY 9311 First released in Issue 3. 9312 Entry included for alignment with the ISO C standard. 9313 Issue 6 9314 The lconv structure is expanded with new members (int_n_cs_precedes, int_n_sep_by_space, 9315 int_n_sign_posn, int_p_cs_precedes, int_p_sep_by_space, and int_p_sign_posn) for alignment 9316 with the ISO/IEC 9899: 1999 standard. 9317 Extensions beyond the ISO C standard are now marked. Base Definitions, Issue 6 261 Headers 9318 NAME 9319 math.h - mathematical declarations 9320 SYNOPSIS 9321 #include 9322 DESCRIPTION 9323 CX Some of the functionality described on this reference page extends the ISO C standard. 9324 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 9325 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 9326 symbols in this header. 9327 The header shall include definitions for at least the following types: | 9328 float_t A real-floating type at least as wide as float. | 9329 double_t A real-floating type at least as wide as double, and at least as wide as float_t. | 9330 If FLT_EVAL_METHOD equals 0, float_t and double_t shall be float and double, respectively; if 9331 FLT_EVAL_METHOD equals 1, they shall both be double; if FLT_EVAL_METHOD equals 2, 9332 they shall both be long double; for other values of FLT_EVAL_METHOD, they are otherwise 9333 implementation-defined. 9334 The header shall define the following macros, where real-floating indicates that the 9335 argument shall be an expression of real-floating type: 9336 int fpclassify(real-floating x); 9337 int isfinite(real-floating x); 9338 int isinf(real-floating x); 9339 int isnan(real-floating x); 9340 int isnormal(real-floating x); 9341 int signbit(real-floating x); 9342 int isgreater(real-floating x, real-floating y); 9343 int isgreaterequal(real-floating x, real-floating y); 9344 int isless(real-floating x, real-floating y); 9345 int islessequal(real-floating x, real-floating y); 9346 int islessgreater(real-floating x, real-floating y); 9347 int isunordered(real-floating x, real-floating y); 9348 The header shall provide for the following constants. The values are of type double 9349 and are accurate within the precision of the double type. 9350 XSI M_E Value of e 9351 M_LOG2E Value of log2e 9352 M_LOG10E Value of log10e 9353 M_LN2 Value of loge2 9354 M_LN10 Value of loge10 9355 M_PI Value of 9356 M_PI_2 Value of /2 9357 M_PI_4 Value of /4 9358 M_1_PI Value of 1/ 9359 M_2_PI Value of 2/ 262 Technical Standard (2001) (Draft April 13, 2001) Headers 9360 M_2_SQRTPI Value of 2/ 9361 M_SQRT2 Value of 2 9362 M_SQRT1_2 Value of 1/ 2 9363 The header shall define the following symbolic constants: 9364 XSI MAXFLOAT Value of maximum non-infinite single-precision floating-point number. 9365 HUGE_VAL A positive double expression, not necessarily representable as a float. Used 9366 as an error value returned by the mathematics library. HUGE_VAL evaluates 9367 to +infinity on systems supporting IEEE Std 754-1985. 9368 HUGE_VALF A positive float constant expression. Used as an error value returned by the 9369 mathematics library. HUGE_VALF evaluates to +infinity on systems 9370 supporting IEEE Std 754-1985. 9371 HUGE_VALL A positive long double constant expression. Used as an error value returned 9372 by the mathematics library. HUGE_VALL evaluates to +infinity on systems 9373 supporting IEEE Std 754-1985. 9374 INFINITY A constant expression of type float representing positive or unsigned infinity, 9375 if available; else a positive constant of type float that overflows at translation 9376 time. 9377 NAN A constant expression of type float representing a quiet NaN. This symbolic 9378 constant is only defined if the implementation supports quiet NaNs for the 9379 float type. 9380 The following macros shall be defined for number classification. They represent the mutually- 9381 exclusive kinds of floating-point values. They expand to integer constant expressions with 9382 distinct values. Additional implementation-defined floating-point classifications, with macro 9383 definitions beginning with FP_ and an uppercase letter, may also be specified by the 9384 implementation. 9385 FP_INFINITE | 9386 FP_NAN | 9387 FP_NORMAL | 9388 FP_SUBNORMAL | 9389 FP_ZERO | 9390 The following optional macros indicate whether the fma( ) family of functions are fast compared 9391 with direct code: 9392 FP_FAST_FMA | 9393 FP_FAST_FMAF | 9394 FP_FAST_FMAL | 9395 The FP_FAST_FMA macro shall be defined to indicate that the fma( ) function generally executes 9396 about as fast as, or faster than, a multiply and an add of double operands. The other macros 9397 have the equivalent meaning for the float and long double versions. 9398 The following macros shall expand to integer constant expressions whose values are returned by 9399 ilogb(x) if x is zero or NaN, respectively. The value of FP_ILOGB0 shall be either {INT_MIN} or 9400 -{INT_MAX}. The value of FP_ILOGBNAN shall be either {INT_MAX} or {INT_MIN}. 9401 FP_ILOGB0 | 9402 FP_ILOGBNAN | Base Definitions, Issue 6 263 Headers 9403 The following macros shall expand to the integer constants 1 and 2, respectively; 9404 MATH_ERRNO | 9405 MATH_ERREXCEPT | 9406 The following macro shall expand to an expression that has type int and the value 9407 MATH_ERRNO, MATH_ERREXCEPT, or the bitwise-inclusive OR of both: 9408 math_errhandling | 9409 The value of math_errhandling is constant for the duration of the program. It is unspecified | 9410 whether math_errhandling is a macro or an identifier with external linkage. If a macro definition | 9411 is suppressed or a program defines an identifier with the name math_errhandling , the behavior | 9412 is undefined. If the expression (math_errhandling & MATH_ERREXCEPT) can be non-zero, the | 9413 implementation shall define the macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in | 9414 . 9415 The following shall be declared as functions and may also be defined as macros. Function | 9416 prototypes shall be provided. | 9417 double acos(double); 9418 float acosf(float); 9419 double acosh(double); 9420 float acoshf(float); 9421 long double acoshl(long double); 9422 long double acosl(long double); 9423 double asin(double); 9424 float asinf(float); 9425 double asinh(double); 9426 float asinhf(float); 9427 long double asinhl(long double); 9428 long double asinl(long double); 9429 double atan(double); 9430 double atan2(double, double); 9431 float atan2f(float, float); 9432 long double atan2l(long double, long double); 9433 float atanf(float); 9434 double atanh(double); 9435 float atanhf(float); 9436 long double atanhl(long double); 9437 long double atanl(long double); 9438 double cbrt(double); 9439 float cbrtf(float); 9440 long double cbrtl(long double); 9441 double ceil(double); 9442 float ceilf(float); 9443 long double ceill(long double); 9444 double copysign(double, double); 9445 float copysignf(float, float); 9446 long double copysignl(long double, long double); 9447 double cos(double); 9448 float cosf(float); 9449 double cosh(double); 9450 float coshf(float); 9451 long double coshl(long double); 264 Technical Standard (2001) (Draft April 13, 2001) Headers 9452 long double cosl(long double); 9453 double erf(double); 9454 double erfc(double); 9455 float erfcf(float); 9456 long double erfcl(long double); 9457 float erff(float); 9458 long double erfl(long double); 9459 double exp(double); 9460 double exp2(double); 9461 float exp2f(float); 9462 long double exp2l(long double); 9463 float expf(float); 9464 long double expl(long double); 9465 double expm1(double); 9466 float expm1f(float); 9467 long double expm1l(long double); 9468 double fabs(double); 9469 float fabsf(float); 9470 long double fabsl(long double); 9471 double fdim(double, double); 9472 float fdimf(float, float); 9473 long double fdiml(long double, long double); 9474 double floor(double); 9475 float floorf(float); 9476 long double floorl(long double); 9477 double fma(double, double, double); 9478 float fmaf(float, float, float); 9479 long double fmal(long double, long double, long double); 9480 double fmax(double, double); 9481 float fmaxf(float, float); 9482 long double fmaxl(long double, long double); 9483 double fmin(double, double); 9484 float fminf(float, float); 9485 long double fminl(long double, long double); 9486 double fmod(double, double); 9487 float fmodf(float, float); 9488 long double fmodl(long double, long double); 9489 double frexp(double, int *); 9490 float frexpf(float value, int *); 9491 long double frexpl(long double value, int *); 9492 double hypot(double, double); 9493 float hypotf(float, float); 9494 long double hypotl(long double, long double); 9495 int ilogb(double); 9496 int ilogbf(float); 9497 int ilogbl(long double); 9498 XSI double j0(double); 9499 double j1(double); 9500 double jn(int, double); 9501 double ldexp(double, int); 9502 float ldexpf(float, int); 9503 long double ldexpl(long double, int); Base Definitions, Issue 6 265 Headers 9504 double lgamma(double); 9505 float lgammaf(float); 9506 long double lgammal(long double); 9507 long long llrint(double); | 9508 long long llrintf(float); | 9509 long long llrintl(long double); | 9510 long long llround(double); | 9511 long long llroundf(float); | 9512 long long llroundl(long double); | 9513 double log(double); | 9514 double log10(double); 9515 float log10f(float); 9516 long double log10l(long double); 9517 double log1p(double); 9518 float log1pf(float); 9519 long double log1pl(long double); 9520 double log2(double); 9521 float log2f(float); 9522 long double log2l(long double); 9523 double logb(double); 9524 float logbf(float); 9525 long double logbl(long double); 9526 float logf(float); 9527 long double logl(long double); 9528 long lrint(double); | 9529 long lrintf(float); 9530 long lrintl(long double); 9531 long lround(double); 9532 long lroundf(float); 9533 long lroundl(long double); 9534 double modf(double, double *); 9535 float modff(float, float *); 9536 long double modfl(long double, long double *); 9537 double nan(const char *); 9538 float nanf(const char *); 9539 long double nanl(const char *); 9540 double nearbyint(double); 9541 float nearbyintf(float); 9542 long double nearbyintl(long double); 9543 double nextafter(double, double); 9544 float nextafterf(float, float); 9545 long double nextafterl(long double, long double); 9546 double nexttoward(double, long double); 9547 float nexttowardf(float, long double); 9548 long double nexttowardl(long double, long double); 9549 double pow(double, double); 9550 float powf(float, float); 9551 long double powl(long double, long double); 9552 double remainder(double, double); 9553 float remainderf(float, float); 9554 long double remainderl(long double, long double); 9555 double remquo(double, double, int *); 266 Technical Standard (2001) (Draft April 13, 2001) Headers 9556 float remquof(float, float, int *); 9557 long double remquol(long double, long double, int *); 9558 double rint(double); 9559 float rintf(float); 9560 long double rintl(long double); 9561 double round(double); 9562 float roundf(float); 9563 long double roundl(long double); 9564 XSI double scalb(double, double); 9565 double scalbln(double, long); 9566 float scalblnf(float, long); 9567 long double scalblnl(long double, long); 9568 double scalbn(double, int); 9569 float scalbnf(float, int); 9570 long double scalbnl(long double, int); 9571 double sin(double); 9572 float sinf(float); 9573 double sinh(double); 9574 float sinhf(float); 9575 long double sinhl(long double); 9576 long double sinl(long double); 9577 double sqrt(double); 9578 float sqrtf(float); 9579 long double sqrtl(long double); 9580 double tan(double); 9581 float tanf(float); 9582 double tanh(double); 9583 float tanhf(float); 9584 long double tanhl(long double); 9585 long double tanl(long double); 9586 double tgamma(double); 9587 float tgammaf(float); 9588 long double tgammal(long double); 9589 double trunc(double); 9590 float truncf(float); 9591 long double truncl(long double); 9592 XSI double y0(double); 9593 double y1(double); 9594 double yn(int, double); 9595 9596 The following external variable shall be defined: 9597 XSI extern int signgam; 9598 9599 The behavior of each of the functions defined in is specified in the System Interfaces 9600 volume of IEEE Std 1003.1-200x for all representable values of its input arguments, except where 9601 stated otherwise. Each function shall execute as if it were a single operation without generating 9602 any externally visible exceptional conditions. Base Definitions, Issue 6 267 Headers 9603 APPLICATION USAGE 9604 The FP_CONTRACT pragma can be used to allow (if the state is on) or disallow (if the state is 9605 off) the implementation to contract expressions. Each pragma can occur either outside external 9606 declarations or preceding all explicit declarations and statements inside a compound statement. 9607 When outside external declarations, the pragma takes effect from its occurrence until another 9608 FP_CONTRACT pragma is encountered, or until the end of the translation unit. When inside a 9609 compound statement, the pragma takes effect from its occurrence until another FP_CONTRACT 9610 pragma is encountered (including within a nested compound statement), or until the end of the 9611 compound statement; at the end of a compound statement the state for the pragma is restored to 9612 its condition just before the compound statement. If this pragma is used in any other context, the 9613 behavior is undefined. The default state (on or off) for the pragma is implementation-defined. 9614 RATIONALE 9615 Before the ISO/IEC 9899: 1999 standard, the math library was defined only for the floating type 9616 double. All the names formed by appending 'f' or 'l' to a name in were reserved 9617 to allow for the definition of float and long double libraries; and the ISO/IEC 9899: 1999 9618 standard provides for all three versions of math functions. 9619 The functions ecvt( ), fcvt( ), and gcvt( ) have been dropped from the ISO C standard since their 9620 capability is available through sprintf( ). These are provided on XSI-conformant systems 9621 supporting the Legacy Option Group. 9622 FUTURE DIRECTIONS 9623 None. 9624 SEE ALSO 9625 The System Interfaces volume of IEEE Std 1003.1-200x, acos( ), acosh( ), asin( ), atan( ), atan2( ), 9626 cbrt( ), ceil( ), cos( ), cosh( ), erf( ), exp( ), expm1( ), fabs( ), floor( ), fmod( ), frexp( ), hypot( ), ilogb( ), 9627 isnan( ), j0( ), ldexp( ), lgamma( ), log( ), log10( ), log1p( ), logb( ), modf( ), nextafter( ), pow( ), 9628 remainder( ), rint( ), scalb( ), sin( ), sinh( ), sqrt( ), tan( ), tanh( ), y0( ) 9629 CHANGE HISTORY 9630 First released in Issue 1. 9631 Issue 6 9632 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. 268 Technical Standard (2001) (Draft April 13, 2001) Headers 9633 NAME 9634 monetary.h - monetary types 9635 SYNOPSIS 9636 XSI #include 9637 9638 DESCRIPTION 9639 The header shall define the following types: 9640 size_t As described in . 9641 ssize_t As described in . 9642 The following shall be declared as a function and may also be defined as a macro. A function | 9643 prototype shall be provided. | 9644 ssize_t strfmon(char *restrict, size_t, const char *restrict, ...); 9645 APPLICATION USAGE 9646 None. 9647 RATIONALE 9648 None. 9649 FUTURE DIRECTIONS 9650 None. 9651 SEE ALSO 9652 The System Interfaces volume of IEEE Std 1003.1-200x, strfmon( ) 9653 CHANGE HISTORY 9654 First released in Issue 4. 9655 Issue 6 9656 The restrict keyword is added to the prototype for strfmon( ). Base Definitions, Issue 6 269 Headers 9657 NAME 9658 mqueue.h - message queues (REALTIME) 9659 SYNOPSIS 9660 MSG #include 9661 9662 DESCRIPTION 9663 The header shall define the mqd_t type, which is used for message queue 9664 descriptors. This is not an array type. 9665 The header shall define the sigevent structure (as described in ) and the 9666 mq_attr structure, which is used in getting and setting the attributes of a message queue. 9667 Attributes are initially set when the message queue is created. An mq_attr structure shall have at 9668 least the following fields: 9669 long mq_flags Message queue flags. 9670 long mq_maxmsg Maximum number of messages. 9671 long mq_msgsize Maximum message size. 9672 long mq_curmsgs Number of messages currently queued. 9673 The following shall be declared as functions and may also be defined as macros. Function | 9674 prototypes shall be provided. | 9675 int mq_close(mqd_t); 9676 int mq_getattr(mqd_t, struct mq_attr *); 9677 int mq_notify(mqd_t, const struct sigevent *); 9678 mqd_t mq_open(const char *, int, ...); 9679 ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); 9680 int mq_send(mqd_t, const char *, size_t, unsigned ); 9681 int mq_setattr(mqd_t, const struct mq_attr *restrict, 9682 struct mq_attr *restrict); 9683 TMO ssize_t mq_timedreceive(mqd_t, char *restrict, size_t, 9684 unsigned *restrict, const struct timespec *restrict); 9685 int mq_timedsend(mqd_t, const char *, size_t, unsigned , 9686 const struct timespec *); 9687 int mq_unlink(const char *); 9688 Inclusion of the header may make visible symbols defined in the headers , 9689 , , and . 9690 APPLICATION USAGE 9691 None. 9692 RATIONALE 9693 None. 9694 FUTURE DIRECTIONS 9695 None. 9696 SEE ALSO 9697 , , , , the System Interfaces volume of 9698 IEEE Std 1003.1-200x, mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), 9699 mq_setattr( ), mq_timedreceive( ), mq_timedsend( ), mq_unlink( ) 270 Technical Standard (2001) (Draft April 13, 2001) Headers 9700 CHANGE HISTORY 9701 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 9702 Issue 6 9703 The header is marked as part of the Message Passing option. 9704 The mq_timedreceive( ) and mq_timedsend( ) functions are added for alignment with 9705 IEEE Std 1003.1d-1999. 9706 The restrict keyword is added to the prototypes for mq_setattr( ) and mq_timedreceive( ). Base Definitions, Issue 6 271 Headers 9707 NAME 9708 ndbm.h - definitions for ndbm database operations 9709 SYNOPSIS 9710 XSI #include 9711 9712 DESCRIPTION 9713 The header shall define the datum type as a structure that includes at least the 9714 following members: 9715 void *dptr A pointer to the application's data. 9716 size_t dsize The size of the object pointed to by dptr. 9717 The size_t type shall be defined as described in . 9718 The header shall define the DBM type. 9719 The following constants shall be defined as possible values for the store_mode argument to 9720 dbm_store( ): 9721 DBM_INSERT Insertion of new entries only. 9722 DBM_REPLACE Allow replacing existing entries. 9723 The following shall be declared as functions and may also be defined as macros. Function | 9724 prototypes shall be provided. | 9725 int dbm_clearerr(DBM *); 9726 void dbm_close(DBM *); 9727 int dbm_delete(DBM *, datum); 9728 int dbm_error(DBM *); 9729 datum dbm_fetch(DBM *, datum); 9730 datum dbm_firstkey(DBM *); 9731 datum dbm_nextkey(DBM *); 9732 DBM *dbm_open(const char *, int, mode_t); 9733 int dbm_store(DBM *, datum, datum, int); 9734 The mode_t type shall be defined through typedef as described in . 9735 APPLICATION USAGE 9736 None. 9737 RATIONALE 9738 None. 9739 FUTURE DIRECTIONS 9740 None. 9741 SEE ALSO 9742 The System Interfaces volume of IEEE Std 1003.1-200x, dbm_clearerr( ) 9743 CHANGE HISTORY 9744 First released in Issue 4, Version 2. 9745 Issue 5 9746 References to the definitions of size_t and mode_t are added to the DESCRIPTION. 272 Technical Standard (2001) (Draft April 13, 2001) Headers 9747 NAME 9748 net/if.h - sockets local interfaces 9749 SYNOPSIS 9750 #include 9751 DESCRIPTION 9752 The header shall define the if_nameindex structure that includes at least the 9753 following members: 9754 unsigned if_index Numeric index of the interface. 9755 char *if_name Null-terminated name of the interface. 9756 The header shall define the following macro for the length of a buffer containing an 9757 interface name (including the terminating NULL character): 9758 IF_NAMESIZE Interface name length. 9759 The following shall be declared as functions and may also be defined as macros. Function | 9760 prototypes shall be provided. | 9761 unsigned if_nametoindex(const char *); | 9762 char *if_indextoname(unsigned, char *); | 9763 struct if_nameindex *if_nameindex(void); | 9764 void if_freenameindex(struct if_nameindex *); | 9765 APPLICATION USAGE | 9766 None. 9767 RATIONALE 9768 None. 9769 FUTURE DIRECTIONS 9770 None. 9771 SEE ALSO 9772 The System Interfaces volume of IEEE Std 1003.1-200x, if_freenameindex( ), if_indextoname( ), 9773 if_nameindex( ), if_nametoindex( ) 9774 CHANGE HISTORY 9775 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. Base Definitions, Issue 6 273 Headers 9776 NAME 9777 netdb.h - definitions for network database operations 9778 SYNOPSIS 9779 #include 9780 DESCRIPTION 9781 The header may define the in_port_t type and the in_addr_t type as described in 9782 . 9783 The header shall define the hostent structure that includes at least the following 9784 members: 9785 char *h_name Official name of the host. 9786 char **h_aliases A pointer to an array of pointers to 9787 alternative host names, terminated by a 9788 null pointer. 9789 int h_addrtype Address type. 9790 int h_length The length, in bytes, of the address. 9791 char **h_addr_list A pointer to an array of pointers to network 9792 addresses (in network byte order) for the host, 9793 terminated by a null pointer. 9794 The header shall define the netent structure that includes at least the following 9795 members: 9796 char *n_name Official, fully-qualified (including the 9797 domain) name of the host. 9798 char **n_aliases A pointer to an array of pointers to 9799 alternative network names, terminated by a 9800 null pointer. 9801 int n_addrtype The address type of the network. 9802 uint32_t n_net The network number, in host byte order. 9803 The uint32_t type shall be defined as described in . 9804 The header shall define the protoent structure that includes at least the following 9805 members: 9806 char *p_name Official name of the protocol. 9807 char **p_aliases A pointer to an array of pointers to 9808 alternative protocol names, terminated by 9809 a null pointer. 9810 int p_proto The protocol number. 9811 The header shall define the servent structure that includes at least the following 9812 members: 9813 char *s_name Official name of the service. 9814 char **s_aliases A pointer to an array of pointers to 9815 alternative service names, terminated by 9816 a null pointer. 9817 int s_port The port number at which the service 9818 resides, in network byte order. 9819 char *s_proto The name of the protocol to use when 9820 contacting the service. 274 Technical Standard (2001) (Draft April 13, 2001) Headers 9821 The header shall define the IPPORT_RESERVED macro with the value of the highest 9822 reserved Internet port number. 9823 OB When the header is included, h_errno shall be available as a modifiable l-value of type 9824 int. It is unspecified whether h_errno is a macro or an identifier declared with external linkage. 9825 The header shall define the following macros for use as error values for 9826 gethostbyaddr( ) and gethostbyname( ): 9827 HOST_NOT_FOUND | 9828 NO_DATA 9829 NO_RECOVERY 9830 TRY_AGAIN 9831 Address Information Structure 9832 The header shall define the addrinfo structure that includes at least the following 9833 members: 9834 int ai_flags Input flags. 9835 int ai_family Address family of socket. 9836 int ai_socktype Socket type. 9837 int ai_protocol Protocol of socket. 9838 socklen_t ai_addrlen Length of socket address. 9839 struct sockaddr *ai_addr Socket address of socket. 9840 char *ai_canonname Canonical name of service location. 9841 struct addrinfo *ai_next Pointer to next in list. 9842 The header shall define the following macros that evaluate to bitwise-distinct integer 9843 constants for use in the flags field of the addrinfo structure: 9844 AI_PASSIVE Socket address is intended for bind( ). 9845 AI_CANONNAME 9846 Request for canonical name. 9847 AI_NUMERICHOST 9848 Return numeric host address as name. | 9849 AI_NUMERICSERV | 9850 Inhibit service name resolution. | 9851 AI_V4MAPPED | 9852 If no IPv6 addresses are found, query for IPv4 addresses and return them to | 9853 the caller as IPv4-mapped IPv6 addresses. | 9854 AI_ALL Query for both IPv4 and IPv6 addresses. | 9855 AI_ADDRCONFIG | 9856 Query for IPv4 addresses only when an IPv4 address is configured; query for | 9857 IPv6 addresses only when an IPv6 address is configured. | 9858 The header shall define the following macros that evaluate to bitwise-distinct integer 9859 constants for use in the flags argument to getnameinfo( ): 9860 NI_NOFQDN Only the nodename portion of the FQDN is returned for local hosts. 9861 NI_NUMERICHOST 9862 The numeric form of the node's address is returned instead of its name. Base Definitions, Issue 6 275 Headers 9863 NI_NAMEREQD Return an error if the node's name cannot be located in the database. 9864 NI_NUMERICSERV 9865 The numeric form of the service address is returned instead of its name. 9866 NI_DGRAM Indicates that the service is a datagram service (SOCK_DGRAM). 9867 Address Information Errors 9868 The header shall define the following macros for use as error values for getaddrinfo( ) 9869 and getnameinfo( ): 9870 EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed. 9871 EAI_BADFLAGS The flags had an invalid value. 9872 EAI_FAIL A non-recoverable error occurred. 9873 EAI_FAMILY The address family was not recognized or the address length was invalid for 9874 the specified family. 9875 EAI_MEMORY There was a memory allocation failure. 9876 EAI_NONAME The name does not resolve for the supplied parameters. 9877 NI_NAMEREQD is set and the host's name cannot be located, or both 9878 nodename and servname were null. 9879 EAI_SERVICE The service passed was not recognized for the specified socket type. 9880 EAI_SOCKTYPE The intended socket type was not recognized. 9881 EAI_SYSTEM A system error occurred. The error code can be found in errno. | 9882 EAI_OVERFLOWAn argument buffer overflowed. | 9883 The following shall be declared as functions and may also be defined as macros. Function | 9884 prototypes shall be provided. | 9885 void endhostent(void); 9886 void endnetent(void); 9887 void endprotoent(void); 9888 void endservent(void); 9889 void freeaddrinfo(struct addrinfo *); 9890 const char *gai_strerror(int); | 9891 int getaddrinfo(const char *restrict, const char *restrict,| 9892 const struct addrinfo *restrict, 9893 struct addrinfo **restrict); 9894 struct hostent *gethostbyaddr(const void *, socklen_t, int); 9895 struct hostent *gethostbyname(const char *); 9896 struct hostent *gethostent(void); 9897 int getnameinfo(const struct sockaddr *restrict, socklen_t, 9898 char *restrict, socklen_t, char *restrict, 9899 socklen_t, unsigned); 9900 struct netent *getnetbyaddr(uint32_t, int); 9901 struct netent *getnetbyname(const char *); 9902 struct netent *getnetent(void); 9903 struct protoent *getprotobyname(const char *); 9904 struct protoent *getprotobynumber(int); 9905 struct protoent *getprotoent(void); 276 Technical Standard (2001) (Draft April 13, 2001) Headers 9906 struct servent *getservbyname(const char *, const char *); 9907 struct servent *getservbyport(int, const char *); 9908 struct servent *getservent(void); 9909 void sethostent(int); 9910 void setnetent(int); 9911 void setprotoent(int); 9912 void setservent(int); 9913 The type socklen_t shall be defined through typedef as described in . 9914 Inclusion of the header may also make visible all symbols from , | 9915 , and . | 9916 APPLICATION USAGE 9917 None. 9918 RATIONALE 9919 None. 9920 FUTURE DIRECTIONS 9921 None. 9922 SEE ALSO 9923 , , , the System Interfaces volume of 9924 IEEE Std 1003.1-200x, bind( ), endhostent( ), endnetent( ), endprotoent( ), endservent( ), getaddrinfo( ), 9925 getnameinfo( ) 9926 CHANGE HISTORY 9927 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 9928 The Open Group Base Resolution bwg2001-009 is applied, which changes the return type for | 9929 gai_strerror( ) from char * to const char *. This is for coordination with the IPnG Working Group. | Base Definitions, Issue 6 277 Headers 9930 NAME 9931 netinet/in.h - Internet address family | 9932 SYNOPSIS 9933 #include 9934 DESCRIPTION 9935 The header shall define the following types: 9936 in_port_t Equivalent to the type uint16_t as defined in . | 9937 in_addr_t Equivalent to the type uint32_t as defined in . | 9938 The sa_family_t type shall be defined as described in . 9939 The uint8_t and uint32_t type shall be defined as described in . Inclusion of the | 9940 header may also make visible all symbols from and . | 9941 The header shall define the in_addr structure that includes at least the following 9942 member: 9943 in_addr_t s_addr 9944 The header shall define the sockaddr_in structure that includes at least the | 9945 following members (all in network byte order): | 9946 sa_family_t sin_family AF_INET. | 9947 in_port_t sin_port Port number. | 9948 struct in_addr sin_addr IP address. | 9949 The sockaddr_in structure is used to store addresses for the Internet address family. Values of | 9950 this type shall be cast by applications to struct sockaddr for use with socket functions. 9951 IP6 The header shall define the in6_addr structure that contains at least the following 9952 member: 9953 uint8_t s6_addr[16] 9954 This array is used to contain a 128-bit IPv6 address, stored in network byte order. 9955 The header shall define the sockaddr_in6 structure that includes at least the | 9956 following members (all in network byte order): | 9957 sa_family_t sin6_family AF_INET6. 9958 in_port_t sin6_port Port number. 9959 uint32_t sin6_flowinfo IPv6 traffic class and flow information. 9960 struct in6_addr sin6_addr IPv6 address. 9961 uint32_t sin6_scope_id Set of interfaces for a scope. 9962 The sockaddr_in6 structure shall be set to zero by an application prior to using it, since 9963 implementations are free to have additional, implementation-defined fields in sockaddr_in6. 9964 The sin6_scope_id field is a 32-bit integer that identifies a set of interfaces as appropriate for the 9965 scope of the address carried in the sin6_addr field. For a link scope sin6_addr, sin6_scope_id would 9966 be an interface index. For a site scope sin6_addr, sin6_scope_id would be a site identifier. The 9967 mapping of sin6_scope_id to an interface or set of interfaces is implementation-defined. 9968 The header shall declare the following external variable: 9969 struct in6_addr in6addr_any 9970 This variable is initialized by the system to contain the wildcard IPv6 address. The 9971 header also defines the IN6ADDR_ANY_INIT macro. This macro must be 278 Technical Standard (2001) (Draft April 13, 2001) Headers 9972 constant at compile time and can be used to initialize a variable of type struct in6_addr to the 9973 IPv6 wildcard address. 9974 The header shall declare the following external variable: 9975 struct in6_addr in6addr_loopback 9976 This variable is initialized by the system to contain the loopback IPv6 address. The 9977 header also defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be 9978 constant at compile time and can be used to initialize a variable of type struct in6_addr to the 9979 IPv6 loopback address. 9980 The header shall define the ipv6_mreq structure that includes at least the 9981 following members: 9982 struct in6_addr ipv6mr_multiaddr IPv6 multicast address. 9983 unsigned ipv6mr_interface Interface index. 9984 9985 The header shall define the following macros for use as values of the level 9986 argument of getsockopt( ) and setsockopt( ): 9987 IPPROTO_IP Internet protocol. 9988 IP6 IPPROTO_IPV6 Internet Protocol Version 6. 9989 IPPROTO_ICMP Control message protocol. 9990 RS IPPROTO_RAW Raw IP Packets Protocol. 9991 IPPROTO_TCP Transmission control protocol. 9992 IPPROTO_UDP User datagram protocol. 9993 The header shall define the following macros for use as destination addresses for 9994 connect( ), sendmsg( ), and sendto( ): 9995 INADDR_ANY IPv4 local host address. 9996 INADDR_BROADCAST IPv4 broadcast address. 9997 The header shall define the following macro to help applications declare buffers 9998 of the proper size to store IPv4 addresses in string form: 9999 INET_ADDRSTRLEN 16. Length of the string form for IP. | 10000 The htonl( ), htons( ), ntohl( ), and ntohs( ) functions shall be available as defined in . 10001 Inclusion of the header may also make visible all symbols from . 10002 IP6 The header shall define the following macro to help applications declare buffers 10003 of the proper size to store IPv6 addresses in string form: 10004 INET6_ADDRSTRLEN 46. Length of the string form for IPv6. | 10005 The header shall define the following macros, with distinct integer values, for use 10006 in the option_name argument in the getsockopt( ) or setsockopt( ) functions at protocol level 10007 IPPROTO_IPV6: 10008 IPV6_JOIN_GROUP Join a multicast group. 10009 IPV6_LEAVE_GROUP Quit a multicast group. 10010 IPV6_MULTICAST_HOPS 10011 Multicast hop limit. Base Definitions, Issue 6 279 Headers 10012 IPV6_MULTICAST_IF Interface to use for outgoing multicast packets. 10013 IPV6_MULTICAST_LOOP 10014 Multicast packets are delivered back to the local application. 10015 IPV6_UNICAST_HOPS Unicast hop limit. | 10016 IPV6_V6ONLY Restrict AF_INET6 socket to IPv6 communications only. | 10017 The header shall define the following macros that test for special IPv6 addresses. 10018 Each macro is of type int and takes a single argument of type const struct in6_addr *: 10019 IN6_IS_ADDR_UNSPECIFIED 10020 Unspecified address. 10021 IN6_IS_ADDR_LOOPBACK 10022 Loopback address. 10023 IN6_IS_ADDR_MULTICAST 10024 Multicast address. 10025 IN6_IS_ADDR_LINKLOCAL 10026 Unicast link-local address. 10027 IN6_IS_ADDR_SITELOCAL 10028 Unicast site-local address. 10029 IN6_IS_ADDR_V4MAPPED 10030 IPv4 mapped address. 10031 IN6_IS_ADDR_V4COMPAT 10032 IPv4-compatible address. 10033 IN6_IS_ADDR_MC_NODELOCAL 10034 Multicast node-local address. 10035 IN6_IS_ADDR_MC_LINKLOCAL 10036 Multicast link-local address. 10037 IN6_IS_ADDR_MC_SITELOCAL 10038 Multicast site-local address. 10039 IN6_IS_ADDR_MC_ORGLOCAL 10040 Multicast organization-local address. 10041 IN6_IS_ADDR_MC_GLOBAL 10042 Multicast global address. 10043 IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true only for the two 10044 local-use IPv6 unicast addresses. They do not return true for multicast addresses of either link- 10045 local or site-local scope. 280 Technical Standard (2001) (Draft April 13, 2001) Headers 10046 APPLICATION USAGE 10047 None. 10048 RATIONALE 10049 None. 10050 FUTURE DIRECTIONS 10051 None. 10052 SEE ALSO 10053 Section 4.8 (on page 97), , , , the System Interfaces | 10054 volume of IEEE Std 1003.1-200x, connect( ), getsockopt( ), htonl( ), htons( ), ntohl( ), ntohs( ), 10055 sendmsg( ), sendto( ), setsockopt( ) 10056 CHANGE HISTORY 10057 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 10058 The sin_zero member was removed from the sockaddr_in structure as per The Open Group Base | 10059 Resolution bwg2001-004. | Base Definitions, Issue 6 281 Headers 10060 NAME 10061 netinet/tcp.h - definitions for the Internet Transmission Control Protocol (TCP) 10062 SYNOPSIS 10063 #include 10064 DESCRIPTION 10065 The header shall define the following macro for use as a socket option at the 10066 IPPROTO_TCP level: 10067 TCP_NODELAY Avoid coalescing of small segments. 10068 The macro shall be defined in the header. The implementation need not allow the value of the 10069 option to be set via setsockopt( ) or retrieved via getsockopt( ). 10070 APPLICATION USAGE 10071 None. 10072 RATIONALE 10073 None. 10074 FUTURE DIRECTIONS 10075 None. 10076 SEE ALSO 10077 , the System Interfaces volume of IEEE Std 1003.1-200x, getsockopt( ), setsockopt( ) 10078 CHANGE HISTORY 10079 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 282 Technical Standard (2001) (Draft April 13, 2001) Headers 10080 NAME 10081 nl_types.h - data types 10082 SYNOPSIS 10083 XSI #include 10084 10085 DESCRIPTION 10086 The header shall contain definitions of at least the following types: 10087 nl_catd Used by the message catalog functions catopen( ), catgets( ), and catclose( ) 10088 to identify a catalog descriptor. 10089 nl_item Used by nl_langinfo ( ) to identify items of langinfo data. Values of objects 10090 of type nl_item are defined in . 10091 The header shall contain definitions of at least the following constants: 10092 NL_SETD Used by gencat when no $set directive is specified in a message text source 10093 file; see the Internationalization Guide. This constant can be passed as the 10094 value of set_id on subsequent calls to catgets( ) (that is, to retrieve 10095 messages from the default message set). The value of NL_SETD is 10096 implementation-defined. 10097 NL_CAT_LOCALE Value that must be passed as the oflag argument to catopen( ) to ensure 10098 that message catalog selection depends on the LC_MESSAGES locale 10099 category, rather than directly on the LANG environment variable. 10100 The following shall be declared as functions and may also be defined as macros. Function | 10101 prototypes shall be provided. | 10102 int catclose(nl_catd); 10103 char *catgets(nl_catd, int, int, const char *); 10104 nl_catd catopen(const char *, int); 10105 APPLICATION USAGE 10106 None. 10107 RATIONALE 10108 None. 10109 FUTURE DIRECTIONS 10110 None. 10111 SEE ALSO 10112 , the System Interfaces volume of IEEE Std 1003.1-200x, catclose( ), catgets( ), 10113 catopen( ), nl_langinfo ( ), the Shell and Utilities volume of IEEE Std 1003.1-200x, gencat 10114 CHANGE HISTORY 10115 First released in Issue 2. Base Definitions, Issue 6 283 Headers 10116 NAME 10117 poll.h - definitions for the poll( ) function 10118 SYNOPSIS 10119 XSI #include 10120 10121 DESCRIPTION 10122 The header shall define the pollfd structure that includes at least the following 10123 members: 10124 int fd The following descriptor being polled. 10125 short events The input event flags (see below). 10126 short revents The output event flags (see below). 10127 The header shall define the following type through typedef: 10128 nfds_t An unsigned integer type used for the number of file descriptors. 10129 The implementation shall support one or more programming environments in which the width | 10130 of nfds_t is no greater than the width of type long. The names of these programming | 10131 environments can be obtained using the confstr( ) function or the getconf utility. | 10132 The following symbolic constants shall be defined, zero or more of which may be OR'ed together | 10133 to form the events or revents members in the pollfd structure: 10134 POLLIN Data other than high-priority data may be read without blocking. 10135 POLLRDNORM Normal data may be read without blocking. 10136 POLLRDBAND Priority data may be read without blocking. 10137 POLLPRI High priority data may be read without blocking. 10138 POLLOUT Normal data may be written without blocking. 10139 POLLWRNORM Equivalent to POLLOUT. | 10140 POLLWRBAND Priority data may be written. 10141 POLLERR An error has occurred (revents only). 10142 POLLHUP Device has been disconnected (revents only). 10143 POLLNVAL Invalid fd member (revents only). 10144 The significance and semantics of normal, priority, and high-priority data are file and device- 10145 specific. 10146 The following shall be declared as a function and may also be defined as a macro. A function | 10147 prototype shall be provided. | 10148 int poll(struct pollfd[], nfds_t, int); 284 Technical Standard (2001) (Draft April 13, 2001) Headers 10149 APPLICATION USAGE 10150 None. 10151 RATIONALE 10152 None. 10153 FUTURE DIRECTIONS 10154 None. 10155 SEE ALSO 10156 The System Interfaces volume of IEEE Std 1003.1-200x, confstr( ), poll( ), the Shell and Utilities | 10157 volume of IEEE Std 1003.1-200x, getconf | 10158 CHANGE HISTORY 10159 First released in Issue 4, Version 2. 10160 Issue 6 10161 The description of the symbolic constants is updated to match the poll( ) function. 10162 Text related to STREAMS has been moved to the poll( ) reference page. 10163 A note is added to the DESCRIPTION regarding the significance and semantics of normal, 10164 priority, and high-priority data. Base Definitions, Issue 6 285 Headers 10165 NAME 10166 pthread.h - threads 10167 SYNOPSIS 10168 THR #include 10169 10170 DESCRIPTION 10171 The header shall define the following symbols: 10172 BAR PTHREAD_BARRIER_SERIAL_THREAD 10173 PTHREAD_CANCEL_ASYNCHRONOUS 10174 PTHREAD_CANCEL_ENABLE 10175 PTHREAD_CANCEL_DEFERRED 10176 PTHREAD_CANCEL_DISABLE 10177 PTHREAD_CANCELED 10178 PTHREAD_COND_INITIALIZER 10179 PTHREAD_CREATE_DETACHED 10180 PTHREAD_CREATE_JOINABLE 10181 PTHREAD_EXPLICIT_SCHED 10182 PTHREAD_INHERIT_SCHED 10183 XSI PTHREAD_MUTEX_DEFAULT 10184 PTHREAD_MUTEX_ERRORCHECK 10185 PTHREAD_MUTEX_INITIALIZER 10186 XSI PTHREAD_MUTEX_NORMAL 10187 PTHREAD_MUTEX_RECURSIVE 10188 PTHREAD_ONCE_INIT 10189 TPP|TPI PTHREAD_PRIO_INHERIT 10190 PTHREAD_PRIO_NONE 10191 PTHREAD_PRIO_PROTECT 10192 PTHREAD_PROCESS_SHARED 10193 PTHREAD_PROCESS_PRIVATE 10194 TPS PTHREAD_SCOPE_PROCESS 10195 PTHREAD_SCOPE_SYSTEM 10196 10197 The following types shall be defined as described in : 10198 pthread_attr_t 10199 BAR pthread_barrier_t 10200 pthread_barrierattr_t 10201 pthread_cond_t 10202 pthread_condattr_t 10203 pthread_key_t 10204 pthread_mutex_t 10205 pthread_mutexattr_t 10206 pthread_once_t 10207 pthread_rwlock_t 10208 pthread_rwlockattr_t 10209 SPI pthread_spinlock_t 10210 pthread_t 10211 The following shall be declared as functions and may also be defined as macros. Function | 10212 prototypes shall be provided. | 286 Technical Standard (2001) (Draft April 13, 2001) Headers 10213 int pthread_atfork(void (*)(void), void (*)(void), 10214 void(*)(void)); 10215 int pthread_attr_destroy(pthread_attr_t *); 10216 int pthread_attr_getdetachstate(const pthread_attr_t *, int *); 10217 XSI int pthread_attr_getguardsize(const pthread_attr_t *restrict, 10218 size_t *restrict); 10219 TPS int pthread_attr_getinheritsched(const pthread_attr_t *restrict, 10220 int *restrict); 10221 int pthread_attr_getschedparam(const pthread_attr_t *restrict, 10222 struct sched_param *restrict); 10223 TPS int pthread_attr_getschedpolicy(const pthread_attr_t *restrict, 10224 int *restrict); 10225 TPS int pthread_attr_getscope(const pthread_attr_t *restrict, 10226 int *restrict); 10227 XSI int pthread_attr_getstack(const pthread_attr_t *restrict, 10228 void **restrict, size_t *restrict); 10229 TSA int pthread_attr_getstackaddr(const pthread_attr_t *restrict, 10230 void **restrict); 10231 int pthread_attr_getstacksize(const pthread_attr_t *restrict, 10232 size_t *restrict); 10233 int pthread_attr_init(pthread_attr_t *); 10234 int pthread_attr_setdetachstate(pthread_attr_t *, int); 10235 XSI int pthread_attr_setguardsize(pthread_attr_t *, size_t); 10236 TPS int pthread_attr_setinheritsched(pthread_attr_t *, int); 10237 int pthread_attr_setschedparam(pthread_attr_t *restrict, 10238 const struct sched_param *restrict); 10239 TPS int pthread_attr_setschedpolicy(pthread_attr_t *, int); 10240 int pthread_attr_setscope(pthread_attr_t *, int); 10241 XSI int pthread_attr_setstack(pthread_attr_t *, void *, size_t); 10242 TSA int pthread_attr_setstackaddr(pthread_attr_t *, void *); 10243 int pthread_attr_setstacksize(pthread_attr_t *, size_t); 10244 BAR int pthread_barrier_destroy(pthread_barrier_t *); 10245 int pthread_barrier_init(pthread_barrier_t *restrict, 10246 const pthread_barrierattr_t *restrict, unsigned); 10247 int pthread_barrier_wait(pthread_barrier_t *); 10248 int pthread_barrierattr_destroy(pthread_barrierattr_t *); 10249 int pthread_barrierattr_getpshared( \ | 10250 const pthread_barrierattr_t *restrict, int *restrict); | 10251 int pthread_barrierattr_init(pthread_barrierattr_t *); | 10252 int pthread_barrierattr_setpshared(pthread_barrierattr_t *, int); 10253 int pthread_cancel(pthread_t); 10254 void pthread_cleanup_push(void (*)(void *), void *); 10255 void pthread_cleanup_pop(int); 10256 int pthread_cond_broadcast(pthread_cond_t *); 10257 int pthread_cond_destroy(pthread_cond_t *); 10258 int pthread_cond_init(pthread_cond_t *restrict, 10259 const pthread_condattr_t *restrict); 10260 int pthread_cond_signal(pthread_cond_t *); 10261 int pthread_cond_timedwait(pthread_cond_t *restrict, 10262 pthread_mutex_t *restrict, const struct timespec *restrict); 10263 int pthread_cond_wait(pthread_cond_t *restrict, 10264 pthread_mutex_t *restrict); Base Definitions, Issue 6 287 Headers 10265 int pthread_condattr_destroy(pthread_condattr_t *); 10266 CS int pthread_condattr_getclock(const pthread_condattr_t *restrict, 10267 clockid_t *restrict); 10268 int pthread_condattr_getpshared(const pthread_condattr_t *restrict, 10269 int *restrict); 10270 int pthread_condattr_init(pthread_condattr_t *); 10271 CS int pthread_condattr_setclock(pthread_condattr_t *, clockid_t); 10272 int pthread_condattr_setpshared(pthread_condattr_t *, int); 10273 int pthread_create(pthread_t *restrict, const pthread_attr_t *restrict, 10274 void *(*)(void *), void *restrict); 10275 int pthread_detach(pthread_t); 10276 int pthread_equal(pthread_t, pthread_t); 10277 void pthread_exit(void *); 10278 XSI int pthread_getconcurrency(void); 10279 TCT int pthread_getcpuclockid(pthread_t, clockid_t *); 10280 TPS int pthread_getschedparam(pthread_t, int *restrict, 10281 struct sched_param *restrict); 10282 void *pthread_getspecific(pthread_key_t); 10283 int pthread_join(pthread_t, void **); 10284 int pthread_key_create(pthread_key_t *, void (*)(void *)); 10285 int pthread_key_delete(pthread_key_t); 10286 int pthread_mutex_destroy(pthread_mutex_t *); 10287 TPP int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict, 10288 int *restrict); 10289 int pthread_mutex_init(pthread_mutex_t *restrict, 10290 const pthread_mutexattr_t *restrict); 10291 int pthread_mutex_lock(pthread_mutex_t *); 10292 TPP int pthread_mutex_setprioceiling(pthread_mutex_t *restrict, int, 10293 int *restrict); 10294 TMO int pthread_mutex_timedlock(pthread_mutex_t *, 10295 const struct timespec *); 10296 int pthread_mutex_trylock(pthread_mutex_t *); 10297 int pthread_mutex_unlock(pthread_mutex_t *); 10298 int pthread_mutexattr_destroy(pthread_mutexattr_t *); 10299 TPP|TPI int pthread_mutexattr_getprioceiling( \ | 10300 const pthread_mutexattr_t *restrict, int *restrict); | 10301 int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict, | 10302 int *restrict); 10303 int pthread_mutexattr_getpshared(const pthread_mutexattr_t *restrict, 10304 int *restrict); 10305 XSI int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict, 10306 int *restrict); 10307 int pthread_mutexattr_init(pthread_mutexattr_t *); 10308 TPP|TPI int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); 10309 int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); 10310 int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); 10311 XSI int pthread_mutexattr_settype(pthread_mutexattr_t *, int); 10312 int pthread_once(pthread_once_t *, void (*)(void)); 10313 int pthread_rwlock_destroy(pthread_rwlock_t *); 10314 int pthread_rwlock_init(pthread_rwlock_t *restrict, 10315 const pthread_rwlockattr_t *restrict); 10316 int pthread_rwlock_rdlock(pthread_rwlock_t *); 288 Technical Standard (2001) (Draft April 13, 2001) Headers 10317 int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict, 10318 const struct timespec *restrict); 10319 int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict, 10320 const struct timespec *restrict); 10321 int pthread_rwlock_tryrdlock(pthread_rwlock_t *); 10322 int pthread_rwlock_trywrlock(pthread_rwlock_t *); 10323 int pthread_rwlock_unlock(pthread_rwlock_t *); 10324 int pthread_rwlock_wrlock(pthread_rwlock_t *); 10325 int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); 10326 int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *restrict, 10327 int *restrict); 10328 int pthread_rwlockattr_init(pthread_rwlockattr_t *); 10329 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); 10330 pthread_t 10331 pthread_self(void); 10332 int pthread_setcancelstate(int, int *); 10333 int pthread_setcanceltype(int, int *); 10334 XSI int pthread_setconcurrency(int); 10335 TPS int pthread_setschedparam(pthread_t, int, 10336 const struct sched_param *); 10337 THR TPS int pthread_setschedprio(pthread_t, int); | 10338 int pthread_setspecific(pthread_key_t, const void *); | 10339 SPI int pthread_spin_destroy(pthread_spinlock_t *); 10340 int pthread_spin_init(pthread_spinlock_t *, int); 10341 int pthread_spin_lock(pthread_spinlock_t *); 10342 int pthread_spin_trylock(pthread_spinlock_t *); 10343 int pthread_spin_unlock(pthread_spinlock_t *); 10344 void pthread_testcancel(void); 10345 Inclusion of the header shall make symbols defined in the headers and 10346 visible. 10347 APPLICATION USAGE 10348 None. 10349 RATIONALE 10350 None. 10351 FUTURE DIRECTIONS 10352 None. 10353 SEE ALSO 10354 , , the System Interfaces volume of IEEE Std 1003.1-200x, 10355 pthread_attr_getguardsize( ), pthread_attr_init( ), pthread_attr_setscope( ), pthread_barrier_destroy( ), 10356 pthread_barrier_init( ), pthread_barrier_wait( ), pthread_barrierattr_destroy( ), 10357 pthread_barrierattr_getpshared( ), pthread_barrierattr_init( ), pthread_barrierattr_setpshared( ), 10358 pthread_cancel( ), pthread_cleanup_pop( ), pthread_cond_init( ), pthread_cond_signal( ), 10359 pthread_cond_wait( ), pthread_condattr_getclock( ), pthread_condattr_init( ), 10360 pthread_condattr_setclock( ), pthread_create( ), pthread_detach( ), pthread_equal( ), pthread_exit( ), 10361 pthread_getconcurrency( ), pthread_getcpuclockid( ), pthread_getschedparam( ), pthread_join( ), 10362 pthread_key_create( ), pthread_key_delete( ), pthread_mutex_init( ), pthread_mutex_lock( ), 10363 pthread_mutex_setprioceiling( ), pthread_mutex_timedlock( ), pthread_mutexattr_init( ), 10364 pthread_mutexattr_gettype( ), pthread_mutexattr_setprotocol( ), pthread_once( ), 10365 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 10366 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), Base Definitions, Issue 6 289 Headers 10367 pthread_rwlock_trywrlock( ), pthread_rwlock_unlock( ), pthread_rwlock_wrlock( ), 10368 pthread_rwlockattr_destroy( ), pthread_rwlockattr_getpshared( ), pthread_rwlockattr_init( ), 10369 pthread_rwlockattr_setpshared( ), pthread_self( ), pthread_setcancelstate( ), pthread_setspecific( ), 10370 pthread_spin_destroy( ), pthread_spin_init( ), pthread_spin_lock( ), pthread_spin_trylock( ), 10371 pthread_spin_unlock( ) 10372 CHANGE HISTORY 10373 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 10374 Issue 6 10375 The RTT margin markers are now broken out into their POSIX options. 10376 The Open Group Corrigendum U021/9 is applied, correcting the prototype for the 10377 pthread_cond_wait( ) function. 10378 The Open Group Corrigendum U026/2 is applied correcting the prototype for the 10379 pthread_setschedparam( ) function so that its second argument is of type int. 10380 The pthread_getcpuclockid( ) and pthread_mutex_timedlock( ) functions are added for alignment 10381 with IEEE Std 1003.1d-1999. 10382 The following functions are added for alignment with IEEE Std 1003.1j-2000: 10383 pthread_barrier_destroy( ), pthread_barrier_init( ), pthread_barrier_wait( ), 10384 pthread_barrierattr_destroy( ), pthread_barrierattr_getpshared( ), pthread_barrierattr_init( ), 10385 pthread_barrierattr_setpshared( ), pthread_condattr_getclock( ), pthread_condattr_setclock( ), 10386 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_spin_destroy( ), 10387 pthread_spin_init( ), pthread_spin_lock( ), pthread_spin_trylock( ), and pthread_spin_unlock( ). 10388 PTHREAD_RWLOCK_INITIALIZER is deleted for alignment with IEEE Std 1003.1j-2000. 10389 Functions previously marked as part of the Read-Write Locks option are now moved to the 10390 Threads option. 10391 The restrict keyword is added to the prototypes for pthread_attr_getguardsize( ), 10392 pthread_attr_getinheritsched( ), pthread_attr_getschedparam( ), pthread_attr_getschedpolicy( ), 10393 pthread_attr_getscope( ), pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), 10394 pthread_attr_setschedparam( ), pthread_barrier_init( ), pthread_barrierattr_getpshared( ), 10395 pthread_cond_init( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( ), 10396 pthread_condattr_getclock( ), pthread_condattr_getpshared( ), pthread_create( ), 10397 pthread_getschedparam( ), pthread_mutex_getprioceiling( ), pthread_mutex_init( ), 10398 pthread_mutex_setprioceiling( ), pthread_mutexattr_getprioceiling( ), pthread_mutexattr_getprotocol( ), 10399 pthread_mutexattr_getpshared( ), pthread_mutexattr_gettype( ), pthread_rwlock_init( ), 10400 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlockattr_getpshared( ), and 10401 pthread_sigmask( ). 10402 IEEE PASC Interpretation 1003.1 #86 is applied, allowing the symbols from and 10403 to be made visible when is included. Previously this was an XSI 10404 extension. 10405 IEEE PASC Interpretation 1003.1c #42 is applied, removing the requirement for prototypes for 10406 the pthread_kill ( ) and pthread_sigmask( ) functions. These are required to be in the 10407 header. They are allowed here through the name space rules. | 10408 IEEE PASC Interpretation 1003.1 #96 is applied, adding the pthread_setschedprio( ) function. | 290 Technical Standard (2001) (Draft April 13, 2001) Headers 10409 NAME 10410 pwd.h - password structure 10411 SYNOPSIS 10412 #include 10413 DESCRIPTION 10414 The header shall provide a definition for struct passwd, which shall include at least the 10415 following members: 10416 char *pw_name User's login name. 10417 uid_t pw_uid Numerical user ID. 10418 gid_t pw_gid Numerical group ID. 10419 char *pw_dir Initial working directory. 10420 char *pw_shell Program to use as shell. 10421 The gid_t and uid_t types shall be defined as described in . 10422 The following shall be declared as functions and may also be defined as macros. Function | 10423 prototypes shall be provided. | 10424 struct passwd *getpwnam(const char *); 10425 struct passwd *getpwuid(uid_t); 10426 TSF int getpwnam_r(const char *, struct passwd *, char *, 10427 size_t, struct passwd **); 10428 int getpwuid_r(uid_t, struct passwd *, char *, 10429 size_t, struct passwd **); 10430 XSI void endpwent(void); 10431 struct passwd *getpwent(void); 10432 void setpwent(void); 10433 10434 APPLICATION USAGE 10435 None. 10436 RATIONALE 10437 None. 10438 FUTURE DIRECTIONS 10439 None. 10440 SEE ALSO 10441 , the System Interfaces volume of IEEE Std 1003.1-200x, endpwent( ), getpwnam( ), 10442 getpwuid( ) 10443 CHANGE HISTORY 10444 First released in Issue 1. 10445 Issue 5 10446 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 10447 Issue 6 10448 The following new requirements on POSIX implementations derive from alignment with the 10449 Single UNIX Specification: 10450 * The gid_t and uid_t types are mandated. 10451 * The getpwnam_r( ) and getpwuid_r( ) functions are marked as part of the 10452 _POSIX_THREAD_SAFE_FUNCTIONS option. Base Definitions, Issue 6 291 Headers 10453 NAME 10454 regex.h - regular expression matching types 10455 SYNOPSIS 10456 #include 10457 DESCRIPTION 10458 The header shall define the structures and symbolic constants used by the regcomp( ), 10459 regexec( ), regerror( ), and regfree( ) functions. 10460 The structure type regex_t shall contain at least the following member: 10461 size_t re_nsub Number of parenthesized subexpressions. 10462 The type size_t shall be defined as described in . 10463 The type regoff_t shall be defined as a signed integer type that can hold the largest value that | 10464 can be stored in either a type off_t or type ssize_t. The structure type regmatch_t shall contain 10465 at least the following members: 10466 regoff_t rm_so Byte offset from start of string 10467 to start of substring. 10468 regoff_t rm_eo Byte offset from start of string of the 10469 first character after the end of substring. 10470 Values for the cflags parameter to the regcomp( ) function: 10471 REG_EXTENDED Use Extended Regular Expressions. 10472 REG_ICASE Ignore case in match. 10473 REG_NOSUB Report only success or fail in regexec( ). 10474 REG_NEWLINE Change the handling of newline. 10475 Values for the eflags parameter to the regexec( ) function: 10476 REG_NOTBOL The circumflex character (' '), when taken as a special character, does 10477 not match the beginning of string. 10478 REG_NOTEOL The dollar sign ('$'), when taken as a special character, does not match 10479 the end of string. 10480 The following constants shall be defined as error return values: 10481 REG_NOMATCH regexec( ) failed to match. 10482 REG_BADPAT Invalid regular expression. 10483 REG_ECOLLATE Invalid collating element referenced. 10484 REG_ECTYPE Invalid character class type referenced. 10485 REG_EESCAPE Trailing '\' in pattern. 10486 REG_ESUBREG Number in \digit invalid or in error. 10487 REG_EBRACK "[]" imbalance. 10488 REG_EPAREN "\(\)" or "()" imbalance. 10489 REG_EBRACE "\{\}" imbalance. 10490 REG_BADBR Content of "\{\}" invalid: not a number, number too large, more than 10491 two numbers, first larger than second. 292 Technical Standard (2001) (Draft April 13, 2001) Headers 10492 REG_ERANGE Invalid endpoint in range expression. 10493 REG_ESPACE Out of memory. 10494 REG_BADRPT '?', '*', or '+' not preceded by valid regular expression. 10495 OB REG_ENOSYS Reserved. 10496 The following shall be declared as functions and may also be defined as macros. Function | 10497 prototypes shall be provided. | 10498 int regcomp(regex_t *restrict, const char *restrict, int); 10499 size_t regerror(int, const regex_t *restrict, char *restrict, size_t); 10500 int regexec(const regex_t *restrict, const char *restrict, size_t, 10501 regmatch_t[restrict], int); 10502 void regfree(regex_t *); 10503 The implementation may define additional macros or constants using names beginning with 10504 REG_. 10505 APPLICATION USAGE 10506 None. 10507 RATIONALE 10508 None. 10509 FUTURE DIRECTIONS 10510 None. 10511 SEE ALSO 10512 The System Interfaces volume of IEEE Std 1003.1-200x, regcomp( ), the Shell and Utilities volume 10513 of IEEE Std 1003.1-200x 10514 CHANGE HISTORY 10515 First released in Issue 4. 10516 Originally derived from the ISO POSIX-2 standard. 10517 Issue 6 10518 The REG_ENOSYS constant is marked obsolescent. 10519 The restrict keyword is added to the prototypes for regcomp( ), regerror( ), and regexec( ). 10520 A statement is added that the size_t type is defined as described in . Base Definitions, Issue 6 293 Headers 10521 NAME 10522 sched.h - execution scheduling (REALTIME) 10523 SYNOPSIS 10524 PS #include 10525 10526 DESCRIPTION 10527 The header shall define the sched_param structure, which contains the scheduling 10528 parameters required for implementation of each supported scheduling policy. This structure 10529 shall contain at least the following member: 10530 int sched_priority Process execution scheduling priority. 10531 SS|TSP In addition, if _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER is 10532 defined, the sched_param structure defined in shall contain the following members 10533 in addition to those specified above: 10534 int sched_ss_low_priority Low scheduling priority for 10535 sporadic server. 10536 struct timespec sched_ss_repl_period Replenishment period for 10537 sporadic server. 10538 struct timespec sched_ss_init_budget Initial budget for sporadic server. 10539 int sched_ss_max_repl Maximum pending replenishments for 10540 sporadic server. 10541 10542 Each process is controlled by an associated scheduling policy and priority. Associated with each 10543 policy is a priority range. Each policy definition specifies the minimum priority range for that 10544 policy. The priority ranges for each policy may overlap the priority ranges of other policies. 10545 Four scheduling policies are defined; others may be defined by the implementation. The four 10546 standard policies are indicated by the values of the following symbolic constants: 10547 SCHED_FIFO First in-first out (FIFO) scheduling policy. 10548 SCHED_RR Round robin scheduling policy. 10549 SS|TSP SCHED_SPORADIC Sporadic server scheduling policy. 10550 SCHED_OTHER Another scheduling policy. 10551 The values of these constants are distinct. 10552 The following shall be declared as functions and may also be defined as macros. Function | 10553 prototypes shall be provided. | 10554 int sched_get_priority_max(int); 10555 int sched_get_priority_min(int); 10556 int sched_getparam(pid_t, struct sched_param *); 10557 int sched_getscheduler(pid_t); 10558 int sched_rr_get_interval(pid_t, struct timespec *); 10559 int sched_setparam(pid_t, const struct sched_param *); 10560 int sched_setscheduler(pid_t, int, const struct sched_param *); 10561 int sched_yield(void); 10562 Inclusion of the header makes symbols defined in the header visible. 294 Technical Standard (2001) (Draft April 13, 2001) Headers 10563 APPLICATION USAGE 10564 None. 10565 RATIONALE 10566 None. 10567 FUTURE DIRECTIONS 10568 None. 10569 SEE ALSO 10570 10571 CHANGE HISTORY 10572 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 10573 Issue 6 10574 The header is marked as part of the Process Scheduling option. 10575 Sporadic server members are added to the sched_param structure, and the SCHED_SPORADIC 10576 scheduling policy is added for alignment with IEEE Std 1003.1d-1999. 10577 IEEE PASC Interpretation 1003.1 #108 is applied, correcting the sched_param structure whose 10578 members sched_ss_repl_period and sched_ss_init_budget members should be type struct timespec 10579 and not timespec. Base Definitions, Issue 6 295 Headers 10580 NAME 10581 search.h - search tables 10582 SYNOPSIS 10583 XSI #include 10584 10585 DESCRIPTION 10586 The header shall define the ENTRY type for structure entry which shall include the 10587 following members: 10588 char *key 10589 void *data 10590 and shall define ACTION and VISIT as enumeration data types through type definitions as 10591 follows: 10592 enum { FIND, ENTER } ACTION; 10593 enum { preorder, postorder, endorder, leaf } VISIT; 10594 The size_t type shall be defined as described in . 10595 The following shall be declared as functions and may also be defined as macros. Function | 10596 prototypes shall be provided. | 10597 int hcreate(size_t); 10598 void hdestroy(void); 10599 ENTRY *hsearch(ENTRY, ACTION); 10600 void insque(void *, void *); 10601 void *lfind(const void *, const void *, size_t *, 10602 size_t, int (*)(const void *, const void *)); 10603 void *lsearch(const void *, void *, size_t *, 10604 size_t, int (*)(const void *, const void *)); 10605 void remque(void *); 10606 void *tdelete(const void *restrict, void **restrict, 10607 int(*)(const void *, const void *)); 10608 void *tfind(const void *, void *const *, 10609 int(*)(const void *, const void *)); 10610 void *tsearch(const void *, void **, 10611 int(*)(const void *, const void *)); 10612 void twalk(const void *, 10613 void (*)(const void *, VISIT, int )); 10614 APPLICATION USAGE 10615 None. 10616 RATIONALE 10617 None. 10618 FUTURE DIRECTIONS 10619 None. 10620 SEE ALSO 10621 , the System Interfaces volume of IEEE Std 1003.1-200x, hcreate( ), insque( ), 10622 lsearch( ), remque( ), tsearch( ) 296 Technical Standard (2001) (Draft April 13, 2001) Headers 10623 CHANGE HISTORY 10624 First released in Issue 1. Derived from Issue 1 of the SVID. 10625 Issue 6 10626 The Open Group Corrigendum U021/6 is applied updating the prototypes for tdelete( ) and 10627 tsearch( ). 10628 The restrict keyword is added to the prototype for tdelete( ). Base Definitions, Issue 6 297 Headers 10629 NAME 10630 semaphore.h - semaphores (REALTIME) 10631 SYNOPSIS 10632 SEM #include 10633 10634 DESCRIPTION 10635 The header shall define the sem_t type, used in performing semaphore 10636 operations. The semaphore may be implemented using a file descriptor, in which case 10637 applications are able to open up at least a total of {OPEN_MAX} files and semaphores. The 10638 symbol SEM_FAILED shall be defined (see sem_open( )). 10639 The following shall be declared as functions and may also be defined as macros. Function | 10640 prototypes shall be provided. | 10641 int sem_close(sem_t *); 10642 int sem_destroy(sem_t *); 10643 int sem_getvalue(sem_t *restrict, int *restrict); 10644 int sem_init(sem_t *, int, unsigned); 10645 sem_t *sem_open(const char *, int, ...); 10646 int sem_post(sem_t *); 10647 TMO int sem_timedwait(sem_t *restrict, const struct timespec *restrict); 10648 int sem_trywait(sem_t *); 10649 int sem_unlink(const char *); 10650 int sem_wait(sem_t *); 10651 Inclusion of the header may make visible symbols defined in the headers 10652 and . 10653 APPLICATION USAGE 10654 None. 10655 RATIONALE 10656 None. 10657 FUTURE DIRECTIONS 10658 None. 10659 SEE ALSO 10660 , , the System Interfaces volume of IEEE Std 1003.1-200x, sem_destroy( ), 10661 sem_getvalue( ), sem_init( ), sem_open( ), sem_post( ), sem_timedwait( ), sem_trywait( ), sem_unlink( ), 10662 sem_wait( ) 10663 CHANGE HISTORY 10664 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 10665 Issue 6 10666 The header is marked as part of the Semaphores option. 10667 The Open Group Corrigendum U021/3 is applied, adding a description of SEM_FAILED. 10668 The sem_timedwait( ) function is added for alignment with IEEE Std 1003.1d-1999. 10669 The restrict keyword is added to the prototypes for sem_getvalue( ) and sem_timedwait( ). 298 Technical Standard (2001) (Draft April 13, 2001) Headers 10670 NAME 10671 setjmp.h - stack environment declarations 10672 SYNOPSIS 10673 #include 10674 DESCRIPTION 10675 CX Some of the functionality described on this reference page extends the ISO C standard. 10676 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 10677 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 10678 symbols in this header. 10679 CX The header shall define the array types jmp_buf andsigjmp_buf. 10680 The following shall be declared as functions and may also be defined as macros. Function | 10681 prototypes shall be provided. | 10682 void longjmp(jmp_buf, int); 10683 CX void siglongjmp(sigjmp_buf, int); 10684 XSI void _longjmp(jmp_buf, int); 10685 10686 The following may be declared as a function, or defined as a macro, or both. Function prototypes | 10687 shall be provided. | 10688 int setjmp(jmp_buf); 10689 CX int sigsetjmp(sigjmp_buf, int); 10690 XSI int _setjmp(jmp_buf); 10691 10692 APPLICATION USAGE 10693 None. 10694 RATIONALE 10695 None. 10696 FUTURE DIRECTIONS 10697 None. 10698 SEE ALSO 10699 The System Interfaces volume of IEEE Std 1003.1-200x, longjmp( ), _longjmp( ), setjmp( ), 10700 siglongjmp( ), sigsetjmp( ) 10701 CHANGE HISTORY 10702 First released in Issue 1. 10703 Issue 6 10704 Extensions beyond the ISO C standard are now marked. Base Definitions, Issue 6 299 Headers 10705 NAME 10706 signal.h - signals 10707 SYNOPSIS 10708 #include 10709 DESCRIPTION 10710 CX Some of the functionality described on this reference page extends the ISO C standard. 10711 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 10712 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 10713 symbols in this header. 10714 The header shall define the following symbolic constants, each of which expands to a 10715 distinct constant expression of the type: 10716 void (*)(int) 10717 whose value matches no declarable function. 10718 SIG_DFL Request for default signal handling. 10719 SIG_ERR Return value from signal( ) in case of error. 10720 CX SIG_HOLD Request that signal be held. 10721 SIG_IGN Request that signal be ignored. 10722 The following data types shall be defined through typedef: 10723 sig_atomic_t Possibly volatile-qualified integer type of an object that can be accessed as 10724 an atomic entity, even in the presence of asynchronous interrupts. 10725 CX sigset_t Integer or structure type of an object used to represent sets of signals. 10726 CX pid_t As described in . 10727 RTS The header shall define the sigevent structure, which has at least the following 10728 members: 10729 int sigev_notify Notification type. 10730 int sigev_signo Signal number. 10731 union sigval sigev_value Signal value. 10732 void(*)(union sigval) sigev_notify_function Notification function. 10733 (pthread_attr_t *) sigev_notify_attributes Notification attributes. 10734 The following values of sigev_notify shall be defined: 10735 SIGEV_NONE No asynchronous notification is delivered when the event of interest 10736 occurs. 10737 SIGEV_SIGNAL A queued signal, with an application-defined value, is generated when 10738 the event of interest occurs. 10739 SIGEV_THREAD A notification function is called to perform notification. 10740 The sigval union shall be defined as: 10741 int sival_int Integer signal value. 10742 void *sival_ptr Pointer signal value. 10743 This header shall also declare the macros SIGRTMIN and SIGRTMAX, which evaluate to integer | 10744 expressions, and specify a range of signal numbers that are reserved for application use and for | 10745 which the realtime signal behavior specified in this volume of IEEE Std 1003.1-200x is supported. | 300 Technical Standard (2001) (Draft April 13, 2001) Headers 10746 The signal numbers in this range do not overlap any of the signals specified in the following | 10747 table. | 10748 The range SIGRTMIN through SIGRTMAX inclusive shall include at least {RTSIG_MAX} signal 10749 numbers. 10750 It is implementation-defined whether realtime signal behavior is supported for other signals. 10751 This header also declares the constants that are used to refer to the signals that occur in the 10752 system. Signals defined here begin with the letters SIG. Each of the signals have distinct positive 10753 integer values. The value 0 is reserved for use as the null signal (see kill( )). Additional 10754 implementation-defined signals may occur in the system. 10755 CX The ISO C standard only requires the signal names SIGABRT, SIGFPE, SIGILL, SIGINT, 10756 SIGSEGV, and SIGTERM to be defined. 10757 The following signals shall be supported on all implementations (default actions are explained 10758 below the table): 10759 _____________________________________________________________________________________ 10760 _ Signal Default Action Description ____________________________________________________________________________________ 10761 SIGABRT A Process abort signal. 10762 SIGALRM T Alarm clock. 10763 SIGBUS A Access to an undefined portion of a memory object. 10764 SIGCHLD I Child process terminated, stopped, | 10765 XSI or continued. | 10766 SIGCONT C Continue executing, if stopped. | 10767 SIGFPE A Erroneous arithmetic operation. 10768 SIGHUP T Hangup. 10769 SIGILL A Illegal instruction. 10770 SIGINT T Terminal interrupt signal. 10771 SIGKILL T Kill (cannot be caught or ignored). 10772 SIGPIPE T Write on a pipe with no one to read it. 10773 SIGQUIT A Terminal quit signal. 10774 SIGSEGV A Invalid memory reference. 10775 SIGSTOP S Stop executing (cannot be caught or ignored). 10776 SIGTERM T Termination signal. 10777 SIGTSTP S Terminal stop signal. 10778 SIGTTIN S Background process attempting read. 10779 SIGTTOU S Background process attempting write. 10780 SIGUSR1 T User-defined signal 1. 10781 SIGUSR2 T User-defined signal 2. 10782 XSI SIGPOLL T Pollable event. 10783 SIGPROF T Profiling timer expired. 10784 SIGSYS A Bad system call. 10785 SIGTRAP A Trace/breakpoint trap. 10786 SIGURG I High bandwidth data is available at a socket. 10787 XSI SIGVTALRM T Virtual timer expired. 10788 SIGXCPU A CPU time limit exceeded. 10789 _ SIGXFSZ A File size limit exceeded. ____________________________________________________________________________________ 10790 The default actions are as follows: 10791 T Abnormal termination of the process. The process is terminated with all the consequences 10792 of _exit( ) except that the status made available to wait( ) and waitpid( ) indicates abnormal 10793 termination by the specified signal. Base Definitions, Issue 6 301 Headers 10794 A Abnormal termination of the process. | 10795 XSI Additionally, implementation-defined abnormal termination actions, such as creation of a | 10796 core file, may occur. 10797 I Ignore the signal. 10798 S Stop the process. 10799 C Continue the process, if it is stopped; otherwise, ignore the signal. 10800 CX The header shall provide a declaration of struct sigaction, including at least the following 10801 members: 10802 void (*sa_handler)(int) What to do on receipt of signal. 10803 sigset_t sa_mask Set of signals to be blocked during execution 10804 of the signal handling function. 10805 int sa_flags Special flags. 10806 void (*)(int, siginfo_t *, void *) sa_sigaction 10807 Pointer to signal handler function or one 10808 of the macros SIG_IGN or SIG_DFL. 10809 10810 XSI The storage occupied by sa_handler and sa_sigaction may overlap, and a portable program must 10811 not use both simultaneously. 10812 The following shall be declared as constants: 10813 CX SA_NOCLDSTOP Do not generate SIGCHLD when children stop | 10814 XSI or stopped children continue. | 10815 CX SIG_BLOCK The resulting set is the union of the current set and the signal set pointed 10816 to by the argument set. 10817 CX SIG_UNBLOCK The resulting set is the intersection of the current set and the complement 10818 of the signal set pointed to by the argument set. 10819 CX SIG_SETMASK The resulting set is the signal set pointed to by the argument set. 10820 XSI SA_ONSTACK Causes signal delivery to occur on an alternate stack. 10821 XSI SA_RESETHAND Causes signal dispositions to be set to SIG_DFL on entry to signal 10822 handlers. 10823 XSI SA_RESTART Causes certain functions to become restartable. 10824 XSI SA_SIGINFO Causes extra information to be passed to signal handlers at the time of 10825 receipt of a signal. 10826 XSI SA_NOCLDWAIT Causes implementations not to create zombie processes on child death. 10827 XSI SA_NODEFER Causes signal not to be automatically blocked on entry to signal handler. 10828 XSI SS_ONSTACK Process is executing on an alternate signal stack. 10829 XSI SS_DISABLE Alternate signal stack is disabled. 10830 XSI MINSIGSTKSZ Minimum stack size for a signal handler. 10831 XSI SIGSTKSZ Default size in bytes for the alternate signal stack. 10832 XSI The ucontext_t structure shall be defined through typedef as described in . 10833 The mcontext_t type shall be defined through typedef as described in . 302 Technical Standard (2001) (Draft April 13, 2001) Headers 10834 The header shall define the stack_t type as a structure that includes at least the 10835 following members: 10836 void *ss_sp Stack base or pointer. 10837 size_t ss_size Stack size. 10838 int ss_flags Flags. 10839 The header shall define the sigstack structure that includes at least the following 10840 members: 10841 int ss_onstack Non-zero when signal stack is in use. 10842 void *ss_sp Signal stack pointer. 10843 10844 CX The header shall define the siginfo_t type as a structure that includes at least the | 10845 following members: | 10846 CX int si_signo Signal number. 10847 XSI int si_errno If non-zero, an errno value associated with 10848 this signal, as defined in . 10849 CX int si_code Signal code. 10850 XSI pid_t si_pid Sending process ID. 10851 uid_t si_uid Real user ID of sending process. 10852 void *si_addr Address of faulting instruction. 10853 int si_status Exit value or signal. 10854 long si_band Band event for SIGPOLL. 10855 RTS union sigval si_value Signal value. 10856 10857 The macros specified in the Code column of the following table are defined for use as values of 10858 XSI si_code that are signal-specific ornon-signal-specific reasons why the signal was generated. Base Definitions, Issue 6 303 Headers 10859 ______________________________________________________________________________________ 10860 _ Signal Code Reason _____________________________________________________________________________________ 10861 XSI SIGILL ILL_ILLOPC Illegal opcode. 10862 ILL_ILLOPN Illegal operand. 10863 ILL_ILLADR Illegal addressing mode. 10864 ILL_ILLTRP Illegal trap. 10865 ILL_PRVOPC Privileged opcode. 10866 ILL_PRVREG Privileged register. 10867 ILL_COPROC Coprocessor error. 10868 _ ILL_BADSTK Internal stack error. _____________________________________________________________________________________ 10869 SIGFPE FPE_INTDIV Integer divide by zero. 10870 FPE_INTOVF Integer overflow. 10871 FPE_FLTDIV Floating-point divide by zero. 10872 FPE_FLTOVF Floating-point overflow. 10873 FPE_FLTUND Floating-point underflow. 10874 FPE_FLTRES Floating-point inexact result. 10875 FPE_FLTINV Invalid floating-point operation. 10876 _ FPE_FLTSUB Subscript out of range. _____________________________________________________________________________________ 10877 SIGSEGV SEGV_MAPERR Address not mapped to object. 10878 _ SEGV_ACCERR Invalid permissions for mapped object. _____________________________________________________________________________________ 10879 SIGBUS BUS_ADRALN Invalid address alignment. 10880 BUS_ADRERR Non-existent physical address. 10881 _ BUS_OBJERR Object specific hardware error. _____________________________________________________________________________________ 10882 SIGTRAP TRAP_BRKPT Process breakpoint. 10883 _ TRAP_TRACE Process trace trap. _____________________________________________________________________________________ 10884 SIGCHLD CLD_EXITED Child has exited. 10885 CLD_KILLED Child has terminated abnormally and did not create a core file. 10886 CLD_DUMPED Child has terminated abnormally and created a core file. 10887 CLD_TRAPPED Traced child has trapped. 10888 CLD_STOPPED Child has stopped. 10889 _ CLD_CONTINUED Stopped child has continued. _____________________________________________________________________________________ 10890 SIGPOLL POLL_IN Data input available. 10891 POLL_OUT Output buffers available. 10892 POLL_MSG Input message available. 10893 POLL_ERR I/O error. 10894 POLL_PRI High priority input available. 10895 _ POLL_HUP Device disconnected. _____________________________________________________________________________________ 10896 CX Any SI_USER Signal sent by kill( ). 10897 SI_QUEUE Signal sent by the sigqueue( ). 10898 SI_TIMER Signal generated by expiration of a timer set by timer_settime( ). 10899 SI_ASYNCIO Signal generated by completion of an asynchronous I/O 10900 request. 10901 SI_MESGQ Signal generated by arrival of a message on an empty message 10902 _ queue. _____________________________________________________________________________________ 10903 XSI Implementations may support additional si_code values not included in this list, may generate 10904 values included in this list under circumstances other than those described in this list, and may 10905 contain extensions or limitations that prevent some values from being generated. 10906 Implementations do not generate a different value from the ones described in this list for 10907 circumstances described in this list. 304 Technical Standard (2001) (Draft April 13, 2001) Headers 10908 In addition, the following signal-specific information shall be available: 10909 _____________________________________________________________________________________ 10910 _ Signal Member Value ____________________________________________________________________________________ 10911 SIGILL void * si_addr Address of faulting instruction. 10912 _ SIGFPE ____________________________________________________________________________________ 10913 SIGSEGV void * si_addr Address of faulting memory reference. 10914 _ SIGBUS ____________________________________________________________________________________ 10915 SIGCHLD pid_t si_pid Child process ID. 10916 int si_status Exit value or signal. 10917 _ uid_t si_uid Real user ID of the process that sent the signal. ____________________________________________________________________________________ 10918 _ SIGPOLL long si_band Band event for POLL_IN, POLL_OUT, or POLL_MSG. ____________________________________________________________________________________ 10919 For some implementations, the value of si_addr may be inaccurate. 10920 The following shall be declared as functions and may also be defined as macros: 10921 XSI void (*bsd_signal(int, void (*)(int)))(int); 10922 CX int kill(pid_t, int); 10923 XSI int killpg(pid_t, int); 10924 THR int pthread_kill(pthread_t, int); | 10925 int pthread_sigmask(int, const sigset_t *, sigset_t *); 10926 int raise(int); 10927 CX int sigaction(int, const struct sigaction *restrict, 10928 struct sigaction *restrict); 10929 int sigaddset(sigset_t *, int); 10930 XSI int sigaltstack(const stack_t *restrict, stack_t *restrict); 10931 CX int sigdelset(sigset_t *, int); 10932 int sigemptyset(sigset_t *); 10933 int sigfillset(sigset_t *); 10934 XSI int sighold(int); 10935 int sigignore(int); 10936 int siginterrupt(int, int); 10937 CX int sigismember(const sigset_t *, int); 10938 void (*signal(int, void (*)(int)))(int); 10939 XSI int sigpause(int); 10940 CX int sigpending(sigset_t *); 10941 int sigprocmask(int, const sigset_t *restrict, sigset_t *restrict); 10942 RTS int sigqueue(pid_t, int, const union sigval); 10943 XSI int sigrelse(int); 10944 void (*sigset(int, void (*)(int)))(int); 10945 CX int sigsuspend(const sigset_t *); 10946 RTS int sigtimedwait(const sigset_t *restrict, siginfo_t *restrict, 10947 const struct timespec *restrict); 10948 CX int sigwait(const sigset_t *restrict, int *restrict); 10949 RTS int sigwaitinfo(const sigset_t *restrict, siginfo_t *restrict); 10950 Base Definitions, Issue 6 305 Headers 10951 CX Inclusion of the header may make visible all symbols from the header. 10952 APPLICATION USAGE 10953 None. 10954 RATIONALE 10955 None. 10956 FUTURE DIRECTIONS 10957 None. 10958 SEE ALSO 10959 , , , , , the System Interfaces volume of 10960 IEEE Std 1003.1-200x, alarm( ), bsd_signal( ), ioctl( ), kill( ), killpg( ), raise( ), sigaction( ), sigaddset( ), 10961 sigaltstack( ), sigdelset( ), sigemptyset( ), sigfillset( ), siginterrupt( ), sigismember( ), signal( ), 10962 sigpending( ), sigprocmask( ), sigqueue( ), sigsuspend( ), sigwaitinfo ( ), wait( ), waitid( ) 10963 CHANGE HISTORY 10964 First released in Issue 1. 10965 Issue 5 10966 The DESCRIPTION is updated for alignment with POSIX Realtime Extension and the POSIX 10967 Threads Extension. 10968 The default action for SIGURG is changed for i to iii. The function prototype for sigmask( ) is 10969 removed. 10970 Issue 6 10971 The Open Group Corrigendum U035/2 is applied. In the DESCRIPTION, the wording for 10972 abnormal termination is clarified. 10973 The Open Group Corrigendum U028/8 is applied, correcting the prototype for the sigset( ) 10974 function. 10975 The Open Group Corrigendum U026/3 is applied, correcting the type of the sigev_notify_function 10976 function member of the sigevent structure. 10977 The following new requirements on POSIX implementations derive from alignment with the 10978 Single UNIX Specification: 10979 * The SIGCHLD, SIGCONT, SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU signals are now 10980 mandated. This is also a FIPS requirement. 10981 * The pid_t definition is mandated. 10982 The RT markings are now changed to RTS to denote that the semantics are part of the Realtime 10983 Signals Extension option. 10984 The restrict keyword is added to the prototypes for sigaction( ), sigaltstack( ), sigprocmask( ), 10985 sigtimedwait( ), sigwait( ), and sigwaitinfo ( ). 10986 IEEE PASC Interpretation 1003.1 #85 is applied, adding the statement that symbols from 10987 may be made visible when is included. Extensions beyond the ISO C 10988 standard are now marked. 306 Technical Standard (2001) (Draft April 13, 2001) Headers 10989 NAME 10990 spawn.h - spawn (ADVANCED REALTIME) 10991 SYNOPSIS 10992 SPN #include 10993 10994 DESCRIPTION 10995 The header shall define the posix_spawnattr_t and posix_spawn_file_actions_t 10996 types used in performing spawn operations. 10997 The header shall define the flags that may be set in a posix_spawnattr_t object using 10998 the posix_spawnattr_setflags( ) function: 10999 POSIX_SPAWN_RESETIDS 11000 POSIX_SPAWN_SETPGROUP 11001 PS POSIX_SPAWN_SETSCHEDPARAM 11002 POSIX_SPAWN_SETSCHEDULER 11003 POSIX_SPAWN_SETSIGDEF 11004 POSIX_SPAWN_SETSIGMASK 11005 The following shall be declared as functions and may also be defined as macros. Function | 11006 prototypes shall be provided. | 11007 int posix_spawn(pid_t *restrict, const char *restrict, 11008 const posix_spawn_file_actions_t *, 11009 const posix_spawnattr_t *restrict, char *const [restrict], 11010 char *const [restrict]); 11011 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *, 11012 int); 11013 int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *, 11014 int, int); 11015 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict, 11016 int, const char *restrict, int, mode_t); 11017 int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t *); 11018 int posix_spawn_file_actions_init(posix_spawn_file_actions_t *); 11019 int posix_spawnattr_destroy(posix_spawnattr_t *); 11020 int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict, 11021 sigset_t *restrict); 11022 int posix_spawnattr_getflags(const posix_spawnattr_t *restrict, 11023 short *restrict); 11024 int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict, 11025 pid_t *restrict); 11026 PS int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict, 11027 struct sched_param *restrict); 11028 int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict, 11029 int *restrict); 11030 int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict, 11031 sigset_t *restrict); 11032 int posix_spawnattr_init(posix_spawnattr_t *); 11033 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict, 11034 const sigset_t *restrict); 11035 int posix_spawnattr_setflags(posix_spawnattr_t *, short); 11036 int posix_spawnattr_setpgroup(posix_spawnattr_t *, pid_t); 11037 PS Base Definitions, Issue 6 307 Headers 11038 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict, 11039 const struct sched_param *restrict); 11040 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *, int); 11041 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict, 11042 const sigset_t *restrict); 11043 int posix_spawnp(pid_t *restrict, const char *restrict, | 11044 const posix_spawn_file_actions_t *, 11045 const posix_spawnattr_t *restrict, 11046 char *const [restrict], char *const [restrict]); 11047 Inclusion of the header may make visible symbols defined in the , 11048 , and headers. 11049 APPLICATION USAGE 11050 None. 11051 RATIONALE 11052 None. 11053 FUTURE DIRECTIONS 11054 None. 11055 SEE ALSO 11056 , , , , the System Interfaces volume of 11057 IEEE Std 1003.1-200x, posix_spawnattr_destroy( ), posix_spawnattr_getsigdefault( ), 11058 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 11059 posix_spawnattr_getschedpolicy( ), posix_spawnattr_getsigmask( ), posix_spawnattr_init( ), 11060 posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), 11061 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 11062 posix_spawn( ), posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_adddup2( ), 11063 posix_spawn_file_actions_addopen( ), posix_spawn_file_actions_destroy( ), 11064 posix_spawn_file_actions_init( ), posix_spawnp( ) 11065 CHANGE HISTORY 11066 First released in Issue 6. Included for alignment with IEEE Std 1003.1d-1999. 11067 The restrict keyword is added to the prototypes for posix_spawn( ), 11068 posix_spawn_file_actions_addopen( ), posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), 11069 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 11070 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setschedparam( ), 11071 posix_spawnattr_setsigmask( ), and posix_spawnp( ). 308 Technical Standard (2001) (Draft April 13, 2001) Headers 11072 NAME 11073 stdarg.h - handle variable argument list 11074 SYNOPSIS 11075 #include 11076 void va_start(va_list ap, argN); 11077 void va_copy(va_list dest, va_list src); 11078 type va_arg(va_list ap, type); 11079 void va_end(va_list ap); 11080 DESCRIPTION 11081 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11082 conflict between the requirements described here and the ISO C standard is unintentional. This 11083 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11084 The header shall contain a set of macros which allows portable functions that accept 11085 variable argument lists to be written. Functions that have variable argument lists (such as 11086 printf( )) but do not use these macros, are inherently non-portable, as different systems use 11087 different argument-passing conventions. 11088 The type va_list shall be defined for variables used to traverse the list. 11089 The va_start( ) macro is invoked to initialize ap to the beginning of the list before any calls to 11090 va_arg( ). 11091 The va_copy( ) macro initializes as a copy of src, as if the va_start( ) macro had been applied to 11092 dest followed by the same sequence of uses of the va_arg( ) macro as had previously been used to 11093 reach the present state of src. Neither the va_copy( ) nor va_start( ) macro shall be invoked to 11094 reinitialize dest without an intervening invocation of the va_end( ) macro for the same dest. 11095 The object ap may be passed as an argument to another function; if that function invokes the 11096 va_arg( ) macro with parameter ap, the value of ap in the calling function is unspecified and shall | 11097 be passed to the va_end( ) macro prior to any further reference to ap. The parameter argN is the | 11098 identifier of the rightmost parameter in the variable parameter list in the function definition (the 11099 one just before the . . .). If the parameter argN is declared with the register storage class, with a 11100 function type or array type, or with a type that is not compatible with the type that results after 11101 application of the default argument promotions, the behavior is undefined. 11102 The va_arg( ) macro shall return the next argument in the list pointed to by ap. Each invocation 11103 of va_arg( ) modifies ap so that the values of successive arguments are returned in turn. The type 11104 parameter is the type the argument is expected to be. This is the type name specified such that 11105 the type of a pointer to an object that has the specified type can be obtained simply by suffixing 11106 a '*' to type. Different types can be mixed, but it is up to the routine to know what type of 11107 argument is expected. 11108 The va_end( ) macro is used to clean up; it invalidates ap for use (unless va_start( ) or va_copy( ) is 11109 invoked again). 11110 Each invocation of the va_start( ) and va_copy( ) macros shall be matched by a corresponding 11111 invocation of the va_end( ) macro in the same function. 11112 Multiple traversals, each bracketed by va_start( ) . . . va_end( ), are possible. 11113 EXAMPLES 11114 This example is a possible implementation of execl( ): 11115 #include Base Definitions, Issue 6 309 Headers 11116 #define MAXARGS 31 11117 /* 11118 * execl is called by 11119 * execl(file, arg1, arg2, ..., (char *)(0)); 11120 */ 11121 int execl(const char *file, const char *args, ...) 11122 { 11123 va_list ap; 11124 char *array[MAXARGS]; 11125 int argno = 0; 11126 va_start(ap, args); 11127 while (args != 0) { 11128 array[argno++] = args; 11129 args = va_arg(ap, const char *); 11130 } 11131 va_end(ap); 11132 return execv(file, array); 11133 } 11134 APPLICATION USAGE 11135 It is up to the calling routine to communicate to the called routine how many arguments there 11136 are, since it is not always possible for the called routine to determine this in any other way. For 11137 example, execl( ) is passed a null pointer to signal the end of the list. The printf( ) function can tell 11138 how many arguments are there by the format argument. 11139 RATIONALE 11140 None. 11141 FUTURE DIRECTIONS 11142 None. 11143 SEE ALSO 11144 The System Interfaces volume of IEEE Std 1003.1-200x, exec( ), printf( ) 11145 CHANGE HISTORY 11146 First released in Issue 4. Derived from the ANSI C standard. 310 Technical Standard (2001) (Draft April 13, 2001) Headers 11147 NAME 11148 stdbool.h - boolean type and values 11149 SYNOPSIS 11150 #include 11151 DESCRIPTION 11152 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11153 conflict between the requirements described here and the ISO C standard is unintentional. This 11154 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11155 The header shall define the following macros: 11156 bool Expands to _Bool. 11157 true Expands to the integer constant 1. 11158 false Expands to the integer constant 0. 11159 _ _bool_true_false_are_defined 11160 Expands to the integer constant 1. 11161 An application may undefine and then possibly redefine the macros bool, true, and false. 11162 APPLICATION USAGE 11163 None. 11164 RATIONALE 11165 None. 11166 FUTURE DIRECTIONS 11167 The ability to undefine and redefine the macros bool, true, and false is an obsolescent feature 11168 and may be withdrawn in the future. 11169 SEE ALSO 11170 None. 11171 CHANGE HISTORY 11172 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. Base Definitions, Issue 6 311 Headers 11173 NAME 11174 stddef.h - standard type definitions 11175 SYNOPSIS 11176 #include 11177 DESCRIPTION 11178 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11179 conflict between the requirements described here and the ISO C standard is unintentional. This 11180 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11181 The header shall define the following macros: 11182 NULL Null pointer constant. 11183 offsetof(type, member-designator) 11184 Integer constant expression of type size_t, the value of which is the offset in bytes 11185 to the structure member (member-designator), from the beginning of its structure 11186 (type). 11187 The header shall define the following types: 11188 ptrdiff_t Signed integer type of the result of subtracting two pointers. 11189 wchar_t Integer type whose range of values can represent distinct wide-character codes for 11190 all members of the largest character set specified among the locales supported by 11191 the compilation environment: the null character has the code value 0 and each | 11192 member of the portable character set has a code value equal to its value when used | 11193 as the lone character in an integer character constant. | 11194 size_t Unsigned integer type of the result of the sizeof operator. 11195 The implementation shall support one or more programming environments in which the widths | 11196 of ptrdiff_t, size_t, and wchar_t are no greater than the width of type long. The names of these | 11197 programming environments can be obtained using the confstr( ) function or the getconf utility. | 11198 APPLICATION USAGE 11199 None. 11200 RATIONALE 11201 None. 11202 FUTURE DIRECTIONS 11203 None. 11204 SEE ALSO 11205 , , the System Interfaces volume of IEEE Std 1003.1-200x, confstr( ), the | 11206 Shell and Utilities volume of IEEE Std 1003.1-200x, getconf | 11207 CHANGE HISTORY 11208 First released in Issue 4. Derived from the ANSI C standard. 312 Technical Standard (2001) (Draft April 13, 2001) Headers 11209 NAME 11210 stdint.h - integer types 11211 SYNOPSIS 11212 #include 11213 DESCRIPTION 11214 CX Some of the functionality described on this reference page extends the ISO C standard. 11215 Applications 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 these 11217 symbols in this header. 11218 The header shall declare sets of integer types having specified widths, and shall 11219 define corresponding sets of macros. It shall also define macros that specify limits of integer 11220 types corresponding to types defined in other standard headers. 11221 Note: The ``width'' of an integer type is the number of bits used to store its value in a pure binary 11222 system; the actual type may use more bits than that (for example, a 28-bit type could be stored 11223 in 32 bits of actual storage). An N-bit signed type has values in the range -2N-1 or 1-2N-1 to 11224 2N-1-1, while an N-bit unsigned type has values in the range 0 to 2N-1. 11225 Types are defined in the following categories: 11226 * Integer types having certain exact widths 11227 * Integer types having at least certain specified widths 11228 * Fastest integer types having at least certain specified widths 11229 * Integer types wide enough to hold pointers to objects 11230 * Integer types having greatest width 11231 (Some of these types may denote the same type.) 11232 Corresponding macros specify limits of the declared types and construct suitable constants. 11233 For each type described herein that the implementation provides, the header shall 11234 declare that typedef name and define the associated macros. Conversely, for each type described 11235 herein that the implementation does not provide, the header shall not declare that 11236 typedef name, nor shall it define the associated macros. An implementation shall provide those 11237 types described as required, but need not provide any of the others (described as optional). 11238 Integer Types 11239 When typedef names differing only in the absence or presence of the initial u are defined, they 11240 shall denote corresponding signed and unsigned types as described in the ISO/IEC 9899: 1999 11241 standard, Section 6.2.5; an implementation providing one of these corresponding types shall also 11242 provide the other. 11243 In the following descriptions, the symbol N represents an unsigned decimal integer with no 11244 leading zeros (for example, 8 or 24, but not 04 or 048). 11245 * Exact-width integer types 11246 The typedef name intN_t designates a signed integer type with width N, no padding bits, 11247 and a two's-complement representation. Thus, int8_t denotes a signed integer type with a 11248 width of exactly 8 bits. 11249 The typedef name uintN_t designates an unsigned integer type with width N. Thus, 11250 uint24_t denotes an unsigned integer type with a width of exactly 24 bits. Base Definitions, Issue 6 313 Headers 11251 CX The following types are required: | 11252 int8_t | 11253 int16_t 11254 int32_t 11255 uint8_t 11256 uint16_t 11257 uint32_t 11258 | 11259 If an implementation provides integer types with width 64 that meet these requirements, | 11260 then the following types are required: | 11261 int64_t || 11262 uint64_t || 11263 CX In particular, this will be the case if any of the following are true: | 11264 - The implementation supports the _POSIX_V6_ILP32_OFFBIG programming | 11265 environment and the application is being built in the _POSIX_V6_ILP32_OFFBIG 11266 programming environment (see the Shell and Utilities volume of IEEE Std 1003.1-200x, 11267 c99, Programming Environments). 11268 - The implementation supports the _POSIX_V6_LP64_OFF64 programming environment 11269 and the application is being built in the _POSIX_V6_LP64_OFF64 programming 11270 environment. 11271 - The implementation supports the _POSIX_V6_LPBIG_OFFBIG programming 11272 environment and the application is being built in the _POSIX_V6_LPBIG_OFFBIG 11273 programming environment. | 11274 All other types are of this form optional. | 11275 * Minimum-width integer types 11276 The typedef name int_leastN_t designates a signed integer type with a width of at least N, 11277 such that no signed integer type with lesser size has at least the specified width. Thus, 11278 int_least32_t denotes a signed integer type with a width of at least 32 bits. 11279 The typedef name uint_leastN_t designates an unsigned integer type with a width of at least 11280 N, such that no unsigned integer type with lesser size has at least the specified width. Thus, 11281 uint_least16_t denotes an unsigned integer type with a width of at least 16 bits. 11282 The following types are required: | 11283 int_least8_t || 11284 int_least16_t | 11285 int_least32_t | 11286 int_least64_t | 11287 uint_least8_t | 11288 uint_least16_t | 11289 uint_least32_t | 11290 uint_least64_t | 11291 All other types of this form are optional. | 11292 * Fastest minimum-width integer types | 11293 Each of the following types designates an integer type that is usually fastest to operate with | 11294 among all integer types that have at least the specified width. | 314 Technical Standard (2001) (Draft April 13, 2001) Headers 11295 The designated type is not guaranteed to be fastest for all purposes; if the implementation | 11296 has no clear grounds for choosing one type over another, it will simply pick some integer | 11297 type satisfying the signedness and width requirements. | 11298 The typedef name int_fastN_t designates the fastest signed integer type with a width of at | 11299 least N. The typedef name uint_fastN_t designates the fastest unsigned integer type with a | 11300 width of at least N. | 11301 The following types are required: | 11302 int_fast8_t || 11303 int_fast16_t | 11304 int_fast32_t | 11305 int_fast64_t | 11306 uint_fast8_t | 11307 uint_fast16_t | 11308 uint_fast32_t | 11309 uint_fast64_t | 11310 All other types of this form are optional. | 11311 * Integer types capable of holding object pointers | 11312 The following type designates a signed integer type with the property that any valid pointer | 11313 to void can be converted to this type, then converted back to a pointer to void, and the result | 11314 will compare equal to the original pointer: | 11315 intptr_t || 11316 The following type designates an unsigned integer type with the property that any valid | 11317 pointer to void can be converted to this type, then converted back to a pointer to void, and | 11318 the result will compare equal to the original pointer: | 11319 uintptr_t || 11320 XSI On XSI-conformant systems, the intptr_t and uintptr_t types are required;otherwise, they are | 11321 optional. | 11322 * Greatest-width integer types | 11323 The following type designates a signed integer type capable of representing any value of any | 11324 signed integer type: | 11325 intmax_t || 11326 The following type designates an unsigned integer type capable of representing any value of | 11327 any unsigned integer type: | 11328 uintmax_t || 11329 These types are required. | 11330 Note: Applications can test for optional types by using the corresponding limit macro from Limits of | 11331 Specified-Width Integer Types (on page 316). | Base Definitions, Issue 6 315 Headers 11332 Limits of Specified-Width Integer Types | 11333 The following macros specify the minimum and maximum limits of the types declared in the 11334 header. Each macro name corresponds to a similar type name in Integer Types (on 11335 page 313). 11336 Each instance of any defined macro shall be replaced by a constant expression suitable for use in 11337 #if preprocessing directives, and this expression shall have the same type as would an 11338 expression that is an object of the corresponding type converted according to the integer 11339 promotions. Its implementation-defined value shall be equal to or greater in magnitude 11340 (absolute value) than the corresponding value given below, with the same sign, except where 11341 stated to be exactly the given value. 11342 * Limits of exact-width integer types 11343 - Minimum values of exact-width signed integer types: 11344 {INTN_MIN} Exactly -(2N-1) 11345 - Maximum values of exact-width signed integer types: 11346 {INTN_MAX} Exactly 2N-1 -1 11347 - Maximum values of exact-width unsigned integer types: 11348 {UINTN_MAX} Exactly 2N -1 11349 * Limits of minimum-width integer types 11350 - Minimum values of minimum-width signed integer types: 11351 {INT_LEASTN_MIN} -(2N-1 -1) 11352 - Maximum values of minimum-width signed integer types: 11353 {INT_LEASTN_MAX} 2N-1 -1 | 11354 - Maximum values of minimum-width unsigned integer types: 11355 {UINT_LEASTN_MAX} 2N -1 11356 * Limits of fastest minimum-width integer types 11357 - Minimum values of fastest minimum-width signed integer types: 11358 {INT_FASTN_MIN} -(2N-1 -1) 11359 - Maximum values of fastest minimum-width signed integer types: 11360 {INT_FASTN_MAX} 2N-1 -1 11361 - Maximum values of fastest minimum-width unsigned integer types: 11362 {UINT_FASTN_MAX} 2N -1 11363 * Limits of integer types capable of holding object pointers 11364 - Minimum value of pointer-holding signed integer type: 11365 {INTPTR_MIN} -(215 -1) 11366 - Maximum value of pointer-holding signed integer type: 11367 {INTPTR_MAX} 215 -1 11368 - Maximum value of pointer-holding unsigned integer type: 316 Technical Standard (2001) (Draft April 13, 2001) Headers 11369 {UINTPTR_MAX} 216 -1 11370 * Limits of greatest-width integer types 11371 - Minimum value of greatest-width signed integer type: 11372 {INTMAX_MIN} -(263 -1) 11373 - Maximum value of greatest-width signed integer type: 11374 {INTMAX_MAX} 263 -1 11375 - Maximum value of greatest-width unsigned integer type: 11376 {UINTMAX_MAX} 264 -1 11377 Limits of Other Integer Types 11378 The following macros specify the minimum and maximum limits of integer types corresponding 11379 to types defined in other standard headers. 11380 Each instance of these macros shall be replaced by a constant expression suitable for use in #if 11381 preprocessing directives, and this expression shall have the same type as would an expression 11382 that is an object of the corresponding type converted according to the integer promotions. Its 11383 implementation-defined value shall be equal to or greater in magnitude (absolute value) than 11384 the corresponding value given below, with the same sign. 11385 * Limits of ptrdiff_t: 11386 {PTRDIFF_MIN} -65535 11387 {PTRDIFF_MAX} +65535 11388 * Limits of sig_atomic_t: 11389 {SIG_ATOMIC_MIN} See below. 11390 {SIG_ATOMIC_MAX} See below. 11391 * Limit of size_t: 11392 {SIZE_MAX} 65535 11393 * Limits of wchar_t: 11394 {WCHAR_MIN} See below. 11395 {WCHAR_MAX} See below. 11396 * Limits of wint_t: 11397 {WINT_MIN} See below. 11398 {WINT_MAX} See below. 11399 If sig_atomic_t (see the header) is defined as a signed integer type, the value of 11400 {SIG_ATOMIC_MIN} shall be no greater than -127 and the value of {SIG_ATOMIC_MAX} shall 11401 be no less than 127; otherwise, sig_atomic_t shall be defined as an unsigned integer type, and the 11402 value of {SIG_ATOMIC_MIN} shall be 0 and the value of {SIG_ATOMIC_MAX} shall be no less 11403 than 255. 11404 If wchar_t (see the header) is defined as a signed integer type, the value of 11405 {WCHAR_MIN} shall be no greater than -127 and the value of {WCHAR_MAX} shall be no less 11406 than 127; otherwise, wchar_t shall be defined as an unsigned integer type, and the value of 11407 {WCHAR_MIN} shall be 0 and the value of {WCHAR_MAX} shall be no less than 255. Base Definitions, Issue 6 317 Headers 11408 If wint_t (see the header) is defined as a signed integer type, the value of 11409 {WINT_MIN} shall be no greater than -32767 and the value of {WINT_MAX} shall be no less 11410 than 32767; otherwise, wint_t shall be defined as an unsigned integer type, and the value of 11411 {WINT_MIN} shall be 0 and the value of {WINT_MAX} shall be no less than 65535. | 11412 Macros for Integer Constant Expressions | 11413 The following macros expand to integer constant expressions suitable for initializing objects that | 11414 have integer types corresponding to types defined in the header. Each macro name 11415 corresponds to a similar type name listed under Minimum-width integer types and Greatest-width 11416 integer types. 11417 Each invocation of one of these macros shall expand to an integer constant expression suitable | 11418 for use in #if preprocessing directives. The type of the expression shall have the same type as | 11419 would an expression that is an object of the corresponding type converted according to the | 11420 integer promotions. The value of the expression shall be that of the argument. | 11421 The argument in any instance of these macros shall be a decimal, octal, or hexadecimal constant | 11422 with a value that does not exceed the limits for the corresponding type. 11423 * Macros for minimum-width integer constant expressions | 11424 The macro INTN_C(value) shall expand to an integer constant expression corresponding to | 11425 the type int_leastN_t. The macro UINTN_C(value) shall expand to an integer constant 11426 expression corresponding to the type uint_leastN_t. For example, if uint_least64_t is a name 11427 for the type unsigned long long, then UINT64_C(0x123) might expand to the integer 11428 constant 0x123ULL. | 11429 * Macros for greatest-width integer constant expressions | 11430 The following macro expands to an integer constant expression having the value specified by | 11431 its argument and the type intmax_t: | 11432 INTMAX_C(value) || 11433 The following macro expands to an integer constant expression having the value specified by | 11434 its argument and the type uintmax_t: | 11435 UINTMAX_C(value) || 11436 APPLICATION USAGE | 11437 None. | 11438 RATIONALE | 11439 The header is a subset of the header more suitable for use in | 11440 freestanding environments, which might not support the formatted I/O functions. In some | 11441 environments, if the formatted conversion support is not wanted, using this header instead of | 11442 the header avoids defining such a large number of macros. | 11443 As a consequence of adding int8_t the following are true: | 11444 * A byte is exactly 8 bits. | 11445 * {CHAR_BIT} has the value 8, {SCHAR_MAX} has the value 127, {SCHAR_MIN} has the | 11446 value -127 or -128, and {UCHAR_MAX} has the value 255. | 11447 FUTURE DIRECTIONS | 11448 typedef names beginning with int or uint and ending with _t may be added to the types defined 11449 in the header. Macro names beginning with INT or UINT and ending with _MAX, 11450 _MIN, or _C may be added to the macros defined in the header. 318 Technical Standard (2001) (Draft April 13, 2001) Headers 11451 SEE ALSO 11452 , , , 11453 CHANGE HISTORY 11454 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. | 11455 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | Base Definitions, Issue 6 319 Headers 11456 NAME 11457 stdio.h - standard buffered input/output 11458 SYNOPSIS 11459 #include 11460 DESCRIPTION 11461 CX Some of the functionality described on this reference page extends the ISO C standard. 11462 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 11463 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 11464 symbols in this header. 11465 The header shall define the following macros as positive integer constant expressions: 11466 BUFSIZ Size of buffers. 11467 _IOFBF Input/output fully buffered. 11468 _IOLBF Input/output line buffered. 11469 _IONBF Input/output unbuffered. 11470 CX L_ctermid Maximum size of character array to hold ctermid( ) output. 11471 L_tmpnam Maximum size of character array to hold tmpnam( ) output. 11472 SEEK_CUR Seek relative to current position. 11473 SEEK_END Seek relative to end-of-file. 11474 SEEK_SET Seek relative to start-of-file. 11475 The following macros shall be defined as positive integer constant expressions which denote 11476 implementation limits: 11477 {FILENAME_MAX} Maximum size in bytes of the longest filename string that the 11478 implementation guarantees can be opened. 11479 {FOPEN_MAX} Number of streams which the implementation guarantees can be open 11480 simultaneously. The value is at least eight. 11481 {TMP_MAX} Minimum number of unique filenames generated by tmpnam( ). 11482 Maximum number of times an application can call tmpnam( ) reliably. The 11483 XSI value of {TMP_MAX} is at least 25. On XSI-conformant systems, the 11484 value of {TMP_MAX} is at least 10,000. 11485 The following macro name shall be defined as a negative integer constant expression: 11486 EOF End-of-file return value. 11487 The following macro name shall be defined as a null pointer constant: 11488 NULL Null pointer. 11489 The following macro name shall be defined as a string constant: 11490 XSI P_tmpdir Default directory prefix for tempnam( ). 11491 The following shall be defined as expressions of type ``pointer to FILE'' that point to the FILE 11492 objects associated, respectively, with the standard error, input, and output streams: 11493 stderr Standard error output stream. 11494 stdin Standard input stream. 320 Technical Standard (2001) (Draft April 13, 2001) Headers 11495 stdout Standard output stream. 11496 The following data types shall be defined through typedef: 11497 FILE A structure containing information about a file. 11498 fpos_t A non-array type containing all information needed to specify uniquely 11499 every position within a file. 11500 XSI va_list As described in . 11501 size_t As described in . 11502 The following shall be declared as functions and may also be defined as macros. Function | 11503 prototypes shall be provided. | 11504 void clearerr(FILE *); 11505 CX char *ctermid(char *); 11506 int fclose(FILE *); 11507 CX FILE *fdopen(int, const char *); 11508 int feof(FILE *); 11509 int ferror(FILE *); 11510 int fflush(FILE *); 11511 int fgetc(FILE *); 11512 int fgetpos(FILE *restrict, fpos_t *restrict); 11513 char *fgets(char *restrict, int, FILE *restrict); 11514 CX int fileno(FILE *); 11515 TSF void flockfile(FILE *); 11516 FILE *fopen(const char *restrict, const char *restrict); 11517 int fprintf(FILE *restrict, const char *restrict, ...); 11518 int fputc(int, FILE *); 11519 int fputs(const char *restrict, FILE *restrict); 11520 size_t fread(void *restrict, size_t, size_t, FILE *restrict); 11521 FILE *freopen(const char *restrict, const char *restrict, 11522 FILE *restrict); 11523 int fscanf(FILE *restrict, const char *restrict, ...); 11524 int fseek(FILE *, long, int); 11525 CX int fseeko(FILE *, off_t, int); 11526 int fsetpos(FILE *, const fpos_t *); 11527 long ftell(FILE *); 11528 CX off_t ftello(FILE *); 11529 TSF int ftrylockfile(FILE *); 11530 void funlockfile(FILE *); 11531 size_t fwrite(const void *restrict, size_t, size_t, FILE *restrict); 11532 int getc(FILE *); 11533 int getchar(void); 11534 TSF int getc_unlocked(FILE *); 11535 int getchar_unlocked(void); 11536 char *gets(char *); 11537 CX int pclose(FILE *); 11538 void perror(const char *); 11539 CX FILE *popen(const char *, const char *); 11540 int printf(const char *restrict, ...); 11541 int putc(int, FILE *); 11542 int putchar(int); 11543 TSF Base Definitions, Issue 6 321 Headers 11544 int putc_unlocked(int, FILE *); 11545 int putchar_unlocked(int); 11546 int puts(const char *); 11547 int remove(const char *); 11548 int rename(const char *, const char *); 11549 void rewind(FILE *); 11550 int scanf(const char *restrict, ...); 11551 void setbuf(FILE *restrict, char *restrict); 11552 int setvbuf(FILE *restrict, char *restrict, int, size_t); 11553 int snprintf(char *restrict, size_t, const char *restrict, ...); 11554 int sprintf(char *restrict, const char *restrict, ...); 11555 int sscanf(const char *restrict, const char *restrict, int ...); 11556 XSI char *tempnam(const char *, const char *); 11557 FILE *tmpfile(void); 11558 char *tmpnam(char *); 11559 int ungetc(int, FILE *); 11560 int vfprintf(FILE *restrict, const char *restrict, va_list); 11561 int vfscanf(FILE *restrict, const char *restrict, va_list); 11562 int vprintf(const char *restrict, va_list); 11563 int vscanf(const char *restrict, va_list); 11564 int vsnprintf(char *restrict, size_t, const char *restrict, va_list; 11565 int vsprintf(char *restrict, const char *restrict, va_list); 11566 int vsscanf(const char *restrict, const char *restrict, va_list arg); 11567 XSI Inclusion of the header may also make visible all symbols from . 11568 APPLICATION USAGE 11569 None. 11570 RATIONALE 11571 None. 11572 FUTURE DIRECTIONS 11573 None. 11574 SEE ALSO 11575 , the System Interfaces volume of IEEE Std 1003.1-200x, clearerr( ), ctermid( ), 11576 fclose( ), fdopen( ), fgetc( ), fgetpos( ), ferror( ), feof( ), fflush( ), fgets( ), fileno( ), flockfile ( ), fopen( ), 11577 fputc( ), fputs( ), fread( ), freopen( ), fseek( ), fsetpos( ), ftell( ), fwrite( ), getc( ), getc_unlocked( ), 11578 getwchar( ), getchar( ), getopt( ), gets( ), pclose( ), perror( ), popen( ), printf( ), putc( ), putchar( ), puts( ), 11579 putwchar( ), remove( ), rename( ), rewind( ), scanf( ), setbuf( ), setvbuf( ), sscanf( ), stdin, system( ), 11580 tempnam( ), tmpfile( ), tmpnam( ), ungetc( ), vfscanf( ), vscanf( ), vprintf( ), vsscanf( ) 11581 CHANGE HISTORY 11582 First released in Issue 1. Derived from Issue 1 of the SVID. 11583 Issue 5 11584 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 11585 Large File System extensions are added. 11586 The constant L_cuserid and the external variables optarg, opterr, optind, and optopt are marked as 11587 extensions and LEGACY. 11588 The cuserid( ) and getopt( ) functions are marked LEGACY. 322 Technical Standard (2001) (Draft April 13, 2001) Headers 11589 Issue 6 11590 The constant L_cuserid and the external variables optarg, opterr, optind, and optopt are removed 11591 as they were previously marked LEGACY. 11592 The cuserid( ), getopt( ), and getw( ) functions are removed as they were previously marked | 11593 LEGACY. 11594 Several functions are marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 11595 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. Note that the 11596 description of the fpos_t type is now explicitly updated to exclude array types. 11597 Extensions beyond the ISO C standard are now marked. | Base Definitions, Issue 6 323 Headers 11598 NAME 11599 stdlib.h - standard library definitions 11600 SYNOPSIS 11601 #include 11602 DESCRIPTION 11603 CX Some of the functionality described on this reference page extends the ISO C standard. 11604 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 11605 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 11606 symbols in this header. 11607 The header shall define the following macros: 11608 EXIT_FAILURE Unsuccessful termination for exit( ); evaluates to a non-zero value. 11609 EXIT_SUCCESS Successful termination for exit( ); evaluates to 0. 11610 NULL Null pointer. 11611 {RAND_MAX} Maximum value returned by rand( ); at least 32,767. 11612 {MB_CUR_MAX} Integer expression whose value is the maximum number of bytes in a 11613 character specified by the current locale. 11614 The following data types shall be defined through typedef: 11615 div_t Structure type returned by the div( ) function. 11616 ldiv_t Structure type returned by the ldiv( ) function. 11617 lldiv_t Structure type returned by the lldiv( ) function. 11618 size_t As described in . 11619 wchar_t As described in . 11620 In addition, the following symbolic names and macros shall be defined as in , for 11621 use in decoding the return value from system( ): 11622 XSI WNOHANG 11623 WUNTRACED 11624 WEXITSTATUS 11625 WIFEXITED 11626 WIFSIGNALED 11627 WIFSTOPPED 11628 WSTOPSIG 11629 WTERMSIG 11630 11631 The following shall be declared as functions and may also be defined as macros. Function | 11632 prototypes shall be provided. | 11633 void _Exit(int); 11634 XSI long a64l(const char *); 11635 void abort(void); 11636 int abs(int); 11637 int atexit(void (*)(void)); 11638 double atof(const char *); 11639 int atoi(const char *); 11640 long atol(const char *); 324 Technical Standard (2001) (Draft April 13, 2001) Headers 11641 long long atoll(const char *); 11642 void *bsearch(const void *, const void *, size_t, size_t, 11643 int (*)(const void *, const void *)); 11644 void *calloc(size_t, size_t); 11645 div_t div(int, int); 11646 XSI double drand48(void); 11647 char *ecvt(double, int, int *restrict, int *restrict); (LEGACY) 11648 double erand48(unsigned short[3]); 11649 void exit(int); 11650 XSI char *fcvt(double, int, int *restrict, int *restrict); (LEGACY) 11651 void free(void *); 11652 XSI char *gcvt(double, int, char *); (LEGACY) 11653 char *getenv(const char *); 11654 XSI int getsubopt(char **, char *const *, char **); 11655 int grantpt(int); 11656 char *initstate(unsigned, char *, size_t); 11657 long jrand48(unsigned short[3]); 11658 char *l64a(long); 11659 long labs(long); 11660 XSI void lcong48(unsigned short[7]); 11661 ldiv_t ldiv(long, long); 11662 long long llabs(long long); 11663 lldiv_t lldiv(long long, long long); 11664 XSI long lrand48(void); 11665 void *malloc(size_t); 11666 int mblen(const char *, size_t); 11667 size_t mbstowcs(wchar_t *restrict, const char *restrict, size_t); 11668 int mbtowc(wchar_t *restrict, const char *restrict, size_t); 11669 XSI char *mktemp(char *); (LEGACY) 11670 int mkstemp(char *); 11671 long mrand48(void); 11672 long nrand48(unsigned short[3]); 11673 ADV int posix_memalign(void **, size_t, size_t); 11674 XSI int posix_openpt(int); 11675 char *ptsname(int); 11676 int putenv(char *); 11677 void qsort(void *, size_t, size_t, int (*)(const void *, 11678 const void *)); 11679 int rand(void); 11680 TSF int rand_r(unsigned *); 11681 XSI long random(void); 11682 void *realloc(void *, size_t); 11683 XSI char *realpath(const char *restrict, char *restrict); 11684 unsigned short seed48(unsigned short[3]); 11685 CX int setenv(const char *, const char *, int); 11686 XSI void setkey(const char *); 11687 char *setstate(const char *); 11688 void srand(unsigned); 11689 XSI void srand48(long); 11690 void srandom(unsigned); 11691 double strtod(const char *restrict, char **restrict); 11692 float strtof(const char *restrict, char **restrict); Base Definitions, Issue 6 325 Headers 11693 long strtol(const char *restrict, char **restrict, int); 11694 long double strtold(const char *restrict, char **restrict); 11695 long long strtoll(const char *restrict, char **restrict, int); 11696 unsigned long strtoul(const char *restrict, char **restrict, int); 11697 long long strtoull(const char *restrict, char **restrict, int); 11698 int system(const char *); 11699 XSI int unlockpt(int); 11700 CX int unsetenv(const char *); 11701 size_t wcstombs(char *restrict, const wchar_t *restrict, size_t); 11702 int wctomb(char *, wchar_t); 11703 XSI Inclusion of the header may also make visible all symbols from , 11704 , , and . 11705 APPLICATION USAGE 11706 None. 11707 RATIONALE 11708 None. 11709 FUTURE DIRECTIONS 11710 None. 11711 SEE ALSO 11712 , the System Interfaces volume of IEEE Std 1003.1-200x, _Exit( ), a64l( ), abort( ), 11713 abs( ), atexit( ), atof( ), atoi( ), atol( ), atoll( ), bsearch( ), calloc( ), div( ), drand48( ), erand48( ), exit( ), 11714 free( ), getenv( ), getsubopt( ), grantpt( ), initstate( ), jrand48( ), l64a( ), labs( ), lcong48( ), ldiv( ), llabs( ), 11715 lldiv( ), lrand48( ), malloc( ), mblen( ), mbstowcs( ), mbtowc( ), mkstemp( ), mrand48( ), nrand48( ), 11716 posix_memalign( ), ptsname( ), putenv( ), qsort( ), rand( ), realloc( ), realpath( ), setstate( ), srand( ), 11717 srand48( ), srandom( ), strtod( ), strtof( ), strtol( ), strtold( ), strtoll( ), strtoul( ), strtoull( ), unlockpt( ), 11718 wcstombs( ), wctomb( ) 11719 CHANGE HISTORY 11720 First released in Issue 3. 11721 Issue 5 11722 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 11723 The ttyslot( ) and valloc( ) functions are marked LEGACY. 11724 The type of the third argument to initstate( ) is changed from int to size_t. The type of the return 11725 value from setstate( ) is changed from char to char *, and the type of the first argument is 11726 changed from char * to const char *. 11727 Issue 6 11728 The Open Group Corrigendum U021/1 is applied, correcting the prototype for realpath( ) to be 11729 consistent with the reference page. 11730 The Open Group Corrigendum U028/13 is applied, correcting the prototype for putenv( ) to be 11731 consistent with the reference page. 11732 The rand_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 11733 Function prototypes for setenv( ) and unsetenv( ) are added. 11734 The posix_memalign( ) function is added for alignment with IEEE Std 1003.1d-1999. 11735 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. 326 Technical Standard (2001) (Draft April 13, 2001) Headers 11736 The ecvt( ), fcvt( ), gcvt( ), and mktemp( ) functions are marked LEGACY. 11737 The ttyslot( ) and valloc( ) functions are removed as they were previously marked LEGACY. | 11738 Extensions beyond the ISO C standard are now marked. | Base Definitions, Issue 6 327 Headers 11739 NAME 11740 string.h - string operations 11741 SYNOPSIS 11742 #include 11743 DESCRIPTION 11744 CX Some of the functionality described on this reference page extends the ISO C standard. 11745 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 11746 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 11747 symbols in this header. 11748 The header shall define the following: 11749 NULL Null pointer constant. 11750 size_t As described in . 11751 The following shall be declared as functions and may also be defined as macros. Function | 11752 prototypes shall be provided. | 11753 XSI void *memccpy(void *restrict, const void *restrict, int, size_t); 11754 void *memchr(const void *, int, size_t); 11755 int memcmp(const void *, const void *, size_t); 11756 void *memcpy(void *restrict, const void *restrict, size_t); 11757 void *memmove(void *, const void *, size_t); 11758 void *memset(void *, int, size_t); 11759 char *strcat(char *restrict, const char *restrict); 11760 char *strchr(const char *, int); 11761 int strcmp(const char *, const char *); 11762 int strcoll(const char *, const char *); 11763 char *strcpy(char *restrict, const char *restrict); 11764 size_t strcspn(const char *, const char *); 11765 XSI char *strdup(const char *); 11766 char *strerror(int); 11767 size_t strlen(const char *); 11768 char *strncat(char *restrict, const char *restrict, size_t); 11769 int strncmp(const char *, const char *, size_t); 11770 char *strncpy(char *restrict, const char *restrict, size_t); 11771 char *strpbrk(const char *, const char *); 11772 char *strrchr(const char *, int); 11773 size_t strspn(const char *, const char *); 11774 char *strstr(const char *, const char *); 11775 char *strtok(char *restrict, const char *restrict); 11776 TSF char *strtok_r(char *, const char *, char **); 11777 size_t strxfrm(char *restrict, const char *restrict, size_t); 11778 XSI Inclusion of the header may also make visible all symbols from . 328 Technical Standard (2001) (Draft April 13, 2001) Headers 11779 APPLICATION USAGE 11780 None. 11781 RATIONALE 11782 None. 11783 FUTURE DIRECTIONS 11784 None. 11785 SEE ALSO 11786 , the System Interfaces volume of IEEE Std 1003.1-200x, memccpy( ), memchr( ), 11787 memcmp( ), memcpy( ), memmove( ), memset( ), strcat( ), strchr( ), strcmp( ), strcoll( ), strcpy( ), 11788 strcspn( ), strdup( ), strerror( ), strlen( ), strncat( ), strncmp( ), strncpy( ), strpbrk( ), strrchr( ), strspn( ), 11789 strstr( ), strtok( ), strxfrm( ) 11790 CHANGE HISTORY 11791 First released in Issue 1. Derived from Issue 1 of the SVID. 11792 Issue 5 11793 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 11794 Issue 6 11795 The strtok_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 11796 This reference page is updated to align with the ISO/IEC 9899: 1999 standard. Base Definitions, Issue 6 329 Headers 11797 NAME 11798 strings.h - string operations 11799 SYNOPSIS 11800 XSI #include 11801 11802 DESCRIPTION 11803 The following shall be declared as functions and may also be defined as macros. Function | 11804 prototypes shall be provided. | 11805 int bcmp(const void *, const void *, size_t); (LEGACY) 11806 void bcopy(const void *, void *, size_t); (LEGACY) 11807 void bzero(void *, size_t); (LEGACY) 11808 int ffs(int); 11809 char *index(const char *, int); (LEGACY) 11810 char *rindex(const char *, int); (LEGACY) 11811 int strcasecmp(const char *, const char *); 11812 int strncasecmp(const char *, const char *, size_t); 11813 The size_t type shall be defined through typedef as described in . 11814 APPLICATION USAGE 11815 None. 11816 RATIONALE 11817 None. 11818 FUTURE DIRECTIONS 11819 None. 11820 SEE ALSO 11821 , the System Interfaces volume of IEEE Std 1003.1-200x, ffs( ), strcasecmp( ), 11822 strncasecmp( ) 11823 CHANGE HISTORY 11824 First released in Issue 4, Version 2. 11825 Issue 6 11826 The Open Group Corrigendum U021/2 is applied, correcting the prototype for index( ) to be 11827 consistent with the reference page. 11828 The bcmp( ), bcopy( ), bzero( ), index( ), and rindex( ) functions are marked LEGACY. 330 Technical Standard (2001) (Draft April 13, 2001) Headers 11829 NAME 11830 stropts.h - STREAMS interface (STREAMS) 11831 SYNOPSIS 11832 XSR #include 11833 11834 DESCRIPTION 11835 The header shall define the bandinfo structure that includes at least the following 11836 members: 11837 unsigned char bi_pri Priority band. | 11838 int bi_flag Flushing type. | 11839 The header shall define the strpeek structure that includes at least the following | 11840 members: 11841 struct strbuf ctlbuf The control portion of the message. | 11842 struct strbuf databuf The data portion of the message. | 11843 t_uscalar_t flags RS_HIPRI or 0. | 11844 The header shall define the strbuf structure that includes at least the following | 11845 members: 11846 int maxlen Maximum buffer length. | 11847 int len Length of data. | 11848 char *buf Pointer to buffer. | 11849 The header shall define the strfdinsert structure that includes at least the following | 11850 members: 11851 struct strbuf ctlbuf The control portion of the message. | 11852 struct strbuf databuf The data portion of the message. | 11853 t_uscalar_t flags RS_HIPRI or 0. | 11854 int fildes File descriptor of the other STREAM. | 11855 int offset Relative location of the stored value. | 11856 The header shall define the strioctl structure that includes at least the following | 11857 members: 11858 int ic_cmd ioctl( ) command. | 11859 int ic_timout Timeout for response. | 11860 int ic_len Length of data. | 11861 char *ic_dp Pointer to buffer. | 11862 The header shall define the strrecvfd structure that includes at least the following | 11863 members: 11864 int fda Received file descriptor. | 11865 uid_t uid UID of sender. | 11866 gid_t gid GID of sender. | 11867 The uid_t and gid_t types shall be defined through typedef as described in . | 11868 The header shall define the t_scalar_t and t_uscalar_t types respectively as signed | 11869 and unsigned opaque types of equal length of at least 32 bits. | 11870 The header shall define the str_list structure that includes at least the following 11871 members: Base Definitions, Issue 6 331 Headers 11872 int sl_nmods Number of STREAMS module names. | 11873 struct str_mlist *sl_modlist STREAMS module names. | 11874 The header shall define the str_mlist structure that includes at least the following | 11875 member: 11876 char l_name[FMNAMESZ+1] A STREAMS module name. | 11877 At least the following macros shall be defined for use as the request argument to ioctl( ): | 11878 I_PUSH Push a STREAMS module. | 11879 I_POP Pop a STREAMS module. | 11880 I_LOOK Get the top module name. | 11881 I_FLUSH Flush a STREAM. | 11882 I_FLUSHBAND Flush one band of a STREAM. | 11883 I_SETSIG Ask for notification signals. | 11884 I_GETSIG Retrieve current notification signals. | 11885 I_FIND Look for a STREAMS module. | 11886 I_PEEK Peek at the top message on a STREAM. | 11887 I_SRDOPT Set the read mode. | 11888 I_GRDOPT Get the read mode. | 11889 I_NREAD Size the top message. | 11890 I_FDINSERT Send implementation-defined information about another STREAM. | 11891 I_STR Send a STREAMS ioctl( ). | 11892 I_SWROPT Set the write mode. | 11893 I_GWROPT Get the write mode. | 11894 I_SENDFD Pass a file descriptor through a STREAMS pipe. | 11895 I_RECVFD Get a file descriptor sent via I_SENDFD. | 11896 I_LIST Get all the module names on a STREAM. | 11897 I_ATMARK Is the top message ``marked''? | 11898 I_CKBAND See if any messages exist in a band. | 11899 I_GETBAND Get the band of the top message on a STREAM. | 11900 I_CANPUT Is a band writable? | 11901 I_SETCLTIME Set close time delay. | 11902 I_GETCLTIME Get close time delay. | 11903 I_LINK Connect two STREAMs. | 11904 I_UNLINK Disconnect two STREAMs. | 11905 I_PLINK Persistently connect two STREAMs. | 11906 I_PUNLINK Dismantle a persistent STREAMS link. | 332 Technical Standard (2001) (Draft April 13, 2001) Headers 11907 At least the following macros shall be defined for use with I_LOOK: | 11908 FMNAMESZ The minimum size in bytes of the buffer referred to by the arg argument. 11909 At least the following macros shall be defined for use with I_FLUSH: | 11910 FLUSHR Flush read queues. 11911 FLUSHW Flush write queues. 11912 FLUSHRW Flush read and write queues. 11913 At least the following macros shall be defined for use with I_SETSIG: | 11914 S_RDNORM A normal (priority band set to 0) message has arrived at the head of a 11915 STREAM head read queue. 11916 S_RDBAND A message with a non-zero priority band has arrived at the head of a STREAM 11917 head read queue. 11918 S_INPUT A message, other than a high-priority message, has arrived at the head of a 11919 STREAM head read queue. 11920 S_HIPRI A high-priority message is present on a STREAM head read queue. 11921 S_OUTPUT The write queue for normal data (priority band 0) just below the STREAM 11922 head is no longer full. This notifies the process that there is room on the queue 11923 for sending (or writing) normal data downstream. 11924 S_WRNORM Equivalent to S_OUTPUT. | 11925 S_WRBAND The write queue for a non-zero priority band just below the STREAM head is 11926 no longer full. 11927 S_MSG A STREAMS signal message that contains the SIGPOLL signal reaches the 11928 front of the STREAM head read queue. 11929 S_ERROR Notification of an error condition reaches the STREAM head. 11930 S_HANGUP Notification of a hangup reaches the STREAM head. 11931 S_BANDURG When used in conjunction with S_RDBAND, SIGURG is generated instead of 11932 SIGPOLL when a priority message reaches the front of the STREAM head read 11933 queue. 11934 At least the following macros shall be defined for use with I_PEEK: | 11935 RS_HIPRI Only look for high-priority messages. 11936 At least the following macros shall be defined for use with I_SRDOPT: | 11937 RNORM Byte-STREAM mode, the default. 11938 RMSGD Message-discard mode. 11939 RMSGN Message-nondiscard mode. 11940 RPROTNORM Fail read( ) with [EBADMSG] if a message containing a control part is at the 11941 front of the STREAM head read queue. 11942 RPROTDAT Deliver the control part of a message as data when a process issues a read( ). 11943 RPROTDIS Discard the control part of a message, delivering any data part, when a 11944 process issues a read( ). Base Definitions, Issue 6 333 Headers 11945 At least the following macros shall be defined for use with I_SWOPT: | 11946 SNDZERO Send a zero-length message downstream when a write( ) of 0 bytes occurs. 11947 At least the following macros shall be defined for use with I_ATMARK: | 11948 ANYMARK Check if the message is marked. 11949 LASTMARK Check if the message is the last one marked on the queue. 11950 At least the following macros shall be defined for use with I_UNLINK: | 11951 MUXID_ALL Unlink all STREAMs linked to the STREAM associated with fildes. 11952 The following macros shall be defined for getmsg( ), getpmsg( ), putmsg( ), and putpmsg( ): | 11953 MSG_ANY Receive any message. 11954 MSG_BAND Receive message from specified band. 11955 MSG_HIPRI Send/receive high-priority message. 11956 MORECTL More control information is left in message. 11957 MOREDATA More data is left in message. 11958 The header may make visible all of the symbols from . 11959 The following shall be declared as functions and may also be defined as macros. Function | 11960 prototypes shall be provided. | 11961 int isastream(int); 11962 int getmsg(int, struct strbuf *restrict, struct strbuf *restrict, 11963 int *restrict); 11964 int getpmsg(int, struct strbuf *restrict, struct strbuf *restrict, 11965 int *restrict, int *restrict); 11966 int ioctl(int, int, ... ); 11967 int putmsg(int, const struct strbuf *, const struct strbuf *, int); 11968 int putpmsg(int, const struct strbuf *, const struct strbuf *, int, 11969 int); 11970 int fattach(int, const char *); 11971 int fdetach(const char *); 11972 APPLICATION USAGE 11973 None. 11974 RATIONALE 11975 None. 11976 FUTURE DIRECTIONS 11977 None. 11978 SEE ALSO 11979 , the System Interfaces volume of IEEE Std 1003.1-200x, close( ), fcntl( ), getmsg( ), 11980 ioctl( ), open( ), pipe( ), read( ), poll( ), putmsg( ), signal( ), write( ) | 11981 CHANGE HISTORY 11982 First released in Issue 4, Version 2. 334 Technical Standard (2001) (Draft April 13, 2001) Headers 11983 Issue 5 11984 The flags member of the strpeek and strfdinsert structures are changed from type long to 11985 t_uscalar_t. 11986 Issue 6 11987 This header is marked as part of the XSI STREAMS Option Group. 11988 The restrict keyword is added to the prototypes for getmsg( ) and getpmsg( ). Base Definitions, Issue 6 335 Headers 11989 NAME 11990 sys/ipc.h - XSI interprocess communication access structure 11991 SYNOPSIS 11992 XSI #include 11993 11994 DESCRIPTION 11995 The header is used by three mechanisms for XSI interprocess communication (IPC): 11996 messages, semaphores, and shared memory. All use a common structure type, ipc_perm to pass 11997 information used in determining permission to perform an IPC operation. 11998 The ipc_perm structure shall contain the following members: 11999 uid_t uid Owner's user ID. 12000 gid_t gid Owner's group ID. 12001 uid_t cuid Creator's user ID. 12002 gid_t cgid Creator's group ID. 12003 mode_t mode Read/write permission. 12004 The uid_t, gid_t, mode_t, and key_t types shall be defined as described in . 12005 Definitions shall be provided for the following constants: 12006 Mode bits: 12007 IPC_CREAT Create entry if key does not exist. 12008 IPC_EXCL Fail if key exists. 12009 IPC_NOWAIT Error if request must wait. 12010 Keys: 12011 IPC_PRIVATE Private key. 12012 Control commands: 12013 IPC_RMID Remove identifier. 12014 IPC_SET Set options. 12015 IPC_STAT Get options. 12016 The following shall be declared as a function and may also be defined as a macro. A function | 12017 prototype shall be provided. | 12018 key_t ftok(const char *, int); 12019 APPLICATION USAGE 12020 None. 12021 RATIONALE 12022 None. 12023 FUTURE DIRECTIONS 12024 None. 12025 SEE ALSO 12026 , the System Interfaces volume of IEEE Std 1003.1-200x, ftok( ) 336 Technical Standard (2001) (Draft April 13, 2001) Headers 12027 CHANGE HISTORY 12028 First released in Issue 2. Derived from System V Release 2.0. Base Definitions, Issue 6 337 Headers 12029 NAME 12030 sys/mman.h - memory management declarations 12031 SYNOPSIS 12032 #include 12033 DESCRIPTION 12034 The header shall be supported if the implementation supports at least one of the 12035 following options: 12036 MF * The Memory Mapped Files option 12037 SHM * The Shared Memory Objects option 12038 ML * The Process Memory Locking option 12039 MPR * The Memory Protection option 12040 TYM * The Typed Memory Objects option 12041 SIO * The Synchronized Input and Output option 12042 ADV * The Advisory Information option 12043 TYM * The Typed Memory Objects option 12044 MC2 If one or more of the Advisory Information, Memory Mapped Files, or Shared Memory Objects 12045 options are supported, the following protection options shall be defined: 12046 MC2 PROT_READ Page can be read. 12047 MC2 PROT_WRITE Page can be written. 12048 MC2 PROT_EXEC Page can be executed. 12049 MC2 PROT_NONE Page cannot be accessed. 12050 The following flag options shall be defined: 12051 MF|SHM MAP_SHARED Share changes. 12052 MF|SHM MAP_PRIVATE Changes are private. 12053 MF|SHM MAP_FIXED Interpret addr exactly. 12054 The following flags shall be defined for msync( ): 12055 MF|SIO MS_ASYNC Perform asynchronous writes. 12056 MF|SIO MS_SYNC Perform synchronous writes. 12057 MF|SIO MS_INVALIDATE Invalidate mappings. 12058 ML The following symbolic constants shall be defined for the mlockall( ) function: 12059 ML MCL_CURRENT Lock currently mapped pages. 12060 ML MCL_FUTURE Lock pages that become mapped. 12061 MF|SHM The symbolic constant MAP_FAILED shall be defined to indicate a failure from the mmap( ) 12062 function. 12063 MC1 If the Advisory Information and either the Memory Mapped Files or Shared Memory Objects 12064 options are supported, values for advice used by posix_madvise( ) shall be defined as follows: 12065 POSIX_MADV_NORMAL 12066 The application has no advice to give on its behavior with respect to the specified range. It 338 Technical Standard (2001) (Draft April 13, 2001) Headers 12067 is the default characteristic if no advice is given for a range of memory. 12068 POSIX_MADV_SEQUENTIAL 12069 The application expects to access the specified range sequentially from lower addresses to 12070 higher addresses. 12071 POSIX_MADV_RANDOM 12072 The application expects to access the specified range in a random order. 12073 POSIX_MADV_WILLNEED 12074 The application expects to access the specified range in the near future. 12075 POSIX_MADV_DONTNEED 12076 The application expects that it will not access the specified range in the near future. 12077 12078 TYM The following flags shall be defined for posix_typed_mem_open( ): 12079 POSIX_TYPED_MEM_ALLOCATE 12080 Allocate on mmap( ). 12081 POSIX_TYPED_MEM_ALLOCATE_CONTIG 12082 Allocate contiguously on mmap( ). 12083 POSIX_TYPED_MEM_MAP_ALLOCATABLE Map on mmap( ), without affecting allocatability. 12084 12085 The mode_t, off_t, and size_t types shall be defined as described in . 12086 TYM The header shall define the structure posix_typed_mem_info, which includes at 12087 least the following member: 12088 size_t posix_tmi_length Maximum length which may be allocated 12089 from a typed memory object. 12090 12091 The following shall be declared as functions and may also be defined as macros. Function | 12092 prototypes shall be provided. | 12093 ML int mlock(const void *, size_t); 12094 int mlockall(int); 12095 MF|SHM void *mmap(void *, size_t, int, int, int, off_t); 12096 MPR int mprotect(void *, size_t, int); 12097 MF|SIO int msync(void *, size_t, int); 12098 ML int munlock(const void *, size_t); 12099 int munlockall(void); 12100 MF|SHM int munmap(void *, size_t); 12101 ADV int posix_madvise(void *, size_t, int); 12102 TYM int posix_mem_offset(const void *restrict, size_t, off_t *restrict, 12103 size_t *restrict, int *restrict); 12104 int posix_typed_mem_get_info(int, struct posix_typed_mem_info *); 12105 int posix_typed_mem_open(const char *, int, int); 12106 SHM int shm_open(const char *, int, mode_t); 12107 int shm_unlink(const char *); 12108 Base Definitions, Issue 6 339 Headers 12109 APPLICATION USAGE 12110 None. 12111 RATIONALE 12112 None. 12113 FUTURE DIRECTIONS 12114 None. 12115 SEE ALSO 12116 , the System Interfaces volume of IEEE Std 1003.1-200x, mlock( ), mlockall( ), 12117 mmap( ), mprotect( ), msync( ), munlock( ), munlockall( ), munmap( ), posix_mem_offset( ), 12118 posix_typed_mem_get_info( ), posix_typed_mem_open( ), shm_open( ), shm_unlink( ) 12119 CHANGE HISTORY 12120 First released in Issue 4, Version 2. 12121 Issue 5 12122 Updated for alignment with the POSIX Realtime Extension. 12123 Issue 6 12124 The header is marked as dependent on support for either the 12125 _POSIX_MAPPED_FILES, _POSIX_MEMLOCK, or _POSIX_SHARED_MEMORY options. 12126 The following changes are made for alignment with IEEE Std 1003.1j-2000: 12127 * The TYM margin code is added to the list of margin codes for the header line, 12128 as well as for other lines. 12129 * The POSIX_TYPED_MEM_ALLOCATE, POSIX_TYPED_MEM_ALLOCATE_CONTIG, and 12130 POSIX_TYPED_MEM_MAP_ALLOCATABLE flags are added. 12131 * The posix_tmi_length structure is added. 12132 * The posix_mem_offset( ), posix_typed_mem_get_info( ), and posix_typed_mem_open( ) functions 12133 are added. 12134 The restrict keyword is added to the prototype for posix_mem_offset( ). 12135 IEEE PASC Interpretation 1003.1 #102 is applied adding the prototype for posix_madvise( ). 340 Technical Standard (2001) (Draft April 13, 2001) Headers 12136 NAME 12137 sys/msg.h - XSI message queue structures 12138 SYNOPSIS 12139 XSI #include 12140 12141 DESCRIPTION 12142 The header shall define the following constant and members of the structure 12143 msqid_ds. 12144 The following data types shall be defined through typedef: 12145 msgqnum_t Used for the number of messages in the message queue. 12146 msglen_t Used for the number of bytes allowed in a message queue. 12147 These types shall be unsigned integer types that are able to store values at least as large as a type 12148 unsigned short. 12149 Message operation flag: 12150 MSG_NOERROR No error if big message. 12151 The msqid_ds structure shall contain the following members: 12152 struct ipc_perm msg_perm Operation permission structure. 12153 msgqnum_t msg_qnum Number of messages currently on queue. 12154 msglen_t msg_qbytes Maximum number of bytes allowed on queue. 12155 pid_t msg_lspid Process ID of last msgsnd( ). 12156 pid_t msg_lrpid Process ID of last msgrcv( ). 12157 time_t msg_stime Time of last msgsnd( ). 12158 time_t msg_rtime Time of last msgrcv( ). 12159 time_t msg_ctime Time of last change. 12160 The pid_t, time_t, key_t, size_t, and ssize_t types shall be defined as described in . 12161 The following shall be declared as functions and may also be defined as macros. Function | 12162 prototypes shall be provided. | 12163 int msgctl(int, int, struct msqid_ds *); 12164 int msgget(key_t, int); 12165 ssize_t msgrcv(int, void *, size_t, long, int); 12166 int msgsnd(int, const void *, size_t, int); 12167 In addition, all of the symbols from shall be defined when this header is included. 12168 APPLICATION USAGE 12169 None. 12170 RATIONALE 12171 None. 12172 FUTURE DIRECTIONS 12173 None. 12174 SEE ALSO 12175 , msgctl( ), msgget( ), msgrcv( ), msgsnd( ) Base Definitions, Issue 6 341 Headers 12176 CHANGE HISTORY 12177 First released in Issue 2. Derived from System V Release 2.0. 342 Technical Standard (2001) (Draft April 13, 2001) Headers 12178 NAME 12179 sys/resource.h - definitions for XSI resource operations 12180 SYNOPSIS 12181 XSI #include 12182 12183 DESCRIPTION 12184 The header shall define the following symbolic constants as possible values of 12185 the which argument of getpriority( ) and setpriority( ): 12186 PRIO_PROCESS Identifies the who argument as a process ID. 12187 PRIO_PGRP Identifies the who argument as a process group ID. 12188 PRIO_USER Identifies the who argument as a user ID. 12189 The following type shall be defined through typedef: 12190 rlim_t Unsigned integer type used for limit values. 12191 The following symbolic constants shall be defined: 12192 RLIM_INFINITY A value of rlim_t indicating no limit. 12193 RLIM_SAVED_MAX A value of type rlim_t indicating an unrepresentable saved hard 12194 limit. 12195 RLIM_SAVED_CUR A value of type rlim_t indicating an unrepresentable saved soft limit. 12196 On implementations where all resource limits are representable in an object of type rlim_t, 12197 RLIM_SAVED_MAX and RLIM_SAVED_CUR need not be distinct from RLIM_INFINITY. 12198 The following symbolic constants shall be defined as possible values of the who parameter of 12199 getrusage( ): 12200 RUSAGE_SELF Returns information about the current process. 12201 RUSAGE_CHILDREN Returns information about children of the current process. 12202 The header shall define the rlimit structure that includes at least the following 12203 members: 12204 rlim_t rlim_cur The current (soft) limit. | 12205 rlim_t rlim_max The hard limit. | 12206 The header shall define the rusage structure that includes at least the following | 12207 members: 12208 struct timeval ru_utime User time used. | 12209 struct timeval ru_stime System time used. | 12210 The timeval structure shall be defined as described in . | 12211 The following symbolic constants shall be defined as possible values for the resource argument of 12212 getrlimit( ) and setrlimit( ): 12213 RLIMIT_CORE Limit on size of core dump file. 12214 RLIMIT_CPU Limit on CPU time per process. 12215 RLIMIT_DATA Limit on data segment size. 12216 RLIMIT_FSIZE Limit on file size. Base Definitions, Issue 6 343 Headers 12217 RLIMIT_NOFILE Limit on number of open files. 12218 RLIMIT_STACK Limit on stack size. 12219 RLIMIT_AS Limit on address space size. 12220 The following shall be declared as functions and may also be defined as macros. Function | 12221 prototypes shall be provided. | 12222 int getpriority(int, id_t); 12223 int getrlimit(int, struct rlimit *); 12224 int getrusage(int, struct rusage *); 12225 int setpriority(int, id_t, int); 12226 int setrlimit(int, const struct rlimit *); 12227 The id_t type shall be defined through typedef as described in . 12228 Inclusion of the header may also make visible all symbols from . 12229 APPLICATION USAGE 12230 None. 12231 RATIONALE 12232 None. 12233 FUTURE DIRECTIONS 12234 None. 12235 SEE ALSO 12236 , , the System Interfaces volume of IEEE Std 1003.1-200x, getpriority( ), 12237 getrusage( ), getrlimit( ) 12238 CHANGE HISTORY 12239 First released in Issue 4, Version 2. 12240 Issue 5 12241 Large File System extensions are added. 344 Technical Standard (2001) (Draft April 13, 2001) Headers 12242 NAME 12243 sys/select.h - select types 12244 SYNOPSIS 12245 #include 12246 DESCRIPTION 12247 The header shall define the timeval structure that includes at least the following 12248 members: 12249 time_t tv_sec Seconds. 12250 suseconds_t tv_usec Microseconds. 12251 The time_t and suseconds_t types shall be defined as described in . 12252 The sigset_t type shall be defined as described in . 12253 The timespec structure shall be defined as described in . 12254 The header shall define the fd_set type as a structure. | 12255 Each of the following may be declared as a function, or defined as a macro, or both: 12256 void FD_CLR(int fd, fd_set *fdset) 12257 Clears the bit for the file descriptor fd in the file descriptor set fdset. 12258 int FD_ISSET(int fd, fd_set *fdset) 12259 Returns a non-zero value if the bit for the file descriptor fd is set in the file descriptor set by 12260 fdset, and 0 otherwise. 12261 void FD_SET(int fd, fd_set *fdset) 12262 Sets the bit for the file descriptor fd in the file descriptor set fdset. 12263 void FD_ZERO(fd_set *fdset) 12264 Initializes the file descriptor set fdset to have zero bits for all file descriptors. 12265 If implemented as macros, these may evaluate their arguments more than once, so applications 12266 should ensure that the arguments they supply are never expressions with side effects. 12267 The following shall be defined as a macro: 12268 FD_SETSIZE 12269 Maximum number of file descriptors in an fd_set structure. 12270 The following shall be declared as functions and may also be defined as macros. Function | 12271 prototypes shall be provided. | 12272 int pselect(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, 12273 const struct timespec *restrict, const sigset_t *restrict); 12274 int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, 12275 struct timeval *restrict); 12276 Inclusion of the header may make visible all symbols from the headers 12277 , , and . Base Definitions, Issue 6 345 Headers 12278 APPLICATION USAGE 12279 None. 12280 RATIONALE 12281 None. 12282 FUTURE DIRECTIONS 12283 None. 12284 SEE ALSO 12285 , , , , the System Interfaces volume of 12286 IEEE Std 1003.1-200x, pselect( ), select( ) 12287 CHANGE HISTORY 12288 First released in Issue 6. Derived from IEEE Std 1003.1g-2000. | 12289 The requirement for the fd_set structure to have a member fds_bits has been removed as per The | 12290 Open Group Base Resolution bwg2001-005. | 346 Technical Standard (2001) (Draft April 13, 2001) Headers 12291 NAME 12292 sys/sem.h - XSI semaphore facility 12293 SYNOPSIS 12294 XSI #include 12295 12296 DESCRIPTION 12297 The header shall define the following constants and structures. 12298 Semaphore operation flags: 12299 SEM_UNDO Set up adjust on exit entry. 12300 Command definitions for the semctl( ) function shall be provided as follows: 12301 GETNCNT Get semncnt. 12302 GETPID Get sempid. 12303 GETVAL Get semval. 12304 GETALL Get all cases of semval. 12305 GETZCNT Get semzcnt. 12306 SETVAL Set semval. 12307 SETALL Set all cases of semval. 12308 The semid_ds structure shall contain the following members: 12309 struct ipc_perm sem_perm Operation permission structure. 12310 unsigned short sem_nsems Number of semaphores in set. 12311 time_t sem_otime Last semop( ) time. 12312 time_t sem_ctime Last time changed by semctl( ). 12313 The pid_t, time_t, key_t, and size_t types shall be defined as described in . 12314 A semaphore shall be represented by an anonymous structure containing the following 12315 members: 12316 unsigned short semval Semaphore value. 12317 pid_t sempid Process ID of last operation. 12318 unsigned short semncnt Number of processes waiting for semval 12319 to become greater than current value. 12320 unsigned short semzcnt Number of processes waiting for semval 12321 to become 0. 12322 The sembuf structure shall contain the following members: 12323 unsigned short sem_num Semaphore number. 12324 short sem_op Semaphore operation. 12325 short sem_flg Operation flags. 12326 The following shall be declared as functions and may also be defined as macros. Function | 12327 prototypes shall be provided. | 12328 int semctl(int, int, int, ...); 12329 int semget(key_t, int, int); 12330 int semop(int, struct sembuf *, size_t); Base Definitions, Issue 6 347 Headers 12331 In addition, all of the symbols from shall be defined when this header is included. 12332 APPLICATION USAGE 12333 None. 12334 RATIONALE 12335 None. 12336 FUTURE DIRECTIONS 12337 None. 12338 SEE ALSO 12339 , semctl( ), semget( ), semop( ) 12340 CHANGE HISTORY 12341 First released in Issue 2. Derived from System V Release 2.0. 348 Technical Standard (2001) (Draft April 13, 2001) Headers 12342 NAME 12343 sys/shm.h - XSI shared memory facility 12344 SYNOPSIS 12345 XSI #include 12346 12347 DESCRIPTION 12348 The header shall define the following symbolic constants: 12349 SHM_RDONLY Attach read-only (else read-write). 12350 SHM_RND Round attach address to SHMLBA. 12351 The header shall define the following symbolic value: 12352 SHMLBA Segment low boundary address multiple. 12353 The following data types shall be defined through typedef: 12354 shmatt_t Unsigned integer used for the number of current attaches that must be able to 12355 store values at least as large as a type unsigned short. 12356 The shmid_ds structure shall contain the following members: 12357 struct ipc_perm shm_perm Operation permission structure. 12358 size_t shm_segsz Size of segment in bytes. 12359 pid_t shm_lpid Process ID of last shared memory operation. 12360 pid_t shm_cpid Process ID of creator. 12361 shmatt_t shm_nattch Number of current attaches. 12362 time_t shm_atime Time of last shmat( ). 12363 time_t shm_dtime Time of last shmdt( ). 12364 time_t shm_ctime Time of last change by shmctl( ). 12365 The pid_t, time_t, key_t, and size_t types shall be defined as described in . 12366 The following shall be declared as functions and may also be defined as macros. Function | 12367 prototypes shall be provided. | 12368 void *shmat(int, const void *, int); 12369 int shmctl(int, int, struct shmid_ds *); 12370 int shmdt(const void *); 12371 int shmget(key_t, size_t, int); 12372 In addition, all of the symbols from shall be defined when this header is included. 12373 APPLICATION USAGE 12374 None. 12375 RATIONALE 12376 None. 12377 FUTURE DIRECTIONS 12378 None. 12379 SEE ALSO 12380 , the System Interfaces volume of IEEE Std 1003.1-200x, shmat( ), shmctl( ), shmdt( ), 12381 shmget( ) Base Definitions, Issue 6 349 Headers 12382 CHANGE HISTORY 12383 First released in Issue 2. Derived from System V Release 2.0. 12384 Issue 5 12385 The type of shm_segsz is changed from int to size_t. 350 Technical Standard (2001) (Draft April 13, 2001) Headers 12386 NAME 12387 sys/socket.h - main sockets header 12388 SYNOPSIS 12389 #include 12390 DESCRIPTION 12391 The header shall define the type socklen_t, which is an integer type of width of | 12392 at least 32 bits; see APPLICATION USAGE. | 12393 The header shall define the unsigned integer type sa_family_t. 12394 The header shall define the sockaddr structure that includes at least the 12395 following members: 12396 sa_family_t sa_family Address family. 12397 char sa_data[] Socket address (variable-length data). 12398 The sockaddr structure is used to define a socket address which is used in the bind( ), connect( ), 12399 getpeername( ), getsockname( ), recvfrom( ), and sendto( ) functions. 12400 The header shall define the sockaddr_storage structure. This structure shall be: 12401 * Large enough to accommodate all supported protocol-specific address structures 12402 * Aligned at an appropriate boundary so that pointers to it can be cast as pointers to protocol- 12403 specific address structures and used to access the fields of those structures without 12404 alignment problems 12405 The sockaddr_storage structure shall contain at least the following members: 12406 sa_family_t ss_family 12407 When a sockaddr_storage structure is cast as a sockaddr structure, the ss_family field of the 12408 sockaddr_storage structure shall map onto the sa_family field of the sockaddr structure. When a 12409 sockaddr_storage structure is cast as a protocol-specific address structure, the ss_family field 12410 shall map onto a field of that structure that is of type sa_family_t and that identifies the 12411 protocol's address family. 12412 The header shall define the msghdr structure that includes at least the following 12413 members: 12414 void *msg_name Optional address. 12415 socklen_t msg_namelen Size of address. 12416 struct iovec *msg_iov Scatter/gather array. 12417 int msg_iovlen Members in msg_iov. 12418 void *msg_control Ancillary data; see below. 12419 socklen_t msg_controllen Ancillary data buffer len. 12420 int msg_flags Flags on received message. 12421 The msghdr structure is used to minimize the number of directly supplied parameters to the 12422 recvmsg( ) and sendmsg( ) functions. This structure is used as a value-result parameter in the | 12423 recvmsg( ) function and value only for the sendmsg( ) function. 12424 The iovec structure shall be defined as described in . | 12425 The header shall define the cmsghdr structure that includes at least the following 12426 members: 12427 socklen_t cmsg_len Data byte count, including the cmsghdr. 12428 int cmsg_level Originating protocol. Base Definitions, Issue 6 351 Headers 12429 int cmsg_type Protocol-specific type. 12430 The cmsghdr structure is used for storage of ancillary data object information. 12431 Ancillary data consists of a sequence of pairs, each consisting of a cmsghdr structure followed 12432 by a data array. The data array contains the ancillary data message, and the cmsghdr structure 12433 contains descriptive information that allows an application to correctly parse the data. 12434 The values for cmsg_level shall be legal values for the level argument to the getsockopt( ) and 12435 setsockopt( ) functions. The system documentation shall specify the cmsg_type definitions for the 12436 supported protocols. 12437 Ancillary data is also possible at the socket level. The header defines the 12438 following macro for use as the cmsg_type value when cmsg_level is SOL_SOCKET: 12439 SCM_RIGHTS Indicates that the data array contains the access rights to be sent or 12440 received. 12441 The header defines the following macros to gain access to the data arrays in the 12442 ancillary data associated with a message header: 12443 CMSG_DATA(cmsg) 12444 If the argument is a pointer to a cmsghdr structure, this macro shall return an unsigned 12445 character pointer to the data array associated with the cmsghdr structure. 12446 CMSG_NXTHDR(mhdr,cmsg) 12447 If the first argument is a pointer to a msghdr structure and the second argument is a pointer 12448 to a cmsghdr structure in the ancillary data pointed to by the msg_control field of that 12449 msghdr structure, this macro shall return a pointer to the next cmsghdr structure, or a null 12450 pointer if this structure is the last cmsghdr in the ancillary data. 12451 CMSG_FIRSTHDR(mhdr) 12452 If the argument is a pointer to a msghdr structure, this macro shall return a pointer to the 12453 first cmsghdr structure in the ancillary data associated with this msghdr structure, or a null 12454 pointer if there is no ancillary data associated with the msghdr structure. 12455 The header shall define the linger structure that includes at least the following 12456 members: 12457 int l_onoff Indicates whether linger option is enabled. 12458 int l_linger Linger time, in seconds. 12459 The header shall define the following macros, with distinct integer values: 12460 SOCK_DGRAM Datagram socket. | 12461 RS SOCK_RAW Raw Protocol Interface. | 12462 SOCK_SEQPACKET Sequenced-packet socket. | 12463 SOCK_STREAM Byte-stream socket. | 12464 The header shall define the following macro for use as the level argument of 12465 setsockopt( ) and getsockopt( ). 12466 SOL_SOCKET Options to be accessed at socket level, not protocol level. 12467 The header shall define the following macros, with distinct integer values, for 12468 use as the option_name argument in getsockopt( ) or setsockopt( ) calls: 12469 SO_ACCEPTCONN Socket is accepting connections. 352 Technical Standard (2001) (Draft April 13, 2001) Headers 12470 SO_BROADCAST Transmission of broadcast messages is supported. 12471 SO_DEBUG Debugging information is being recorded. 12472 SO_DONTROUTE Bypass normal routing. 12473 SO_ERROR Socket error status. 12474 SO_KEEPALIVE Connections are kept alive with periodic messages. 12475 SO_LINGER Socket lingers on close. 12476 SO_OOBINLINE Out-of-band data is transmitted in line. 12477 SO_RCVBUF Receive buffer size. 12478 SO_RCVLOWAT Receive ``low water mark''. 12479 SO_RCVTIMEO Receive timeout. 12480 SO_REUSEADDR Reuse of local addresses is supported. 12481 SO_SNDBUF Send buffer size. 12482 SO_SNDLOWAT Send ``low water mark''. 12483 SO_SNDTIMEO Send timeout. 12484 SO_TYPE Socket type. 12485 The header shall define the following macro as the maximum backlog queue 12486 length which may be specified by the backlog field of the listen( ) function: 12487 SOMAXCONN The maximum backlog queue length. 12488 The header shall define the following macros, with distinct integer values, for 12489 use as the valid values for the msg_flags field in the msghdr structure, or the flags parameter in 12490 recvfrom( ), recvmsg( ), sendmsg( ), or sendto( ) calls: 12491 MSG_CTRUNC Control data truncated. 12492 MSG_DONTROUTE Send without using routing tables. 12493 MSG_EOR Terminates a record (if supported by the protocol). 12494 MSG_OOB Out-of-band data. 12495 MSG_PEEK Leave received data in queue. 12496 MSG_TRUNC Normal data truncated. 12497 MSG_WAITALL Attempt to fill the read buffer. | 12498 The header shall define the following macros, with distinct integer values: 12499 AF_INET Internet domain sockets for use with IPv4 addresses. | 12500 IP6 AF_INET6 Internet domain sockets for use with IPv6 addresses. | 12501 AF_UNIX UNIX domain sockets. | 12502 AF_UNSPEC Unspecified . | 12503 The header shall define the following macros, with distinct integer values: 12504 SHUT_RD Disables further receive operations. | Base Definitions, Issue 6 353 Headers 12505 SHUT_RDWR Disables further send and receive operations. | 12506 SHUT_WR Disables further send operations. | 12507 The following shall be declared as functions and may also be defined as macros. Function | 12508 prototypes shall be provided. | 12509 int accept(int, struct sockaddr *restrict, socklen_t *restrict); 12510 int bind(int, const struct sockaddr *, socklen_t); 12511 int connect(int, const struct sockaddr *, socklen_t); 12512 int getpeername(int, struct sockaddr *restrict, socklen_t *restrict); 12513 int getsockname(int, struct sockaddr *restrict, socklen_t *restrict); 12514 int getsockopt(int, int, int, void *restrict, socklen_t *restrict); 12515 int listen(int, int); 12516 ssize_t recv(int, void *, size_t, int); 12517 ssize_t recvfrom(int, void *restrict, size_t, int, 12518 struct sockaddr *restrict, socklen_t *restrict); 12519 ssize_t recvmsg(int, struct msghdr *, int); 12520 ssize_t send(int, const void *, size_t, int); 12521 ssize_t sendmsg(int, const struct msghdr *, int); 12522 ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *, 12523 socklen_t); 12524 int setsockopt(int, int, int, const void *, socklen_t); 12525 int shutdown(int, int); 12526 int socket(int, int, int); 12527 int socketpair(int, int, int, int[2]); | 12528 Inclusion of may also make visible all symbols from . | 12529 APPLICATION USAGE 12530 To forestall portability problems, it is recommended that applications not use values larger than | 12531 231 -1 for the socklen_t type. | 12532 The sockaddr_storage structure solves the problem of declaring storage for automatic variables 12533 which is both large enough and aligned enough for storing the socket address data structure of 12534 any family. For example, code with a file descriptor and without the context of the address 12535 family can pass a pointer to a variable of this type, where a pointer to a socket address structure 12536 is expected in calls such as getpeername( ), and determine the address family by accessing the 12537 received content after the call. 12538 The example below illustrates a data structure which aligns on a 64-bit boundary. An | 12539 implementation-defined field _ss_align following _ss_pad1 is used to force a 64-bit alignment | 12540 which covers proper alignment good enough for needs of at least sockaddr_in6 (IPv6) and | 12541 sockaddr_in (IPv4) address data structures. The size of padding field _ss_pad1 depends on the | 12542 chosen alignment boundary. The size of padding field _ss_pad2 depends on the value of overall | 12543 size chosen for the total size of the structure. This size and alignment are represented in the | 12544 above example by implementation-defined (not required) constants _SS_MAXSIZE (chosen | 12545 value 128) and _SS_ALIGNMENT (with chosen value 8). Constants _SS_PAD1SIZE (derived | 12546 value 6) and _SS_PAD2SIZE (derived value 112) are also for illustration and not required. The | 12547 implementation-defined definitions and structure field names above start with an underscore to | 12548 denote implementation private name space. Portable code is not expected to access or reference | 12549 those fields or constants. | 12550 /* 12551 * Desired design of maximum size and alignment. 12552 */ 354 Technical Standard (2001) (Draft April 13, 2001) Headers 12553 #define _SS_MAXSIZE 128 12554 /* Implementation-defined maximum size. */ 12555 #define _SS_ALIGNSIZE (sizeof(int64_t)) 12556 /* Implementation-defined desired alignment. */ 12557 /* 12558 * Definitions used for sockaddr_storage structure paddings design. 12559 */ 12560 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t)) 12561 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+ 12562 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 12563 struct sockaddr_storage { 12564 sa_family_t ss_family; /* Address family. */ 12565 /* 12566 * Following fields are implementation-defined. */ 12567 */ 12568 char _ss_pad1[_SS_PAD1SIZE]; 12569 /* 6-byte pad; this is to make implementation-defined 12570 pad up to alignment field that follows explicit in 12571 the data structure. */ 12572 int64_t _ss_align; /* Field to force desired structure 12573 storage alignment. */ 12574 char _ss_pad2[_SS_PAD2SIZE]; 12575 /* 112-byte pad to achieve desired size, 12576 _SS_MAXSIZE value minus size of ss_family 12577 __ss_pad1, __ss_align fields is 112. */ 12578 }; 12579 RATIONALE | 12580 None. 12581 FUTURE DIRECTIONS 12582 None. 12583 SEE ALSO 12584 , the System Interfaces volume of IEEE Std 1003.1-200x, accept( ), bind( ), connect( ), 12585 getpeername( ), getsockname( ), getsockopt( ), listen( ), recv( ), recvfrom( ), recvmsg( ), send( ), 12586 sendmsg( ), sendto( ), setsockopt( ), shutdown( ), socket( ), socketpair( ) 12587 CHANGE HISTORY 12588 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 12589 The restrict keyword is added to the prototypes for accept( ), getpeername( ), getsockname( ), 12590 getsockopt( ), and recvfrom( ). Base Definitions, Issue 6 355 Headers 12591 NAME 12592 sys/stat.h - data returned by the stat( ) function 12593 SYNOPSIS 12594 #include 12595 DESCRIPTION 12596 The header shall define the structure of the data returned by the functions fstat( ), 12597 lstat( ), and stat( ). 12598 The stat structure shall contain at least the following members: 12599 dev_t st_dev ID of device containing file. 12600 ino_t st_ino File serial number. 12601 mode_t st_mode Mode of file (see below). 12602 nlink_t st_nlink Number of hard links to the file. 12603 uid_t st_uid User ID of file. 12604 gid_t st_gid Group ID of file. 12605 XSI dev_t st_rdev Device ID (if file is character or block special). 12606 off_t st_size For regular files, the file size in bytes. 12607 For symbolic links, the length in bytes of the 12608 pathname contained in the symbolic link. | 12609 SHM For a shared memory object, the length in bytes. | 12610 TYM For a typed memory object, the length in bytes. | 12611 For other file types, the use of this field is | 12612 unspecified 12613 time_t st_atime Time of last access. 12614 time_t st_mtime Time of last data modification. 12615 time_t st_ctime Time of last status change. 12616 XSI blksize_t st_blksize A file system-specific preferred I/O block size for 12617 this object. In some file system types, this may 12618 vary from file to file. 12619 blkcnt_t st_blocks Number of blocks allocated for this object. 12620 12621 File serial number and device ID taken together uniquely identify the file within the system. The 12622 blkcnt_t, blksize_t, dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types shall be 12623 defined as described in . Times shall be given in seconds since the Epoch. 12624 Unless otherwise specified, the structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, 12625 st_ctime, and st_mtime shall have meaningful values for all file types defined in 12626 IEEE Std 1003.1-200x. 12627 For symbolic links, the st_mode member shall contain meaningful information, which can be 12628 used with the file type macros described below, that take a mode argument. The st_size member | 12629 shall contain the length, in bytes, of the pathname contained in the symbolic link. File mode bits | 12630 and the contents of the remaining members of the stat structure are unspecified. The value 12631 returned in the st_size field shall be the length of the contents of the symbolic link, and shall not 12632 count a trailing null if one is present. 12633 The following symbolic names for the values of type mode_t shall also be defined. 12634 File type: 12635 XSI S_IFMT Type of file. 12636 S_IFBLK Block special. 356 Technical Standard (2001) (Draft April 13, 2001) Headers 12637 S_IFCHR Character special. 12638 S_IFIFO FIFO special. 12639 S_IFREG Regular. 12640 S_IFDIR Directory. 12641 S_IFLNK Symbolic link. 12642 S_IFSOCK Socket. 12643 File mode bits: 12644 S_IRWXU Read, write, execute/search by owner. 12645 S_IRUSR Read permission, owner. 12646 S_IWUSR Write permission, owner. 12647 S_IXUSR Execute/search permission, owner. 12648 S_IRWXG Read, write, execute/search by group. 12649 S_IRGRP Read permission, group. 12650 S_IWGRP Write permission, group. 12651 S_IXGRP Execute/search permission, group. 12652 S_IRWXO Read, write, execute/search by others. 12653 S_IROTH Read permission, others. 12654 S_IWOTH Write permission, others. 12655 S_IXOTH Execute/search permission, others. 12656 S_ISUID Set-user-ID on execution. 12657 S_ISGID Set-group-ID on execution. 12658 XSI S_ISVTX On directories, restricted deletion flag. 12659 The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, 12660 XSI S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, and S_ISVTXshall be unique. 12661 S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR. 12662 S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP. 12663 S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH. 12664 Implementations may OR other implementation-defined bits into S_IRWXU, S_IRWXG, and 12665 S_IRWXO, but they shall not overlap any of the other bits defined in this volume of 12666 IEEE Std 1003.1-200x. The file permission bits are defined to be those corresponding to the 12667 bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO. 12668 The following macros shall be provided to test whether a file is of the specified type. The value 12669 m supplied to the macros is the value of st_mode from a stat structure. The macro shall evaluate 12670 to a non-zero value if the test is true; 0 if the test is false. 12671 S_ISBLK(m) Test for a block special file. 12672 S_ISCHR(m) Test for a character special file. Base Definitions, Issue 6 357 Headers 12673 S_ISDIR(m) Test for a directory. 12674 S_ISFIFO(m) Test for a pipe or FIFO special file. 12675 S_ISREG(m) Test for a regular file. 12676 S_ISLNK(m) Test for a symbolic link. 12677 S_ISSOCK(m) Test for a socket. 12678 The implementation may implement message queues, semaphores, or shared memory objects as 12679 distinct file types. The following macros shall be provided to test whether a file is of the 12680 specified type. The value of the buf argument supplied to the macros is a pointer to a stat 12681 structure. The macro shall evaluate to a non-zero value if the specified object is implemented as 12682 a distinct file type and the specified file type is contained in the stat structure referenced by buf. 12683 Otherwise, the macro shall evaluate to zero. 12684 S_TYPEISMQ(buf) Test for a message queue. 12685 S_TYPEISSEM(buf) Test for a semaphore. 12686 S_TYPEISSHM(buf) Test for a shared memory object. 12687 TYM The implementation may implement typed memory objects as distinct file types, and the 12688 following macro shall test whether a file is of the specified type. The value of the buf argument 12689 supplied to the macros is a pointer to a stat structure. The macro shall evaluate to a non-zero 12690 value if the specified object is implemented as a distinct file type and the specified file type is 12691 contained in the stat structure referenced by buf. Otherwise, the macro shall evaluate to zero. 12692 S_TYPEISTMO(buf) Test macro for a typed memory object. 12693 12694 The following shall be declared as functions and may also be defined as macros. Function | 12695 prototypes shall be provided. | 12696 int chmod(const char *, mode_t); 12697 int fchmod(int, mode_t); 12698 int fstat(int, struct stat *); 12699 int lstat(const char *restrict, struct stat *restrict); 12700 int mkdir(const char *, mode_t); 12701 int mkfifo(const char *, mode_t); 12702 XSI int mknod(const char *, mode_t, dev_t); 12703 int stat(const char *restrict, struct stat *restrict); 12704 mode_t umask(mode_t); 12705 APPLICATION USAGE 12706 Use of the macros is recommended for determining the type of a file. 12707 RATIONALE 12708 A conforming C-language application must include for functions that have 12709 arguments or return values of type mode_t, so that symbolic values for that type can be used. 12710 An alternative would be to require that these constants are also defined by including 12711 . 12712 The S_ISUID and S_ISGID bits may be cleared on any write, not just on open( ), as some historical 12713 implementations do it. 12714 System calls that update the time entry fields in the stat structure must be documented by the 12715 implementors. POSIX-conforming systems should not update the time entry fields for functions 12716 listed in the System Interfaces volume of IEEE Std 1003.1-200x unless the standard requires that 358 Technical Standard (2001) (Draft April 13, 2001) Headers 12717 they do, except in the case of documented extensions to the standard. 12718 Note that st_dev must be unique within a Local Area Network (LAN) in a ``system'' made up of 12719 multiple computers' file systems connected by a LAN. 12720 Networked implementations of a POSIX-conforming system must guarantee that all files visible 12721 within the file tree (including parts of the tree that may be remotely mounted from other 12722 machines on the network) on each individual processor are uniquely identified by the 12723 combination of the st_ino and st_dev fields. 12724 FUTURE DIRECTIONS 12725 No new S_IFMT symbolic names for the file type values of mode_t will be defined by 12726 IEEE Std 1003.1-200x; if new file types are required, they will only be testable through S_ISxx( ) 12727 macros instead. 12728 SEE ALSO 12729 , the System Interfaces volume of IEEE Std 1003.1-200x, chmod( ), fchmod( ), fstat( ), 12730 lstat( ), mkdir( ), mkfifo( ), mknod( ), stat( ), umask( ) 12731 CHANGE HISTORY 12732 First released in Issue 1. Derived from Issue 1 of the SVID. 12733 Issue 5 12734 The DESCRIPTION is updated for alignment with POSIX Realtime Extension. 12735 The type of st_blksize is changed from long to blksize_t; the type of st_blocks is changed from 12736 long to blkcnt_t. 12737 Issue 6 12738 The S_TYPEISMQ( ), S_TYPEISSEM( ), and S_TYPEISSHM( ) macros are unconditionally 12739 mandated. 12740 The Open Group Corrigendum U035/4 is applied. In the DESCRIPTION, the types blksize_t 12741 and blkcnt_t have been described. 12742 The following new requirements on POSIX implementations derive from alignment with the 12743 Single UNIX Specification: 12744 * The dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types are mandated. 12745 S_IFSOCK and S_ISSOCK are added for sockets. 12746 The description of stat structure members is changed to reflect contents when file type is a 12747 symbolic link. 12748 The test macro S_TYPEISTMO is added for alignment with IEEE Std 1003.1j-2000. 12749 The restrict keyword is added to the prototypes for lstat( ) and stat( ). 12750 The lstat( ) function is now mandatory. Base Definitions, Issue 6 359 Headers 12751 NAME 12752 sys/statvfs.h - VFS File System information structure 12753 SYNOPSIS 12754 XSI #include 12755 12756 DESCRIPTION 12757 The header shall define the statvfs structure that includes at least the following 12758 members: 12759 unsigned long f_bsize File system block size. 12760 unsigned long f_frsize Fundamental file system block size. 12761 fsblkcnt_t f_blocks Total number of blocks on file system in units of f_frsize. 12762 fsblkcnt_t f_bfree Total number of free blocks. 12763 fsblkcnt_t f_bavail Number of free blocks available to 12764 non-privileged process. 12765 fsfilcnt_t f_files Total number of file serial numbers. 12766 fsfilcnt_t f_ffree Total number of free file serial numbers. 12767 fsfilcnt_t f_favail Number of file serial numbers available to 12768 non-privileged process. 12769 unsigned long f_fsid File system ID. 12770 unsigned long f_flag Bit mask of f_flag values. 12771 unsigned long f_namemax Maximum filename length. 12772 The fsblkcnt_t and fsfilcnt_t types shall be defined as described in . 12773 The following flags for the f_flag member shall be defined: 12774 ST_RDONLY Read-only file system. 12775 ST_NOSUID Does not support setuid/setgid semantics. 12776 The following shall be declared as functions and may also be defined as macros. Function | 12777 prototypes shall be provided. | 12778 int statvfs(const char *restrict, struct statvfs *restrict); 12779 int fstatvfs(int, struct statvfs *); 12780 APPLICATION USAGE 12781 None. 12782 RATIONALE 12783 None. 12784 FUTURE DIRECTIONS 12785 None. 12786 SEE ALSO 12787 , the System Interfaces volume of IEEE Std 1003.1-200x, fstatvfs( ), statvfs( ) 12788 CHANGE HISTORY 12789 First released in Issue 4, Version 2. 12790 Issue 5 12791 The type of f_blocks, f_bfree, and f_bavail is changed from unsigned long to fsblkcnt_t; the type 12792 of f_files, f_ffree, and f_favail is changed from unsigned long to fsfilcnt_t. 360 Technical Standard (2001) (Draft April 13, 2001) Headers 12793 Issue 6 12794 The Open Group Corrigendum U035/5 is applied. In the DESCRIPTION, the types fsblkcnt_t 12795 and fsfilcnt_t have been described. 12796 The restrict keyword is added to the prototype for statvfs( ). Base Definitions, Issue 6 361 Headers 12797 NAME 12798 sys/time.h - time types 12799 SYNOPSIS 12800 XSI #include 12801 12802 DESCRIPTION 12803 The header shall define the timeval structure that includes at least the following 12804 members: 12805 time_t tv_sec Seconds. 12806 suseconds_t tv_usec Microseconds. 12807 The header shall define the itimerval structure that includes at least the following 12808 members: 12809 struct timeval it_interval Timer interval. 12810 struct timeval it_value Current value. 12811 The time_t and suseconds_t types shall be defined as described in . 12812 The fd_set type shall be defined as described in . | 12813 The header shall define the following values for the which argument of getitimer( ) 12814 and setitimer( ): 12815 ITIMER_REAL Decrements in real time. 12816 ITIMER_VIRTUAL Decrements in process virtual time. 12817 ITIMER_PROF Decrements both in process virtual time and when the system is running 12818 on behalf of the process. 12819 The following shall be defined as described in : | 12820 FD_CLR( ) || 12821 FD_ISSET( ) || 12822 FD_SET( ) || 12823 FD_ZERO( ) || 12824 FD_SETSIZE( ) || 12825 The following shall be declared as functions and may also be defined as macros. Function | 12826 prototypes shall be provided. | 12827 int getitimer(int, struct itimerval *); 12828 int gettimeofday(struct timeval *restrict, void *restrict); | 12829 int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, | 12830 struct timeval *restrict); 12831 int setitimer(int, const struct itimerval *restrict, 12832 struct itimerval *restrict); 12833 int utimes(const char *, const struct timeval [2]); (LEGACY) 12834 Inclusion of the header may make visible all symbols from the 12835 header. 362 Technical Standard (2001) (Draft April 13, 2001) Headers 12836 APPLICATION USAGE 12837 None. 12838 RATIONALE 12839 None. 12840 FUTURE DIRECTIONS 12841 None. 12842 SEE ALSO 12843 , the System Interfaces volume of IEEE Std 1003.1-200x, getitimer( ), gettimeofday( ), 12844 select( ), setitimer( ) 12845 CHANGE HISTORY 12846 First released in Issue 4, Version 2. 12847 Issue 5 12848 The type of tv_usec is changed from long to suseconds_t. 12849 Issue 6 12850 The restrict keyword is added to the prototypes for gettimeofday( ), select( ), and setitimer( ). | 12851 The note is added that inclusion of this header may also make symbols visible from | 12852 . | 12853 The utimes( ) function is marked LEGACY. | Base Definitions, Issue 6 363 Headers 12854 NAME 12855 sys/timeb.h - additional definitions for date and time 12856 SYNOPSIS 12857 XSI #include 12858 12859 DESCRIPTION 12860 The header shall define the timeb structure that includes at least the following 12861 members: 12862 time_t time The seconds portion of the current time. 12863 unsigned short millitm The milliseconds portion of the current time. 12864 short timezone The local timezone in minutes west of Greenwich. 12865 short dstflag TRUE if Daylight Savings Time is in effect. 12866 The time_t type shall be defined as described in . 12867 The following shall be declared as a function and may also be defined as a macro. A function | 12868 prototype shall be provided. | 12869 int ftime(struct timeb *); (LEGACY) 12870 APPLICATION USAGE 12871 None. 12872 RATIONALE 12873 None. 12874 FUTURE DIRECTIONS 12875 None. 12876 SEE ALSO 12877 , 12878 CHANGE HISTORY 12879 First released in Issue 4, Version 2. 12880 Issue 6 12881 The ftime( ) function is marked LEGACY. 364 Technical Standard (2001) (Draft April 13, 2001) Headers 12882 NAME 12883 sys/times.h - file access and modification times structure 12884 SYNOPSIS 12885 #include 12886 DESCRIPTION 12887 The header shall define the structure tms, which is returned by times( ) and 12888 includes at least the following members: 12889 clock_t tms_utime User CPU time. 12890 clock_t tms_stime System CPU time. 12891 clock_t tms_cutime User CPU time of terminated child processes. 12892 clock_t tms_cstime System CPU time of terminated child processes. 12893 The clock_t type shall be defined as described in . 12894 The following shall be declared as a function and may also be defined as a macro. A function | 12895 prototype shall be provided. | 12896 clock_t times(struct tms *); 12897 APPLICATION USAGE 12898 None. 12899 RATIONALE 12900 None. 12901 FUTURE DIRECTIONS 12902 None. 12903 SEE ALSO 12904 , the System Interfaces volume of IEEE Std 1003.1-200x, times( ) 12905 CHANGE HISTORY 12906 First released in Issue 1. Derived from Issue 1 of the SVID. Base Definitions, Issue 6 365 Headers 12907 NAME 12908 sys/types.h - data types 12909 SYNOPSIS 12910 #include 12911 DESCRIPTION 12912 The header shall include definitions for at least the following types: 12913 blkcnt_t Used for file block counts. 12914 blksize_t Used for block sizes. 12915 XSI clock_t Used for system times in clock ticks or CLOCKS_PER_SEC; see 12916 . 12917 TMR clockid_t Used for clock ID type in the clock and timer functions. 12918 dev_t Used for device IDs. 12919 XSI fsblkcnt_t Used for file system block counts. 12920 XSI fsfilcnt_t Used for file system file counts. 12921 gid_t Used for group IDs. 12922 XSI id_t Used as a general identifier; can be used to contain at least a pid_t, 12923 uid_t, or gid_t. 12924 ino_t Used for file serial numbers. 12925 XSI key_t Used for XSI interprocess communication. 12926 mode_t Used for some file attributes. 12927 nlink_t Used for link counts. 12928 off_t Used for file sizes. 12929 pid_t Used for process IDs and process group IDs. 12930 THR pthread_attr_t Used to identify a thread attribute object. 12931 BAR pthread_barrier_t Used to identify a barrier. 12932 BAR pthread_barrierattr_t Used to define a barrier attributes object. 12933 THR pthread_cond_t Used for condition variables. 12934 THR pthread_condattr_t Used to identify a condition attribute object. 12935 THR pthread_key_t Used for thread-specific data keys. 12936 THR pthread_mutex_t Used for mutexes. 12937 THR pthread_mutexattr_t Used to identify a mutex attribute object. 12938 THR pthread_once_t Used for dynamic package initialization. 12939 THR pthread_rwlock_t Used for read-write locks. 12940 THR pthread_rwlockattr_t Used for read-write lock attributes. 12941 SPI pthread_spinlock_t Used to identify a spin lock. 12942 THR pthread_t Used to identify a thread. 366 Technical Standard (2001) (Draft April 13, 2001) Headers 12943 size_t Used for sizes of objects. 12944 ssize_t Used for a count of bytes or an error indication. 12945 XSI suseconds_t Used for time in microseconds 12946 time_t Used for time in seconds. 12947 TMR timer_t Used for timer ID returned by timer_create( ). 12948 uid_t Used for user IDs. 12949 XSI useconds_t Used for time in microseconds. 12950 All of the types shall be defined as arithmetic types of an appropriate length, with the following 12951 exceptions: 12952 XSI key_t 12953 THR pthread_attr_t 12954 BAR pthread_barrier_t 12955 pthread_barrierattr_t 12956 THR pthread_cond_t 12957 pthread_condattr_t 12958 pthread_key_t 12959 pthread_mutex_t 12960 pthread_mutexattr_t 12961 pthread_once_t 12962 pthread_rwlock_t 12963 pthread_rwlockattr_t 12964 SPI pthread_spinlock_t 12965 TRC trace_attr_t 12966 trace_event_id_t 12967 TRC TEF trace_event_set_t 12968 TRC trace_id_t 12969 12970 Additionally: 12971 * mode_t shall be an integer type. | 12972 * nlink_t, uid_t, gid_t, and id_t shall be integer types. | 12973 * blkcnt_t and off_t shall be signed integer types. | 12974 XSI * fsblkcnt_t, fsfilcnt_t, andino_t shall be defined as unsigned integer types. 12975 * size_t shall be an unsigned integer type. 12976 * blksize_t, pid_t, and ssize_t shall be signed integer types. | 12977 * time_t and clock_t shall be integer or real-floating types. | 12978 XSI The type ssize_t shall be capable of storing values at least in the range [-1, {SSIZE_MAX}]. The 12979 type useconds_t shall be an unsigned integer type capable of storing values at least in the range 12980 [0, 1 000 000]. The type suseconds_t shall be a signed integer type capable of storing values at 12981 least in the range [-1, 1 000 000]. 12982 The implementation shall support one or more programming environments in which the widths | 12983 of blksize_t, pid_t, size_t, ssize_t, suseconds_t, and useconds_t are no greater than the width of | 12984 type long. The names of these programming environments can be obtained using the confstr( ) | 12985 function or the getconf utility. | Base Definitions, Issue 6 367 Headers 12986 There are no defined comparison or assignment operators for the following types: | 12987 THR pthread_attr_t 12988 BAR pthread_barrier_t 12989 pthread_barrierattr_t 12990 THR pthread_cond_t 12991 pthread_condattr_t 12992 pthread_mutex_t 12993 pthread_mutexattr_t 12994 pthread_rwlock_t 12995 pthread_rwlockattr_t 12996 SPI pthread_spinlock_t 12997 TRC trace_attr_t 12998 12999 APPLICATION USAGE 13000 None. 13001 RATIONALE 13002 None. 13003 FUTURE DIRECTIONS 13004 None. 13005 SEE ALSO 13006 , the System Interfaces volume of IEEE Std 1003.1-200x, confstr( ), the Shell and Utilities | 13007 volume of IEEE Std 1003.1-200x, getconf | 13008 CHANGE HISTORY 13009 First released in Issue 1. Derived from Issue 1 of the SVID. 13010 Issue 5 13011 The clockid_t and timer_t types are defined for alignment with the POSIX Realtime Extension. 13012 The types blkcnt_t, blksize_t, fsblkcnt_t, fsfilcnt_t, and suseconds_t are added. 13013 Large File System extensions are added. 13014 Updated for alignment with the POSIX Threads Extension. 13015 Issue 6 13016 The pthread_barrier_t, pthread_barrierattr_t, and pthread_spinlock_t types are added for 13017 alignment with IEEE Std 1003.1j-2000. 13018 The margin code is changed from XSI to THR for the pthread_rwlock_t and 13019 pthread_rwlockattr_t types as Read-Write Locks have been absorbed into the POSIX Threads 13020 option. The threads types are now marked THR. 368 Technical Standard (2001) (Draft April 13, 2001) Headers 13021 NAME 13022 sys/uio.h - definitions for vector I/O operations 13023 SYNOPSIS 13024 XSI #include 13025 13026 DESCRIPTION 13027 The header shall define the iovec structure that includes at least the following 13028 members: 13029 void *iov_base Base address of a memory region for input or output. 13030 size_t iov_len The size of the memory pointed to by iov_base. 13031 The header uses the iovec structure for scatter/gather I/O. 13032 The ssize_t and size_t types shall be defined as described in . 13033 The following shall be declared as functions and may also be defined as macros. Function | 13034 prototypes shall be provided. | 13035 ssize_t readv(int, const struct iovec *, int); 13036 ssize_t writev(int, const struct iovec *, int); 13037 APPLICATION USAGE 13038 The implementation can put a limit on the number of scatter/gather elements which can be 13039 processed in one call. The symbol {IOV_MAX} defined in should always be used to 13040 learn about the limits instead of assuming a fixed value. 13041 RATIONALE 13042 Traditionally, the maximum number of scatter/gather elements the system can process in one 13043 call were described by the symbolic value {UIO_MAXIOV}. In IEEE Std 1003.1-200x this value 13044 was replaced by the constant {IOV_MAX} which can be found in . 13045 FUTURE DIRECTIONS 13046 None. 13047 SEE ALSO 13048 , , the System Interfaces volume of IEEE Std 1003.1-200x, read( ), write( ) 13049 CHANGE HISTORY 13050 First released in Issue 4, Version 2. 13051 Issue 6 13052 Text referring to scatter/gather I/O is added to the DESCRIPTION. Base Definitions, Issue 6 369 Headers 13053 NAME 13054 sys/un.h - definitions for UNIX domain sockets 13055 SYNOPSIS 13056 #include 13057 DESCRIPTION 13058 The header shall define the sockaddr_un structure that includes at least the 13059 following members: 13060 sa_family_t sun_family Address family. 13061 char sun_path[] Socket pathname. | 13062 The sockaddr_un structure is used to store addresses for UNIX domain sockets. Values of this | 13063 type shall be cast by applications to struct sockaddr for use with socket functions. 13064 The sa_family_t type shall be defined as described in . 13065 APPLICATION USAGE 13066 The size of sun_path has intentionally been left undefined. This is because different 13067 implementations use different sizes. For example, BSD4.3 uses a size of 108, and BSD4.4 uses a 13068 size of 104. Since most implementations originate from BSD versions, the size is typically in the 13069 range 92 to 108. 13070 Applications should not assume a particular length for sun_path or assume that it can hold 13071 _POSIX_PATH_MAX characters (255). 13072 RATIONALE 13073 None. 13074 FUTURE DIRECTIONS 13075 None. 13076 SEE ALSO 13077 , the System Interfaces volume of IEEE Std 1003.1-200x, bind( ), socket( ), 13078 socketpair( ) 13079 CHANGE HISTORY 13080 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 370 Technical Standard (2001) (Draft April 13, 2001) Headers 13081 NAME 13082 sys/utsname.h - system name structure 13083 SYNOPSIS 13084 #include 13085 DESCRIPTION 13086 The header shall define the structure utsname which shall include at least the 13087 following members: 13088 char sysname[] Name of this implementation of the operating system. 13089 char nodename[] Name of this node within an implementation-defined 13090 communications network. 13091 char release[] Current release level of this implementation. 13092 char version[] Current version level of this release. 13093 char machine[] Name of the hardware type on which the system is running. 13094 The character arrays are of unspecified size, but the data stored in them shall be terminated by a 13095 null byte. 13096 The following shall be declared as a function and may also be defined as a macro: 13097 int uname(struct utsname *); 13098 APPLICATION USAGE 13099 None. 13100 RATIONALE 13101 None. 13102 FUTURE DIRECTIONS 13103 None. 13104 SEE ALSO 13105 The System Interfaces volume of IEEE Std 1003.1-200x, uname( ) 13106 CHANGE HISTORY 13107 First released in Issue 1. Derived from Issue 1 of the SVID. Base Definitions, Issue 6 371 Headers 13108 NAME 13109 sys/wait.h - declarations for waiting 13110 SYNOPSIS 13111 #include 13112 DESCRIPTION 13113 The header shall define the following symbolic constants for use with waitpid( ): 13114 WNOHANG Do not hang if no status is available; return immediately. 13115 WUNTRACED Report status of stopped child process. 13116 The header shall define the following macros for analysis of process status values: 13117 WEXITSTATUS Return exit status. 13118 XSI WIFCONTINUED True if child has been continued 13119 WIFEXITED True if child exited normally. 13120 WIFSIGNALED True if child exited due to uncaught signal. 13121 WIFSTOPPED True if child is currently stopped. 13122 WSTOPSIG Return signal number that caused process to stop. 13123 WTERMSIG Return signal number that caused process to terminate. 13124 XSI The following symbolic constants shall be defined as possible values for the options argument to 13125 waitid( ): 13126 WEXITED Wait for processes that have exited. 13127 WSTOPPED Status is returned for any child that has stopped upon receipt of a signal. 13128 WCONTINUED Status is returned for any child that was stopped and has been continued. 13129 WNOHANG Return immediately if there are no children to wait for. 13130 WNOWAIT Keep the process whose status is returned in infop in a waitable state. 13131 The type idtype_t shall be defined as an enumeration type whose possible values shall include 13132 at least the following: 13133 P_ALL | 13134 P_PID | 13135 P_PGID | 13136 13137 The id_t and pid_t types shall be defined as described in . 13138 XSI The siginfo_t type shall be defined as described in . 13139 The rusage structure shall be defined as described in . 13140 Inclusion of the header may also make visible all symbols from and 13141 . 13142 The following shall be declared as functions and may also be defined as macros. Function | 13143 prototypes shall be provided. | 13144 pid_t wait(int *); 13145 XSI int waitid(idtype_t, id_t, siginfo_t *, int); 13146 pid_t waitpid(pid_t, int *, int); 372 Technical Standard (2001) (Draft April 13, 2001) Headers 13147 APPLICATION USAGE 13148 None. 13149 RATIONALE 13150 None. 13151 FUTURE DIRECTIONS 13152 None. 13153 SEE ALSO 13154 , , , , the System Interfaces volume of 13155 IEEE Std 1003.1-200x, wait( ), waitid( ) 13156 CHANGE HISTORY 13157 First released in Issue 3. 13158 Entry included for alignment with the POSIX.1-1988 standard. 13159 Issue 6 13160 The wait3( ) function is removed. Base Definitions, Issue 6 373 Headers 13161 NAME 13162 syslog - definitions for system error logging 13163 SYNOPSIS 13164 XSI #include 13165 13166 DESCRIPTION 13167 The header shall define the following symbolic constants, zero or more of which may 13168 be OR'ed together to form the logopt option of openlog( ): 13169 LOG_PID Log the process ID with each message. 13170 LOG_CONS Log to the system console on error. 13171 LOG_NDELAY Connect to syslog daemon immediately. 13172 LOG_ODELAY Delay open until syslog( ) is called. 13173 LOG_NOWAIT Do not wait for child processes. 13174 The following symbolic constants shall be defined as possible values of the facility argument to 13175 openlog( ): 13176 LOG_KERN Reserved for message generated by the system. 13177 LOG_USER Message generated by a process. 13178 LOG_MAIL Reserved for message generated by mail system. 13179 LOG_NEWS Reserved for message generated by news system. 13180 LOG_UUCP Reserved for message generated by UUCP system. 13181 LOG_DAEMON Reserved for message generated by system daemon. 13182 LOG_AUTH Reserved for message generated by authorization daemon. 13183 LOG_CRON Reserved for message generated by the clock daemon. 13184 LOG_LPR Reserved for message generated by printer system. 13185 LOG_LOCAL0 Reserved for local use. 13186 LOG_LOCAL1 Reserved for local use. 13187 LOG_LOCAL2 Reserved for local use. 13188 LOG_LOCAL3 Reserved for local use. 13189 LOG_LOCAL4 Reserved for local use. 13190 LOG_LOCAL5 Reserved for local use. 13191 LOG_LOCAL6 Reserved for local use. 13192 LOG_LOCAL7 Reserved for local use. 13193 The following shall be declared as macros for constructing the maskpri argument to setlogmask( ). 13194 The following macros expand to an expression of type int when the argument pri is an 13195 expression of type int: 13196 LOG_MASK(pri) A mask for priority pri. 13197 The following constants shall be defined as possible values for the priority argument of syslog( ): 374 Technical Standard (2001) (Draft April 13, 2001) Headers 13198 LOG_EMERG A panic condition was reported to all processes. 13199 LOG_ALERT A condition that should be corrected immediately. 13200 LOG_CRIT A critical condition. 13201 LOG_ERR An error message. 13202 LOG_WARNING A warning message. 13203 LOG_NOTICE A condition requiring special handling. 13204 LOG_INFO A general information message. 13205 LOG_DEBUG A message useful for debugging programs. 13206 The following shall be declared as functions and may also be defined as macros. Function | 13207 prototypes shall be provided. | 13208 void closelog(void); 13209 void openlog(const char *, int, int); 13210 int setlogmask(int); 13211 void syslog(int, const char *, ...); 13212 APPLICATION USAGE 13213 None. 13214 RATIONALE 13215 None. 13216 FUTURE DIRECTIONS 13217 None. 13218 SEE ALSO 13219 The System Interfaces volume of IEEE Std 1003.1-200x, closelog( ) 13220 CHANGE HISTORY 13221 First released in Issue 4, Version 2. 13222 Issue 5 13223 Moved to X/Open UNIX to BASE. Base Definitions, Issue 6 375 Headers 13224 NAME 13225 tar.h - extended tar definitions 13226 SYNOPSIS 13227 #include 13228 DESCRIPTION 13229 The header shall define header block definitions as follows. 13230 General definitions: 13231 ______________________________________________________________________________ 13232 Name Description Value ______________________________________________________________________________ 13233 TMAGIC "ustar" ustar plus null byte. 13234 TMAGLEN 6 Length of the above. 13235 TVERSION "00" 00 without a null byte. 13236 TVERSLEN 2 Length of the above. ______________________________________________________________________________ 13237 Typeflag field definitions: 13238 ______________________________________________________________________________ 13239 Name Description Value ______________________________________________________________________________ 13240 REGTYPE '0' Regular file. 13241 AREGTYPE '\0' Regular file. 13242 LNKTYPE '1' Link. 13243 SYMTYPE '2' Symbolic link. 13244 CHRTYPE '3' Character special. 13245 BLKTYPE '4' Block special. 13246 DIRTYPE '5' Directory. 13247 FIFOTYPE '6' FIFO special. 13248 CONTTYPE '7' Reserved. ______________________________________________________________________________ 13249 Mode field bit definitions (octal): 13250 ______________________________________________________________________________ 13251 Name Description Value ______________________________________________________________________________ 13252 TSUID 04000 Set UID on execution. 13253 TSGID 02000 Set GID on execution. 13254 XSI TSVTX 01000 On directories, restricted deletion flag. 13255 TUREAD 00400 Read by owner. 13256 TUWRITE 00200 Write by owner special. 13257 TUEXEC 00100 Execute/search by owner. 13258 TGREAD 00040 Read by group. 13259 TGWRITE 00020 Write by group. 13260 TGEXEC 00010 Execute/search by group. 13261 TOREAD 00004 Read by other. 13262 TOWRITE 00002 Write by other. 13263 TOEXEC 00001 Execute/search by other. ______________________________________________________________________________ 376 Technical Standard (2001) (Draft April 13, 2001) Headers 13264 APPLICATION USAGE 13265 None. 13266 RATIONALE 13267 None. 13268 FUTURE DIRECTIONS 13269 None. 13270 SEE ALSO 13271 The Shell and Utilities volume of IEEE Std 1003.1-200x, pax 13272 CHANGE HISTORY 13273 First released in Issue 3. Derived from the entry in the POSIX.1-1988 standard. 13274 Issue 6 13275 The SEE ALSO section now refers to pax since the Shell and Utilities volume of 13276 IEEE Std 1003.1-200x no longer contains the tar utility. Base Definitions, Issue 6 377 Headers 13277 NAME 13278 termios.h - define values for termios 13279 SYNOPSIS 13280 #include 13281 DESCRIPTION 13282 The header contains the definitions used by the terminal I/O interfaces (see 13283 Chapter 11 (on page 183) for the structures and names defined). 13284 The termios Structure 13285 The following data types shall be defined through typedef: 13286 cc_t Used for terminal special characters. 13287 speed_t Used for terminal baud rates. 13288 tcflag_t Used for terminal modes. 13289 The above types shall be all unsigned integer types. 13290 The implementation shall support one or more programming environments in which the widths | 13291 of cc_t, speed_t, and tcflag_t are no greater than the width of type long. The names of these | 13292 programming environments can be obtained using the confstr( ) function or the getconf utility. | 13293 The termios structure shall be defined, and shall include at least the following members: | 13294 tcflag_t c_iflag Input modes. 13295 tcflag_t c_oflag Output modes. 13296 tcflag_t c_cflag Control modes. 13297 tcflag_t c_lflag Local modes. 13298 cc_t c_cc[NCCS] Control characters. 13299 A definition shall be provided for: 13300 NCCS Size of the array c_cc for control characters. 13301 The following subscript names for the array c_cc shall be defined: 13302 __________________________________________________________ 13303 Subscript Usage 13304 _ Canonical Mode Non-Canonical Mode Description _________________________________________________________ 13305 VEOF EOF character. 13306 VEOL EOL character. 13307 VERASE ERASE character. 13308 VINTR VINTR INTR character. 13309 VKILL KILL character. 13310 VMIN MIN value. 13311 VQUIT VQUIT QUIT character. 13312 VSTART VSTART START character. 13313 VSTOP VSTOP STOP character. 13314 VSUSP VSUSP SUSP character. 13315 _ VTIME TIME value. _________________________________________________________ 13316 The subscript values shall be unique, except that the VMIN and VTIME subscripts may have the 13317 same values as the VEOF and VEOL subscripts, respectively. 13318 The following flags shall be provided. 378 Technical Standard (2001) (Draft April 13, 2001) Headers 13319 Input Modes 13320 The c_iflag field describes the basic terminal input control: 13321 BRKINT Signal interrupt on break. 13322 ICRNL Map CR to NL on input. 13323 IGNBRK Ignore break condition. 13324 IGNCR Ignore CR. 13325 IGNPAR Ignore characters with parity errors. 13326 INLCR Map NL to CR on input. 13327 INPCK Enable input parity check. 13328 ISTRIP Strip character. 13329 XSI IXANY Enable any character to restart output. 13330 IXOFF Enable start/stop input control. 13331 IXON Enable start/stop output control. 13332 PARMRK Mark parity errors. 13333 Output Modes 13334 The c_oflag field specifies the system treatment of output: 13335 OPOST Post-process output. 13336 XSI ONLCR Map NL to CR-NL on output. 13337 OCRNL Map CR to NL on output. 13338 ONOCR No CR output at column 0. 13339 ONLRET NL performs CR function. 13340 OFILL Use fill characters for delay. 13341 NLDLY Select newline delays: 13342 NL0 type 0. 13343 NL1 type 1. 13344 CRDLY Select carriage-return delays: 13345 CR0 Carriage-return delay type 0. 13346 CR1 Carriage-return delay type 1. 13347 CR2 Carriage-return delay type 2. 13348 CR3 Carriage-return delay type 3. 13349 TABDLY Select horizontal-tab delays: 13350 TAB0 Horizontal-tab delay type 0. 13351 TAB1 Horizontal-tab delay type 1. 13352 TAB2 Horizontal-tab delay type 2. Base Definitions, Issue 6 379 Headers 13353 TAB3 Expand tabs to spaces. 13354 BSDLY Select backspace delays: 13355 BS0 Backspace-delay type 0. 13356 BS1 Backspace-delay type 1. 13357 VTDLY Select vertical-tab delays: 13358 VT0 Vertical-tab delay type 0. 13359 VT1 Vertical-tab delay type 1. 13360 FFDLY Select form-feed delays: 13361 FF0 Form-feed delay type 0. 13362 FF1 Form-feed delay type 1. 13363 Baud Rate Selection 13364 The input and output baud rates are stored in the termios structure. These are the valid values 13365 for objects of type speed_t. The following values shall be defined, but not all baud rates need be 13366 supported by the underlying hardware. 13367 B0 Hang up 13368 B50 50 baud 13369 B75 75 baud 13370 B110 110 baud 13371 B134 134.5 baud 13372 B150 150 baud 13373 B200 200 baud 13374 B300 300 baud 13375 B600 600 baud 13376 B1200 1200 baud 13377 B1800 1800 baud 13378 B2400 2400 baud 13379 B4800 4800 baud 13380 B9600 9600 baud 13381 B19200 19200 baud 13382 B38400 38400 baud 380 Technical Standard (2001) (Draft April 13, 2001) Headers 13383 Control Modes 13384 The c_cflag field describes the hardware control of the terminal; not all values specified are 13385 required to be supported by the underlying hardware: 13386 CSIZE Character size: 13387 CS5 5 bits 13388 CS6 6 bits 13389 CS7 7 bits 13390 CS8 8 bits 13391 CSTOPB Send two stop bits, else one. 13392 CREAD Enable receiver. 13393 PARENB Parity enable. 13394 PARODD Odd parity, else even. 13395 HUPCL Hang up on last close. 13396 CLOCAL Ignore modem status lines. 13397 The implementation shall support the functionality associated with the symbols CS7, CS8, | 13398 CSTOPB, PARODD, and PARENB. | 13399 Local Modes 13400 The c_lflag field of the argument structure is used to control various terminal functions: 13401 ECHO Enable echo. 13402 ECHOE Echo erase character as error-correcting backspace. 13403 ECHOK Echo KILL. 13404 ECHONL Echo NL. 13405 ICANON Canonical input (erase and kill processing). 13406 IEXTEN Enable extended input character processing. 13407 ISIG Enable signals. 13408 NOFLSH Disable flush after interrupt or quit. 13409 TOSTOP Send SIGTTOU for background output. 13410 Attribute Selection 13411 The following symbolic constants for use with tcsetattr( ) are defined: 13412 TCSANOW Change attributes immediately. 13413 TCSADRAIN Change attributes when output has drained. 13414 TCSAFLUSH Change attributes when output has drained; also flush pending input. Base Definitions, Issue 6 381 Headers 13415 Line Control 13416 The following symbolic constants for use with tcflush( ) shall be defined: 13417 TCIFLUSH Flush pending input. Flush untransmitted output. 13418 TCIOFLUSH Flush both pending input and untransmitted output. 13419 TCOFLUSH Flush untransmitted output. 13420 The following symbolic constants for use with tcflow( ) shall be defined: 13421 TCIOFF Transmit a STOP character, intended to suspend input data. 13422 TCION Transmit a START character, intended to restart input data. 13423 TCOOFF Suspend output. 13424 TCOON Restart output. 13425 The following shall be declared as functions and may also be defined as macros. Function | 13426 prototypes shall be provided. | 13427 speed_t cfgetispeed(const struct termios *); 13428 speed_t cfgetospeed(const struct termios *); 13429 int cfsetispeed(struct termios *, speed_t); 13430 int cfsetospeed(struct termios *, speed_t); 13431 int tcdrain(int); 13432 int tcflow(int, int); 13433 int tcflush(int, int); 13434 int tcgetattr(int, struct termios *); 13435 XSI pid_t tcgetsid(int); 13436 int tcsendbreak(int, int); 13437 int tcsetattr(int, int, const struct termios *); | 13438 APPLICATION USAGE | 13439 The following names are reserved for XSI-conformant systems to use as an extension to the 13440 above; therefore strictly conforming applications shall not use them: 13441 CBAUD EXTB VDSUSP 13442 DEFECHO FLUSHO VLNEXT 13443 ECHOCTL LOBLK VREPRINT 13444 ECHOKE PENDIN VSTATUS 13445 ECHOPRT SWTCH VWERASE 13446 EXTA VDISCARD 13447 RATIONALE 13448 None. 13449 FUTURE DIRECTIONS 13450 None. 13451 SEE ALSO 13452 The System Interfaces volume of IEEE Std 1003.1-200x, cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), 13453 cfsetospeed( ), getconf( ), tcdrain( ), tcflow( ), tcflush( ), tcgetattr( ), tcgetsid( ), tcsendbreak( ), tcsetattr( ), | 13454 the Shell and Utilities volume of IEEE Std 1003.1-200x, getconf, Chapter 11 (on page 183) | 382 Technical Standard (2001) (Draft April 13, 2001) Headers 13455 CHANGE HISTORY 13456 First released in Issue 3. 13457 Entry included for alignment with the ISO POSIX-1 standard. 13458 Issue 6 13459 The LEGACY symbols IUCLC, ULCUC, and XCASE are removed. | 13460 FIPS 151-2 requirements for the symbols CS7, CS8, CSTOPB, PARODD, and PARENB are | 13461 reaffirmed. | Base Definitions, Issue 6 383 Headers 13462 NAME 13463 tgmath.h - type-generic macros 13464 SYNOPSIS 13465 #include 13466 DESCRIPTION 13467 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13468 conflict between the requirements described here and the ISO C standard is unintentional. This 13469 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13470 The header shall include the headers and and shall define 13471 several type-generic macros. 13472 Of the functions contained within the and headers without an f (float) or 13473 l (long double) suffix, several have one or more parameters whose corresponding real type is 13474 double. For each such function, except modf( ), there shall be a corresponding type-generic 13475 macro. The parameters whose corresponding real type is double in the function synopsis are 13476 generic parameters. Use of the macro invokes a function whose corresponding real type and 13477 type domain are determined by the arguments for the generic parameters. 13478 Use of the macro invokes a function whose generic parameters have the corresponding real type 13479 determined as follows: 13480 * First, if any argument for generic parameters has type long double, the type determined is 13481 long double. 13482 * Otherwise, if any argument for generic parameters has type double or is of integer type, the 13483 type determined is double. 13484 * Otherwise, the type determined is float. 13485 For each unsuffixed function in the header for which there is a function in the 13486 header with the same name except for a c prefix, the corresponding type-generic 13487 macro (for both functions) has the same name as the function in the header. The 13488 corresponding type-generic macro for fabs( ) and cabs( ) is fabs( ). _________________________________________ | 13489 Type-Generic | 13490 _ Function Function Macro ________________________________________ || 13491 acos( ) cacos( ) acos( ) | 13492 asin( ) casin( ) asin( ) | 13493 atan( ) catan( ) atan( ) | 13494 acosh( ) cacosh( ) acosh( ) | 13495 asinh( ) casinh( ) asinh( ) | 13496 atanh( ) catanh( ) atanh( ) | 13497 cos( ) ccos( ) cos( ) | 13498 sin( ) csin( ) sin( ) | 13499 tan( ) ctan( ) tan( ) | 13500 cosh( ) ccosh( ) cosh( ) | 13501 sinh( ) csinh( ) sinh( ) | 13502 tanh( ) ctanh( ) tanh( ) | 13503 exp( ) cexp( ) exp( ) | 13504 log( ) clog( ) log( ) | 13505 pow() cpow() pow() | 13506 sqrt( ) csqrt( ) sqrt( ) | 13507 _ fabs( ) cabs( ) fabs( ) ________________________________________ |||||| 384 Technical Standard (2001) (Draft April 13, 2001) Headers 13508 If at least one argument for a generic parameter is complex, then use of the macro invokes a 13509 complex function; otherwise, use of the macro invokes a real function. 13510 For each unsuffixed function in the header without a c-prefixed counterpart in the 13511 header, the corresponding type-generic macro has the same name as the function. 13512 These type-generic macros are: 13513 atan2( ) fma( ) llround( ) remainder( ) ||||||||| 13514 cbrt( ) fmax( ) log10( ) remquo( ) |||||||| 13515 ceil( ) fmin( ) log1p( ) rint( ) |||||||| 13516 copysign( ) fmod( ) log2( ) round( ) |||||||| 13517 erf( ) frexp( ) logb( ) scalbn( ) |||||||| 13518 erfc( ) hypot( ) lrint( ) scalbln( ) |||||||| 13519 exp2( ) ilogb( ) lround( ) tgamma( ) |||||||| 13520 expm1( ) ldexp( ) nearbyint( ) trunc( ) |||||||| 13521 fdim( ) lgamma( ) nextafter( ) |||||| 13522 floor( ) llrint( ) nexttoward( ) |||||| 13523 If all arguments for generic parameters are real, then use of the macro invokes a real function; 13524 otherwise, use of the macro results in undefined behavior. 13525 For each unsuffixed function in the header that is not a c-prefixed counterpart to a 13526 function in the header, the corresponding type-generic macro has the same name as 13527 the function. These type-generic macros are: 13528 carg( ) | 13529 cimag( ) | 13530 conj( ) | 13531 cproj( ) | 13532 creal( ) | 13533 Use of the macro with any real or complex argument invokes a complex function. 13534 APPLICATION USAGE 13535 With the declarations: 13536 #include 13537 int n; 13538 float f; 13539 double d; 13540 long double ld; 13541 float complex fc; 13542 double complex dc; 13543 long double complex ldc; 13544 functions invoked by use of type-generic macros are shown in the following table: | 13545 ___________________________________________ || 13546 _ Macro Use Invokes __________________________________________ |||||||||| 13547 exp(n) exp(n), the function | 13548 acosh(f) acoshf(f) 13549 sin(d) sin(d), the function 13550 _ atan(ld) atanl(ld) __________________________________________ Base Definitions, Issue 6 385 Headers 13551 ___________________________________________ | 13552 _ Macro Use Invokes __________________________________________ ||||| 13553 log(fc) clogf(fc) 13554 sqrt(dc) csqrt(dc) 13555 pow(ldc,f) cpowl(ldc, f) 13556 remainder(n,n) remainder(n, n), the function 13557 nextafter(d,f) nextafter(d, f), the function 13558 nexttoward(f,ld) nexttowardf(f, ld) 13559 copysign(n,ld) copysignl(n, ld) 13560 ceil(fc) Undefined behavior 13561 rint(dc) Undefined behavior 13562 fmax(ldc,ld) Undefined behavior 13563 carg(n) carg(n), the function 13564 cproj(f) cprojf(f) 13565 creal(d) creal(d), the function 13566 cimag(ld) cimagl(ld) 13567 cabs(fc) cabsf(fc) 13568 carg(dc) carg(dc), the function 13569 _ cproj(ldc) cprojl(ldc) __________________________________________ 13570 RATIONALE | 13571 Type-generic macros allow calling a function whose type is determined by the argument type, as 13572 is the case for C operators such as '+' and '*'. For example, with a type-generic cos( ) macro, 13573 the expression cos((float)x) will have type float. This feature enables writing more portably 13574 efficient code and alleviates need for awkward casting and suffixing in the process of porting or 13575 adjusting precision. Generic math functions are a widely appreciated feature of Fortran. 13576 The only arguments that affect the type resolution are the arguments corresponding to the 13577 parameters that have type double in the synopsis. Hence the type of a type-generic call to 13578 nexttoward( ), whose second parameter is long double in the synopsis, is determined solely by 13579 the type of the first argument. 13580 The term ``type-generic'' was chosen over the proposed alternatives of intrinsic and overloading. 13581 The term is more specific than intrinsic, which already is widely used with a more general 13582 meaning, and reflects a closer match to Fortran's generic functions than to C++ overloading. 13583 The macros are placed in their own header in order not to silently break old programs that 13584 include the header; for example, with: 13585 printf ("%e", sin(x)) 13586 modf(double, double *) is excluded because no way was seen to make it safe without 13587 complicating the type resolution. 13588 The implementation might, as an extension, endow appropriate ones of the macros that 13589 IEEE Std 1003.1-200x specifies only for real arguments with the ability to invoke the complex 13590 functions. 13591 IEEE Std 1003.1-200x does not prescribe any particular implementation mechanism for generic 13592 macros. It could be implemented simply with built-in macros. The generic macro for sqrt( ), for 13593 example, could be implemented with: 13594 #undef sqrt 13595 #define sqrt(x) __BUILTIN_GENERIC_sqrt(x) 13596 Generic macros are designed for a useful level of consistency with C++ overloaded math 13597 functions. 386 Technical Standard (2001) (Draft April 13, 2001) Headers 13598 The great majority of existing C programs are expected to be unaffected when the 13599 header is included instead of the or headers. Generic macros are similar 13600 to the ISO/IEC 9899: 1999 standard library masking macros, though the semantic types of return 13601 values differ. 13602 The ability to overload on integer as well as floating types would have been useful for some 13603 functions; for example, copysign( ). Overloading with different numbers of arguments would 13604 have allowed reusing names; for example, remainder( ) for remquo( ). However, these facilities 13605 would have complicated the specification; and their natural consistent use, such as for a floating 13606 abs( ) or a two-argument atan( ), would have introduced further inconsistencies with the 13607 ISO/IEC 9899: 1999 standard for insufficient benefit. 13608 The ISO C standard in no way limits the implementation's options for efficiency, including 13609 inlining library functions. 13610 FUTURE DIRECTIONS 13611 None. 13612 SEE ALSO 13613 , , the System Interfaces volume of IEEE Std 1003.1-200x, cabs( ), fabs( ), 13614 modf( ) 13615 CHANGE HISTORY 13616 First released in Issue 6. Included for alignment with the ISO/IEC 9899: 1999 standard. Base Definitions, Issue 6 387 Headers 13617 NAME 13618 time.h - time types 13619 SYNOPSIS 13620 #include 13621 DESCRIPTION 13622 CX Some of the functionality described on this reference page extends the ISO C standard. 13623 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 13624 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 13625 symbols in this header. 13626 The header shall declare the structure tm, which shall include at least the following 13627 members: 13628 int tm_sec Seconds [0,60]. 13629 int tm_min Minutes [0,59]. 13630 int tm_hour Hour [0,23]. 13631 int tm_mday Day of month [1,31]. 13632 int tm_mon Month of year [0,11]. 13633 int tm_year Years since 1900. 13634 int tm_wday Day of week [0,6] (Sunday =0). 13635 int tm_yday Day of year [0,365]. 13636 int tm_isdst Daylight savings flag. 13637 The value of tm_isdst shall be positive if Daylight Saving Time is in effect, 0 if Daylight Saving 13638 Time is not in effect, and negative if the information is not available. 13639 The header shall define the following symbolic names: 13640 NULL Null pointer constant. 13641 CLOCKS_PER_SEC A number used to convert the value returned by the clock( ) function into 13642 seconds. 13643 TMR|CPT CLOCK_PROCESS_CPUTIME_ID 13644 The identifier of the CPU-time clock associated with the process making a 13645 clock( ) or timer*( ) function call. 13646 TMR|TCT CLOCK_THREAD_CPUTIME_ID 13647 The identifier of the CPU-time clock associated with the thread making a 13648 clock( ) or timer*( ) function call. 13649 TMR The header shall declare the structure timespec, which has at least the following 13650 members: 13651 time_t tv_sec Seconds. 13652 long tv_nsec Nanoseconds. 13653 The header shall also declare the itimerspec structure, which has at least the following 13654 members: 13655 struct timespec it_interval Timer period. 13656 struct timespec it_value Timer expiration. 13657 The following manifest constants shall be defined: 13658 CLOCK_REALTIME The identifier of the system-wide realtime clock. 13659 TIMER_ABSTIME Flag indicating time is absolute with respect to the clock associated with a 13660 timer. 388 Technical Standard (2001) (Draft April 13, 2001) Headers 13661 MON CLOCK_MONOTONIC 13662 The identifier for the system-wide monotonic clock, which is defined as a 13663 clock whose value cannot be set via clock_settime( ) and which cannot 13664 have backward clock jumps. The maximum possible clock jump shall be 13665 implementation-defined. 13666 TMR The clock_t, size_t, time_t, clockid_t, and timer_t types shall be defined as described in 13667 . 13668 XSI Although the value of CLOCKS_PER_SEC is required to be 1 million on all XSI-conformant 13669 systems, it may be variable on other systems, and it should not be assumed that 13670 CLOCKS_PER_SEC is a compile-time constant. 13671 XSI The header shall provide a declaration for getdate_err. 13672 The following shall be declared as functions and may also be defined as macros. Function | 13673 prototypes shall be provided. | 13674 char *asctime(const struct tm *); 13675 TSF char *asctime_r(const struct tm *restrict, char *restrict); 13676 clock_t clock(void); 13677 CPT int clock_getcpuclockid(pid_t, clockid_t *); 13678 TMR int clock_getres(clockid_t, struct timespec *); 13679 int clock_gettime(clockid_t, struct timespec *); 13680 CS int clock_nanosleep(clockid_t, int, const struct timespec *, 13681 struct timespec *); 13682 TMR int clock_settime(clockid_t, const struct timespec *); 13683 char *ctime(const time_t *); 13684 TSF char *ctime_r(const time_t *, char *); 13685 double difftime(time_t, time_t); 13686 XSI struct tm *getdate(const char *); 13687 struct tm *gmtime(const time_t *); 13688 TSF struct tm *gmtime_r(const time_t *restrict, struct tm *restrict); | 13689 struct tm *localtime(const time_t *); 13690 TSF struct tm *localtime_r(const time_t *restrict, struct tm *restrict); 13691 time_t mktime(struct tm *); 13692 TMR int nanosleep(const struct timespec *, struct timespec *); 13693 size_t strftime(char *restrict, size_t, const char *restrict, 13694 const struct tm *restrict); 13695 XSI char *strptime(const char *restrict, const char *restrict, 13696 struct tm *restrict); 13697 time_t time(time_t *); 13698 TMR int timer_create(clockid_t, struct sigevent *restrict, 13699 timer_t *restrict); 13700 int timer_delete(timer_t); 13701 int timer_gettime(timer_t, struct itimerspec *); 13702 int timer_getoverrun(timer_t); 13703 int timer_settime(timer_t, int, const struct itimerspec *restrict, 13704 struct itimerspec *restrict); 13705 CX void tzset(void); 13706 13707 The following shall be declared as variables: 13708 XSI extern int daylight; 13709 extern long timezone; Base Definitions, Issue 6 389 Headers 13710 CX extern char *tzname[]; 13711 13712 CX Inclusion of the header may make visible all symbols from the header. 13713 APPLICATION USAGE 13714 The range [0,60] for tm_sec allows for the occasional leap second. 13715 tm_year is a signed value; therefore, years before 1900 may be represented. 13716 To obtain the number of clock ticks per second returned by the times( ) function, applications 13717 should call sysconf(_SC_CLK_TCK). 13718 RATIONALE 13719 The range [0,60] seconds allows for positive or negative leap seconds. The formal definition of 13720 UTC does not permit double leap seconds, so all mention of double leap seconds has been 13721 removed, and the range shortened from the former [0,61] seconds seen in previous versions of 13722 POSIX. 13723 FUTURE DIRECTIONS 13724 None. 13725 SEE ALSO 13726 , the System Interfaces volume of IEEE Std 1003.1-200x, asctime( ), clock( ), 13727 clock_getcpuclockid( ), clock_getres( ), clock_nanosleep( ), ctime( ), difftime( ), getdate( ), gmtime( ), 13728 localtime( ), mktime( ), nanosleep( ), strftime( ), strptime( ), sysconf( ), time( ), timer_create( ), 13729 timer_delete( ), timer_getoverrun( ), tzname, tzset( ), utime( ) 13730 CHANGE HISTORY 13731 First released in Issue 1. Derived from Issue 1 of the SVID. 13732 Issue 5 13733 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 13734 Threads Extension. 13735 Issue 6 13736 The Open Group Corrigendum U035/6 is applied. In the DESCRIPTION, the types clockid_t 13737 and timer_t have been described. 13738 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 13739 * The POSIX timer-related functions are now marked as part of the Timers option. 13740 The symbolic name CLK_TCK is removed. Application usage is added describing how its 13741 equivalent functionality can be obtained using sysconf( ). 13742 The clock_getcpuclockid( ) function and manifest constants CLOCK_PROCESS_CPUTIME_ID and 13743 CLOCK_THREAD_CPUTIME_ID are added for alignment with IEEE Std 1003.1d-1999. 13744 The manifest constant CLOCK_MONOTONIC and the clock_nanosleep( ) function are added for 13745 alignment with IEEE Std 1003.1j-2000. 13746 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 13747 * The range for seconds is changed from [0,61] to [0,60]. 13748 * The restrict keyword is added to the prototypes for asctime_r( ), gmtime_r( ), localtime_r ( ), 13749 strftime( ), strptime( ), timer_create( ), and timer_settime( ). 13750 IEEE PASC Interpretation 1003.1 #84 is applied adding the statement that symbols from the 13751 header may be made visible when the header is included. 390 Technical Standard (2001) (Draft April 13, 2001) Headers 13752 Extensions beyond the ISO C standard are now marked. Base Definitions, Issue 6 391 Headers 13753 NAME 13754 trace.h - tracing 13755 SYNOPSIS 13756 TRC #include | 13757 | 13758 DESCRIPTION 13759 The header shall define the posix_trace_event_info structure that includes at least the 13760 following members: 13761 trace_event_id_t posix_event_id 13762 pid_t posix_pid 13763 void *posix_prog_address 13764 int posix_truncation_status 13765 struct timespec posix_timestamp 13766 THR pthread_t posix_thread_id 13767 13768 The header shall define the posix_trace_status_info structure that includes at least the 13769 following members: 13770 int posix_stream_status 13771 int posix_stream_full_status 13772 int posix_stream_overrun_status 13773 TRL int posix_stream_flush_status 13774 int posix_stream_flush_error 13775 int posix_log_overrun_status 13776 int posix_log_full_status 13777 13778 The header shall define the following symbols: 13779 POSIX_TRACE_RUNNING 13780 POSIX_TRACE_SUSPENDED 13781 POSIX_TRACE_FULL 13782 POSIX_TRACE_NOT_FULL 13783 POSIX_TRACE_NO_OVERRUN 13784 POSIX_TRACE_OVERRUN 13785 TRL POSIX_TRACE_FLUSHING 13786 POSIX_TRACE_NOT_FLUSHING 13787 POSIX_TRACE_NOT_TRUNCATED 13788 POSIX_TRACE_TRUNCATED_READ 13789 POSIX_TRACE_TRUNCATED_RECORD 13790 TRL POSIX_TRACE_FLUSH 13791 POSIX_TRACE_LOOP 13792 POSIX_TRACE_UNTIL_FULL 13793 TRI POSIX_TRACE_CLOSE_FOR_CHILD 13794 POSIX_TRACE_INHERITED 13795 TRL POSIX_TRACE_APPEND 13796 POSIX_TRACE_LOOP 13797 POSIX_TRACE_UNTIL_FULL 13798 TEF POSIX_TRACE_FILTER 13799 TRL POSIX_TRACE_FLUSH_START 13800 POSIX_TRACE_FLUSH_STOP 13801 POSIX_TRACE_OVERFLOW 392 Technical Standard (2001) (Draft April 13, 2001) Headers 13802 POSIX_TRACE_RESUME 13803 POSIX_TRACE_START 13804 POSIX_TRACE_STOP 13805 POSIX_TRACE_UNNAMED_USER_EVENT 13806 The following types shall be defined as described in : 13807 trace_attr_t 13808 trace_id_t 13809 trace_event_id_t 13810 TEF trace_event_set_t 13811 13812 The following shall be declared as functions and may also be defined as macros. Function | 13813 prototypes shall be provided. | 13814 int posix_trace_attr_destroy(trace_attr_t *); 13815 int posix_trace_attr_getclockres(const trace_attr_t *, 13816 struct timespec *); 13817 int posix_trace_attr_getcreatetime(const trace_attr_t *, 13818 struct timespec *); 13819 int posix_trace_attr_getgenversion(const trace_attr_t *, char *); 13820 TRI int posix_trace_attr_getinherited(const trace_attr_t *restrict, 13821 int *restrict); 13822 TRL int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict, 13823 int *restrict); 13824 int posix_trace_attr_getlogsize(const trace_attr_t *restrict, 13825 size_t *restrict); 13826 int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict, 13827 size_t *restrict); 13828 int posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *restrict, 13829 size_t *restrict); 13830 int posix_trace_attr_getmaxusereventsize(const trace_attr_t *restrict, 13831 size_t, size_t *restrict); 13832 int posix_trace_attr_getname(const trace_attr_t *, char *); 13833 int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict, 13834 int *restrict); 13835 int posix_trace_attr_getstreamsize(const trace_attr_t *restrict, 13836 size_t *restrict); 13837 int posix_trace_attr_init(trace_attr_t *); 13838 TRI int posix_trace_attr_setinherited(trace_attr_t *, int); 13839 TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *, int); 13840 int posix_trace_attr_setlogsize(trace_attr_t *, size_t); 13841 int posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t); 13842 int posix_trace_attr_setname(trace_attr_t *, const char *); 13843 int posix_trace_attr_setstreamsize(trace_attr_t *, size_t); 13844 int posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int); 13845 int posix_trace_clear(trace_id_t); 13846 TRL int posix_trace_close(trace_id_t); 13847 int posix_trace_create(pid_t, const trace_attr_t *restrict, 13848 trace_id_t *restrict); 13849 TRL int posix_trace_create_withlog(pid_t, const trace_attr_t *restrict, 13850 int, trace_id_t *restrict); 13851 void posix_trace_event(trace_event_id_t, const void *restrict, size_t); Base Definitions, Issue 6 393 Headers 13852 int posix_trace_eventid_equal(trace_id_t, trace_event_id_t, | 13853 trace_event_id_t); | 13854 int posix_trace_eventid_get_name(trace_id_t, trace_event_id_t, char *); | 13855 int posix_trace_eventid_open(const char *restrict, | 13856 trace_event_id_t *restrict); 13857 int posix_trace_eventtypelist_getnext_id(trace_id_t, 13858 trace_event_id_t *restrict, int *restrict); | 13859 int posix_trace_eventtypelist_rewind(trace_id_t); | 13860 TEF int posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *); 13861 int posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *); 13862 int posix_trace_eventset_empty(trace_event_set_t *); 13863 int posix_trace_eventset_fill(trace_event_set_t *, int); 13864 int posix_trace_eventset_ismember(trace_event_id_t, 13865 const trace_event_set_t *restrict, int *restrict); 13866 int posix_trace_flush(trace_id_t); 13867 int posix_trace_get_attr(trace_id_t, trace_attr_t *); 13868 TEF int posix_trace_get_filter(trace_id_t, trace_event_set_t *); 13869 int posix_trace_get_status(trace_id_t, 13870 struct posix_trace_status_info *); 13871 int posix_trace_getnext_event(trace_id_t, 13872 struct posix_trace_event_info *restrict , void *restrict, 13873 size_t, size_t *restrict, int *restrict); 13874 TRL int posix_trace_open(int, trace_id_t *); 13875 int posix_trace_rewind(trace_id_t); 13876 TEF int posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int); 13877 int posix_trace_shutdown(trace_id_t); 13878 int posix_trace_start(trace_id_t); 13879 int posix_trace_stop(trace_id_t); 13880 TMO int posix_trace_timedgetnext_event(trace_id_t, 13881 struct posix_trace_event_info *restrict, void *restrict, 13882 size_t, size_t *restrict, int *restrict, 13883 const struct timespec *restrict); 13884 TEF int posix_trace_trid_eventid_open(trace_id_t, const char *restrict, 13885 trace_event_id_t *restrict); | 13886 int posix_trace_trygetnext_event(trace_id_t, | 13887 struct posix_trace_event_info *restrict, void *restrict, size_t, 13888 size_t *restrict, int *restrict); 13889 APPLICATION USAGE 13890 None. 13891 RATIONALE 13892 None. 13893 FUTURE DIRECTIONS 13894 None. 13895 SEE ALSO 13896 , the System Interfaces volume of IEEE Std 1003.1-200x, Section 2.11, Tracing, the 13897 System Interfaces volume of IEEE Std 1003.1-200x, posix_trace_attr_destroy( ), 13898 posix_trace_attr_getclockres( ), posix_trace_attr_getcreatetime( ), posix_trace_attr_getgenversion( ), 13899 posix_trace_attr_getinherited( ), posix_trace_attr_getlogfullpolicy( ), posix_trace_attr_getlogsize( ), 13900 posix_trace_attr_getmaxdatasize( ), posix_trace_attr_getmaxsystemeventsize( ), 13901 posix_trace_attr_getmaxusereventsize( ), posix_trace_attr_getname( ), 394 Technical Standard (2001) (Draft April 13, 2001) Headers 13902 posix_trace_attr_getstreamfullpolicy( ), posix_trace_attr_getstreamsize( ), posix_trace_attr_init( ), 13903 posix_trace_attr_setinherited( ), posix_trace_attr_setlogfullpolicy( ), posix_trace_attr_setlogsize( ), 13904 posix_trace_attr_setmaxdatasize( ), posix_trace_attr_setname( ), posix_trace_attr_setstreamsize( ), 13905 posix_trace_attr_setstreamfullpolicy( ), posix_trace_clear( ), posix_trace_close( ), posix_trace_create( ), 13906 posix_trace_create_withlog( ), posix_trace_event( ), posix_trace_eventid_equal( ), 13907 posix_trace_eventid_get_name( ), posix_trace_eventid_open( ), posix_trace_eventtypelist_getnext_id( ), 13908 posix_trace_eventtypelist_rewind( ), posix_trace_eventset_add( ), posix_trace_eventset_del( ), 13909 posix_trace_eventset_empty( ), posix_trace_eventset_fill( ), posix_trace_eventset_ismember( ), 13910 posix_trace_flush( ), posix_trace_get_attr( ), posix_trace_get_filter( ), posix_trace_get_status( ), 13911 posix_trace_getnext_event( ), posix_trace_open( ), posix_trace_rewind( ), posix_trace_set_filter( ), 13912 posix_trace_shutdown( ), posix_trace_start( ), posix_trace_stop( ), posix_trace_timedgetnext_event( ), 13913 posix_trace_trid_eventid_open( ), posix_trace_trygetnext_event( ) 13914 CHANGE ~ HISTORY 13915 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. Base Definitions, Issue 6 395 Headers 13916 NAME 13917 ucontext.h - user context 13918 SYNOPSIS 13919 XSI #include 13920 13921 DESCRIPTION 13922 The header shall define the mcontext_t type through typedef. 13923 The header shall define the ucontext_t type as a structure that shall include at least 13924 the following members: 13925 ucontext_t *uc_link Pointer to the context that is resumed 13926 when this context returns. 13927 sigset_t uc_sigmask The set of signals that are blocked when this 13928 context is active. 13929 stack_t uc_stack The stack used by this context. 13930 mcontext_t uc_mcontext A machine-specific representation of the saved 13931 context. 13932 The types sigset_t and stack_t shall be defined as in . 13933 The following shall be declared as functions and may also be defined as macros, Function | 13934 prototypes shall be provided. | 13935 int getcontext(ucontext_t *); 13936 int setcontext(const ucontext_t *); 13937 void makecontext(ucontext_t *, void (*)(void), int, ...); 13938 int swapcontext(ucontext_t *restrict, const ucontext_t *restrict); 13939 APPLICATION USAGE 13940 None. 13941 RATIONALE 13942 None. 13943 FUTURE DIRECTIONS 13944 None. 13945 SEE ALSO 13946 , the System Interfaces volume of IEEE Std 1003.1-200x, getcontext( ), makecontext( ), 13947 sigaction( ), sigprocmask( ), sigaltstack( ) 13948 CHANGE HISTORY 13949 First released in Issue 4, Version 2. 396 Technical Standard (2001) (Draft April 13, 2001) Headers 13950 NAME 13951 ulimit.h - ulimit commands 13952 SYNOPSIS 13953 XSI #include 13954 13955 DESCRIPTION 13956 The header shall define the symbolic constants used by the ulimit( ) function. 13957 Symbolic constants: 13958 UL_GETFSIZE Get maximum file size. 13959 UL_SETFSIZE Set maximum file size. 13960 The following shall be declared as a function and may also be defined as a macro. A function | 13961 prototype shall be provided. | 13962 long ulimit(int, ...); 13963 APPLICATION USAGE 13964 None. 13965 RATIONALE 13966 None. 13967 FUTURE DIRECTIONS 13968 None. 13969 SEE ALSO 13970 The System Interfaces volume of IEEE Std 1003.1-200x, ulimit( ) 13971 CHANGE HISTORY 13972 First released in Issue 3. Base Definitions, Issue 6 397 Headers 13973 NAME 13974 unistd.h - standard symbolic constants and types 13975 SYNOPSIS 13976 #include 13977 DESCRIPTION 13978 The header defines miscellaneous symbolic constants and types, and declares 13979 miscellaneous functions. The actual value of the constants are unspecified except as shown. The 13980 contents of this header are shown below. 13981 Version Test Macros 13982 The following symbolic constants shall be defined: 13983 _POSIX_VERSION 13984 Integer value indicating version of IEEE Std 1003.1 (C-language binding) to which the | 13985 implementation conforms. For implementations conforming to IEEE Std 1003.1-200x, the | 13986 value shall be 200xxxL. | 13987 _POSIX2_VERSION 13988 Integer value indicating version of the Shell and Utilities volume of IEEE Std 1003.1 to | 13989 which the implementation conforms. For implementations conforming to | 13990 IEEE Std 1003.1-200x, the value shall be 200xxxL. | 13991 The following symbolic constant shall be defined only if the implementation supports the XSI | 13992 option; see Section 2.1.4 (on page 19). | 13993 XSI _XOPEN_VERSION | 13994 Integer value indicating version of the X/Open Portability Guide to which the 13995 implementation conforms. The value shall be 600. 13996 Constants for Options and Option Groups | 13997 The following symbolic constants, if defined in , shall have a value of -1, 0, or greater, 13998 unless otherwise specified below. If these are undefined, the fpathconf( ), pathconf( ), or sysconf( ) | 13999 functions can be used to determine whether the option is provided for a particular invocation of | 14000 the application. 14001 If a symbolic constant is defined with the value -1, the option is not supported. Headers, data 14002 types, and function interfaces required only for the option need not be supplied. An application 14003 that attempts to use anything associated only with the option is considered to be requiring an 14004 extension. 14005 If a symbolic constant is defined with a value greater than zero, the option shall always be 14006 supported when the application is executed. All headers, data types, and functions shall be 14007 present and shall operate as specified. 14008 If a symbolic constant is defined with the value zero, all headers, data types, and functions shall | 14009 be present. The application can check at runtime to see whether the option is supported by | 14010 calling fpathconf( ), pathconf( ), or sysconf( ) with the indicated name parameter. | 14011 Unless explicitly specified otherwise, the behavior of functions associated with an unsupported 14012 option is unspecified, and an application that uses such functions without first checking | 14013 fpathconf( ), pathconf( ), or sysconf( ) is considered to be requiring an extension. | 14014 For conformance requirements, refer to Chapter 2 (on page 15). 398 Technical Standard (2001) (Draft April 13, 2001) Headers 14015 ADV _POSIX_ADVISORY_INFO 14016 The implementation supports the Advisory Information option. If this symbol has a value | 14017 other than -1 or 0, it shall have the value 200xxxL. | 14018 AIO _POSIX_ASYNCHRONOUS_IO 14019 The implementation supports the Asynchronous Input and Output option. If this symbol | 14020 has a value other than -1 or 0, it shall have the value 200xxxL. | 14021 BAR _POSIX_BARRIERS 14022 The implementation supports the Barriers option. If this symbol has a value other than -1 or | 14023 0, it shall have the value 200xxxL. | 14024 _POSIX_CHOWN_RESTRICTED 14025 The use of chown( ) and fchown( ) is restricted to a process with appropriate privileges, and 14026 to changing the group ID of a file only to the effective group ID of the process or to one of | 14027 its supplementary group IDs. This symbol shall always be set to a value other than -1. | 14028 CS _POSIX_CLOCK_SELECTION 14029 The implementation supports the Clock Selection option. If this symbol has a value other | 14030 than -1 or 0, it shall have the value 200xxxL. | 14031 CPT _POSIX_CPUTIME 14032 The implementation supports the Process CPU-Time Clocks option. If this symbol has a | 14033 value other than -1 or 0, it shall have the value 200xxxL. | 14034 FSC _POSIX_FSYNC 14035 The implementation supports the File Synchronization option. If this symbol has a value | 14036 other than -1 or 0, it shall have the value 200xxxL. | 14037 _POSIX_JOB_CONTROL 14038 The implementation supports job control. This symbol shall always be set to a value greater | 14039 than zero. | 14040 MF _POSIX_MAPPED_FILES 14041 The implementation supports the Memory Mapped Files option. If this symbol has a value | 14042 other than -1 or 0, it shall have the value 200xxxL. | 14043 ML _POSIX_MEMLOCK 14044 The implementation supports the Process Memory Locking option. If this symbol has a | 14045 value other than -1 or 0, it shall have the value 200xxxL. | 14046 MLR _POSIX_MEMLOCK_RANGE 14047 The implementation supports the Range Memory Locking option. If this symbol has a value | 14048 other than -1 or 0, it shall have the value 200xxxL. | 14049 MPR _POSIX_MEMORY_PROTECTION 14050 The implementation supports the Memory Protection option. If this symbol has a value | 14051 other than -1 or 0, it shall have the value 200xxxL. | 14052 MSG _POSIX_MESSAGE_PASSING 14053 The implementation supports the Message Passing option. If this symbol has a value other | 14054 than -1 or 0, it shall have the value 200xxxL. | 14055 MON _POSIX_MONOTONIC_CLOCK 14056 The implementation supports the Monotonic Clock option. If this symbol has a value other | 14057 than -1 or 0, it shall have the value 200xxxL. | 14058 _POSIX_NO_TRUNC 14059 Pathname components longer than {NAME_MAX} generate an error. This symbol shall | Base Definitions, Issue 6 399 Headers 14060 always be set to a value other than -1. | 14061 PIO _POSIX_PRIORITIZED_IO 14062 The implementation supports the Prioritized Input and Output option. If this symbol has a | 14063 value other than -1 or 0, it shall have the value 200xxxL. | 14064 PS _POSIX_PRIORITY_SCHEDULING 14065 The implementation supports the Process Scheduling option. If this symbol has a value | 14066 other than -1 or 0, it shall have the value 200xxxL. | 14067 RS _POSIX_RAW_SOCKETS | 14068 The implementation supports the Raw Sockets option. If this symbol has a value other than | 14069 -1 or 0, it shall have the value 200xxxL. | 14070 THR _POSIX_READER_WRITER_LOCKS 14071 The implementation supports the Read-Write Locks option. This is always set to a value 14072 greater than zero if the Threads option is supported. If this symbol has a value other than -1 | 14073 or 0, it shall have the value 200xxxL. | 14074 RTS _POSIX_REALTIME_SIGNALS 14075 The implementation supports the Realtime Signals Extension option. If this symbol has a | 14076 value other than -1 or 0, it shall have the value 200xxxL. | 14077 _POSIX_REGEXP 14078 The implementation supports the Regular Expression Handling option. This symbol shall | 14079 always be set to a value greater than zero. | 14080 _POSIX_SAVED_IDS 14081 Each process has a saved set-user-ID and a saved set-group-ID. This symbol shall always | 14082 be set to a value greater than zero. | 14083 SEM _POSIX_SEMAPHORES 14084 The implementation supports the Semaphores option. If this symbol has a value other than | 14085 -1 or 0, it shall have the value 200xxxL. | 14086 SHM _POSIX_SHARED_MEMORY_OBJECTS 14087 The implementation supports the Shared Memory Objects option. If this symbol has a value | 14088 other than -1 or 0, it shall have the value 200xxxL. | 14089 _POSIX_SHELL 14090 The implementation supports the POSIX shell. This symbol shall always be set to a value | 14091 greater than zero. | 14092 SPN _POSIX_SPAWN 14093 The implementation supports the Spawn option. If this symbol has a value other than -1 or | 14094 0, it shall have the value 200xxxL. | 14095 SPI _POSIX_SPIN_LOCKS 14096 The implementation supports the Spin Locks option. If this symbol has a value other than | 14097 -1 or 0, it shall have the value 200xxxL. | 14098 SS _POSIX_SPORADIC_SERVER 14099 The implementation supports the Process Sporadic Server option. If this symbol has a value | 14100 other than -1 or 0, it shall have the value 200xxxL. | 14101 SIO _POSIX_SYNCHRONIZED_IO 14102 The implementation supports the Synchronized Input and Output option. If this symbol | 14103 has a value other than -1 or 0, it shall have the value 200xxxL. | 400 Technical Standard (2001) (Draft April 13, 2001) Headers 14104 TSA _POSIX_THREAD_ATTR_STACKADDR 14105 The implementation supports the Thread Stack Address Attribute option. If this symbol | 14106 has a value other than -1 or 0, it shall have the value 200xxxL. | 14107 TSS _POSIX_THREAD_ATTR_STACKSIZE 14108 The implementation supports the Thread Stack Address Size option. If this symbol has a | 14109 value other than -1 or 0, it shall have the value 200xxxL. | 14110 TCT _POSIX_THREAD_CPUTIME 14111 The implementation supports the Thread CPU-Time Clocks option. If this symbol has a | 14112 value other than -1 or 0, it shall have the value 200xxxL. | 14113 TPI _POSIX_THREAD_PRIO_INHERIT 14114 The implementation supports the Thread Priority Inheritance option. If this symbol has a | 14115 value other than -1 or 0, it shall have the value 200xxxL. | 14116 TPP _POSIX_THREAD_PRIO_PROTECT 14117 The implementation supports the Thread Priority Protection option. If this symbol has a | 14118 value other than -1 or 0, it shall have the value 200xxxL. | 14119 TPS _POSIX_THREAD_PRIORITY_SCHEDULING 14120 The implementation supports the Thread Execution Scheduling option. If this symbol has a | 14121 value other than -1 or 0, it shall have the value 200xxxL. | 14122 TSH _POSIX_THREAD_PROCESS_SHARED 14123 The implementation supports the Thread Process-Shared Synchronization option. If this | 14124 symbol has a value other than -1 or 0, it shall have the value 200xxxL. | 14125 TSF _POSIX_THREAD_SAFE_FUNCTIONS 14126 The implementation supports the Thread-Safe Functions option. If this symbol has a value | 14127 other than -1 or 0, it shall have the value 200xxxL. | 14128 TSP _POSIX_THREAD_SPORADIC_SERVER 14129 The implementation supports the Thread Sporadic Server option. If this symbol has a value | 14130 other than -1 or 0, it shall have the value 200xxxL. | 14131 THR _POSIX_THREADS 14132 The implementation supports the Threads option. If this symbol has a value other than -1 | 14133 or 0, it shall have the value 200xxxL. | 14134 TMO _POSIX_TIMEOUTS 14135 The implementation supports the Timeouts option. If this symbol has a value other than -1 | 14136 or 0, it shall have the value 200xxxL. | 14137 TMR _POSIX_TIMERS | 14138 The implementation supports the Timers option. If this symbol has a value other than -1 or | 14139 0, it shall have the value 200xxxL. | 14140 TRC _POSIX_TRACE 14141 The implementation supports the Trace option. If this symbol has a value other than -1 or 0, | 14142 it shall have the value 200xxxL. | 14143 TEF _POSIX_TRACE_EVENT_FILTER 14144 The implementation supports the Trace Event Filter option. If this symbol has a value other | 14145 than -1 or 0, it shall have the value 200xxxL. | 14146 TRI _POSIX_TRACE_INHERIT 14147 The implementation supports the Trace Inherit option. If this symbol has a value other than | 14148 -1 or 0, it shall have the value 200xxxL. | Base Definitions, Issue 6 401 Headers 14149 TRL _POSIX_TRACE_LOG | 14150 The implementation supports the Trace Log option. If this symbol has a value other than -1 | 14151 or 0, it shall have the value 200xxxL. | 14152 TYM _POSIX_TYPED_MEMORY_OBJECTS 14153 The implementation supports the Typed Memory Objects option. If this symbol has a value | 14154 other than -1 or 0, it shall have the value 200xxxL. | 14155 _POSIX_VDISABLE 14156 This symbol shall be defined to be the value of a character that shall disable terminal special | 14157 character handling as described in . This symbol shall always be set to a value | 14158 other than -1. | 14159 _POSIX2_C_BIND 14160 The implementation supports the C-Language Binding option. This symbol shall always | 14161 have the value 200xxxL. | 14162 CD _POSIX2_C_DEV 14163 The implementation supports the C-Language Development Utilities option. If this symbol | 14164 has a value other than -1 or 0, it shall have the value 200xxxL. | 14165 _POSIX2_CHAR_TERM 14166 The implementation supports at least one terminal type. 14167 FD _POSIX2_FORT_DEV 14168 The implementation supports the FORTRAN Development Utilities option. If this symbol | 14169 has a value other than -1 or 0, it shall have the value 200xxxL. | 14170 FR _POSIX2_FORT_RUN 14171 The implementation supports the FORTRAN Runtime Utilities option. If this symbol has a | 14172 value other than -1 or 0, it shall have the value 200xxxL. | 14173 _POSIX2_LOCALEDEF 14174 The implementation supports the creation of locales by the localedef utility. If this symbol | 14175 has a value other than -1 or 0, it shall have the value 200xxxL. | 14176 BE _POSIX2_PBS 14177 The implementation supports the Batch Environment Services and Utilities option. If this | 14178 symbol has a value other than -1 or 0, it shall have the value 200xxxL. | 14179 BE _POSIX2_PBS_ACCOUNTING 14180 The implementation supports the Batch Accounting option. If this symbol has a value other | 14181 than -1 or 0, it shall have the value 200xxxL. | 14182 BE _POSIX2_PBS_CHECKPOINT 14183 The implementation supports the Batch Checkpoint/Restart option. If this symbol has a | 14184 value other than -1 or 0, it shall have the value 200xxxL. | 14185 BE _POSIX2_PBS_LOCATE 14186 The implementation supports the Locate Batch Job Request option. If this symbol has a | 14187 value other than -1 or 0, it shall have the value 200xxxL. | 14188 BE _POSIX2_PBS_MESSAGE 14189 The implementation supports the Batch Job Message Request option. If this symbol has a | 14190 value other than -1 or 0, it shall have the value 200xxxL. | 14191 BE _POSIX2_PBS_TRACK 14192 The implementation supports the Track Batch Job Request option. If this symbol has a value | 14193 other than -1 or 0, it shall have the value 200xxxL. | 402 Technical Standard (2001) (Draft April 13, 2001) Headers 14194 SD _POSIX2_SW_DEV 14195 The implementation supports the Software Development Utilities option. If this symbol has | 14196 a value other than -1 or 0, it shall have the value 200xxxL. | 14197 UP _POSIX2_UPE 14198 The implementation supports the User Portability Utilities option. If this symbol has a value | 14199 other than -1 or 0, it shall have the value 200xxxL. | 14200 _V6_ILP32_OFF32 14201 The implementation provides a C-language compilation environment with 32-bit int, long, 14202 pointer, and off_t types. 14203 _V6_ILP32_OFFBIG 14204 The implementation provides a C-language compilation environment with 32-bit int, long, 14205 and pointer types and an off_t type using at least 64 bits. 14206 _V6_LP64_OFF64 14207 The implementation provides a C-language compilation environment with 32-bit int and 14208 64-bit long, pointer, and off_t types. 14209 _V6_LPBIG_OFFBIG 14210 The implementation provides a C-language compilation environment with an int type 14211 using at least 32 bits and long, pointer, and off_t types using at least 64 bits. 14212 XSI _XBS5_ILP32_OFF32 (LEGACY) 14213 The implementation provides a C-language compilation environment with 32-bit int, long, 14214 pointer, and off_t types. 14215 XSI _XBS5_ILP32_OFFBIG (LEGACY) 14216 The implementation provides a C-language compilation environment with 32-bit int, long, 14217 and pointer types and an off_t type using at least 64 bits. 14218 XSI _XBS5_LP64_OFF64 (LEGACY) 14219 The implementation provides a C-language compilation environment with 32-bit int and 14220 64-bit long, pointer, and off_t types. 14221 XSI _XBS5_LPBIG_OFFBIG (LEGACY) 14222 The implementation provides a C-language compilation environment with an int type 14223 using at least 32 bits and long, pointer, and off_t types using at least 64 bits. 14224 XSI _XOPEN_CRYPT 14225 The implementation supports the X/Open Encryption Option Group. 14226 _XOPEN_ENH_I18N 14227 The implementation supports the Issue 4, Version 2 Enhanced Internationalization Option | 14228 Group. This symbol shall always be set to a value other than -1. | 14229 _XOPEN_LEGACY 14230 The implementation supports the Legacy Option Group. 14231 _XOPEN_REALTIME 14232 The implementation supports the X/Open Realtime Option Group. 14233 _XOPEN_REALTIME_THREADS 14234 The implementation supports the X/Open Realtime Threads Option Group. 14235 _XOPEN_SHM 14236 The implementation supports the Issue 4, Version 2 Shared Memory Option Group. This | 14237 symbol shall always be set to a value other than -1. | Base Definitions, Issue 6 403 Headers 14238 _XOPEN_STREAMS 14239 The implementation supports the XSI STREAMS Option Group. | 14240 XSI _XOPEN_UNIX | 14241 The implementation supports the XSI extension. | 14242 Execution-Time Symbolic Constants | 14243 If any of the following constants are not defined in the header, the value shall vary 14244 depending on the file to which it is applied. 14245 If any of the following constants are defined to have value -1 in the header, the 14246 implementation shall not provide the option on any file; if any are defined to have a value other 14247 than -1 in the header, the implementation shall provide the option on all applicable 14248 files. 14249 All of the following constants, whether defined in or not, may be queried with 14250 respect to a specific file using the pathconf( ) or fpathconf( ) functions: 14251 _POSIX_ASYNC_IO 14252 Asynchronous input or output operations may be performed for the associated file. 14253 _POSIX_PRIO_IO 14254 Prioritized input or output operations may be performed for the associated file. 14255 _POSIX_SYNC_IO 14256 Synchronized input or output operations may be performed for the associated file. 14257 Constants for Functions 14258 The following symbolic constant shall be defined: 14259 NULL Null pointer 14260 The following symbolic constants shall be defined for the access( ) function: 14261 F_OK Test for existence of file. 14262 R_OK Test for read permission. 14263 W_OK Test for write permission. 14264 X_OK Test for execute (search) permission. 14265 The constants F_OK, R_OK, W_OK, and X_OK and the expressions R_OK|W_OK, R_OK|X_OK, 14266 and R_OK|W_OK|X_OK shall all have distinct values. 14267 The following symbolic constants shall be defined for the confstr( ) function: 14268 _CS_POSIX_PATH | 14269 This is the value for the PATH environment variable that finds all standard utilities. | 14270 _CS_POSIX_V6_ILP32_OFF32_CFLAGS | 14271 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14272 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14273 build an application using a programming model with 32-bit int, long, pointer, and off_t 14274 types. | 14275 _CS_POSIX_V6_ILP32_OFF32_LDFLAGS | 14276 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14277 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14278 an application using a programming model with 32-bit int, long, pointer, and off_t types. | 404 Technical Standard (2001) (Draft April 13, 2001) Headers 14279 _CS_POSIX_V6_ILP32_OFF32_LIBS | 14280 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14281 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14282 application using a programming model with 32-bit int, long, pointer, and off_t types. | 14283 _CS_POSIX_V6_ILP32_OFF32_LINTFLAGS | 14284 If sysconf(_SC_V6_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14285 Otherwise, this value is the set of options to be given to the lint utility to check application 14286 source using a programming model with 32-bit int, long, pointer, and off_t types. | 14287 _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS | 14288 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14289 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14290 build an application using a programming model with 32-bit int, long, and pointer types, 14291 and an off_t type using at least 64 bits. | 14292 _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS | 14293 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14294 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14295 an application using a programming model with 32-bit int, long, and pointer types, and an 14296 off_t type using at least 64 bits. | 14297 _CS_POSIX_V6_ILP32_OFFBIG_LIBS | 14298 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14299 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14300 application using a programming model with 32-bit int, long, and pointer types, and an 14301 off_t type using at least 64 bits. | 14302 _CS_POSIX_V6_ILP32_OFFBIG_LINTFLAGS | 14303 If sysconf(_SC_V6_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14304 Otherwise, this value is the set of options to be given to the lint utility to check an 14305 application using a programming model with 32-bit int, long, and pointer types, and an 14306 off_t type using at least 64 bits. | 14307 _CS_POSIX_V6_LP64_OFF64_CFLAGS | 14308 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14309 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14310 build an application using a programming model with 64-bit int, long, pointer, and off_t 14311 types. | 14312 _CS_POSIX_V6_LP64_OFF64_LDFLAGS | 14313 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14314 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14315 an application using a programming model with 64-bit int, long, pointer, and off_t types. | 14316 _CS_POSIX_V6_LP64_OFF64_LIBS | 14317 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14318 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14319 application using a programming model with 64-bit int, long, pointer, and off_t types. | 14320 _CS_POSIX_V6_LP64_OFF64_LINTFLAGS | 14321 If sysconf(_SC_V6_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14322 Otherwise, this value is the set of options to be given to the lint utility to check application 14323 source using a programming model with 64-bit int, long, pointer, and off_t types. | 14324 _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS | 14325 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. Base Definitions, Issue 6 405 Headers 14326 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14327 build an application using a programming model with an int type using at least 32 bits and 14328 long, pointer, and off_t types using at least 64 bits. | 14329 _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS | 14330 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14331 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14332 an application using a programming model with an int type using at least 32 bits and long, 14333 pointer, and off_t types using at least 64 bits. | 14334 _CS_POSIX_V6_LPBIG_OFFBIG_LIBS | 14335 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14336 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14337 application using a programming model with an int type using at least 32 bits and long, 14338 pointer, and off_t types using at least 64 bits. | 14339 _CS_POSIX_V6_LPBIG_OFFBIG_LINTFLAGS | 14340 If sysconf(_SC_V6_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14341 Otherwise, this value is the set of options to be given to the lint utility to check application 14342 source using a programming model with an int type using at least 32 bits and long, pointer, 14343 and off_t types using at least 64 bits. | 14344 _CS_V6_WIDTH_RESTRICTED_ENVS | 14345 This value is a -separated list of names of programming environments supported | 14346 by the implementation in which the widths of the blksize_t, cc_t, mode_t, nfds_t, pid_t, | 14347 ptrdiff_t, size_t, speed_t, ssize_t, suseconds_t, tcflag_t, useconds_t, wchar_t, and wint_t | 14348 types are no greater than the width of type long. | 14349 XSI _CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY) 14350 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14351 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14352 build an application using a programming model with 32-bit int, long, pointer, and off_t 14353 types. 14354 XSI _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY) 14355 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14356 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14357 an application using a programming model with 32-bit int, long, pointer, and off_t types. 14358 XSI _CS_XBS5_ILP32_OFF32_LIBS (LEGACY) 14359 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14360 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14361 application using a programming model with 32-bit int, long, pointer, and off_t types. 14362 XSI _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY) 14363 If sysconf(_SC_XBS5_ILP32_OFF32) returns -1, the meaning of this value is unspecified. 14364 Otherwise, this value is the set of options to be given to the lint utility to check application 14365 source using a programming model with 32-bit int, long, pointer, and off_t types. 14366 XSI _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY) 14367 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14368 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14369 build an application using a programming model with 32-bit int, long, and pointer types, 14370 and an off_t type using at least 64 bits. 14371 XSI _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY) 14372 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 406 Technical Standard (2001) (Draft April 13, 2001) Headers 14373 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14374 an application using a programming model with 32-bit int, long, and pointer types, and an 14375 off_t type using at least 64 bits. 14376 XSI _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY) 14377 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14378 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14379 application using a programming model with 32-bit int, long, and pointer types, and an 14380 off_t type using at least 64 bits. 14381 XSI _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY) 14382 If sysconf(_SC_XBS5_ILP32_OFFBIG) returns -1, the meaning of this value is unspecified. 14383 Otherwise, this value is the set of options to be given to the lint utility to check an 14384 application using a programming model with 32-bit int, long, and pointer types, and an 14385 off_t type using at least 64 bits. 14386 XSI _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY) 14387 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14388 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14389 build an application using a programming model with 64-bit int, long, pointer, and off_t 14390 types. 14391 XSI _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY) 14392 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14393 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14394 an application using a programming model with 64-bit int, long, pointer, and off_t types. 14395 XSI _CS_XBS5_LP64_OFF64_LIBS (LEGACY) 14396 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14397 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14398 application using a programming model with 64-bit int, long, pointer, and off_t types. 14399 XSI _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY) 14400 If sysconf(_SC_XBS5_LP64_OFF64) returns -1, the meaning of this value is unspecified. 14401 Otherwise, this value is the set of options to be given to the lint utility to check application 14402 source using a programming model with 64-bit int, long, pointer, and off_t types. 14403 XSI _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY) 14404 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14405 Otherwise, this value is the set of initial options to be given to the cc and c99 utilities to 14406 build an application using a programming model with an int type using at least 32 bits and 14407 long, pointer, and off_t types using at least 64 bits. 14408 XSI _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY) 14409 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14410 Otherwise, this value is the set of final options to be given to the cc and c99 utilities to build 14411 an application using a programming model with an int type using at least 32 bits and long, 14412 pointer, and off_t types using at least 64 bits. 14413 XSI _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY) 14414 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. 14415 Otherwise, this value is the set of libraries to be given to the cc and c99 utilities to build an 14416 application using a programming model with an int type using at least 32 bits and long, 14417 pointer, and off_t types using at least 64 bits. 14418 XSI _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY) 14419 If sysconf(_SC_XBS5_LPBIG_OFFBIG) returns -1, the meaning of this value is unspecified. Base Definitions, Issue 6 407 Headers 14420 Otherwise, this value is the set of options to be given to the lint utility to check application 14421 source using a programming model with an int type using at least 32 bits and long, pointer, 14422 and off_t types using at least 64 bits. 14423 The following symbolic constants shall be defined for the lseek( ) and fcntl( ) functions and shall | 14424 have distinct values: | 14425 SEEK_CUR Set file offset to current plus offset. 14426 SEEK_END Set file offset to EOF plus offset. 14427 SEEK_SET Set file offset to offset. 14428 The following symbolic constants shall be defined as possible values for the function argument 14429 to the lockf( ) function: 14430 F_LOCK Lock a section for exclusive use. 14431 F_TEST Test section for locks by other processes. 14432 F_TLOCK Test and lock a section for exclusive use. 14433 F_ULOCK Unlock locked sections. 14434 The following symbolic constants shall be defined for pathconf( ): 14435 ADV _PC_ALLOC_SIZE_MIN 14436 AIO _PC_ASYNC_IO 14437 _PC_CHOWN_RESTRICTED 14438 _PC_FILESIZEBITS 14439 _PC_LINK_MAX 14440 _PC_MAX_CANON 14441 _PC_MAX_INPUT 14442 _PC_NAME_MAX 14443 _PC_NO_TRUNC 14444 _PC_PATH_MAX 14445 _PC_PIPE_BUF 14446 _PC_PRIO_IO 14447 ADV _PC_REC_INCR_XFER_SIZE 14448 _PC_REC_MAX_XFER_SIZE 14449 _PC_REC_MIN_XFER_SIZE 14450 _PC_REC_XFER_ALIGN 14451 _PC_SYNC_IO 14452 _PC_VDISABLE 14453 The following symbolic constants shall be defined for sysconf( ): 14454 _SC_2_C_BIND 14455 _SC_2_C_DEV 14456 _SC_2_C_VERSION 14457 _SC_2_CHAR_TIME | 14458 _SC_2_FORT_DEV | 14459 _SC_2_FORT_RUN 14460 _SC_2_LOCALEDEF 14461 _SC_2_PBS 14462 _SC_2_PBS_ACCOUNTING 14463 _SC_2_PBS_CHECKPOINT 14464 _SC_2_PBS_LOCATE 14465 _SC_2_PBS_MESSAGE 408 Technical Standard (2001) (Draft April 13, 2001) Headers 14466 _SC_2_PBS_TRACK 14467 _SC_2_SW_DEV 14468 _SC_2_UPE 14469 _SC_2_VERSION 14470 _SC_ADVISORY_INFO | 14471 _SC_ARG_MAX | 14472 _SC_AIO_LISTIO_MAX 14473 _SC_AIO_MAX 14474 _SC_AIO_PRIO_DELTA_MAX 14475 _SC_ASYNCHRONOUS_IO 14476 XSI _SC_ATEXIT_MAX 14477 BAR _SC_BARRIERS 14478 _SC_BASE 14479 _SC_BC_BASE_MAX 14480 _SC_BC_DIM_MAX 14481 _SC_BC_SCALE_MAX 14482 _SC_BC_STRING_MAX 14483 _SC_C_LANG_SUPPORT 14484 _SC_C_LANG_SUPPORT_R 14485 _SC_CHILD_MAX 14486 _SC_CLK_TCK 14487 CS _SC_CLOCK_SELECTION 14488 _SC_COLL_WEIGHTS_MAX 14489 _SC_CPUTIME | 14490 _SC_DELAYTIMER_MAX | 14491 _SC_DEVICE_IO 14492 _SC_DEVICE_SPECIFIC 14493 _SC_DEVICE_SPECIFIC_R 14494 _SC_EXPR_NEST_MAX 14495 _SC_FD_MGMT 14496 _SC_FIFO 14497 _SC_FILE_ATTRIBUTES 14498 _SC_FILE_LOCKING 14499 _SC_FILE_SYSTEM 14500 _SC_FSYNC 14501 _SC_GETGR_R_SIZE_MAX 14502 _SC_GETPW_R_SIZE_MAX 14503 _SC_HOST_NAME_MAX | 14504 XSI _SC_IOV_MAX | 14505 _SC_JOB_CONTROL 14506 _SC_LINE_MAX 14507 _SC_LOGIN_NAME_MAX 14508 _SC_MAPPED_FILES 14509 _SC_MEMLOCK 14510 _SC_MEMLOCK_RANGE 14511 _SC_MEMORY_PROTECTION 14512 _SC_MESSAGE_PASSING 14513 MON _SC_MONOTONIC_CLOCK 14514 _SC_MQ_OPEN_MAX 14515 _SC_MQ_PRIO_MAX 14516 _SC_MULTIPLE_PROCESS 14517 _SC_NETWORKING Base Definitions, Issue 6 409 Headers 14518 _SC_NGROUPS_MAX 14519 _SC_OPEN_MAX 14520 XSI _SC_PAGE_SIZE 14521 _SC_PAGESIZE 14522 _SC_PIPE 14523 _SC_PRIORITIZED_IO 14524 _SC_PRIORITY_SCHEDULING 14525 _SC_RE_DUP_MAX 14526 THR _SC_READER_WRITER_LOCKS 14527 _SC_REALTIME_SIGNALS 14528 _SC_REGEXP 14529 _SC_RTSIG_MAX 14530 _SC_SAVED_IDS 14531 _SC_SEMAPHORES 14532 _SC_SEM_NSEMS_MAX 14533 _SC_SEM_VALUE_MAX 14534 _SC_SHARED_MEMORY_OBJECTS 14535 _SC_SHELL 14536 _SC_SIGNALS 14537 _SC_SIGQUEUE_MAX 14538 _SC_SINGLE_PROCESS 14539 _SC_SPAWN | 14540 SPI _SC_SPIN_LOCKS | 14541 _SC_SPORADIC_SERVER | 14542 _SC_STREAM_MAX | 14543 _SC_SYNCHRONIZED_IO 14544 _SC_SYSTEM_DATABASE 14545 _SC_SYSTEM_DATABASE_R 14546 _SC_THREAD_ATTR_STACKADDR 14547 _SC_THREAD_ATTR_STACKSIZE 14548 _SC_THREAD_CPUTIME | 14549 _SC_THREAD_DESTRUCTOR_ITERATIONS | 14550 _SC_THREAD_KEYS_MAX 14551 _SC_THREAD_PRIO_INHERIT 14552 _SC_THREAD_PRIO_PROTECT 14553 _SC_THREAD_PRIORITY_SCHEDULING 14554 _SC_THREAD_PROCESS_SHARED 14555 _SC_THREAD_SAFE_FUNCTIONS 14556 _SC_THREAD_SPORADIC_SERVER | 14557 _SC_THREAD_STACK_MIN | 14558 _SC_THREAD_THREADS_MAX 14559 _SC_TIMEOUTS | 14560 _SC_THREADS | 14561 _SC_TIMER_MAX 14562 _SC_TIMERS 14563 TRC _SC_TRACE 14564 TEF _SC_TRACE_EVENT_FILTER 14565 TRI _SC_TRACE_INHERIT | 14566 TRL _SC_TRACE_LOG | 14567 _SC_TTY_NAME_MAX | 14568 TYM _SC_TYPED_MEMORY_OBJECTS 14569 _SC_TZNAME_MAX 410 Technical Standard (2001) (Draft April 13, 2001) Headers 14570 _SC_USER_GROUPS 14571 _SC_USER_GROUPS_R 14572 _SC_V6_ILP32_OFF32 14573 _SC_V6_ILP32_OFFBIG 14574 _SC_V6_LP64_OFF64 14575 _SC_V6_LPBIG_OFFBIG 14576 _SC_VERSION 14577 XSI _SC_XBS5_ILP32_OFF32 (LEGACY) 14578 _SC_XBS5_ILP32_OFFBIG (LEGACY) 14579 _SC_XBS5_LP64_OFF64 (LEGACY) 14580 _SC_XBS5_LPBIG_OFFBIG (LEGACY) 14581 _SC_XOPEN_CRYPT 14582 _SC_XOPEN_ENH_I18N 14583 _SC_XOPEN_LEGACY 14584 _SC_XOPEN_REALTIME 14585 _SC_XOPEN_REALTIME_THREADS 14586 _SC_XOPEN_SHM 14587 _SC_XOPEN_STREAMS 14588 _SC_XOPEN_UNIX 14589 _SC_XOPEN_VERSION 14590 _SC_XOPEN_XCU_VERSION 14591 14592 The two constants _SC_PAGESIZE and _SC_PAGE_SIZE may be defined to have the same 14593 value. 14594 The following symbolic constants shall be defined for file streams: 14595 STDERR_FILENO File number of stderr; 2. 14596 STDIN_FILENO File number of stdin; 0. 14597 STDOUT_FILENO File number of stdout; 1. 14598 Type Definitions 14599 The size_t, ssize_t, uid_t, gid_t, off_t, and pid_t types shall be defined as described in 14600 . 14601 The useconds_t type shall be defined as described in . 14602 The intptr_t type shall be defined as described in . | 14603 Declarations 14604 The following shall be declared as functions and may also be defined as macros. Function | 14605 prototypes shall be provided. | 14606 int access(const char *, int); 14607 unsigned alarm(unsigned); 14608 int chdir(const char *); 14609 int chown(const char *, uid_t, gid_t); 14610 int close(int); 14611 size_t confstr(int, char *, size_t); 14612 XSI char *crypt(const char *, const char *); 14613 char *ctermid(char *); 14614 int dup(int); Base Definitions, Issue 6 411 Headers 14615 int dup2(int, int); 14616 XSI void encrypt(char[64], int); 14617 int execl(const char *, const char *, ...); 14618 int execle(const char *, const char *, ...); 14619 int execlp(const char *, const char *, ...); 14620 int execv(const char *, char *const []); 14621 int execve(const char *, char *const [], char *const []); 14622 int execvp(const char *, char *const []); 14623 void _exit(int); 14624 int fchown(int, uid_t, gid_t); 14625 XSI int fchdir(int); 14626 SIO int fdatasync(int); 14627 pid_t fork(void); 14628 long fpathconf(int, int); 14629 int fsync(int); 14630 int ftruncate(int, off_t); 14631 char *getcwd(char *, size_t); 14632 gid_t getegid(void); 14633 uid_t geteuid(void); 14634 gid_t getgid(void); 14635 int getgroups(int, gid_t []); 14636 XSI long gethostid(void); 14637 int gethostname(char *, size_t); | 14638 char *getlogin(void); | 14639 int getlogin_r(char *, size_t); 14640 int getopt(int, char * const [], const char *); 14641 XSI pid_t getpgid(pid_t); 14642 pid_t getpgrp(void); 14643 pid_t getpid(void); 14644 pid_t getppid(void); 14645 XSI pid_t getsid(pid_t); 14646 uid_t getuid(void); 14647 XSI char *getwd(char *); (LEGACY) 14648 int isatty(int); 14649 XSI int lchown(const char *, uid_t, gid_t); 14650 int link(const char *, const char *); 14651 XSI int lockf(int, int, off_t); 14652 off_t lseek(int, off_t, int); 14653 XSI int nice(int); 14654 long pathconf(const char *, int); 14655 int pause(void); 14656 int pipe(int [2]); 14657 XSI ssize_t pread(int, void *, size_t, off_t); 14658 ssize_t pwrite(int, const void *, size_t, off_t); 14659 ssize_t read(int, void *, size_t); 14660 ssize_t readlink(const char *restrict, char *restrict, size_t); 14661 int rmdir(const char *); 14662 int setegid(gid_t); 14663 int seteuid(uid_t); 14664 int setgid(gid_t); 412 Technical Standard (2001) (Draft April 13, 2001) Headers 14665 int setpgid(pid_t, pid_t); 14666 XSI pid_t setpgrp(void); 14667 int setregid(gid_t, gid_t); 14668 int setreuid(uid_t, uid_t); 14669 pid_t setsid(void); 14670 int setuid(uid_t); 14671 unsigned sleep(unsigned); 14672 XSI void swab(const void *restrict, void *restrict, ssize_t); 14673 int symlink(const char *, const char *); 14674 void sync(void); 14675 long sysconf(int); 14676 pid_t tcgetpgrp(int); 14677 int tcsetpgrp(int, pid_t); 14678 XSI int truncate(const char *, off_t); 14679 char *ttyname(int); 14680 int ttyname_r(int, char *, size_t); 14681 XSI useconds_t ualarm(useconds_t, useconds_t); 14682 int unlink(const char *); 14683 XSI int usleep(useconds_t); 14684 pid_t vfork(void); 14685 ssize_t write(int, const void *, size_t); 14686 Implementations may also include the pthread_atfork( ) prototype as defined in (on 14687 page 286). 14688 The following external variables shall be declared: 14689 extern char *optarg; 14690 extern int optind, opterr, optopt; 14691 APPLICATION USAGE 14692 IEEE Std 1003.1-200x only describes the behavior of systems that claim conformance to it. | 14693 However, application developers who want to write applications that adapt to other versions of | 14694 IEEE Std 1003.1 (or to systems that do not conform to any POSIX standard) may find it useful to | 14695 code them so as to conditionally compile different code depending on the value of | 14696 _POSIX_VERSION, for example. | 14697 #if _POSIX_VERSION == 200xxxL | 14698 /* Use the newer function that copes with large files. */ | 14699 off_t pos=ftello(fp); | 14700 #else | 14701 /* Either this is an old version of POSIX, or _POSIX_VERSION is | 14702 not even defined, so use the traditional function. */ | 14703 long pos=ftell(fp); | 14704 #endif | 14705 Earlier versions of IEEE Std 1003.1 and of the Single UNIX Specification can be identified by the | 14706 following macros: | 14707 POSIX.1-1988 standard | 14708 _POSIX_VERSION= =198808L | 14709 POSIX.1-1990 standard | 14710 _POSIX_VERSION= =199009L | 14711 ISO POSIX-1: 1996 standard | 14712 _POSIX_VERSION= =199506L | Base Definitions, Issue 6 413 Headers 14713 Single UNIX Specification, Version 1 | 14714 _XOPEN_UNIX and _XOPEN_VERSION= =4 | 14715 Single UNIX Specification, Version 2 | 14716 _XOPEN_UNIX and _XOPEN_VERSION= =500 | 14717 IEEE Std 1003.1-200x does not make any attempt to define application binary interaction with | 14718 the underlying operating system. However, application developers may find it useful to query | 14719 _SC_VERSION at runtime via sysconf( ) to determine whether the current version of the | 14720 operating system supports the necessary functionality as in the following program fragment: | 14721 if (sysconf(_SC_VERSION) < 200xxxL) { | 14722 fprintf(stderr, "POSIX.1-200x system required, terminating \n"); | 14723 exit(1); | 14724 } | 14725 RATIONALE | 14726 As IEEE Std 1003.1-200x evolved, certain options became sufficiently standardized that it was 14727 concluded that simply requiring one of the option choices was simpler than retaining the option. 14728 However, for backwards compatibility, the option flags (with required constant values) are 14729 retained. 14730 Version Test Macros 14731 The standard developers considered altering the definition of _POSIX_VERSION and removing 14732 _SC_VERSION from the specification of sysconf( ) since the utility to an application was deemed 14733 by some to be minimal, and since the implementation of the functionality is potentially | 14734 problematic. However, they recognized that support for existing application binaries is a | 14735 concern to manufacturers, application developers, and the users of implementations conforming | 14736 to IEEE Std 1003.1-200x. | 14737 While the example using _SC_VERSION in the APPLICATION USAGE section does not provide | 14738 the greatest degree of imaginable utility to the application developer or user, it is arguably better | 14739 than a core dump or some other equally obscure result. (It is also possible for implementations | 14740 to encode and recognize application binaries compiled in various POSIX.1-conforming | 14741 environments, and modify the semantics of the underlying system to conform to the | 14742 expectations of the application.) For the reasons outlined in the preceding paragraphs and in the | 14743 APPLICATION USAGE section, the standard developers elected to retain the _POSIX_VERSION | 14744 and _SC_VERSION functionality. | 14745 Compile-Time Symbolic Constants for System-Wide Options 14746 IEEE Std 1003.1-200x now includes support in certain areas for the newly adopted policy 14747 governing options and stubs. 14748 This policy provides flexibility for implementations in how they support options. It also 14749 specifies how conforming applications can adapt to different implementations that support 14750 different sets of options. It allows the following: 14751 1. If an implementation has no interest in supporting an option, it does not have to provide 14752 anything associated with that option beyond the announcement that it does not support it. 14753 2. An implementation can support a partial or incompatible version of an option (as a non- 14754 standard extension) as long as it does not claim to support the option. 14755 3. An application can determine whether the option is supported. A strictly conforming 14756 application must check this announcement mechanism before first using anything 14757 associated with the option. 414 Technical Standard (2001) (Draft April 13, 2001) Headers 14758 There is an important implication of this policy. IEEE Std 1003.1-200x cannot dictate the 14759 behavior of interfaces associated with an option when the implementation does not claim to 14760 support the option. In particular, it cannot require that a function associated with an 14761 unsupported option will fail if it does not perform as specified. However, this policy does not 14762 prevent a standard from requiring certain functions to always be present, but that they shall 14763 always fail on some implementations. The setpgid( ) function in the POSIX.1-1990 standard, for 14764 example, is considered appropriate. 14765 The POSIX standards include various options, and the C language binding support for an option 14766 implies that the implementation must supply data types and function interfaces. An application 14767 must be able to discover whether the implementation supports each option. 14768 Any application must consider the following three cases for each option: 14769 1. Option never supported. 14770 The implementation advertises at compile time that the option will never be supported. In 14771 this case, it is not necessary for the implementation to supply any of the data types or 14772 function interfaces that are provided only as part of the option. The implementation might 14773 provide data types and functions that are similar to those defined by IEEE Std 1003.1-200x, 14774 but there is no guarantee for any particular behavior. 14775 2. Option always supported. 14776 The implementation advertises at compile time that the option will always be supported. 14777 In this case, all data types and function interfaces shall be available and shall operate as 14778 specified. 14779 3. Option might or might not be supported. 14780 Some implementations might not provide a mechanism to specify support of options at 14781 compile time. In addition, the implementation might be unable or unwilling to specify 14782 support or non-support at compile time. In either case, any application that might use the 14783 option at runtime must be able to compile and execute. The implementation must provide, 14784 at compile time, all data types and function interfaces that are necessary to allow this. In 14785 this situation, there must be a mechanism that allows the application to query, at runtime, 14786 whether the option is supported. If the application attempts to use the option when it is 14787 not supported, the result is unspecified unless explicitly specified otherwise in 14788 IEEE Std 1003.1-200x. 14789 FUTURE DIRECTIONS 14790 None. 14791 SEE ALSO 14792 , , , , , , the System | 14793 Interfaces volume of IEEE Std 1003.1-200x, access( ), alarm( ), chdir( ), chown( ), close( ), crypt( ), 14794 ctermid( ), dup( ), encrypt( ), environ, exec( ), exit( ), fchdir( ), fchown( ), fcntl( ), fork( ), fpathconf( ), 14795 fsync( ), ftruncate( ), getcwd( ), getegid( ), geteuid( ), getgid( ), getgroups( ), gethostid( ), gethostname( ), 14796 getlogin( ), getpgid( ), getpgrp( ), getpid( ), getppid( ), getsid( ), getuid( ), isatty( ), lchown( ), link( ), 14797 lockf( ), lseek( ), nice( ), pathconf( ), pause( ), pipe( ), read( ), readlink( ), rmdir( ), setgid( ), setpgid( ), 14798 setpgrp( ), setregid( ), setreuid( ), setsid( ), setuid( ), sleep( ), swab( ), symlink( ), sync( ), sysconf( ), 14799 tcgetpgrp( ), tcsetpgrp( ), truncate( ), ttyname( ), ualarm( ), unlink( ), usleep( ), vfork( ), write( ) 14800 CHANGE HISTORY 14801 First released in Issue 1. Derived from Issue 1 of the SVID. Base Definitions, Issue 6 415 Headers 14802 Issue 5 14803 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 14804 Threads Extension. 14805 The symbolic constants _XOPEN_REALTIME and _XOPEN_REALTIME_THREADS are added. 14806 _POSIX2_C_BIND, _XOPEN_ENH_I18N, and _XOPEN_SHM must now be set to a value other 14807 than -1 by a conforming implementation. 14808 Large File System extensions are added. 14809 The type of the argument to sbrk( ) is changed from int to intptr_t. 14810 _XBS_ constants are added to the list of constants for Options and Option Groups, to the list of 14811 constants for the confstr( ) function, and to the list of constants to the sysconf( ) function. These 14812 are all marked EX. 14813 Issue 6 14814 _POSIX2_C_VERSION is removed. 14815 The Open Group Corrigendum U026/4 is applied, adding the prototype for fdatasync( ). 14816 The Open Group Corrigendum U026/1 is applied, adding the symbols _SC_XOPEN_LEGACY, 14817 _SC_XOPEN_REALTIME, and _SC_XOPEN_REALTIME_THREADS. 14818 The symbols _XOPEN_STREAMS and _SC_XOPEN_STREAMS are added to support the XSI 14819 STREAMS Option Group. 14820 Text in the DESCRIPTION relating to conformance requirements is moved elsewhere in | 14821 IEEE Std 1003.1-200x. 14822 The legacy symbol _SC_PASS_MAX is removed. 14823 The following new requirements on POSIX implementations derive from alignment with the 14824 Single UNIX Specification: 14825 * The _CS_POSIX_* and _CS_XBS5_* constants are added for the confstr( ) function. | 14826 * The _SC_XBS5_* constants are added for the sysconf( ) function. 14827 * The symbolic constants F_ULOCK, F_LOCK, F_TLOCK, and F_TEST are added. 14828 * The uid_t, gid_t, off_t, pid_t, and useconds_t types are mandated. 14829 The gethostname( ) prototype is added for sockets. 14830 New section added for System Wide Options. 14831 Function prototypes for setegid( ) and seteuid( ) are added. 14832 Option symbolic constants are added for _POSIX_ADVISORY_INFO, _POSIX_CPUTIME, | 14833 _POSIX_SPAWN, _POSIX_SPORADIC_SERVER, _POSIX_THREAD_CPUTIME, 14834 _POSIX_THREAD_SPORADIC_SERVER, and _POSIX_TIMEOUTS, and pathconf( ) variables are 14835 added for _PC_ALLOC_SIZE_MIN, _PC_REC_INCR_XFER_SIZE, _PC_REC_MAX_XFER_SIZE, 14836 _PC_REC_MIN_XFER_SIZE, and _PC_REC_XFER_ALIGN for alignment with 14837 IEEE Std 1003.1d-1999. | 14838 The following are added for alignment with IEEE Std 1003.1j-2000: 14839 * Option symbolic constants _POSIX_BARRIERS, _POSIX_CLOCK_SELECTION, 14840 _POSIX_MONOTONIC_CLOCK, _POSIX_READER_WRITER_LOCKS, 14841 _POSIX_SPIN_LOCKS, and _POSIX_TYPED_MEMORY_OBJECTS 416 Technical Standard (2001) (Draft April 13, 2001) Headers 14842 * sysconf( ) variables _SC_BARRIERS, _SC_CLOCK_SELECTION, 14843 _SC_MONOTONIC_CLOCK, _SC_READER_WRITER_LOCKS, _SC_SPIN_LOCKS, and 14844 _SC_TYPED_MEMORY_OBJECTS 14845 The _SC_XBS5 macros associated with the ISO/IEC 9899: 1990 standard are marked LEGACY, 14846 and new equivalent _SC_V6 macros associated with the ISO/IEC 9899: 1999 standard are 14847 introduced. 14848 The getwd( ) function is marked LEGACY. 14849 The restrict keyword is added to the prototypes for readlink( ) and swab( ). | 14850 Constants for options are now harmonized, so when supported they take the year of approval of 14851 IEEE Std 1003.1-200x as the value. 14852 The following are added for alignment with IEEE Std 1003.1q-2000: 14853 * Optional symbolic constants _POSIX_TRACE, _POSIX_TRACE_EVENT_FILTER, 14854 _POSIX_TRACE_LOG, and _POSIX_TRACE_INHERIT 14855 * The sysconf( ) symbolic constants _SC_TRACE, _SC_TRACE_EVENT_FILTER, 14856 _SC_TRACE_LOG, and _SC_TRACE_INHERIT. 14857 The brk( ) and sbrk( ) legacy functions are removed. | 14858 The Open Group Base Resolution bwg2001-006 is applied, which reworks the XSI versioning | 14859 information. | 14860 The Open Group Base Resolution bwg2001-008 is applied, changing the namelen parameter for | 14861 gethostname( ) from socklen_t to size_t. | Base Definitions, Issue 6 417 Headers 14862 NAME 14863 utime.h - access and modification times structure 14864 SYNOPSIS 14865 #include 14866 DESCRIPTION 14867 The header shall declare the structure utimbuf, which shall include the following 14868 members: 14869 time_t actime Access time. 14870 time_t modtime Modification time. 14871 The times shall be measured in seconds since the Epoch. 14872 The type time_t shall be defined as described in . 14873 The following shall be declared as a function and may also be defined as a macro. A function | 14874 prototype shall be provided. | 14875 int utime(const char *, const struct utimbuf *); 14876 APPLICATION USAGE 14877 None. 14878 RATIONALE 14879 None. 14880 FUTURE DIRECTIONS 14881 None. 14882 SEE ALSO 14883 , the System Interfaces volume of IEEE Std 1003.1-200x, utime( ) 14884 CHANGE HISTORY 14885 First released in Issue 3. 14886 Issue 6 14887 The following new requirements on POSIX implementations derive from alignment with the 14888 Single UNIX Specification: 14889 * The time_t type is defined. 418 Technical Standard (2001) (Draft April 13, 2001) Headers 14890 NAME 14891 utmpx.h - user accounting database definitions 14892 SYNOPSIS 14893 XSI #include 14894 14895 DESCRIPTION 14896 The header shall define the utmpx structure that shall include at least the following 14897 members: 14898 char ut_user[] User login name. 14899 char ut_id[] Unspecified initialization process identifier. 14900 char ut_line[] Device name. 14901 pid_t ut_pid Process ID. 14902 short ut_type Type of entry. 14903 struct timeval ut_tv Time entry was made. 14904 The pid_t type shall be defined through typedef as described in . 14905 The timeval structure shall be defined as described in . 14906 Inclusion of the header may also make visible all symbols from . 14907 The following symbolic constants shall be defined as possible values for the ut_type member of 14908 the utmpx structure: 14909 EMPTY No valid user accounting information. 14910 BOOT_TIME Identifies time of system boot. 14911 OLD_TIME Identifies time when system clock changed. 14912 NEW_TIME Identifies time after system clock changed. 14913 USER_PROCESS Identifies a process. 14914 INIT_PROCESS Identifies a process spawned by the init process. 14915 LOGIN_PROCESS Identifies the session leader of a logged in user. 14916 DEAD_PROCESS Identifies a session leader who has exited. 14917 The following shall be declared as functions and may also be defined as macros. Function | 14918 prototypes shall be provided. | 14919 void endutxent(void); 14920 struct utmpx *getutxent(void); 14921 struct utmpx *getutxid(const struct utmpx *); 14922 struct utmpx *getutxline(const struct utmpx *); 14923 struct utmpx *pututxline(const struct utmpx *); 14924 void setutxent(void); Base Definitions, Issue 6 419 Headers 14925 APPLICATION USAGE 14926 None. 14927 RATIONALE 14928 None. 14929 FUTURE DIRECTIONS 14930 None. 14931 SEE ALSO 14932 , , the System Interfaces volume of IEEE Std 1003.1-200x, endutxent( ) 14933 CHANGE HISTORY 14934 First released in Issue 4, Version 2. 420 Technical Standard (2001) (Draft April 13, 2001) Headers 14935 NAME 14936 wchar.h - wide-character handling | 14937 SYNOPSIS 14938 #include 14939 DESCRIPTION 14940 CX Some of the functionality described on this reference page extends the ISO C standard. 14941 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 14942 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 14943 symbols in this header. 14944 The header shall define the following types: 14945 wchar_t As described in . 14946 wint_t An integer type capable of storing any valid value of wchar_t or WEOF. 14947 XSI wctype_t A scalar type of a data object that can hold values which represent locale- 14948 specific character classification. 14949 mbstate_t An object type other than an array type that can hold the conversion state 14950 information necessary to convert between sequences of (possibly multi-byte) 14951 XSI characters and wide characters. If a codeset is being used such that an 14952 mbstate_t needs to preserve more than 2 levels of reserved state, the results 14953 are unspecified. 14954 XSI FILE As described in . 14955 size_t As described in . | 14956 XSI va_list As described in . | 14957 The implementation shall support one or more programming environments in which the width | 14958 of wint_t is no greater than the width of type long. The names of these programming | 14959 environments can be obtained using the confstr( ) function or the getconf utility. | 14960 The following shall be declared as functions and may also be defined as macros. Function | 14961 prototypes shall be provided. | 14962 wint_t btowc(int); 14963 wint_t fgetwc(FILE *); 14964 wchar_t *fgetws(wchar_t *restrict, int, FILE *restrict); 14965 wint_t fputwc(wchar_t, FILE *); 14966 int fputws(const wchar_t *restrict, FILE *restrict); 14967 int fwide(FILE *, int); 14968 int fwprintf(FILE *restrict, const wchar_t *restrict, ...); 14969 int fwscanf(FILE *restrict, const wchar_t *restrict, ...); 14970 wint_t getwc(FILE *); 14971 wint_t getwchar(void); 14972 XSI int iswalnum(wint_t); 14973 int iswalpha(wint_t); 14974 int iswcntrl(wint_t); 14975 int iswctype(wint_t, wctype_t); 14976 int iswdigit(wint_t); 14977 int iswgraph(wint_t); 14978 int iswlower(wint_t); 14979 int iswprint(wint_t); 14980 int iswpunct(wint_t); Base Definitions, Issue 6 421 Headers 14981 int iswspace(wint_t); 14982 int iswupper(wint_t); 14983 int iswxdigit(wint_t); 14984 size_t mbrlen(const char *restrict, size_t, mbstate_t *restrict); 14985 size_t mbrtowc(wchar_t *restrict, const char *restrict, size_t, 14986 mbstate_t *restrict); 14987 int mbsinit(const mbstate_t *); 14988 size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t, 14989 mbstate_t *restrict); 14990 wint_t putwc(wchar_t, FILE *); 14991 wint_t putwchar(wchar_t); 14992 int swprintf(wchar_t *restrict, size_t, 14993 const wchar_t *restrict, ...); 14994 int swscanf(const wchar_t *restrict, 14995 const wchar_t *restrict, ...); 14996 XSI wint_t towlower(wint_t); 14997 wint_t towupper(wint_t); 14998 wint_t ungetwc(wint_t, FILE *); 14999 int vfwprintf(FILE *restrict, const wchar_t *restrict, va_list); 15000 int vfwscanf(FILE *restrict, const wchar_t *restrict, va_list); 15001 int vwprintf(const wchar_t *restrict, va_list); 15002 int vswprintf(wchar_t *restrict, size_t, 15003 const wchar_t *restrict, va_list); 15004 int vswscanf(const wchar_t *restrict, const wchar_t *restrict, 15005 va_list); 15006 int vwscanf(const wchar_t *restrict, va_list); 15007 size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict); 15008 wchar_t *wcscat(wchar_t *restrict, const wchar_t *restrict); 15009 wchar_t *wcschr(const wchar_t *, wchar_t); 15010 int wcscmp(const wchar_t *, const wchar_t *); 15011 int wcscoll(const wchar_t *, const wchar_t *); 15012 wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict); 15013 size_t wcscspn(const wchar_t *, const wchar_t *); 15014 size_t wcsftime(wchar_t *restrict, size_t, 15015 const wchar_t *restrict, const struct tm *restrict); 15016 size_t wcslen(const wchar_t *); 15017 wchar_t *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t); 15018 int wcsncmp(const wchar_t *, const wchar_t *, size_t); 15019 wchar_t *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t); 15020 wchar_t *wcspbrk(const wchar_t *, const wchar_t *); 15021 wchar_t *wcsrchr(const wchar_t *, wchar_t); 15022 size_t wcsrtombs(char *restrict, const wchar_t **restrict, 15023 size_t, mbstate_t *restrict); 15024 size_t wcsspn(const wchar_t *, const wchar_t *); 15025 wchar_t *wcsstr(const wchar_t *restrict, const wchar_t *restrict); 15026 double wcstod(const wchar_t *restrict, wchar_t **restrict); 15027 float wcstof(const wchar_t *restrict, wchar_t **restrict); 15028 wchar_t *wcstok(wchar_t *restrict, const wchar_t *restrict, 15029 wchar_t **restrict); 15030 long wcstol(const wchar_t *restrict, wchar_t **restrict, int); 15031 long double wcstold(const wchar_t *restrict, wchar_t **restrict); 15032 long long wcstoll(const wchar_t *restrict, wchar_t **restrict, int); 422 Technical Standard (2001) (Draft April 13, 2001) Headers 15033 unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int); 15034 unsigned long long 15035 wcstoull(const wchar_t *restrict, wchar_t **restrict, int); 15036 XSI wchar_t *wcswcs(const wchar_t *, const wchar_t *); 15037 int wcswidth(const wchar_t *, size_t); 15038 size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t); 15039 int wctob(wint_t); 15040 XSI wctype_t wctype(const char *); 15041 int wcwidth(wchar_t); 15042 wchar_t *wmemchr(const wchar_t *, wchar_t, size_t); 15043 int wmemcmp(const wchar_t *, const wchar_t *, size_t); 15044 wchar_t *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t); 15045 wchar_t *wmemmove(wchar_t *, const wchar_t *, size_t); 15046 wchar_t *wmemset(wchar_t *, wchar_t, size_t); 15047 int wprintf(const wchar_t *restrict, ...); 15048 int wscanf(const wchar_t *restrict, ...); 15049 The header shall define the following macros: 15050 WCHAR_MAX The maximum value representable by an object of type wchar_t. 15051 WCHAR_MIN The minimum value representable by an object of type wchar_t. 15052 WEOF Constant expression of type wint_t that is returned by several WP functions 15053 to indicate end-of-file. 15054 NULL As described in . 15055 The tag tm shall be declared as naming an incomplete structure type, the contents of which are 15056 described in the header . 15057 CX Inclusion of the header may make visible all symbols from the headers , 15058 , , , , , and . 15059 APPLICATION USAGE 15060 None. 15061 RATIONALE 15062 In the ISO C standard, the symbols referenced as XSI extensions are in . Their | 15063 presence here is thus an extension. | 15064 FUTURE DIRECTIONS 15065 None. 15066 SEE ALSO 15067 , , , , , , , the System 15068 Interfaces volume of IEEE Std 1003.1-200x, btowc( ), confstr( ), fgetwc( ), fgetws( ), fputwc( ), | 15069 fputws( ), fwide( ), fwprintf( ), fwscanf( ), getwc( ), getwchar( ), iswalnum( ), iswalpha( ), iswcntrl( ), 15070 iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), iswspace( ), iswupper( ), 15071 iswxdigit( ), iswctype( ), mbsinit( ), mbrlen( ), mbrtowc( ), mbsrtowcs( ), putwc( ), putwchar( ), 15072 swprintf( ), swscanf( ), towlower( ), towupper( ), ungetwc( ), vfwprintf( ), vfwscanf( ), vswprintf( ), 15073 vswscanf( ), vwscanf( ), wcrtomb( ), wcsrtombs( ), wcscat( ), wcschr( ), wcscmp( ), wcscoll( ), wcscpy( ), 15074 wcscspn( ), wcsftime( ), wcslen( ), wcsncat( ), wcsncmp( ), wcsncpy( ), wcspbrk( ), wcsrchr( ), wcsspn( ), 15075 wcsstr( ), wcstod( ), wcstof( ), wcstok( ), wcstol( ), wcstold( ), wcstoll( ), wcstoul( ), wcstoull( ), wcswcs( ), 15076 wcswidth( ), wcsxfrm( ), wctob( ), wctype( ), wcwidth( ), wmemchr( ), wmemcmp( ), wmemcpy( ), 15077 wmemmove( ), wmemset( ), wprintf( ), wscanf( ), the Shell and Utilities volume of | 15078 IEEE Std 1003.1-200x, getconf | Base Definitions, Issue 6 423 Headers 15079 CHANGE HISTORY 15080 First released in Issue 4. 15081 Issue 5 15082 Aligned with the ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 15083 Issue 6 15084 The Open Group Corrigendum U021/10 is applied. The prototypes for wcswidth( ) and 15085 wcwidth( ) are marked as extensions. 15086 The Open Group Corrigendum U028/5 is applied, correcting the prototype for the mbsinit( ) 15087 function. 15088 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 15089 * Various function prototypes are updated to add the restrict keyword. 15090 * The functions vfwscanf( ), vswscanf( ), wcstof( ), wcstold( ), wcstoll( ), and wcstoull( ) are added. 15091 The type wctype_t, the isw*( ), to*( ), and wctype( ) functions are marked as XSI extensions. 424 Technical Standard (2001) (Draft April 13, 2001) Headers 15092 NAME 15093 wctype.h - wide-character classification and mapping utilities 15094 SYNOPSIS 15095 #include 15096 DESCRIPTION 15097 CX Some of the functionality described on this reference page extends the ISO C standard. 15098 Applications shall define the appropriate feature test macro (see the System Interfaces volume of 15099 IEEE Std 1003.1-200x, Section 2.2, The Compilation Environment) to enable the visibility of these 15100 symbols in this header. 15101 The header shall define the following types: 15102 wint_t As described in . 15103 wctrans_t A scalar type that can hold values which represent locale-specific character 15104 mappings. 15105 wctype_t As described in . 15106 The following shall be declared as functions and may also be defined as macros. Function | 15107 prototypes shall be provided. | 15108 int iswalnum(wint_t); 15109 int iswalpha(wint_t); 15110 int iswblank(wint_t); 15111 int iswcntrl(wint_t); 15112 int iswdigit(wint_t); 15113 int iswgraph(wint_t); 15114 int iswlower(wint_t); 15115 int iswprint(wint_t); 15116 int iswpunct(wint_t); 15117 int iswspace(wint_t); 15118 int iswupper(wint_t); 15119 int iswxdigit(wint_t); 15120 int iswctype(wint_t, wctype_t); 15121 wint_t towctrans(wint_t, wctrans_t); 15122 wint_t towlower(wint_t); 15123 wint_t towupper(wint_t); 15124 wctrans_t wctrans(const char *); 15125 wctype_t wctype(const char *); 15126 The header shall define the following macro name: 15127 WEOF Constant expression of type wint_t that is returned by several MSE functions 15128 to indicate end-of-file. 15129 For all functions described in this header that accept an argument of type wint_t, the value is 15130 representable as a wchar_t or equals the value of WEOF. If this argument has any other value, 15131 the behavior is undefined. 15132 The behavior of these functions shall be affected by the LC_CTYPE category of the current locale. 15133 CX Inclusion of the header may make visible all symbols from the headers , 15134 , , , , , , and . Base Definitions, Issue 6 425 Headers 15135 APPLICATION USAGE 15136 None. 15137 RATIONALE 15138 None. 15139 FUTURE DIRECTIONS 15140 None. 15141 SEE ALSO 15142 , , the System Interfaces volume of IEEE Std 1003.1-200x, iswalnum( ), 15143 iswalpha( ), iswblank( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 15144 iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), towctrans( ), towlower( ), towupper( ), 15145 wctrans( ), wctype( ) 15146 CHANGE HISTORY 15147 First released in Issue 5. Derived from the ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 15148 Issue 6 15149 The iswblank( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. 426 Technical Standard (2001) (Draft April 13, 2001) Headers 15150 NAME 15151 wordexp.h - word-expansion types 15152 SYNOPSIS 15153 #include 15154 DESCRIPTION 15155 The header shall define the structures and symbolic constants used by the 15156 wordexp( ) and wordfree( ) functions. 15157 The structure type wordexp_t shall contain at least the following members: 15158 size_t we_wordc Count of words matched by words. 15159 char **we_wordv Pointer to list of expanded words. 15160 size_t we_offs Slots to reserve at the beginning of we_wordv. 15161 The flags argument to the wordexp( ) function shall be the bitwise-inclusive OR of the following 15162 flags: 15163 WRDE_APPEND Append words to those previously generated. 15164 WRDE_DOOFFS Number of null pointers to prepend to we_wordv. 15165 WRDE_NOCMD Fail if command substitution is requested. 15166 WRDE_REUSE The pwordexp argument was passed to a previous successful call to 15167 wordexp( ), and has not been passed to wordfree( ). The result is the same 15168 as if the application had called wordfree( ) and then called wordexp( ) 15169 without WRDE_REUSE. 15170 WRDE_SHOWERR Do not redirect stderr to /dev/null. 15171 WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. 15172 The following constants shall be defined as error return values: 15173 WRDE_BADCHAR One of the unquoted characters-, '|', '&', ';', '<', '>', 15174 '(', ')', '{', '}'-appears in words in an inappropriate context. 15175 WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags. 15176 WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. 15177 WRDE_NOSPACE Attempt to allocate memory failed. 15178 OB XSI WRDE_NOSYS Reserved. 15179 WRDE_SYNTAX Shell syntax error, such as unbalanced parentheses or unterminated 15180 string. 15181 The header shall define the following type: | 15182 XSI size_t As described in . | 15183 The following shall be declared as functions and may also be defined as macros. Function | 15184 prototypes shall be provided. | 15185 int wordexp(const char *restrict, wordexp_t *restrict, int); 15186 void wordfree(wordexp_t *); 15187 The implementation may define additional macros or constants using names beginning with 15188 WRDE_. Base Definitions, Issue 6 427 Headers 15189 APPLICATION USAGE 15190 None. 15191 RATIONALE 15192 None. 15193 FUTURE DIRECTIONS 15194 None. 15195 SEE ALSO 15196 , the System Interfaces volume of IEEE Std 1003.1-200x, wordexp( ), the Shell and | 15197 Utilities volume of IEEE Std 1003.1-200x 15198 CHANGE HISTORY 15199 First released in Issue 4. Derived from the ISO POSIX-2 standard. 15200 Issue 6 15201 The restrict keyword is added to the prototype for wordexp( ). 15202 The WRDE_NOSYS constant is marked obsolescent. 428 Technical Standard (2001) (Draft April 13, 2001) 1 Index 2 (time) resolution .......................................................77 .....................................................................284 3 / .................................................................................181 .............................................................286 4 /dev ...........................................................................181 ...................................................................291 5 /dev/console...........................................................181 ..................................................................292 6 /dev/null..................................................................181 .................................................................294 7 /dev/tty ...................................................................181 ................................................................296 8 /tmp..........................................................................181 .......................................................298 9 ......................................................................202 ...............................................................299 10 .........................................................................34 .................................................................300 11 ..........................................................204 .......................................................................81 12 .................................................................205 ...............................................................307 13 ..............................................................37 ................................................................309 14 .......................................................................42 ..............................................................311 15 ......................................................44 ................................................................312 16 ............................................................206 .................................................................313 17 ....................................................................209 ...................................................................320 18 ..................................................................210 .................................................................324 19 .................................................................212 .................................................................328 20 ..................................................................214 ...............................................................330 21 ..................................................................215 ...............................................................331 22 ...................................................................219 ..............................................................212 23 ....................................................................222 ..............................................................336 24 ...................................................................225 ........................................................338 25 .............................................................229 ............................................................341 26 ............................................................231 ....................................................343 27 ...............................................................58 .........................................................345 28 .....................................................................232 ............................................................347 29 ....................................................................234 ............................................................349 30 .....................................................................236 ........................................................351 31 ..................................................................237 .............................................................356 32 .............................................................238 .......................................................360 33 ................................................................240 ...........................................................362 34 ............................................................241 .........................................................364 35 ................................................................244 .........................................................365 36 .................................................................245 .........................................................366 37 .................................................................260 ..............................................................369 38 ..................................................................262 ...............................................................370 39 ..........................................................269 ....................................................371 40 .............................................................270 ...........................................................372 41 .................................................................272 ................................................................374 42 .................................................................273 ...........................................................................86 43 .................................................................274 .......................................................................376 44 .........................................................278 ..............................................................378 45 .......................................................282 ..............................................................384 46 ...................................................................65 ...................................................................388 47 ............................................................283 ...................................................................392 Base Definitions, Issue 6 429 Index 48 ............................................................396 _POSIX2_LINE_MAX ...........................250, 254, 257 49 .................................................................397 _POSIX2_LOCALEDEF.........................................402 50 ................................................................398 _POSIX2_PBS ..........................................................402 51 .................................................................418 _POSIX2_PBS_ACCOUNTING ..........................402 52 ...............................................................419 _POSIX2_PBS_CHECKPOINT ............................402 53 ............................................................91 _POSIX2_PBS_LOCATE........................................402 54 ................................................................421 _POSIX2_PBS_MESSAGE.....................................402 55 ..............................................................425 _POSIX2_PBS_TRACK..........................................402 56 ...........................................................427 _POSIX2_RE_DUP_MAX.....................247, 250, 254 57 ±0..................................................................................93 _POSIX2_SW_DEV ................................................403 58 _Complex_I..............................................................206 _POSIX2_UPE .........................................................403 59 _CS_XBS5_ILP32_OFF32_CFLAGS....................406 _POSIX2_VERSION...............................................398 60 _CS_XBS5_ILP32_OFF32_LDFLAGS.................406 _POSIX_ADVISORY_INFO.....................17, 23, 399 61 _CS_XBS5_ILP32_OFF32_LIBS............................406 _POSIX_AIO_LISTIO_MAX........................246, 251 62 _CS_XBS5_ILP32_OFF32_LINTFLAGS.............406 _POSIX_AIO_MAX........................................246, 251 63 _CS_XBS5_ILP32_OFFBIG_CFLAGS.................406 _POSIX_ARG_MAX ......................................246, 251 64 _CS_XBS5_ILP32_OFFBIG_LDFLAGS ..............406 _POSIX_ASYNCHRONOUS_IO............17, 22, 399 65 _CS_XBS5_ILP32_OFFBIG_LIBS.........................407 _POSIX_ASYNC_IO ..............................................404 66 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS..........407 _POSIX_BARRIERS ...................................17, 24, 399 67 _CS_XBS5_LP64_OFF64_CFLAGS .....................407 _POSIX_CHILD_MAX..................................246, 251 68 _CS_XBS5_LP64_OFF64_LDFLAGS ..................407 _POSIX_CHOWN_RESTRICTED ................16, 399 69 _CS_XBS5_LP64_OFF64_LIBS.............................407 _POSIX_CLOCKRES_MIN...................................251 70 _CS_XBS5_LP64_OFF64_LINTFLAGS ..............407 _POSIX_CLOCK_SELECTION...............17, 23, 399 71 _CS_XBS5_LPBIG_OFFBIG_CFLAGS ...............407 _POSIX_CPUTIME ....................................17, 23, 399 72 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS.............407 _POSIX_DELAYTIMER_MAX ....................246, 251 73 _CS_XBS5_LPBIG_OFFBIG_LIBS .......................407 _POSIX_FSYNC ...................................17, 19, 22, 399 74 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS ........407 _POSIX_IPV6.............................................................17 75 _Imaginary_I ...........................................................206 _POSIX_JOB_CONTROL ...............................16, 399 76 _IOFBF ......................................................................320 _POSIX_LINK_MAX.....................................249, 251 77 _IOLBF......................................................................320 _POSIX_LOGIN_NAME_MAX ..................246, 251 78 _IONBF.....................................................................320 _POSIX_MAPPED_FILES ..................17, 19, 22, 399 79 _MIN .........................................................................245 _POSIX_MAPPED_FILES,......................................22 80 _PC constants _POSIX_MAX_CANON...............................249, 252 81 defined in ........................................408 _POSIX_MAX_INPUT ..................................249, 252 82 _POSIX......................................................................245 _POSIX_MEMLOCK .................................17, 22, 399 83 _POSIX maximum values _POSIX_MEMLOCK_RANGE................17, 22, 399 84 in ........................................................251 _POSIX_MEMORY_PROTECTION 17, 19, 22, 399 85 _POSIX minimum values _POSIX_MESSAGE_PASSING ...............17, 22, 399 86 in ........................................................251 _POSIX_MONOTONIC_CLOCK...........17, 23, 399 87 _POSIX2_BC_BASE_MAX ...........................250, 254 _POSIX_MQ_OPEN_MAX ..........................246, 252 88 _POSIX2_BC_DIM_MAX .............................250, 254 _POSIX_MQ_PRIO_MAX ............................247, 252 89 _POSIX2_BC_SCALE_MAX ........................250, 254 _POSIX_NAME_MAX ..................................249, 252 90 _POSIX2_BC_STRING_MAX......................250, 254 _POSIX_NGROUPS_MAX...........................250, 252 91 _POSIX2_CHARCLASS_NAME_MAX.....250, 254 _POSIX_NO_TRUNC ...............................16, 98, 399 92 _POSIX2_CHAR_TERM .......................................402 _POSIX_OPEN_MAX....................................247, 252 93 _POSIX2_COLL_WEIGHTS_MAX ............250, 254 _POSIX_PATH_MAX ....................................249, 252 94 _POSIX2_C_BIND..................................................402 _POSIX_PIPE_BUF ........................................249, 252 95 _POSIX2_C_DEV....................................................402 _POSIX_PRIORITIZED_IO......................17, 22, 400 96 _POSIX2_EXPR_NEST_MAX......................250, 254 _POSIX_PRIORITY_SCHEDULING17, 22-23, 400 97 _POSIX2_FORT_DEV............................................402 _POSIX_PRIO_IO...................................................404 98 _POSIX2_FORT_RUN...........................................402 _POSIX_RAW_SOCKETS.......................................17 430 Technical Standard (2001) (Draft April 13, 2001) Index 99 _POSIX_READER_WRITER_LOCKS ................400 _POSIX_TRACE_INHERIT .....................18, 25, 401 100 _POSIX_REALTIME_SIGNALS..............17, 22, 400 _POSIX_TRACE_LOG ......................................18, 25 101 _POSIX_REGEXP ...................................................400 _POSIX_TRACE_NAME_MAX ..................248, 253 102 _POSIX_RE_DUP_MAX .......................................252 _POSIX_TRACE_SYS_MAX........................248, 253 103 _POSIX_RTSIG_MAX ...................................247, 252 _POSIX_TRACE_USER_EVENT_MAX ....248, 253 104 _POSIX_SAVED_IDS.......................................16, 400 _POSIX_TTY_NAME_MAX ........................248, 253 105 _POSIX_SEMAPHORES...........................17, 22, 400 _POSIX_TYPED_MEMORY_OBJECTS.18, 23, 402 106 _POSIX_SEM_NSEMS_MAX ......................247, 252 _POSIX_TZNAME_MAX.............................248, 254 107 _POSIX_SEM_VALUE_MAX.......................247, 252 _POSIX_VDISABLE.........................................16, 402 108 _POSIX_SHARED_MEMORY_OBJECTS............17 _POSIX_VERSION.................................................398 109 ..........................................................................22, 400 _SC constants 110 _POSIX_SHELL.......................................................400 defined in ........................................408 111 _POSIX_SIGQUEUE_MAX..........................247, 252 _V6_ILP32_OFF32..................................................403 112 _POSIX_SPAWN........................................17, 23, 400 _V6_ILP32_OFFBIG ...............................................403 113 _POSIX_SPIN_LOCKS..............................17, 24, 400 _V6_LP64_OFF64 ...................................................403 114 _POSIX_SPORADIC_SERVER................17, 23, 400 _V6_LPBIG_OFFBIG..............................................403 115 _POSIX_SSIZE_MAX ....................................253, 255 _XBS5_ILP32_OFF32..............................................403 116 _POSIX_SS_REPL_MAX...............................247, 253 _XBS5_ILP32_OFFBIG...........................................403 117 _POSIX_STREAM_MAX ..............................248, 253 _XBS5_LP64_OFF64...............................................403 118 _POSIX_SYMLINK_MAX ............................249, 253 _XBS5_LPBIG_OFFBIG .........................................403 119 _POSIX_SYMLOOP_MAX...........................248, 253 _XOPEN_CRYPT .......................................18, 21, 403 120 _POSIX_SYNCHRONIZED_IO..............17, 22, 400 _XOPEN_ENH_I18N.............................................403 121 _POSIX_SYNC_IO .................................................404 _XOPEN_IOV_MAX .....................................246, 254 122 _POSIX_THREADS .............................17, 19, 24, 401 _XOPEN_LEGACY ..............................18, 25-26, 403 123 _POSIX_THREAD_ATTR_STACKADDR...........17 _XOPEN_NAME_MAX................................249, 254 124 ..........................................................................19, 401 _XOPEN_PATH_MAX..................................249, 255 125 _POSIX_THREAD_ATTR_STACKSIZE ..............17 _XOPEN_REALTIME................................18, 22, 403 126 ..........................................................................19, 401 _XOPEN_REALTIME_THREADS ....18, 23-24, 403 127 _POSIX_THREAD_CPUTIME ................17, 24, 401 _XOPEN_SHM........................................................403 128 _POSIX_THREAD_DESTRUCTOR_........................ _XOPEN_STREAMS........................................25, 404 129 ITERATIONS...................................................247, 253 _XOPEN_UNIX...................................................18-19 130 _POSIX_THREAD_KEYS_MAX.................247, 253 _XOPEN_VERSION...............................................398 131 _POSIX_THREAD_PRIORITY_SCHEDULING .... ABDAY_....................................................................242 132 ..............................................................17, 23-24, 401 ABMON_..................................................................242 133 _POSIX_THREAD_PRIO_INHERIT ....................17 abortive release .........................................................33 134 ....................................................................23-24, 401 absolute pathname.............................................33, 98 135 _POSIX_THREAD_PRIO_PROTECT...................17 access mode ...............................................................33 136 ....................................................................23-24, 401 additional file access control mechanism............33 137 _POSIX_THREAD_PROCESS_SHARED............17 address space.............................................................33 138 ..........................................................................19, 401 ADV...............................................................................6 139 _POSIX_THREAD_SAFE_FUNCTIONS.............17 advanced realtime ....................................................23 140 ....................................................................19, 24, 401 ADVANCED REALTIME......................................307 141 _POSIX_THREAD_SPORADIC_SERVER ..........17 advanced realtime threads .....................................24 142 ..........................................................................24, 401 advisory information...............................................33 143 _POSIX_THREAD_THREADS_MAX........247, 253 affirmative response ................................................33 144 _POSIX_TIMEOUTS..................................18, 23, 401 AF_INET...................................................................353 145 _POSIX_TIMERS...........................................18, 22-24 AF_INET6 ................................................................353 146 _POSIX_TIMER_MAX ..................................248, 253 AIO ................................................................................6 147 _POSIX_TRACE .........................................18, 25, 401 AIO_ALLDONE .....................................................202 148 _POSIX_TRACE_EVENT_FILTER .........18, 25, 401 AIO_CANCELED...................................................202 149 _POSIX_TRACE_EVENT_NAME_MAX..248, 253 AIO_LISTIO_MAX.................................................246 Base Definitions, Issue 6 431 Index 150 AIO_MAX ................................................................246 basename....................................................................38 151 AIO_NOTCANCELED .........................................202 basic regular expression..................................38, 167 152 AIO_PRIO_DELTA_MAX.....................................246 batch access list .........................................................38 153 AI_CANONNAME................................................275 batch administrator..................................................38 154 AI_NUMERICHOST..............................................275 batch client .................................................................38 155 AI_PASSIVE.............................................................275 batch destination ......................................................39 156 alert..............................................................................34 batch destination identifier.....................................39 157 alert character............................................................34 batch directive...........................................................39 158 alias name...................................................................34 batch job......................................................................39 159 alignment....................................................................34 batch job attribute.....................................................39 160 alternate file access control mechanism ..............34 batch job identifier....................................................39 161 alternate signal stack................................................34 batch job name ..........................................................39 162 ALT_DIGITS............................................................242 batch job owner.........................................................40 163 AM_STR ...................................................................242 batch job priority ......................................................40 164 anchoring..................................................................171 batch job state............................................................40 165 ancillary data .............................................................35 batch name service...................................................40 166 angle brackets............................................................35 batch name space......................................................40 167 ANYMARK..............................................................334 batch node..................................................................40 168 API ...............................................................................35 batch operator ...........................................................40 169 application .................................................................35 batch queue................................................................40 170 application address ..................................................35 batch queue attribute...............................................41 171 application conformance ........................................28 batch queue position................................................41 172 application program interface ...............................35 batch queue priority.................................................41 173 appropriate privileges .............................................35 batch rerunability .....................................................41 174 AREGTYPE..............................................................376 batch restart ...............................................................41 175 argument ....................................................................35 batch server................................................................41 176 ARG_MAX...............................................................246 batch server name.....................................................41 177 arm (a timer)..............................................................36 batch service ..............................................................42 178 asterisk........................................................................36 batch service request................................................42 179 async-cancel-safe function......................................36 batch submission ......................................................42 180 async-signal-safe function ......................................36 batch system ..............................................................42 181 asynchronous events ...............................................36 batch target user .......................................................42 182 asynchronous I/O completion ..............................37 batch user ...................................................................42 183 asynchronous I/O operation .................................36 baud rate selection .................................................380 184 asynchronous input and output............................36 BC_BASE_MAX ......................................................250 185 asynchronously-generated signal .........................36 BC_DIM_MAX........................................................250 186 ATEXIT_MAX .........................................................246 BC_SCALE_MAX ...................................................250 187 attribute selection...................................................381 BC_STRING_MAX.................................................250 188 authentication............................................................37 BE ...................................................................................7 189 authorization .............................................................37 bind..............................................................................42 190 background job .........................................................37 blank character..........................................................42 191 background process .................................................37 blank line ....................................................................43 192 background process group.....................................37 blkcnt_t .....................................................................366 193 backquote ...................................................................37 blksize_t....................................................................366 194 BACKREF.................................................................175 BLKTYPE..................................................................376 195 backslash ....................................................................37 block special file........................................................43 196 backspace character .................................................37 block-mode terminal................................................43 197 bandinfo....................................................................331 blocked process (or thread) ....................................43 198 BAR................................................................................7 blocking ......................................................................43 199 barrier..........................................................................38 BOOT_TIME............................................................419 200 base character............................................................38 braces...........................................................................43 432 Technical Standard (2001) (Draft April 13, 2001) Index 201 brackets.......................................................................43 CLOCK_PROCESS_CPUTIME_ID.....................388 202 BRE (ERE) matching a single character .............166 CLOCK_REALTIME......................................251, 388 203 BRE (ERE) matching multiple characters..........166 clock_t .......................................................................366 204 BRKINT ....................................................................379 CLOCK_THREAD_CPUTIME_ID......................388 205 broadcast ....................................................................43 CMSG_DATA ..........................................................352 206 BSD ............................................................................212 CMSG_FIRSTHDR.................................................352 207 BSDLY .......................................................................380 CMSG_NXTHDR ...................................................352 208 BSn.............................................................................380 coded character set...................................................46 209 BUFSIZ......................................................................320 codeset ........................................................................46 210 built-in.........................................................................44 CODESET.................................................................242 211 built-in utility ............................................................44 collating element.......................................................46 212 BUS_ADRALN........................................................304 collation ......................................................................46 213 BUS_ADRERR.........................................................304 collation sequence ....................................................46 214 BUS_OBJERR...........................................................304 COLL_ELEM_MULTI............................................175 215 byte ..............................................................................44 COLL_ELEM_SINGLE..........................................175 216 byte input/output functions ..................................44 COLL_WEIGHTS_MAX .......................................250 217 can..................................................................................5 column position ........................................................47 218 canonical mode input processing .......................185 COLUMNS...............................................................161 219 carriage-return character.........................................44 command....................................................................47 220 CD ..................................................................................7 command language interpreter.............................47 221 character .....................................................................44 complex ....................................................................206 222 character array...........................................................45 composite graphic symbol......................................47 223 character class ...........................................................45 concurrent execution ...............................................95 224 character encoding .................................................114 condition variable.....................................................47 225 state-dependent ..................................................118 conformance........................................................15, 28 226 character set...............................................................45 POSIX......................................................................15 227 character special file.................................................45 POSIX system interfaces.....................................16 228 character string..........................................................45 XSI............................................................................15 229 CHARCLASS_NAME_MAX.......................250, 256 XSI system interfaces...........................................19 230 charmap conformance document...........................................15 231 description ...........................................................115 conforming application...........................................15 232 CHAR_BIT ...............................................................255 conforming implementation options ...................20 233 CHAR_MAX............................................................255 connection..................................................................48 234 CHAR_MIN.............................................................256 connection mode.......................................................48 235 child process ..............................................................45 connectionless mode................................................48 236 CHILD_MAX...........................................................246 control character .......................................................48 237 CHRTYPE ................................................................376 control modes..........................................................381 238 circumflex...................................................................45 control operator ........................................................48 239 CLD_CONTINUED ...............................................304 controlling process ...................................................48 240 CLD_DUMPED.......................................................304 controlling terminal .........................................48, 184 241 CLD_EXITED ..........................................................304 CONTTYPE .............................................................376 242 CLD_KILLED ..........................................................304 conversion descriptor ..............................................49 243 CLD_STOPPED.......................................................304 core file........................................................................49 244 CLD_TRAPPED......................................................304 CPT ................................................................................7 245 CLOCAL...................................................................381 CPU ...........................................................................365 246 clock.............................................................................45 CPU time ....................................................................49 247 clock jump..................................................................46 clock ........................................................................49 248 clock tick.....................................................................46 timer ........................................................................49 249 clockid_t ...................................................................366 CRDLY ......................................................................379 250 CLOCKS_PER_SEC ...............................366, 388-389 CREAD .....................................................................381 251 CLOCK_MONOTONIC .......................................389 CRn............................................................................379 Base Definitions, Issue 6 433 Index 252 CRNCYSTR .............................................................242 mbstate_t..............................................................421 253 CS ...................................................................................7 msglen_t ...............................................................341 254 CSIZE ........................................................................381 msgqnum_t..........................................................341 255 CSn.............................................................................381 nl_catd ..................................................................283 256 CSTOPB....................................................................381 nl_item..................................................................283 257 current job ..................................................................49 pid_t ......................................................................300 258 current working directory ................................49, 92 ptrdiff_t ................................................................312 259 cursor position ..........................................................49 regex_t ..................................................................292 260 CX...................................................................................7 regmatch_t ...........................................................292 261 C_ constants in .......................................209 regoff_t .................................................................292 262 C_IRGRP ..................................................................209 shmatt_t................................................................349 263 C_IROTH .................................................................209 sigset_t..................................................................300 264 C_IRUSR...................................................................209 sig_atomic_t ........................................................300 265 C_ISBLK ...................................................................209 size_t .....................................................................312 266 C_ISCHR ..................................................................209 speed_t..................................................................378 267 C_ISCTG...................................................................209 tcflag_t ..................................................................378 268 C_ISDIR....................................................................209 VISIT .....................................................................296 269 C_ISFIFO ..................................................................209 wchar_t.................................................................312 270 C_ISGID....................................................................209 wctrans_t..............................................................425 271 C_ISLNK ..................................................................209 wctype_t...............................................................421 272 C_ISREG...................................................................209 wint_t....................................................................421 273 C_ISSOCK................................................................209 data types 274 C_ISUID....................................................................209 defined in ............................................222 275 C_ISVTX...................................................................209 defined in ..................................366 276 C_IWGRP.................................................................209 DATEMSK................................................................161 277 C_IWOTH................................................................209 DAY_ .........................................................................242 278 C_IWUSR .................................................................209 DBL_ constants 279 C_IXGRP ..................................................................209 defined in ............................................226 280 C_IXOTH .................................................................209 DBL_DIG..........................................................226, 255 281 C_IXUSR...................................................................209 DBL_EPSILON........................................................227 282 data segment..............................................................50 DBL_MANT_DIG...................................................226 283 data structure DBL_MAX........................................................227, 255 284 dirent.....................................................................212 DBL_MAX_10_EXP................................................227 285 entry ......................................................................296 DBL_MAX_EXP......................................................227 286 group.....................................................................236 DBL_MIN.................................................................228 287 lconv......................................................................260 DBL_MIN_10_EXP.................................................227 288 msqid_ds..............................................................341 DBL_MIN_EXP .......................................................227 289 stat .........................................................................356 DBM...........................................................................272 290 tms.........................................................................365 DBM_INSERT .........................................................272 291 utimbuf.................................................................418 DBM_REPLACE .....................................................272 292 data type DEAD_PROCESS ...................................................419 293 ACTION...............................................................296 DECIMAL_DIG.......................................................226 294 cc_t.........................................................................378 deferred batch service..............................................50 295 DIR.........................................................................212 DELAYTIMER_MAX .............................................246 296 div_t ......................................................................324 device ..........................................................................50 297 ENTRY..................................................................296 output ...................................................................181 298 FILE .......................................................................321 device ID.....................................................................50 299 fpos_t ....................................................................321 dev_t..........................................................................366 300 glob_t ....................................................................234 DIR.............................................................................212 301 ldiv_t .....................................................................324 directory .....................................................................50 302 lldiv_t....................................................................324 directory entry (or link)...........................................50 434 Technical Standard (2001) (Draft April 13, 2001) Index 303 directory protection .................................................95 EFAULT ....................................................................215 304 directory stream........................................................50 EFBIG ........................................................................215 305 dirent structure .......................................................212 effective group ID.....................................................52 306 DIRTYPE ..................................................................376 effective user ID........................................................52 307 disarm (a timer).........................................................50 EHOSTUNREACH ................................................215 308 display.........................................................................50 EIDRM ......................................................................215 309 display line.................................................................51 eight-bit transparency..............................................52 310 documentation ..........................................................15 EILSEQ......................................................................215 311 dollar sign...................................................................51 EINPROGRESS .......................................................216 312 domain error............................................................103 EINTR .......................................................................216 313 dot................................................................................51 EINVAL ....................................................................216 314 dot-dot ........................................................................51 EIO.............................................................................216 315 double-quote..............................................................51 EISCONN.................................................................216 316 downshifting .............................................................51 EISDIR.......................................................................216 317 driver...........................................................................51 ELOOP......................................................................216 318 DUP_COUNT..........................................................175 EMFILE.....................................................................216 319 D_FMT ......................................................................242 EMLINK ...................................................................216 320 D_T_FMT .................................................................242 EMPTY......................................................................419 321 E2BIG ........................................................................215 empty directory.........................................................52 322 EACCES....................................................................215 empty line...................................................................52 323 EADDRINUSE ........................................................215 empty string (or null string)...................................52 324 EADDRNOTAVAIL................................................215 empty wide-character string..................................52 325 EAFNOSUPPORT ..................................................215 EMSGSIZE ...............................................................216 326 EAGAIN ...................................................................215 EMULTIHOP...........................................................216 327 EAI_AGAIN ............................................................276 ENAMETOOLONG...............................................216 328 EAI_BADFLAGS.....................................................276 encoding 329 EAI_FAIL..................................................................276 character...............................................................114 330 EAI_FAMILY ...........................................................276 encoding rule.............................................................52 331 EAI_MEMORY........................................................276 encryption ..................................................................21 332 EAI_NONAME.......................................................276 ENETDOWN...........................................................216 333 EAI_SERVICE..........................................................276 ENETUNREACH ...................................................216 334 EAI_SOCKTYPE.....................................................276 ENFILE .....................................................................216 335 EAI_SYSTEM...........................................................276 ENOBUFS.................................................................216 336 EALREADY .............................................................215 ENODATA ...............................................................216 337 EBADF ......................................................................215 ENODEV ..................................................................216 338 EBADMSG ...............................................................215 ENOENT ..................................................................216 339 EBUSY.......................................................................215 ENOEXEC ................................................................216 340 ECANCELED ..........................................................215 ENOLCK ..................................................................216 341 ECHILD....................................................................215 ENOLINK ................................................................216 342 ECHO........................................................................381 ENOMEM.................................................................216 343 ECHOE .....................................................................381 ENOMSG..................................................................216 344 ECHOK.....................................................................381 ENOPROTOOPT....................................................216 345 ECHONL..................................................................381 ENOSPC ...................................................................216 346 ECONNABORTED ................................................215 ENOSR......................................................................216 347 ECONNREFUSED..................................................215 ENOSTR ...................................................................216 348 ECONNRESET........................................................215 ENOSYS....................................................................216 349 EDEADLK................................................................215 ENOTCONN...........................................................216 350 EDESTADDRREQ ..................................................215 ENOTDIR.................................................................216 351 EDOM .......................................................................215 ENOTEMPTY..........................................................216 352 EDQUOT ..................................................................215 ENOTSOCK.............................................................216 353 EEXIST ......................................................................215 ENOTSUP ................................................................216 Base Definitions, Issue 6 435 Index 354 ENOTTY...................................................................217 FD_CLR ....................................................................345 355 entire regular expression ................................52, 165 FD_ISSET..................................................................345 356 environment variables FD_SET .....................................................................345 357 internationalization............................................158 fd_set.................................................................345, 362 358 ENXIO.......................................................................217 FD_SETSIZE ............................................................345 359 EOF............................................................................320 FD_ZERO .................................................................345 360 EOPNOTSUPP........................................................217 feature test macro.....................................................54 361 EOVERFLOW..........................................................217 fenv_t ........................................................................222 362 EPERM......................................................................217 fexcept_t ...................................................................222 363 EPIPE.........................................................................217 FE_ constants 364 epoch ...........................................................................53 defined in ............................................222 365 EPROTO ...................................................................217 FE_ALL_EXCEPT ...................................................222 366 EPROTONOSUPPORT .........................................217 FE_DFL_ENV ..........................................................223 367 EPROTOTYPE.........................................................217 FE_DIVBYZERO.....................................................222 368 equivalence class ......................................................53 FE_DOWNWARD..................................................222 369 era.................................................................................53 FE_INEXACT ..........................................................222 370 ERA............................................................................242 FE_INVALID ...........................................................222 371 ERANGE ..................................................................217 FE_OVERFLOW .....................................................222 372 ERA_D_FMT ...........................................................242 FE_TONEAREST ....................................................222 373 ERA_D_T_FMT.......................................................242 FE_TOWARDZERO...............................................222 374 ERA_T_FMT ............................................................242 FE_UNDERFLOW..................................................222 375 EROFS.......................................................................217 FE_UPWARD ..........................................................222 376 error conditions FFDLY .......................................................................380 377 mathematical functions ....................................103 FFn .............................................................................380 378 ESPIPE.......................................................................217 field..............................................................................54 379 ESRCH ......................................................................217 FIFO.............................................................................55 380 ESTALE.....................................................................217 FIFO special file ........................................................55 381 ETIME .......................................................................217 FIFOTYPE ................................................................376 382 ETIMEDOUT...........................................................217 file ................................................................................55 383 ETXTBSY ..................................................................217 FILE ...................................................................320, 421 384 event management...................................................53 file access permissions.............................................95 385 EWOULDBLOCK...................................................217 file characteristics 386 EXDEV ......................................................................217 data structure ......................................................358 387 executable file............................................................53 header ...................................................................358 388 execute ........................................................................53 file description...........................................................55 389 execution time.....................................................49, 54 file descriptor.............................................................55 390 measurement.........................................................97 file group class ..........................................................55 391 monitoring .............................................................54 file hierarchy..............................................................96 392 EXIT_FAILURE.......................................................324 file mode.....................................................................55 393 EXIT_SUCCESS ......................................................324 file mode bits .............................................................56 394 expand.........................................................................54 file offset .....................................................................56 395 EXPR_NEST_MAX.................................................250 file other class............................................................56 396 extended regular expression..........................54, 171 file owner class..........................................................56 397 extended security controls ...............................54, 95 file permission bits ...................................................56 398 extension file serial number......................................................57 399 CX ..............................................................................7 file system ..................................................................57 400 OH .............................................................................9 file times update .......................................................96 401 XSI............................................................................13 file type .......................................................................57 402 F-LOCK.....................................................................408 filename ......................................................................56 403 FD...................................................................................7 filename portability..................................................56 404 FD_CLOEXEC.........................................................219 FILENAME_MAX ..................................................320 436 Technical Standard (2001) (Draft April 13, 2001) Index 405 FILESIZEBITS..........................................................248 FTW_ constants 406 filter .............................................................................57 in .............................................................232 407 FIPS..............................................................................16 FTW_CHDIR...........................................................232 408 first open (of a file) ...................................................57 FTW_D......................................................................232 409 flow control................................................................57 FTW_DEPTH...........................................................232 410 FLT_ constants FTW_DNR ...............................................................232 411 defined in ............................................226 FTW_DP ...................................................................232 412 FLT_DIG...........................................................226, 255 FTW_F.......................................................................232 413 FLT_EPSILON.........................................................227 FTW_MOUNT ........................................................232 414 FLT_EVAL_METHOD...........................................225 FTW_NS ...................................................................232 415 FLT_MANT_DIG....................................................226 FTW_PHYS..............................................................232 416 FLT_MAX.........................................................227, 255 FTW_SL ....................................................................232 417 FLT_MAX_10_EXP.................................................227 FTW_SLN.................................................................232 418 FLT_MAX_EXP .......................................................227 F_DUPFD .................................................................219 419 FLT_MIN ..................................................................228 F_GETFD..................................................................219 420 FLT_MIN_10_EXP..................................................227 F_GETFL...................................................................219 421 FLT_MIN_EXP ........................................................227 F_GETLK..................................................................219 422 FLT_RADIX..............................................................226 F_GETOWN ............................................................219 423 FLT_ROUNDS.........................................................225 F_OK .........................................................................404 424 FLUSHR....................................................................333 F_RDLCK .................................................................219 425 FLUSHRW ...............................................................333 F_SETFD...................................................................219 426 FLUSHW ..................................................................333 F_SETFL....................................................................219 427 FMNAMESZ ....................................................332-333 F_SETLK...................................................................219 428 FNM_ constants F_SETLKW...............................................................219 429 in ....................................................231 F_SETOWN .............................................................219 430 FNM_NOESCAPE..................................................231 F_TEST......................................................................408 431 FNM_NOMATCH..................................................231 F_TLOCK .................................................................408 432 FNM_NOSYS ..........................................................231 F_ULOCK.................................................................408 433 FNM_PATHNAME................................................231 F_UNLCK.................................................................219 434 FNM_PERIOD.........................................................231 F_WRLCK ................................................................219 435 FOPEN_MAX..................................................248, 320 GETALL....................................................................347 436 foreground job...........................................................57 GETNCNT ...............................................................347 437 foreground process ..................................................57 GETPID.....................................................................347 438 foreground process group ......................................57 GETVAL ...................................................................347 439 foreground process group ID.................................58 GETZCNT................................................................347 440 form-feed character..................................................58 gid_t...........................................................................366 441 format of entries......................................................201 GLOB_ constants 442 FPE_FLTDIV............................................................304 defined in ............................................234 443 FPE_FLTINV............................................................304 GLOB_ABORTED ..................................................234 444 FPE_FLTOVF...........................................................304 GLOB_APPEND .....................................................234 445 FPE_FLTRES ............................................................304 GLOB_DOOFFS......................................................234 446 FPE_FLTSUB............................................................304 GLOB_ERR ..............................................................234 447 FPE_FLTUND..........................................................304 GLOB_MARK..........................................................234 448 FPE_INTDIV............................................................304 GLOB_NOCHECK.................................................234 449 FPE_INTOVF...........................................................304 GLOB_NOESCAPE................................................234 450 FR ...................................................................................7 GLOB_NOMATCH................................................234 451 fsblkcnt_t..................................................................366 GLOB_NOSORT.....................................................234 452 FSC.................................................................................8 GLOB_NOSPACE ..................................................234 453 fsfilcnt_t....................................................................366 GLOB_NOSYS.........................................................234 454 FTW...........................................................................232 grammar 455 locale .....................................................................149 Base Definitions, Issue 6 437 Index 456 regular expression..............................................175 Inf.................................................................................59 457 graphic character ......................................................58 INFINITY .................................................................263 458 group database..........................................................58 INIT_PROCESS.......................................................419 459 group ID .....................................................................58 INLCR.......................................................................379 460 group name................................................................58 ino_t...........................................................................366 461 hard limit....................................................................59 INPCK.......................................................................379 462 hard link......................................................................59 instrumented application........................................59 463 headers......................................................................201 interactive shell.........................................................59 464 HOME.......................................................................161 internationalization..................................................60 465 home directory..........................................................59 interprocess communication..................................60 466 host byte order ..........................................................59 INTMAX_MAX.......................................................317 467 HUGE_VAL .............................................................263 INTMAX_MIN........................................................317 468 HUGE_VALF...........................................................263 INTN_MAX .............................................................316 469 HUGE_VALL...........................................................263 INTN_MIN ..............................................................316 470 HUPCL .....................................................................381 INTPTR_MAX.........................................................316 471 I ..................................................................................206 INTPTR_MIN..........................................................316 472 ICANON ..................................................................381 INT_FASTN_MAX.................................................316 473 ICRNL.......................................................................379 INT_FASTN_MIN..................................................316 474 idtype_t.....................................................................372 INT_LEASTN_MAX..............................................316 475 id_t.............................................................................366 INT_LEASTN_MIN ...............................................316 476 IEXTEN.....................................................................381 INT_MAX.................................................................255 477 IGNBRK....................................................................379 INT_MIN..................................................................256 478 IGNCR ......................................................................379 invalid .......................................................................166 479 IGNPAR....................................................................379 invariant values ......................................................256 480 ILL_BADSTK...........................................................304 invoke..........................................................................60 481 ILL_COPROC..........................................................304 iovec ..........................................................................369 482 ILL_ILLADR............................................................304 IOV_MAX ........................................................246, 369 483 ILL_ILLOPC ............................................................304 IP6 ..................................................................................8 484 ILL_ILLOPN............................................................304 IPC .............................................................................336 485 ILL_ILLTRP..............................................................304 IPC_ constants 486 ILL_PRVOPC...........................................................304 defined in ......................................336 487 ILL_PRVREG...........................................................304 IPC_CREAT .............................................................336 488 imaginary .................................................................206 IPC_EXCL ................................................................336 489 implementation-defined ...........................................5 IPC_NOWAIT .........................................................336 490 IN6_IS_ADDR_LINKLOCAL..............................280 IPC_PRIVATE..........................................................336 491 IN6_IS_ADDR_LOOPBACK................................280 IPC_RMID................................................................336 492 IN6_IS_ADDR_MC_GLOBAL.............................280 IPC_SET....................................................................336 493 IN6_IS_ADDR_MC_LINKLOCAL.....................280 IPC_STAT .................................................................336 494 IN6_IS_ADDR_MC_NODELOCAL...................280 IPPROTO_ICMP.....................................................279 495 IN6_IS_ADDR_MC_ORGLOCAL......................280 IPPROTO_IP............................................................279 496 IN6_IS_ADDR_MC_SITELOCAL.......................280 IPPROTO_IPV6.......................................................279 497 IN6_IS_ADDR_MULTICAST...............................280 IPPROTO_RAW......................................................279 498 IN6_IS_ADDR_SITELOCAL................................280 IPPROTO_TCP........................................................279 499 IN6_IS_ADDR_UNSPECIFIED ...........................280 IPPROTO_UDP.......................................................279 500 IN6_IS_ADDR_V4COMPAT................................280 IPV6_JOIN_GROUP ..............................................279 501 IN6_IS_ADDR_V4MAPPED................................280 IPV6_LEAVE_GROUP...........................................279 502 INADDR_ANY .......................................................279 IPV6_MULTICAST_HOPS ...................................279 503 INADDR_BROADCAST.......................................279 IPV6_MULTICAST_IF...........................................280 504 incomplete line..........................................................59 IPV6_MULTICAST_LOOP...................................280 505 INET6_ADDRSTRLEN .........................................279 IPV6_UNICAST_HOPS ........................................280 506 INET_ADDRSTRLEN............................................279 ISIG............................................................................381 438 Technical Standard (2001) (Draft April 13, 2001) Index 507 ISOC standard.........................................................206 link ...............................................................................61 508 ISTRIP .......................................................................379 link count....................................................................61 509 itimerval ...................................................................362 LINK_MAX..............................................................249 510 ITIMER_PROF.........................................................362 LIO_NOP..................................................................202 511 ITIMER_REAL ........................................................362 LIO_NOWAIT.........................................................202 512 ITIMER_VIRTUAL.................................................362 LIO_READ ...............................................................202 513 IXANY ......................................................................379 LIO_WAIT................................................................202 514 IXOFF........................................................................379 LIO_WRITE .............................................................202 515 IXON .........................................................................379 LLONG_MAX .........................................................256 516 I_LOOK.....................................................................332 LLONG_MIN ..........................................................256 517 I_POP ........................................................................332 LNKTYPE.................................................................376 518 I_PUSH .....................................................................332 local customs .............................................................61 519 job.................................................................................60 local IPC......................................................................61 520 job control...................................................................60 local modes ..............................................................381 521 job control job ID ......................................................60 locale ...................................................................61, 119 522 key_t..........................................................................366 grammar...............................................................149 523 LANG........................................................................158 POSIX....................................................................120 524 last close (of a file) ....................................................61 locale definition ......................................................120 525 LASTMARK.............................................................334 localization.................................................................62 526 LC_ALL............................................................159, 260 login.............................................................................62 527 LC_COLLATE.........................................159, 250, 260 login name..................................................................62 528 description ...........................................................130 LOGIN_NAME_MAX...........................................246 529 LC_CTYPE ......................................159, 242, 260, 425 LOGIN_PROCESS..................................................419 530 description ...........................................................122 LOGNAME..............................................................162 531 LC_MESSAGES..............................159, 242, 260, 283 LOG_ALERT ...........................................................375 532 description ...........................................................148 LOG_AUTH.............................................................374 533 LC_MONETARY....................................159, 242, 260 LOG_CONS.............................................................374 534 description ...........................................................138 LOG_CRIT ...............................................................375 535 LC_NUMERIC........................................159, 242, 260 LOG_CRON ............................................................374 536 description ...........................................................141 LOG_DAEMON .....................................................374 537 LC_TIME..................................................159, 242, 260 LOG_DEBUG ..........................................................375 538 description ...........................................................142 LOG_EMERG ..........................................................375 539 LDBL_ constants LOG_ERR.................................................................375 540 defined in ............................................226 LOG_INFO...............................................................375 541 LDBL_DIG................................................................227 LOG_KERN .............................................................374 542 LDBL_EPSILON .....................................................228 LOG_LOCAL...........................................................374 543 LDBL_MANT_DIG ................................................226 LOG_LPR .................................................................374 544 LDBL_MAX .............................................................227 LOG_MAIL..............................................................374 545 LDBL_MAX_10_EXP .............................................227 LOG_MASK.............................................................374 546 LDBL_MAX_EXP....................................................227 LOG_NDELAY........................................................374 547 LDBL_MIN...............................................................228 LOG_NEWS.............................................................374 548 LDBL_MIN_10_EXP ..............................................227 LOG_NOTICE.........................................................375 549 LDBL_MIN_EXP.....................................................227 LOG_NOWAIT .......................................................374 550 legacy ......................................................................5, 25 LOG_ODELAY........................................................374 551 limit LOG_PID..................................................................374 552 numerical .............................................................255 LOG_USER ..............................................................374 553 line ...............................................................................61 LOG_UUCP .............................................................374 554 line control ...............................................................382 LOG_WARNING ...................................................375 555 LINES........................................................................161 LONG_BIT ...............................................................255 556 LINE_MAX ..............................................................250 LONG_MAX............................................................255 557 linger............................................................................61 LONG_MIN.............................................................256 Base Definitions, Issue 6 439 Index 558 lower multiplexing...................................................82 MM_HALT...............................................................229 559 L_ANCHOR ............................................................175 MM_HARD..............................................................229 560 L_ctermid .................................................................320 MM_INFO................................................................229 561 L_tmpnam................................................................320 MM_NOCON..........................................................230 562 MAGIC .....................................................................209 MM_NOMSG ..........................................................229 563 map..............................................................................62 MM_NOSEV............................................................229 564 MAP_FIXED ............................................................338 MM_NOTOK...........................................................229 565 MAP_PRIVATE .......................................................338 MM_NRECOV ........................................................229 566 MAP_SHARED.......................................................338 MM_NULLACT......................................................229 567 margin codes MM_NULLLBL.......................................................229 568 notation...................................................................14 MM_NULLMC........................................................229 569 marked message .......................................................62 MM_NULLSEV.......................................................229 570 matched..............................................................62, 165 MM_NULLTAG ......................................................229 571 mathematical functions MM_NULLTXT.......................................................229 572 domain error........................................................103 MM_OK....................................................................229 573 error conditions ..................................................103 MM_OPSYS .............................................................229 574 NaN arguments..................................................104 MM_PRINT .............................................................229 575 pole error..............................................................104 MM_RECOVER ......................................................229 576 range error ...........................................................104 MM_SOFT................................................................229 577 MAXARGS...............................................................310 MM_UTIL.................................................................229 578 MAXFLOAT.............................................................263 MM_WARNING.....................................................229 579 maximum values....................................................251 mode............................................................................63 580 MAX_CANON........................................................249 mode_t ......................................................................366 581 MAX_INPUT...........................................................249 MON..............................................................................9 582 may ................................................................................5 monotonic clock........................................................64 583 MB_CUR_MAX.......................................................324 MON_ .......................................................................242 584 MB_LEN_MAX .......................................................255 MORECTL................................................................334 585 MC1 ...............................................................................8 MOREDATA ............................................................334 586 MC2 ...............................................................................8 mount point ...............................................................64 587 MCL_CURRENT ....................................................338 MPR ...............................................................................9 588 MCL_FUTURE........................................................338 MQ_OPEN_MAX...................................................246 589 mcontext_t ...............................................................396 MQ_PRIO_MAX.....................................................247 590 memory mapped files..............................................62 MSG...............................................................................9 591 memory object...........................................................63 MSGVERB................................................................162 592 memory synchronization........................................98 MSG_ANY ...............................................................334 593 memory-resident ......................................................63 MSG_BAND ............................................................334 594 message.......................................................................63 MSG_CTRUNC.......................................................353 595 message catalog ........................................................63 MSG_DONTROUTE..............................................353 596 message catalog descriptor ....................................63 MSG_EOR ................................................................353 597 message queue ..........................................................63 MSG_HIPRI .............................................................334 598 META_CHAR..........................................................175 MSG_NOERROR....................................................341 599 MF ..................................................................................8 MSG_OOB................................................................353 600 minimum values.....................................................251 MSG_PEEK ..............................................................353 601 MINSIGSTKSZ........................................................302 MSG_TRUNC..........................................................353 602 ML..................................................................................8 MSG_WAITALL......................................................353 603 MLR ...............................................................................9 MS_ASYNC .............................................................338 604 MM_ macros............................................................229 MS_INVALIDATE ..................................................338 605 MM_APPL................................................................229 MS_SYNC ................................................................338 606 MM_CONSOLE......................................................229 multi-character collating element .........................64 607 MM_ERROR............................................................229 mutex ..........................................................................64 608 MM_FIRM................................................................229 MUXID_ALL ...........................................................334 440 Technical Standard (2001) (Draft April 13, 2001) Index 609 MX..................................................................................9 NUL.............................................................................66 610 M_ ..............................................................................262 NULL...............................312, 320, 324, 328, 388, 404 611 M_E............................................................................262 null byte......................................................................66 612 M_LN ........................................................................262 null pointer.................................................................66 613 M_LOG10E ..............................................................262 null string ...................................................................66 614 M_LOG2E.................................................................262 null wide-character code.........................................66 615 M_PI ..........................................................................262 number sign...............................................................66 616 M_SQRT1_2.............................................................263 numerical limits......................................................255 617 M_SQRT2 .................................................................263 NZERO .....................................................................257 618 name............................................................................64 OB...................................................................................9 619 named STREAM .......................................................64 object file.....................................................................66 620 NAME_MAX.............................................98, 212, 249 OCRNL.....................................................................379 621 NaN...........................................................................225 octet .............................................................................67 622 NAN..........................................................................263 OF...................................................................................9 623 NaN (Not a Number) ..............................................64 offset maximum........................................................67 624 NaN arguments off_t............................................................................366 625 mathematical functions ....................................104 OFILL ........................................................................379 626 native language.........................................................64 OH..................................................................................9 627 NCCS ........................................................................378 OLD_TIME...............................................................419 628 NDEBUG..................................................................205 ONLCR.....................................................................379 629 negative response.....................................................65 ONLRET...................................................................379 630 network.......................................................................65 ONOCR ....................................................................379 631 network address .......................................................65 opaque address .........................................................67 632 network byte order...................................................65 open file ......................................................................67 633 newline character......................................................65 open file description ................................................67 634 NEW_TIME .............................................................419 OPEN_MAX....................................................247, 298 635 NGROUPS_MAX ...................................................250 operand.......................................................................67 636 nice value....................................................................65 operator ......................................................................67 637 NI_DGRAM.............................................................276 OPOST ......................................................................379 638 NI_NAMEREQD ....................................................276 option ..........................................................................67 639 NI_NOFQDN..........................................................275 ADV...........................................................................6 640 NI_NUMERICHOST .............................................275 AIO ............................................................................6 641 NI_NUMERICSERV ..............................................276 BAR............................................................................7 642 NLDLY......................................................................379 BE ...............................................................................7 643 nlink_t .......................................................................366 CD..............................................................................7 644 NLn............................................................................379 CPT ............................................................................7 645 NLSPATH.................................................................159 CS...............................................................................7 646 NL_ARGMAX.........................................................256 FD...............................................................................7 647 NL_CAT_LOCALE.................................................283 FR...............................................................................7 648 NL_LANGMAX......................................................256 FSC.............................................................................8 649 NL_MSGMAX.........................................................257 IP6 ..............................................................................8 650 NL_NMAX...............................................................257 MC1 ...........................................................................8 651 NL_SETD..................................................................283 MC2 ...........................................................................8 652 NL_SETMAX...........................................................257 MF..............................................................................8 653 NL_TEXTMAX........................................................257 ML..............................................................................8 654 NOEXPR...................................................................242 MLR...........................................................................9 655 NOFLSH...................................................................381 MON .........................................................................9 656 non-blocking..............................................................65 MPR...........................................................................9 657 non-canonical mode input processing...............186 MSG...........................................................................9 658 non-spacing characters............................................66 MX .............................................................................9 659 NOSTR......................................................................242 PIO...........................................................................10 Base Definitions, Issue 6 441 Index 660 PS .............................................................................10 O_WRONLY............................................................220 661 RS.............................................................................10 page .............................................................................68 662 RTS ..........................................................................10 page size .....................................................................68 663 SD.............................................................................10 PAGESIZE................................................................247 664 SEM .........................................................................10 PAGE_SIZE..............................................................247 665 SHM ........................................................................10 parameter ...................................................................68 666 SIO ...........................................................................10 PARENB ...................................................................381 667 SPI............................................................................11 parent directory ........................................................68 668 SPN..........................................................................11 parent process ...........................................................69 669 SS..............................................................................11 parent process ID......................................................69 670 TCT..........................................................................11 PARMRK..................................................................379 671 TEF...........................................................................11 PARODD..................................................................381 672 THR .........................................................................11 PATH.........................................................................162 673 TMO ........................................................................11 path prefix..................................................................69 674 TMR.........................................................................12 pathname....................................................................69 675 TPI............................................................................12 pathname component..............................................69 676 TPP ..........................................................................12 pathname resolution................................................98 677 TPS...........................................................................12 PATH_MAX.....................................................249, 257 678 TRC..........................................................................12 pattern.........................................................................69 679 TRI ...........................................................................12 period ..........................................................................69 680 TRL ..........................................................................12 permissions................................................................70 681 TSA..........................................................................12 persistence..................................................................70 682 TSF...........................................................................13 pid_t ..........................................................................366 683 TSH..........................................................................13 PIO...............................................................................10 684 TSP...........................................................................13 pipe..............................................................................70 685 TSS...........................................................................13 PIPE_BUF .................................................................249 686 TYM.........................................................................13 PM_STR....................................................................242 687 UP ............................................................................13 pole error..................................................................104 688 XSR ..........................................................................14 POLLERR .................................................................284 689 option-argument.......................................................67 pollfd.........................................................................284 690 options POLLHUP ................................................................284 691 shell and utilities...................................................26 POLLIN ....................................................................284 692 system interfaces ..................................................26 polling .........................................................................70 693 ORD_CHAR ............................................................175 POLLNVAL .............................................................284 694 orientation..................................................................68 POLLOUT ................................................................284 695 orphaned process group .........................................68 POLLPRI...................................................................284 696 output devices.........................................................181 POLLRDBAND.......................................................284 697 O_ constants POLLRDNORM......................................................284 698 defined in ....................................219-220 POLLWRBAND......................................................284 699 O_ACCMODE.........................................................220 POLLWRNORM.....................................................284 700 O_APPEND .............................................................219 POLL_ERR ...............................................................304 701 O_CREAT .................................................................219 POLL_HUP..............................................................304 702 O_DSYNC ................................................................219 POLL_IN ..................................................................304 703 O_EXCL....................................................................219 POLL_MSG..............................................................304 704 O_NOCTTY.............................................................219 POLL_OUT ..............................................................304 705 O_NONBLOCK ......................................................219 POLL_PRI.................................................................304 706 O_RDONLY.............................................................220 portable character set ......................................70, 111 707 O_RDWR..................................................................220 portable filename character set .......................70, 96 708 O_RSYNC ................................................................220 positional parameter................................................70 709 O_SYNC ...................................................................220 POSIX 710 O_TRUNC................................................................219 conformance..........................................................15 442 Technical Standard (2001) (Draft April 13, 2001) Index 711 POSIX locale ............................................................120 PRIO_PROCESS......................................................343 712 POSIX shell and utilities..........................................18 PRIO_USER .............................................................343 713 POSIX system interfaces privilege......................................................................72 714 conformance..........................................................16 process ........................................................................72 715 POSIX2_CHAR_TERM .....................................18, 27 process group ............................................................72 716 POSIX2_C_DEV..................................................18, 26 process group ID.......................................................72 717 POSIX2_FORT_DEV..........................................18, 27 process group leader................................................72 718 POSIX2_FORT_RUN.........................................18, 27 process group lifetime.............................................73 719 POSIX2_LOCALEDEF.......................................18, 27 process groups 720 POSIX2_PBS ........................................................18, 27 termios..................................................................183 721 POSIX2_PBS_ACCOUNTING ........................18, 27 process ID...................................................................73 722 POSIX2_PBS_CHECKPOINT ................................27 process ID reuse........................................................99 723 POSIX2_PBS_LOCATE......................................18, 27 process lifetime .........................................................73 724 POSIX2_PBS_MESSAGE...................................18, 27 process memory locking .........................................73 725 POSIX2_PBS_TRACK........................................18, 27 process termination..................................................73 726 POSIX2_SW_DEV ..............................................18, 27 process virtual time..................................................74 727 POSIX2_UPE .......................................................18, 28 process-to-process communication......................74 728 POSIX_ALLOC_SIZE_MIN .................................249 program ......................................................................74 729 POSIX_FADV_DONTNEED................................220 protocol.......................................................................74 730 POSIX_FADV_NOREUSE ....................................220 PROT_EXEC ............................................................338 731 POSIX_FADV_NORMAL.....................................220 PROT_NONE..........................................................338 732 POSIX_FADV_RANDOM ....................................220 PROT_READ ...........................................................338 733 POSIX_FADV_SEQUENTIAL .............................220 PROT_READ constants 734 POSIX_FADV_WILLNEED..................................220 in ...............................................338 735 POSIX_MADV_DONTNEED ..............................339 PROT_WRITE .........................................................338 736 POSIX_MADV_NORMAL ...................................338 PS..................................................................................10 737 POSIX_MADV_RANDOM...................................339 pseudo-terminal........................................................74 738 POSIX_MADV_SEQUENTIAL............................339 PTHREAD_BARRIER_SERIAL_THREAD .......286 739 POSIX_MADV_WILLNEED ................................339 PTHREAD_CANCELED ......................................286 740 POSIX_REC_INCR_XFER_SIZE .........................249 PTHREAD_CANCEL_ASYNCHRONOUS .....286 741 POSIX_REC_MAX_XFER_SIZE..........................249 PTHREAD_CANCEL_DEFERRED ....................286 742 POSIX_REC_MIN_XFER_SIZE ...........................249 PTHREAD_CANCEL_DISABLE ........................286 743 POSIX_REC_XFER_ALIGN .................................249 PTHREAD_CANCEL_ENABLE .........................286 744 POSIX_TYPED_MEM_ALLOCATE ...................339 PTHREAD_COND_INITIALIZER .....................286 745 POSIX_TYPED_MEM_ALLOCATE_CONTIG....... PTHREAD_CREATE_DETACHED....................286 746 ................................................................................339 PTHREAD_CREATE_JOINABLE .......................286 747 POSIX_TYPED_MEM_MAP_ALLOCATABLE...... PTHREAD_DESTRUCTOR_ITERATIONS ......247 748 ................................................................................339 PTHREAD_EXPLICIT_SCHED...........................286 749 preallocation..............................................................71 PTHREAD_INHERIT_SCHED............................286 750 preempted process (or thread) ..............................71 PTHREAD_KEYS_MAX .......................................247 751 previous job ...............................................................71 PTHREAD_MUTEX_DEFAULT..........................286 752 printable character....................................................71 PTHREAD_MUTEX_ERRORCHECK ...............286 753 printable file...............................................................71 PTHREAD_MUTEX_INITIALIZER ...................286 754 priority ........................................................................71 PTHREAD_MUTEX_NORMAL .........................286 755 priority band..............................................................71 PTHREAD_MUTEX_RECURSIVE .....................286 756 priority inversion......................................................72 PTHREAD_ONCE_INIT ......................................286 757 priority scheduling...................................................72 PTHREAD_PRIO_INHERIT................................286 758 priority-based scheduling.......................................72 PTHREAD_PRIO_NONE.....................................286 759 PRIO_ constants PTHREAD_PRIO_PROTECT ..............................286 760 defined in ............................343 PTHREAD_PROCESS_PRIVATE........................286 761 PRIO_PGRP.............................................................343 PTHREAD_PROCESS_SHARED........................286 Base Definitions, Issue 6 443 Index 762 PTHREAD_RWLOCK_INITIALIZER ...............286 REG_ECTYPE..........................................................292 763 PTHREAD_SCOPE_PROCESS............................286 REG_EESCAPE .......................................................292 764 PTHREAD_SCOPE_SYSTEM..............................286 REG_ENOSYS.........................................................293 765 PTHREAD_STACK_MIN .....................................247 REG_EPAREN.........................................................292 766 PTHREAD_THREADS_MAX..............................247 REG_ERANGE........................................................293 767 PTRDIFF_MAX.......................................................317 REG_ESPACE..........................................................293 768 PTRDIFF_MIN ........................................................317 REG_ESUBREG.......................................................292 769 PWD ..........................................................................162 REG_EXTENDED...................................................292 770 P_ALL .......................................................................372 REG_ICASE .............................................................292 771 P_GID........................................................................372 REG_NEWLINE .....................................................292 772 P_PID ........................................................................372 REG_NOMATCH...................................................292 773 P_tmpdir...................................................................320 REG_NOSUB...........................................................292 774 quiet NaN.................................................................225 REG_NOTBOL........................................................292 775 QUOTED_CHAR ...................................................175 REG_NOTEOL........................................................292 776 radix character...........................................................74 relative pathname...............................................76, 98 777 RADIXCHAR ..........................................................242 relocatable file ...........................................................76 778 RAND_MAX ...........................................................324 relocation....................................................................76 779 range error................................................................104 requested batch service ...........................................76 780 result overflows..................................................104 requirements..............................................................15 781 result underflows ...............................................104 result overflows ......................................................104 782 read-only file system................................................74 result underflows ...................................................104 783 read-write lock ..........................................................74 RE_DUP_MAX................................................247, 250 784 real group ID..............................................................75 rlimit..........................................................................343 785 real time......................................................................75 RLIMIT_AS..............................................................344 786 real user ID.................................................................75 RLIMIT_CORE........................................................343 787 realtime.......................................................................22 RLIMIT_CPU...........................................................343 788 REALTIME ......................................202, 270, 294, 298 RLIMIT_DATA........................................................343 789 realtime signal extension ........................................75 RLIMIT_FSIZE ........................................................343 790 realtime threads ........................................................23 RLIMIT_NOFILE....................................................344 791 REALTIME THREADS ............................................24 RLIMIT_STACK......................................................344 792 record ..........................................................................75 RLIM_INFINITY.....................................................343 793 redirection ..................................................................75 RLIM_SAVED_CUR...............................................343 794 redirection operator .................................................75 RLIM_SAVED_MAX..............................................343 795 reentrant function.....................................................75 RMSGD.....................................................................333 796 referenced shared memory object.........................76 RMSGN.....................................................................333 797 refresh .........................................................................76 RNORM....................................................................333 798 region ..........................................................................76 root directory.............................................................77 799 REGTYPE .................................................................376 RPROTDAT..............................................................333 800 regular expression ....................................................76 RPROTDIS ...............................................................333 801 basic.......................................................................167 RPROTNORM.........................................................333 802 extended...............................................................171 RS .................................................................................10 803 grammar...............................................................175 RS_HIPRI .................................................................333 804 regular file ..................................................................76 RTLD_GLOBAL......................................................214 805 REG_ constants RTLD_LAZY............................................................214 806 defined in ..........................................292 RTLD_LOCAL ........................................................214 807 REG_BADBR ...........................................................292 RTLD_NOW............................................................214 808 REG_BADPAT.........................................................292 RTS...............................................................................10 809 REG_BADRPT.........................................................293 RTSIG_MAX....................................................247, 301 810 REG_EBRACE.........................................................292 runnable process (or thread) ..................................77 811 REG_EBRACK.........................................................292 running process (or thread)....................................77 812 REG_ECOLLATE....................................................292 444 Technical Standard (2001) (Draft April 13, 2001) Index 813 runtime values SETVAL ....................................................................347 814 increasable ...........................................................250 shall................................................................................5 815 invariant ...............................................................246 shared memory object .............................................79 816 rusage........................................................................343 shell..............................................................................79 817 RUSAGE_CHILDREN...........................................343 SHELL.......................................................................162 818 RUSAGE_SELF .......................................................343 shell script ..................................................................79 819 R_ANCHOR............................................................175 shell, the......................................................................79 820 R_OK.........................................................................404 SHM.............................................................................10 821 saved resource limits ...............................................77 SHMLBA ..................................................................349 822 saved set-group-ID...................................................77 SHM_RDONLY.......................................................349 823 saved set-user-ID......................................................77 SHM_RND...............................................................349 824 SA_ constants should............................................................................5 825 declared in .......................................302 SHRT_MAX.............................................................255 826 SA_NOCLDSTOP...................................................302 SHRT_MIN ..............................................................256 827 SA_NOCLDWAIT..................................................302 SHUT_RD.................................................................353 828 SA_NODEFER.........................................................302 SHUT_RDWR..........................................................354 829 SA_ONSTACK ........................................................302 SIGABRT ..................................................................301 830 SA_RESETHAND...................................................302 SIGALRM.................................................................301 831 SA_RESTART ..........................................................302 SIGBUS .............................................................301, 304 832 SA_SIGINFO ...........................................................302 SIGCHLD.........................................................301, 304 833 SCHAR_MAX .........................................................255 SIGCONT.................................................................301 834 SCHAR_MIN...........................................................256 SIGEV_NONE.........................................................300 835 scheduling..................................................................77 SIGEV_SIGNAL......................................................300 836 scheduling allocation domain................................78 SIGEV_THREAD....................................................300 837 scheduling contention scope..................................78 SIGFPE..............................................................301, 304 838 scheduling policy ...............................................78, 99 SIGHUP ....................................................................301 839 SCHED_FIFO ..........................................................294 SIGILL...............................................................301, 304 840 SCHED_OTHER.....................................................294 siginfo_t ....................................................................303 841 SCHED_RR..............................................................294 SIGINT......................................................................301 842 SCHED_SPORADIC ..............................................294 SIGKILL....................................................................301 843 SCM_RIGHTS .........................................................352 signal ...........................................................................79 844 screen...........................................................................78 signal stack.................................................................80 845 scroll ............................................................................78 signaling NaN .........................................................225 846 SD.................................................................................10 SIGPIPE ....................................................................301 847 seconds since the Epoch........................................100 SIGPOLL ..........................................................301, 304 848 SEEK_CUR ..............................................219, 320, 408 SIGPROF ..................................................................301 849 SEEK_END..............................................219, 320, 408 SIGQUEUE_MAX...................................................247 850 SEEK_SET................................................219, 320, 408 SIGQUIT...................................................................301 851 SEGV_ACCERR......................................................304 SIGRTMAX..............................................................300 852 SEGV_MAPERR .....................................................304 SIGRTMIN ...............................................................300 853 SEM..............................................................................10 SIGSEGV ..........................................................301, 304 854 semaphore..........................................................78, 100 SIGSTKSZ.................................................................302 855 semaphore lock operation ....................................100 SIGSTOP...................................................................301 856 semaphore unlock operation ...............................101 SIGSYS ......................................................................301 857 SEM_NSEMS_MAX ...............................................247 SIGTERM..................................................................301 858 SEM_UNDO ............................................................347 SIGTRAP..........................................................301, 304 859 SEM_VALUE_MAX ...............................................247 SIGTSTP ...................................................................301 860 session.........................................................................78 SIGTTIN ...................................................................301 861 session leader.............................................................79 SIGTTOU..................................................................301 862 session lifetime..........................................................79 SIGURG ....................................................................301 863 SETALL.....................................................................347 SIGUSR1...................................................................301 Base Definitions, Issue 6 445 Index 864 SIGUSR2...................................................................301 special parameter......................................................81 865 SIGVTALRM............................................................301 SPEC_CHAR ...........................................................175 866 SIGXCPU..................................................................301 SPI ................................................................................11 867 SIGXFSZ ...................................................................301 spin lock......................................................................81 868 SIG_ATOMIC_MAX ..............................................317 SPN..............................................................................11 869 SIG_ATOMIC_MIN ...............................................317 sporadic server..........................................................81 870 SIG_BLOCK.............................................................302 SS..................................................................................11 871 SIG_DFL ...................................................................300 SSIZE_MAX.....................................................255, 367 872 SIG_ERR ...................................................................300 ssize_t........................................................................366 873 SIG_HOLD...............................................................300 SS_DISABLE ............................................................302 874 SIG_IGN ...................................................................300 SS_ONSTACK .........................................................302 875 SIG_SETMASK........................................................302 SS_REPL_MAX .......................................................247 876 SIG_UNBLOCK ......................................................302 stack_t .......................................................................303 877 single-quote ...............................................................80 standard error............................................................81 878 SIO ...............................................................................10 standard input...........................................................81 879 SIZE_MAX ...............................................................317 standard output ........................................................81 880 size_t .................................................................328, 366 standard utilities.......................................................82 881 SI_ASYNCIO...........................................................304 stat data structure...................................................356 882 SI_MESGQ ...............................................................304 stderr .........................................................................320 883 SI_QUEUE................................................................304 STDERR_FILENO ..................................................411 884 SI_TIMER .................................................................304 stdin...........................................................................320 885 SI_USER....................................................................304 STDIN_FILENO......................................................411 886 slash.............................................................................80 stdout ........................................................................321 887 SNDZERO................................................................334 STDOUT_FILENO .................................................411 888 socket...........................................................................80 strbuf .........................................................................331 889 socket address ...........................................................80 STREAM.....................................................................82 890 SOCK_DGRAM ......................................................352 stream..........................................................................82 891 SOCK_RAW.............................................................352 STREAM...................................................................216 892 soft limit......................................................................80 STREAM end .............................................................82 893 SOL_SOCKET .........................................................352 STREAM head...........................................................82 894 SOMAXCONN .......................................................353 STREAMS...........................................................25, 331 895 source code ................................................................80 STREAMS multiplexor............................................82 896 SO_ACCEPTCONN ..............................................352 STREAM_MAX.......................................................248 897 SO_BROADCAST...................................................353 strfdinsert .................................................................331 898 SO_DEBUG..............................................................353 string............................................................................82 899 SO_DONTROUTE..................................................353 strioctl .......................................................................331 900 SO_ERROR ..............................................................353 strpeek.......................................................................331 901 SO_KEEPALIVE......................................................353 strrecvfd....................................................................331 902 SO_LINGER.............................................................353 str_list........................................................................331 903 SO_OOBINLINE.....................................................353 str_mlist....................................................................332 904 SO_RCVBUF............................................................353 ST_NOSUID ............................................................360 905 SO_RCVLOWAT.....................................................353 ST_RDONLY ...........................................................360 906 SO_RCVTIMEO......................................................353 subshell.......................................................................83 907 SO_REUSEADDR...................................................353 successfully transferred...........................................83 908 SO_SNDBUF............................................................353 supplementary group ID ........................................83 909 SO_SNDLOWAT ....................................................353 suseconds_t..............................................................366 910 SO_SNDTIMEO......................................................353 suspended job............................................................83 911 SO_TYPE ..................................................................353 symbolic link .............................................................83 912 space character..........................................................81 SYMLINK_MAX.............................................249, 257 913 spawn..........................................................................81 SYMLOOP_MAX....................................................248 914 special built-in...........................................................81 SYMTYPE.................................................................376 446 Technical Standard (2001) (Draft April 13, 2001) Index 915 synchronized I/O completion ...............................83 S_IWUSR..................................................................357 916 synchronized I/O data integrity completion .....84 S_IXGRP ...................................................................357 917 synchronized I/O file integrity completion........84 S_IXOTH ..................................................................357 918 synchronized I/O operation ..................................84 S_IXUSR ...................................................................357 919 synchronized input and output.............................83 S_MSG.......................................................................333 920 synchronous I/O operation....................................84 S_OUTPUT ..............................................................333 921 synchronously-generated signal ...........................84 S_RDBAND .............................................................333 922 system .........................................................................84 S_RDNORM ............................................................333 923 system console ..........................................................85 S_TYPEISMQ...........................................................358 924 system crash ..............................................................85 S_TYPEISSEM .........................................................358 925 system databases ......................................................85 S_TYPEISSHM ........................................................358 926 system documentation ............................................85 S_TYPEISTMO........................................................358 927 system process ..........................................................85 S_WRBAND ............................................................333 928 system reboot ............................................................86 S_WRNORM ...........................................................333 929 system trace event....................................................86 tab character ..............................................................86 930 system-wide...............................................................86 TABDLY....................................................................379 931 S_ constants TABn..........................................................................379 932 defined in .............................356-357 TCIFLUSH ...............................................................382 933 S_ macros TCIOFF .....................................................................382 934 defined in .....................................357 TCIOFLUSH ............................................................382 935 S_BANDURG ..........................................................333 TCION ......................................................................382 936 S_ERROR..................................................................333 TCOFLUSH..............................................................382 937 S_HANGUP.............................................................333 TCOOFF ...................................................................382 938 S_HIPRI ....................................................................333 TCOON ....................................................................382 939 S_IFBLK ....................................................................356 TCP_NODELAY .....................................................282 940 S_IFCHR...................................................................357 TCSADRAIN...........................................................381 941 S_IFDIR.....................................................................357 TCSAFLUSH ...........................................................381 942 S_IFIFO .....................................................................357 TCSANOW ..............................................................381 943 S_IFLNK ...................................................................357 TCT ..............................................................................11 944 S_IFMT......................................................................356 TEF...............................................................................11 945 S_IFREG....................................................................357 TERM ........................................................................162 946 S_IFSOCK.................................................................357 terminal 947 S_INPUT...................................................................333 controlling............................................................184 948 S_IRGRP ...................................................................357 terminal (or terminal device) .................................86 949 S_IROTH ..................................................................357 terminal types..........................................................181 950 S_IRUSR ...................................................................357 termios ......................................................................183 951 S_IRWXG .................................................................357 canonical mode input processing ...................185 952 S_IRWXO .................................................................357 control modes......................................................192 953 S_IRWXU .................................................................357 controlling terminal ...........................................184 954 S_ISBLK ....................................................................357 input modes.........................................................189 955 S_ISCHR...................................................................357 local modes..........................................................193 956 S_ISDIR.....................................................................358 non-canonical mode input processing...........186 957 S_ISFIFO...................................................................358 output modes......................................................190 958 S_ISGID.............................................................357-358 process groups....................................................183 959 S_ISLNK ...................................................................358 special control characters .................................194 960 S_ISREG....................................................................358 text column ................................................................86 961 S_ISSOCK.................................................................358 text file ........................................................................86 962 S_ISUID.............................................................357-358 TGEXEC....................................................................376 963 S_ISVTX....................................................................357 TGREAD...................................................................376 964 S_IWGRP..................................................................357 TGWRITE.................................................................376 965 S_IWOTH.................................................................357 THOUSEP ................................................................242 Base Definitions, Issue 6 447 Index 966 THR .............................................................................11 TRAP_TRACE.........................................................304 967 thread ..........................................................................87 TRC..............................................................................12 968 thread ID.....................................................................87 TRI ...............................................................................12 969 thread list....................................................................87 TRL ..............................................................................12 970 thread-safe..................................................................87 TSA ..............................................................................12 971 thread-safety............................................................101 TSF ...............................................................................13 972 thread-specific data key ..........................................87 TSGID........................................................................376 973 tilde..............................................................................87 TSH..............................................................................13 974 timeb..........................................................................364 TSP...............................................................................13 975 timeouts......................................................................88 TSS ...............................................................................13 976 timer ............................................................................88 TSUID........................................................................376 977 timer overrun.............................................................88 TSVTX.......................................................................376 978 TIMER_ABSTIME...................................................388 TTY_NAME_MAX.................................................248 979 TIMER_MAX...........................................................248 TUEXEC....................................................................376 980 timer_t.......................................................................366 TUREAD...................................................................376 981 timeval..............................................................345, 362 TUWRITE.................................................................376 982 time_t ........................................................................366 TVERSION...............................................................376 983 TMAGIC...................................................................376 TVERSLEN...............................................................376 984 TMAGLEN...............................................................376 TYM.............................................................................13 985 TMO ............................................................................11 typed memory name space ....................................90 986 TMPDIR....................................................................162 typed memory object ...............................................90 987 TMP_MAX ...............................................................320 typed memory pool..................................................90 988 TMR.............................................................................12 typed memory port ..................................................90 989 TOEXEC ...................................................................376 TZ...............................................................................162 990 token............................................................................88 TZNAME_MAX......................................................248 991 TOREAD...................................................................376 T_FMT.......................................................................242 992 TOSTOP....................................................................381 T_FMT_AMPM.......................................................242 993 TOWRITE.................................................................376 t_uscalar_t................................................................331 994 TPI................................................................................12 UCHAR_MAX ........................................................255 995 TPP...............................................................................12 ucontext_t.................................................................396 996 TPS...............................................................................12 uid_t ..........................................................................366 997 trace analyzer process..............................................88 UINTMAX_MAX....................................................317 998 trace controller process ...........................................88 UINTN_MAX..........................................................316 999 trace event..................................................................88 UINTPTR_MAX......................................................317 1000 trace event type.........................................................88 UINT_FASTN_MAX..............................................316 1001 trace event type mapping .......................................88 UINT_LEASTN_MAX...........................................316 1002 trace filter ...................................................................89 UINT_MAX .............................................................255 1003 trace generation version..........................................89 ULLONG_MAX......................................................256 1004 trace log ......................................................................89 ULONG_MAX ........................................................256 1005 trace point ..................................................................89 UL_GETFSIZE.........................................................397 1006 trace stream................................................................89 UL_SETFSIZE..........................................................397 1007 trace stream identifier..............................................89 unbind.........................................................................90 1008 trace system ...............................................................89 undefined .....................................................................6 1009 traced process............................................................89 unspecified...................................................................6 1010 TRACE_EVENT_NAME_MAX...........................248 UP.................................................................................13 1011 TRACE_NAME_MAX...........................................248 upper multiplexing ..................................................82 1012 TRACE_SYS_MAX.................................................248 upshifting ...................................................................90 1013 TRACE_USER_EVENT_MAX .............................248 user database.............................................................90 1014 tracing .................................................................25, 101 user ID.........................................................................91 1015 tracing status of a trace stream..............................89 user name ...................................................................91 1016 TRAP_BRKPT..........................................................304 user trace event .........................................................91 448 Technical Standard (2001) (Draft April 13, 2001) Index 1017 USER_PROCESS.....................................................419 WRDE_NOCMD ....................................................427 1018 USHRT_MAX..........................................................256 WRDE_NOSPACE .................................................427 1019 utility...................................................................91, 105 WRDE_NOSYS .......................................................427 1020 Utility Syntax Guidelines......................................199 WRDE_REUSE ........................................................427 1021 utmpx........................................................................419 WRDE_SHOWERR................................................427 1022 variable .......................................................................91 WRDE_SYNTAX.....................................................427 1023 variable assignment ...............................................105 WRDE_UNDEF.......................................................427 1024 VEOF .........................................................................378 write.............................................................................93 1025 VEOL.........................................................................378 WSTOPPED .............................................................372 1026 VERASE....................................................................378 WSTOPSIG ......................................................324, 372 1027 vertical-tab character ...............................................91 WTERMSIG.....................................................324, 372 1028 VFS.............................................................................360 WUNTRACED................................................324, 372 1029 VINTR.......................................................................378 W_OK........................................................................404 1030 VKILL........................................................................378 XSI..........................................................................13, 93 1031 VQUIT.......................................................................378 conformance..........................................................15 1032 VSTART ....................................................................378 XSI conformance.......................................................19 1033 VSTOP.......................................................................378 XSI options groups...................................................21 1034 VSUSP .......................................................................378 XSI STREAMS ...........................................................25 1035 VTDLY ......................................................................380 XSI system interfaces 1036 VTn ............................................................................380 conformance..........................................................19 1037 warning XSI-conformant.........................................................93 1038 OB ..............................................................................9 XSR ..............................................................................14 1039 OF...............................................................................9 X_OK.........................................................................404 1040 WCHAR_MAX ...............................................317, 423 YESEXPR..................................................................242 1041 WCHAR_MIN ................................................317, 423 YESSTR.....................................................................242 1042 WCONTINUED......................................................372 zombie process..........................................................93 1043 WEOF .......................................................421, 423, 425 1044 WEXITED.................................................................372 1045 WEXITSTATUS ...............................................324, 372 1046 white space ................................................................92 1047 wide characters .......................................................115 1048 wide-character code (C language) ........................92 1049 wide-character input/output functions...............92 1050 wide-character string...............................................92 1051 WIFCONTINUED ..................................................372 1052 WIFEXITED.....................................................324, 372 1053 WIFSIGNALED ..............................................324, 372 1054 WIFSTOPPED .................................................324, 372 1055 WINT_MAX ............................................................317 1056 WINT_MIN..............................................................317 1057 WNOHANG ...................................................324, 372 1058 WNOWAIT..............................................................372 1059 word ............................................................................92 1060 WORD_BIT ......................................................255-256 1061 working directory.....................................................92 1062 worldwide portability interface ............................92 1063 WRDE_APPEND....................................................427 1064 WRDE_BADCHAR................................................427 1065 WRDE_BADVAL....................................................427 1066 WRDE_CMDSUB ...................................................427 1067 WRDE_DOOFFS.....................................................427 Base Definitions, Issue 6 449 Index 1068 450 Technical Standard (2001) (Draft April 13, 2001) ||||||||||| 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 Change History | 12 Change history is described in the Rationale (Informative) volume of IEEE Std 1003.1-200x, and | 13 in the CHANGE HISTORY section of reference pages. | 14 1.5 Terminology 15 This section appears in the Base Definitions volume of IEEE Std 1003.1-200x, but is repeated here 16 for convenience: 17 For the purposes of IEEE Std 1003.1-200x, the following terminology definitions apply: 18 can 19 Describes a permissible optional feature or behavior available to the user or application. The 20 feature or behavior is mandatory for an implementation that conforms to 21 IEEE Std 1003.1-200x. An application can rely on the existence of the feature or behavior. 22 implementation-defined 23 Describes a value or behavior that is not defined by IEEE Std 1003.1-200x but is selected by 24 an implementor. The value or behavior may vary among implementations that conform to 25 IEEE Std 1003.1-200x. An application should not rely on the existence of the value or 26 behavior. An application that relies on such a value or behavior cannot be assured to be 27 portable across conforming implementations. 28 The implementor shall document such a value or behavior so that it can be used correctly 29 by an application. 30 legacy 31 Describes a feature or behavior that is being retained for compatibility with older 32 applications, but which has limitations which make it inappropriate for developing portable System Interfaces, Issue 6 451 Terminology Introduction 33 applications. New applications should use alternative means of obtaining equivalent 34 functionality. 35 may 36 Describes a feature or behavior that is optional for an implementation that conforms to 37 IEEE Std 1003.1-200x. An application should not rely on the existence of the feature or 38 behavior. An application that relies on such a feature or behavior cannot be assured to be 39 portable across conforming implementations. 40 To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. 41 shall 42 For an implementation that conforms to IEEE Std 1003.1-200x, describes a feature or 43 behavior that is mandatory. An application can rely on the existence of the feature or 44 behavior. 45 For an application or user, describes a behavior that is mandatory. 46 should 47 For an implementation that conforms to IEEE Std 1003.1-200x, describes a feature or 48 behavior that is recommended but not mandatory. An application should not rely on the 49 existence of the feature or behavior. An application that relies on such a feature or behavior 50 cannot be assured to be portable across conforming implementations. 51 For an application, describes a feature or behavior that is recommended programming 52 practice for optimum portability. 53 undefined 54 Describes the nature of a value or behavior not defined by IEEE Std 1003.1-200x which 55 results from use of an invalid program construct or invalid data input. 56 The value or behavior may vary among implementations that conform to 57 IEEE Std 1003.1-200x. An application should not rely on the existence or validity of the 58 value or behavior. An application that relies on any particular value or behavior cannot be 59 assured to be portable across conforming implementations. 60 unspecified 61 Describes the nature of a value or behavior not specified by IEEE Std 1003.1-200x which 62 results from use of a valid program construct or valid data input. 63 The value or behavior may vary among implementations that conform to 64 IEEE Std 1003.1-200x. An application should not rely on the existence or validity of the 65 value or behavior. An application that relies on any particular value or behavior cannot be 66 assured to be portable across conforming implementations. 452 Technical Standard (2001) (Draft April 16, 2001) Introduction Definitions 67 1.6 Definitions 68 Concepts and definitions are defined in the Base Definitions volume of IEEE Std 1003.1-200x. 69 1.7 Relationship to Other Formal Standards 70 Great care has been taken to ensure that this volume of IEEE Std 1003.1-200x is fully aligned 71 with the following standards: 72 ISO C (1999) 73 ISO/IEC 9899: 1999, Programming Languages - C. 74 Parts of the ISO/IEC 9899: 1999 standard (hereinafter referred to as the ISO C standard) are 75 referenced to describe requirements also mandated by this volume of IEEE Std 1003.1-200x. 76 Some functions and headers included within this volume of IEEE Std 1003.1-200x have a version 77 in the ISO C standard; in this case CX markings are added as appropriate to show where the | 78 ISO C standard has been extended (see Section 1.8.1). Any conflict between this volume of | 79 IEEE Std 1003.1-200x and the ISO C standard is unintentional. | 80 This volume of IEEE Std 1003.1-200x also allows, but does not require, mathematics functions to 81 support IEEE Std 754-1985 and IEEE Std 854-1987. 82 1.8 Portability 83 Some of the utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x and functions in 84 the System Interfaces volume of IEEE Std 1003.1-200x describe functionality that might not be 85 fully portable to systems meeting the requirements for POSIX conformance (see the Base 86 Definitions volume of IEEE Std 1003.1-200x, Chapter 2, Conformance). 87 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in 88 the margin identifies the nature of the option, extension, or warning (see Section 1.8.1). For 89 maximum portability, an application should avoid such functionality. 90 1.8.1 Codes 91 Margin codes and their meanings are listed in the Base Definitions volume of 92 IEEE Std 1003.1-200x, but are repeated here for convenience: 93 ADV Advisory Information 94 The functionality described is optional. The functionality described is also an extension to the 95 ISO C standard. 96 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. 97 Where additional semantics apply to a function, the material is identified by use of the ADV 98 margin legend. 99 AIO Asynchronous Input and Output 100 The functionality described is optional. The functionality described is also an extension to the 101 ISO C standard. 102 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. 103 Where additional semantics apply to a function, the material is identified by use of the AIO 104 margin legend. 105 BAR Barriers 106 The functionality described is optional. The functionality described is also an extension to the System Interfaces, Issue 6 453 Portability Introduction 107 ISO C standard. 108 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. 109 Where additional semantics apply to a function, the material is identified by use of the BAR 110 margin legend. 111 BE Batch Environment Services and Utilities 112 The functionality described is optional. 113 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. 114 Where additional semantics apply to a utility, the material is identified by use of the BE margin 115 legend. 116 CD C-Language Development Utilities 117 The functionality described is optional. 118 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. 119 Where additional semantics apply to a utility, the material is identified by use of the CD margin 120 legend. 121 CPT Process CPU-Time Clocks 122 The functionality described is optional. The functionality described is also an extension to the 123 ISO C standard. 124 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. 125 Where additional semantics apply to a function, the material is identified by use of the CPT 126 margin legend. 127 CS Clock Selection 128 The functionality described is optional. The functionality described is also an extension to the 129 ISO C standard. 130 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. 131 Where additional semantics apply to a function, the material is identified by use of the CS 132 margin legend. 133 CX Extension to the ISO C standard 134 The functionality described is an extension to the ISO C standard. Application writers may make 135 use of an extension as it is supported on all IEEE Std 1003.1-200x-conforming systems. 136 With each function or header from the ISO C standard, a statement to the effect that ``any 137 conflict is unintentional'' is included. That is intended to refer to a direct conflict. 138 IEEE Std 1003.1-200x acts in part as a profile of the ISO C standard, and it may choose to further 139 constrain behaviors allowed to vary by the ISO C standard. Such limitations are not considered 140 conflicts. 141 FD FORTRAN Development Utilities 142 The functionality described is optional. 143 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. 144 Where additional semantics apply to a utility, the material is identified by use of the FD margin 145 legend. 146 FR FORTRAN Runtime Utilities 147 The functionality described is optional. 148 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. 149 Where additional semantics apply to a utility, the material is identified by use of the FR margin 150 legend. 454 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 151 FSC File Synchronization 152 The functionality described is optional. The functionality described is also an extension to the 153 ISO C standard. 154 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. 155 Where additional semantics apply to a function, the material is identified by use of the FSC 156 margin legend. 157 IP6 IPV6 158 The functionality described is optional. The functionality described is also an extension to the 159 ISO C standard. 160 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. 161 Where additional semantics apply to a function, the material is identified by use of the IP6 162 margin legend. | 163 MC1 Advisory Information and either Memory Mapped Files or Shared Memory Objects 164 The functionality described is optional. The functionality described is also an extension to the 165 ISO C standard. 166 This is a shorthand notation for combinations of multiple option codes. 167 Where applicable, functions are marked with the MC1 margin legend in the SYNOPSIS section. 168 Where additional semantics apply to a function, the material is identified by use of the MC1 169 margin legend. 170 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, Section 1.5.2, Margin Code 171 Notation. 172 MC2 Memory Mapped Files, Shared Memory Objects, or Memory Protection 173 The functionality described is optional. The functionality described is also an extension to the 174 ISO C standard. 175 This is a shorthand notation for combinations of multiple option codes. 176 Where applicable, functions are marked with the MC2 margin legend in the SYNOPSIS section. 177 Where additional semantics apply to a function, the material is identified by use of the MC2 178 margin legend. 179 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, Section 1.5.2, Margin Code 180 Notation. 181 MF Memory Mapped Files 182 The functionality described is optional. The functionality described is also an extension to the 183 ISO C standard. 184 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. 185 Where additional semantics apply to a function, the material is identified by use of the MF 186 margin legend. 187 ML Process Memory Locking 188 The functionality described is optional. The functionality described is also an extension to the 189 ISO C standard. 190 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. 191 Where additional semantics apply to a function, the material is identified by use of the ML 192 margin legend. 193 MLR Range Memory Locking 194 The functionality described is optional. The functionality described is also an extension to the System Interfaces, Issue 6 455 Portability Introduction 195 ISO C standard. 196 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. 197 Where additional semantics apply to a function, the material is identified by use of the MLR 198 margin legend. 199 MON Monotonic Clock 200 The functionality described is optional. The functionality described is also an extension to the 201 ISO C standard. 202 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. 203 Where additional semantics apply to a function, the material is identified by use of the MON 204 margin legend. 205 MPR Memory Protection 206 The functionality described is optional. The functionality described is also an extension to the 207 ISO C standard. 208 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. 209 Where additional semantics apply to a function, the material is identified by use of the MPR 210 margin legend. 211 MSG Message Passing 212 The functionality described is optional. The functionality described is also an extension to the 213 ISO C standard. 214 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. 215 Where additional semantics apply to a function, the material is identified by use of the MSG 216 margin legend. 217 MX IEC 60559 Floating-Point Option 218 The functionality described is optional. The functionality described is also an extension to the 219 ISO C standard. 220 Where applicable, functions are marked with the MX margin legend in the SYNOPSIS section. 221 Where additional semantics apply to a function, the material is identified by use of the MX 222 margin legend. 223 OB Obsolescent 224 The functionality described may be withdrawn in a future version of this volume of 225 IEEE Std 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI 226 Applications shall not use obsolescent features. 227 OF Output Format Incompletely Specified 228 The functionality described is an XSI extension. The format of the output produced by the utility 229 is not fully specified. It is therefore not possible to post-process this output in a consistent 230 fashion. Typical problems include unknown length of strings and unspecified field delimiters. 231 OH Optional Header 232 In the SYNOPSIS section of some interfaces in the System Interfaces volume of 233 IEEE Std 1003.1-200x an included header is marked as in the following example: 234 OH #include 235 #include 236 struct group *getgrnam(const char *name); 237 This indicates that the marked header is not required on XSI-conformant systems. 456 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 238 PIO Prioritized Input and Output 239 The functionality described is optional. The functionality described is also an extension to the 240 ISO C standard. 241 Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. 242 Where additional semantics apply to a function, the material is identified by use of the PIO 243 margin legend. 244 PS Process Scheduling 245 The functionality described is optional. The functionality described is also an extension to the 246 ISO C standard. 247 Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. 248 Where additional semantics apply to a function, the material is identified by use of the PS 249 margin legend. 250 RS Raw Sockets 251 The functionality described is optional. The functionality described is also an extension to the 252 ISO C standard. 253 Where applicable, functions are marked with the RS margin legend in the SYNOPSIS section. 254 Where additional semantics apply to a function, the material is identified by use of the RS 255 margin legend. 256 RTS Realtime Signals Extension 257 The functionality described is optional. The functionality described is also an extension to the 258 ISO C standard. 259 Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. 260 Where additional semantics apply to a function, the material is identified by use of the RTS 261 margin legend. 262 SD Software Development Utilities 263 The functionality described is optional. 264 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. 265 Where additional semantics apply to a utility, the material is identified by use of the SD margin 266 legend. 267 SEM Semaphores 268 The functionality described is optional. The functionality described is also an extension to the 269 ISO C standard. 270 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. 271 Where additional semantics apply to a function, the material is identified by use of the SEM 272 margin legend. 273 SHM Shared Memory Objects 274 The functionality described is optional. The functionality described is also an extension to the 275 ISO C standard. 276 Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. 277 Where additional semantics apply to a function, the material is identified by use of the SHM 278 margin legend. 279 SIO Synchronized Input and Output 280 The functionality described is optional. The functionality described is also an extension to the 281 ISO C standard. System Interfaces, Issue 6 457 Portability Introduction 282 Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. 283 Where additional semantics apply to a function, the material is identified by use of the SIO 284 margin legend. 285 SPI Spin Locks 286 The functionality described is optional. The functionality described is also an extension to the 287 ISO C standard. 288 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. 289 Where additional semantics apply to a function, the material is identified by use of the SPI 290 margin legend. 291 SPN Spawn 292 The functionality described is optional. The functionality described is also an extension to the 293 ISO C standard. 294 Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. 295 Where additional semantics apply to a function, the material is identified by use of the SPN 296 margin legend. 297 SS Process Sporadic Server 298 The functionality described is optional. The functionality described is also an extension to the 299 ISO C standard. 300 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. 301 Where additional semantics apply to a function, the material is identified by use of the SS 302 margin legend. 303 TCT Thread CPU-Time Clocks 304 The functionality described is optional. The functionality described is also an extension to the 305 ISO C standard. 306 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. 307 Where additional semantics apply to a function, the material is identified by use of the TCT 308 margin legend. 309 TEF Trace Event Filter 310 The functionality described is optional. The functionality described is also an extension to the 311 ISO C standard. 312 Where applicable, functions are marked with the TEF margin legend in the SYNOPSIS section. 313 Where additional semantics apply to a function, the material is identified by use of the TEF 314 margin legend. 315 THR Threads 316 The functionality described is optional. The functionality described is also an extension to the 317 ISO C standard. 318 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. 319 Where additional semantics apply to a function, the material is identified by use of the THR 320 margin legend. 321 TMO Timeouts 322 The functionality described is optional. The functionality described is also an extension to the 323 ISO C standard. 324 Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. 325 Where additional semantics apply to a function, the material is identified by use of the TMO 326 margin legend. 458 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 327 TMR Timers 328 The functionality described is optional. The functionality described is also an extension to the 329 ISO C standard. 330 Where applicable, functions are marked with the TMR margin legend in the SYNOPSIS section. 331 Where additional semantics apply to a function, the material is identified by use of the TMR 332 margin legend. 333 TPI Thread Priority Inheritance 334 The functionality described is optional. The functionality described is also an extension to the 335 ISO C standard. 336 Where applicable, functions are marked with the TPI margin legend in the SYNOPSIS section. 337 Where additional semantics apply to a function, the material is identified by use of the TPI 338 margin legend. 339 TPP Thread Priority Protection 340 The functionality described is optional. The functionality described is also an extension to the 341 ISO C standard. 342 Where applicable, functions are marked with the TPP margin legend in the SYNOPSIS section. 343 Where additional semantics apply to a function, the material is identified by use of the TPP 344 margin legend. 345 TPS Thread Execution Scheduling 346 The functionality described is optional. The functionality described is also an extension to the 347 ISO C standard. 348 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. 349 Where additional semantics apply to a function, the material is identified by use of the TPS 350 margin legend. 351 TRC Trace 352 The functionality described is optional. The functionality described is also an extension to the 353 ISO C standard. 354 Where applicable, functions are marked with the TRC margin legend in the SYNOPSIS section. 355 Where additional semantics apply to a function, the material is identified by use of the TRC 356 margin legend. 357 TRI Trace Inherit 358 The functionality described is optional. The functionality described is also an extension to the 359 ISO C standard. 360 Where applicable, functions are marked with the TRI margin legend in the SYNOPSIS section. 361 Where additional semantics apply to a function, the material is identified by use of the TRI 362 margin legend. 363 TRL Trace Log 364 The functionality described is optional. The functionality described is also an extension to the 365 ISO C standard. 366 Where applicable, functions are marked with the TRL margin legend in the SYNOPSIS section. 367 Where additional semantics apply to a function, the material is identified by use of the TRL 368 margin legend. 369 TSA Thread Stack Address Attribute 370 The functionality described is optional. The functionality described is also an extension to the 371 ISO C standard. System Interfaces, Issue 6 459 Portability Introduction 372 Where applicable, functions are marked with the TSA margin legend for the SYNOPSIS section. 373 Where additional semantics apply to a function, the material is identified by use of the TSA 374 margin legend. 375 TSF Thread-Safe Functions 376 The functionality described is optional. The functionality described is also an extension to the 377 ISO C standard. 378 Where applicable, functions are marked with the TSF margin legend in the SYNOPSIS section. 379 Where additional semantics apply to a function, the material is identified by use of the TSF 380 margin legend. 381 TSH Thread Process-Shared Synchronization 382 The functionality described is optional. The functionality described is also an extension to the 383 ISO C standard. 384 Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. 385 Where additional semantics apply to a function, the material is identified by use of the TSH 386 margin legend. 387 TSP Thread Sporadic Server 388 The functionality described is optional. The functionality described is also an extension to the 389 ISO C standard. 390 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. 391 Where additional semantics apply to a function, the material is identified by use of the TSP 392 margin legend. 393 TSS Thread Stack Address Size 394 The functionality described is optional. The functionality described is also an extension to the 395 ISO C standard. 396 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. 397 Where additional semantics apply to a function, the material is identified by use of the TSS 398 margin legend. 399 TYM Typed Memory Objects 400 The functionality described is optional. The functionality described is also an extension to the 401 ISO C standard. 402 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. 403 Where additional semantics apply to a function, the material is identified by use of the TYM 404 margin legend. | 405 UP User Portability Utilities 406 The functionality described is optional. 407 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. 408 Where additional semantics apply to a utility, the material is identified by use of the UP margin 409 legend. 410 XSI Extension 411 The functionality described is an XSI extension. Functionality marked XSI is also an extension to 412 the ISO C standard. Application writers may confidently make use of an extension on all 413 systems supporting the X/Open System Interfaces Extension. 414 If an entire SYNOPSIS section is shaded and marked XSI, all the functionality described in that 415 reference page is an extension. See the Base Definitions volume of IEEE Std 1003.1-200x, Section 416 3.439, XSI. 460 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 417 XSR XSI STREAMS 418 The functionality described is optional. The functionality described is also an extension to the 419 ISO C standard. 420 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. 421 Where additional semantics apply to a function, the material is identified by use of the XSR 422 margin legend. 423 1.9 Format of Entries 424 The entries in Chapter 3 are based on a common format as follows. The only sections relating to 425 conformance are the SYNOPSIS, DESCRIPTION, RETURN VALUE, and ERRORS sections. 426 NAME 427 This section gives the name or names of the entry and briefly states its purpose. 428 SYNOPSIS 429 This section summarizes the use of the entry being described. If it is necessary to 430 include a header to use this function, the names of such headers are shown, for 431 example: 432 #include 433 DESCRIPTION 434 This section describes the functionality of the function or header. 435 RETURN VALUE 436 This section indicates the possible return values, if any. 437 If the implementation can detect errors, ``successful completion'' means that no error 438 has been detected during execution of the function. If the implementation does detect 439 an error, the error is indicated. 440 For functions where no errors are defined, ``successful completion'' means that if the 441 implementation checks for errors, no error has been detected. If the implementation can 442 detect errors, and an error is detected, the indicated return value is returned and errno 443 may be set. 444 ERRORS 445 This section gives the symbolic names of the error values returned by a function or 446 stored into a variable accessed through the symbol errno if an error occurs. 447 ``No errors are defined'' means that error values returned by a function or stored into a 448 variable accessed through the symbol errno, if any, depend on the implementation. 449 EXAMPLES 450 This section is non-normative. 451 This section gives examples of usage, where appropriate. In the event of conflict 452 between an example and a normative part of this volume of IEEE Std 1003.1-200x, the 453 normative material is to be taken as correct. 454 APPLICATION USAGE 455 This section is non-normative. 456 This section gives warnings and advice to application writers about the entry. In the 457 event of conflict between warnings and advice and a normative part of this volume of 458 IEEE Std 1003.1-200x, the normative material is to be taken as correct. System Interfaces, Issue 6 461 Format of Entries Introduction 459 RATIONALE 460 This section is non-normative. 461 This section contains historical information concerning the contents of this volume of 462 IEEE Std 1003.1-200x and why features were included or discarded by the standard 463 developers. 464 FUTURE DIRECTIONS 465 This section is non-normative. 466 This section provides comments which should be used as a guide to current thinking; 467 there is not necessarily a commitment to adopt these future directions. 468 SEE ALSO 469 This section is non-normative. 470 This section gives references to related information. 471 CHANGE HISTORY 472 This section is non-normative. 473 This section shows the derivation of the entry and any significant changes that have 474 been made to it. | 462 Technical Standard (2001) (Draft April 16, 2001) Chapter 2 General Information 475 476 This chapter covers information that is relevant to all the functions specified in Chapter 3 and 477 the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers. 478 2.1 Use and Implementation of Functions 479 Each of the following statements shall apply unless explicitly stated otherwise in the detailed 480 descriptions that follow: 481 1. If an argument to a function has an invalid value (such as a value outside the domain of 482 the function, or a pointer outside the address space of the program, or a null pointer), the 483 behavior is undefined. 484 2. Any function declared in a header may also be implemented as a macro defined in the 485 header, so a function should not be declared explicitly if its header is included. Any macro 486 definition of a function can be suppressed locally by enclosing the name of the function in 487 parentheses, because the name is then not followed by the left parenthesis that indicates 488 expansion of a macro function name. For the same syntactic reason, it is permitted to take 489 the address of a function even if it is also defined as a macro. The use of the C-language 490 #undef construct to remove any such macro definition shall also ensure that an actual 491 function is referred to. 492 3. Any invocation of a function that is implemented as a macro shall expand to code that 493 evaluates each of its arguments exactly once, fully protected by parentheses where 494 necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those 495 function-like macros described in the following sections may be invoked in an expression 496 anywhere a function with a compatible return type could be called. 497 4. Provided that a function can be declared without reference to any type defined in a header, 498 it is also permissible to declare the function, either explicitly or implicitly, and use it 499 without including its associated header. 500 5. If a function that accepts a variable number of arguments is not declared (explicitly or by 501 including its associated header), the behavior is undefined. 502 2.2 The Compilation Environment 503 2.2.1 POSIX.1 Symbols 504 Certain symbols in this volume of IEEE Std 1003.1-200x are defined in headers (see the Base 505 Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers). Some of those headers could 506 also define symbols other than those defined by IEEE Std 1003.1-200x, potentially conflicting | 507 with symbols used by the application. Also, IEEE Std 1003.1-200x defines symbols that are not | 508 permitted by other standards to appear in those headers without some control on the visibility | 509 of those symbols. 510 Symbols called ``feature test macros'' are used to control the visibility of symbols that might be 511 included in a header. Implementations, future versions of IEEE Std 1003.1-200x, and other | 512 standards may define additional feature test macros. | System Interfaces, Issue 6 463 The Compilation Environment General Information 513 In the compilation of an application that #defines a feature test macro specified by 514 IEEE Std 1003.1-200x, no header defined by IEEE Std 1003.1-200x shall be included prior to the 515 definition of the feature test macro. This restriction also applies to any implementation- 516 provided header in which these feature test macros are used. If the definition of the macro does 517 not precede the #include, the result is undefined. 518 Feature test macros shall begin with the underscore character ('_'). 519 2.2.1.1 The _POSIX_C_SOURCE Feature Test Macro 520 A POSIX-conforming application should ensure that the feature test macro _POSIX_C_SOURCE 521 is defined before inclusion of any header. 522 When an application includes a header described by IEEE Std 1003.1-200x, and when this feature | 523 test macro is defined to have the value 200xxxL: | 524 1. All symbols required by IEEE Std 1003.1-200x to appear when the header is included shall | 525 be made visible. 526 2. Symbols that are explicitly permitted, but not required, by IEEE Std 1003.1-200x to appear | 527 in that header (including those in reserved name spaces) may be made visible. 528 3. Additional symbols not required or explicitly permitted by IEEE Std 1003.1-200x to be in | 529 that header shall not be made visible, except when enabled by another feature test macro. | 530 Identifiers in IEEE Std 1003.1-200x may only be undefined using the #undef directive as | 531 described in Section 2.1 (on page 463) or Section 2.2.2. These #undef directives shall follow all 532 #include directives of any header in IEEE Std 1003.1-200x. | 533 Note: The POSIX.1-1990 standard specified a macro called _POSIX_SOURCE. This has been | 534 superseded by _POSIX_C_SOURCE. | 535 2.2.1.2 The _XOPEN_SOURCE Feature Test Macro 536 XSI An XSI-conforming application should ensure that the feature test macro _XOPEN_SOURCE is 537 defined with the value 600 before inclusion of any header. This is needed to enable the 538 functionality described in Section 2.2.1.1 and in addition to enable the X/Open System Interfaces 539 Extension. 540 Since this volume of IEEE Std 1003.1-200x is aligned with the ISO C standard, and since all 541 functionality enabled by _POSIX_C_SOURCE set equal to 200xxxL is enabled by | 542 _XOPEN_SOURCE set equal to 600, there should be no need to define _POSIX_C_SOURCE if | 543 _XOPEN_SOURCE is so defined. Therefore, if _XOPEN_SOURCE is set equal to 600 and | 544 _POSIX_C_SOURCE is set equal to 200xxxL, the behavior is the same as if only | 545 _XOPEN_SOURCE is defined and set equal to 600. However, should _POSIX_C_SOURCE be set | 546 to a value greater than 200xxxL, the behavior is unspecified. | 547 2.2.2 The Name Space 548 All identifiers in this volume of IEEE Std 1003.1-200x, except environ, are defined in at least one 549 of the headers, as shown in the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 13, 550 XSI Headers. When _XOPEN_SOURCE or _POSIX_C_SOURCE is defined, each header defines or 551 declares some identifiers, potentially conflicting with identifiers used by the application. The set 552 of identifiers visible to the application consists of precisely those identifiers from the header 553 pages of the included headers, as well as additional identifiers reserved for the implementation. 554 In addition, some headers may make visible identifiers from other headers as indicated on the 555 relevant header pages. 464 Technical Standard (2001) (Draft April 16, 2001) General Information The Compilation Environment 556 Implementations may also add members to a structure or union without controlling the 557 visibility of those members with a feature test macro, as long as a user-defined macro with the 558 same name cannot interfere with the correct interpretation of the program. The identifiers 559 reserved for use by the implementation are described below: 560 1. Each identifier with external linkage described in the header section is reserved for use as 561 an identifier with external linkage if the header is included. 562 2. Each macro described in the header section is reserved for any use if the header is 563 included. 564 3. Each identifier with file scope described in the header section is reserved for use as an 565 identifier with file scope in the same name space if the header is included. 566 The prefixes posix_, POSIX_, and _POSIX_ are reserved for use by IEEE Std 1003.1-200x and 567 other POSIX standards. Implementations may add symbols to the headers shown in the 568 following table, provided the identifiers for those symbols begin with the corresponding 569 reserved prefixes in the following table, and do not use the reserved prefixes posix_, POSIX_, or 570 _POSIX_. System Interfaces, Issue 6 465 The Compilation Environment General Information 571 ______________________________________________________________________________________ 572 Complete 573 _ Header Prefix Suffix Name _____________________________________________________________________________________ 574 AIO aio_, lio_, AIO_, LIO_ 575 in_, inet_ 576 to[a-z], is[a-z] 577 d_ 578 E[0-9], E[A-Z] 579 l_ 580 gl_ 581 gr_ 582 int[0-9a-z_]*_t, | 583 uint[0-9a-z_]*_t 584 _MAX, _MIN 585 LC_[A-Z] 586 MSG mq_, MQ_ 587 XSI dbm_ 588 h_, n_, p_, s_ 589 if_ 590 in_, ip_, s_, sin_ 591 IP6 in6_, s6_, sin6_ | 592 XSI pd_, ph_, ps_ | 593 pthread_, PTHREAD_ 594 pw_ 595 re_, rm_ 596 PS sched_, SCHED_ | 597 SEM sem_, SEM_ 598 sa_, uc_, SIG[A-Z], SIG_[A-Z] 599 XSI ss_, sv_ 600 RTS si_, SI_, sigev_, SIGEV_, sival_ 601 XSI bi_, ic_, l_, sl_, str_ 602 int[0-9a-z_]*_t, 603 uint[0-9a-z_]*_t 604 str[a-z] 605 str[a-z], mem[a-z], wcs[a-z] 606 XSI ipc_ key, pad, seq 607 MF shm_, MAP_, MCL_, MS_, PROT_ 608 XSI msg msg 609 XSI rlim_, ru_ 610 fd_, fds_, FD_ | 611 XSI sem sem | 612 XSI shm 613 ss_, sa_, if_, ifc_, ifru_, infu_, ifra_, | 614 msg_, cmsg_, l_ | 615 st_ 616 XSI f_ 617 fds_, it_, tv_, FD_ 618 _ tms_ _____________________________________________________________________________________ | 466 Technical Standard (2001) (Draft April 16, 2001) General Information The Compilation Environment 619 ______________________________________________________________________________________ 620 Complete 621 _ Header Prefix Suffix Name _____________________________________________________________________________________ 622 XSI iov_ UIO_MAXIOV | 623 sun_ | 624 uts_ | 625 XSI si_, W[A-Z], P_ | 626 c_ | 627 tm_ 628 TMR clock_, timer_, it_, tv_, 629 TMR CLOCK_, TIMER_ 630 XSI uc_, ss_ 631 XSI UL_ | 632 utim_ | 633 XSI ut_ _LVL, _TIME, 634 _PROCESS 635 wcs[a-z] 636 is[a-z], to[a-z] 637 we_ 638 _ ANY header POSIX_, _POSIX_, posix_ _t _____________________________________________________________________________________ 639 Note: The notation [A-Z] indicates any uppercase letter in the portable character set. The notation 640 [a-z] indicates any lowercase letter in the portable character set. Commas and spaces in the 641 lists of prefixes and complete names in the above table are not part of any prefix or complete 642 name. 643 If any header in the following table is included, macros with the prefixes shown may be defined. 644 After the last inclusion of a given header, an application may use identifiers with the 645 corresponding prefixes for its own purpose, provided their use is preceded by a #undef of the 646 corresponding macro. System Interfaces, Issue 6 467 The Compilation Environment General Information 647 _____________________________________________________________________________________ 648 _ Header Prefix ____________________________________________________________________________________ 649 XSI RTLD_ | 650 F_, O_, S_ | 651 XSI MM_ 652 FNM_ 653 XSI FTW 654 GLOB_ 655 PRI[a-z], SCN[a-z] 656 XSI DBM_ 657 IF_ 658 IMPLINK_, IN_, INADDR_, IP_, IPPORT_, IPPROTO_, SOCK_ 659 IP6 IPV6_, IN6_ | 660 TCP_ | 661 XSI NL_ 662 XSI POLL 663 REG_ 664 SA_, SIG_[0-9a-z_], 665 XSI BUS_, CLD_, FPE_, ILL_, POLL_, SEGV_, SI_, SS_, SV_, TRAP_ 666 stdint.h INT[0-9A-Z_]_MIN, INT[0-9A-Z_]_MAX, INT[0-9A-Z_]_C 667 UINT[0-9A-Z_]_MIN, UINT[0-9A-Z_]_MAX, UINT[0-9A-Z_]_C 668 XSI FLUSH[A-Z], I_, M_, MUXID_R[A-Z], S_, SND[A-Z], STR 669 XSI LOG_ 670 XSI IPC_ 671 XSI PROT_, MAP_, MS_ 672 XSI MSG[A-Z] 673 XSI PRIO_, RLIM_, RLIMIT_, RUSAGE_ 674 XSI SEM_ 675 XSI SHM[A-Z], SHM_[A-Z] 676 XSI AF_, CMSG_, MSG_, PF_, SCM_, SHUT_, SO 677 S_ 678 XSI ST_ 679 XSI FD_, ITIMER_ 680 XSI IOV_ 681 XSI BUS_, CLD_, FPE_, ILL_, POLL_, SEGV_, SI_, TRAP_ 682 V, I, O, TC, B[0-9] (See below.) 683 _ WRDE_ ____________________________________________________________________________________ 684 Note: The notation [0-9] indicates any digit. The notation [A-Z] indicates any uppercase letter in the 685 portable character set. The notation [0-9a-z_] indicates any digit, any lowercase letter in the 686 portable character set, or underscore. 687 The following reserved names are used as exact matches for : 688 XSI CBAUD EXTB VDSUSP 689 DEFECHO FLUSHO VLNEXT 690 ECHOCTL LOBLK VREPRINT 691 ECHOKE PENDIN VSTATUS 692 ECHOPRT SWTCH VWERASE 693 EXTA VDISCARD 468 Technical Standard (2001) (Draft April 16, 2001) General Information The Compilation Environment 694 The following identifiers are reserved regardless of the inclusion of headers: 695 1. All identifiers that begin with an underscore and either an uppercase letter or another 696 underscore are always reserved for any use by the implementation. 697 2. All identifiers that begin with an underscore are always reserved for use as identifiers with 698 file scope in both the ordinary identifier and tag name spaces. 699 3. All identifiers in the table below are reserved for use as identifiers with external linkage. 700 Some of these identifiers do not appear in this volume of IEEE Std 1003.1-200x, but are 701 reserved for future use by the ISO C standard. 702 _Exit cexp fesetexceptflag localtime scalbn 703 abort cexpf fesetround log scalbnf 704 abs cexpl fetestexcept log10 scalbnl 705 acos cimag feupdateenv log10f scanf 706 acosf cimagf fflush log10l setbuf 707 acosh cimagl fgetc log1p setjmp 708 acoshf clearerr fgetpos log1pf setlocale 709 acoshl clock fgets log1pl setvbuf 710 acosl clog fgetwc log2 signal 711 acosl clogf fgetws log2f sin 712 asctime clogl floor log2l sinf 713 asin conj floorf logb sinh 714 asinf conjf floorl logbf sinhf 715 asinh conjl fma logbl sinhl 716 asinhf copysign fmaf logf sinl 717 asinhl copysignf fmal logl sprintf 718 asinl copysignl fmax longjmp sqrt 719 asinl cos fmaxf lrint sqrtf 720 atan cosf fmaxl lrintf sqrtl 721 atan2 cosh fmin lrintl srand 722 atan2f coshf fminf lround sscanf 723 atan2l coshl fminl lroundf str[a-z]* 724 atanf cosl fmod lroundl strtof 725 atanf cpow fmodf malloc strtoimax 726 atanh cpowf fmodl mblen strtold 727 atanh cpowl fopen mbrlen strtoll 728 atanhf cproj fprintf mbrtowc strtoull 729 atanhl cprojf fputc mbsinit strtoumax 730 atanl cprojl fputs mbsrtowcs swprintf 731 atanl creal fputwc mbstowcs swscanf 732 atexit crealf fputws mbtowc system 733 atof creall fread mem[a-z]* tan 734 atoi csin free mktime tanf 735 atol csinf freopen modf tanh 736 atoll csinh frexp modff tanhf 737 bsearch csinhf frexpf modfl tanhl 738 cabs csinhl frexpl nan tanl 739 cabsf csinl fscanf nanf tgamma 740 cabsl csqrt fseek nanl tgammaf 741 cacos csqrtf fsetpos nearbyint tgammal System Interfaces, Issue 6 469 The Compilation Environment General Information 742 cacosf csqrtl ftell nearbyintf time 743 cacosh ctan fwide nearbyintl tmpfile 744 cacoshf ctanf fwprintf nextafterf tmpnam 745 cacoshl ctanl fwrite nextafterl to[a-z]* 746 cacosl ctime fwscanf nexttoward trunc 747 calloc difftime getc nexttowardf truncf 748 carg div getchar nexttowardl truncl 749 cargf erfcf getenv perror ungetc 750 cargl erfcl gets pow ungetwc 751 casin erff getwc powf va_end 752 casinf erfl getwchar powl vfprintf 753 casinh errno gmtime printf vfscanf 754 casinhf exit hypotf putc vfwprintf 755 casinhl exp hypotl putchar vfwscanf 756 casinl exp2 ilogb puts vprintf 757 catan exp2f ilogbf putwc vscanf 758 catanf exp2l ilogbl putwchar vsprintf 759 catanh expf imaxabs qsort vsscanf 760 catanh expl imaxdiv raise vswprintf 761 catanhf expm1 is[a-z]* rand vswscanf 762 catanhf expm1f isblank realloc vwprintf 763 catanhl expm1l iswblank remainderf vwscanf 764 catanhl fabs labs remainderl wcrtomb 765 catanl fabsf ldexp remove wcs[a-z]* 766 cbrt fabsl ldexpf remquo wcstof 767 cbrtf fclose ldexpl remquof wcstoimax 768 cbrtl fdim ldiv remquol wcstold 769 ccos fdimf ldiv rename wcstoll 770 ccosf fdiml lgammaf rewind wcstoull 771 ccosh feclearexcept lgammal rint wcstoumax 772 ccoshf fegetenv llabs rintf wctob 773 ccoshl fegetexceptflag llrint rintl wctomb 774 ccosl fegetround llrintf round wctrans 775 ceil feholdexcept llrintl roundf wctype 776 ceilf feof llround roundl wcwidth 777 ceilf feraiseexcept llroundf scalbln wmem[a-z]* 778 ceill ferror llroundl scalblnf wprintf 779 ceill fesetenv localeconv scalblnl wscanf 780 Note: The notation [a-z] indicates any lowercase letter in the portable character set. The 781 notation '*' indicates any combination of digits, letters in the portable character set, or 782 underscore. 783 4. All functions and external identifiers defined in the Base Definitions volume of 784 IEEE Std 1003.1-200x, Chapter 13, Headers are reserved for use as identifiers with external 785 linkage. 786 5. All the identifiers defined in this volume of IEEE Std 1003.1-200x that have external linkage 787 are always reserved for use as identifiers with external linkage. 788 No other identifiers are reserved. 789 Applications shall not declare or define identifiers with the same name as an identifier reserved 790 in the same context. Since macro names are replaced whenever found, independent of scope and 791 name space, macro names matching any of the reserved identifier names shall not be defined by 470 Technical Standard (2001) (Draft April 16, 2001) General Information The Compilation Environment 792 an application if any associated header is included. 793 Except that the effect of each inclusion of depends on the definition of NDEBUG, 794 headers may be included in any order, and each may be included more than once in a given 795 scope, with no difference in effect from that of being included only once. 796 If used, the application shall ensure that a header is included outside of any external declaration 797 or definition, and it shall be first included before the first reference to any type or macro it 798 defines, or to any function or object it declares. However, if an identifier is declared or defined in 799 more than one header, the second and subsequent associated headers may be included after the 800 initial reference to the identifier. Prior to the inclusion of a header, the application shall not 801 define any macros with names lexically identical to symbols defined by that header. 802 2.3 Error Numbers 803 Most functions can provide an error number. The means by which each function provides its 804 error numbers is specified in its description. 805 Some functions provide the error number in a variable accessed through the symbol errno. The 806 symbol errno, defined by including the header, expands to a modifiable lvalue of type | 807 int. It is unspecified whether errno is a macro or an identifier declared with external linkage. If a 808 macro definition is suppressed in order to access an actual object, or a program defines an 809 identifier with the name errno, the behavior is undefined. 810 The value of errno should only be examined when it is indicated to be valid by a function's return 811 value. No function in this volume of IEEE Std 1003.1-200x shall set errno to zero. For each thread 812 of a process, the value of errno shall not be affected by function calls or assignments to errno by 813 other threads. 814 Some functions return an error number directly as the function value. These functions return a 815 value of zero to indicate success. 816 If more than one error occurs in processing a function call, any one of the possible errors may be 817 returned, as the order of detection is undefined. 818 Implementations may support additional errors not included in this list, may generate errors 819 included in this list under circumstances other than those described here, or may contain 820 extensions or limitations that prevent some errors from occurring. The ERRORS section on each | 821 reference page specifies whether an error shall be returned, or whether it may be returned. 822 Implementations shall not generate a different error number from the ones described here for 823 error conditions described in this volume of IEEE Std 1003.1-200x, but may generate additional 824 errors unless explicitly disallowed for a particular function. 825 Each implementation shall document, in the conformance document, situations in which each of 826 the optional conditions defined in IEEE Std 1003.1-200x is detected. The conformance document 827 may also contain statements that one or more of the optional error conditions are not detected. 828 For functions under the Threads option for which [EINTR] is not listed as a possible error 829 condition in this volume of IEEE Std 1003.1-200x, an implementation shall not return an error 830 code of [EINTR]. 831 The following symbolic names identify the possible error numbers, in the context of the 832 functions specifically defined in this volume of IEEE Std 1003.1-200x; these general descriptions 833 are more precisely defined in the ERRORS sections of the functions that return them. Only these 834 symbolic names should be used in programs, since the actual value of the error number is 835 unspecified. All values listed in this section shall be unique integer constant expressions with System Interfaces, Issue 6 471 Error Numbers General Information 836 type int suitable for use in #if preprocessing directives, except as noted below. The values for all 837 these names shall be found in the header defined in the Base Definitions volume of 838 IEEE Std 1003.1-200x. The actual values are unspecified by this volume of IEEE Std 1003.1-200x. 839 [E2BIG] 840 Argument list too long. The sum of the number of bytes used by the new process image's 841 argument list and environment list is greater than the system-imposed limit of {ARG_MAX} 842 bytes. 843 or: 844 Lack of space in an output buffer. 845 or: 846 Argument is greater than the system-imposed maximum. 847 [EACCES] 848 Permission denied. An attempt was made to access a file in a way forbidden by its file 849 access permissions. 850 [EADDRINUSE] 851 Address in use. The specified address is in use. 852 [EADDRNOTAVAIL] 853 Address not available. The specified address is not available from the local system. 854 [EAFNOSUPPORT] 855 Address family not supported. The implementation does not support the specified address 856 family, or the specified address is not a valid address for the address family of the specified 857 socket. 858 [EAGAIN] 859 Resource temporarily unavailable. This is a temporary condition and later calls to the same 860 routine may complete normally. 861 [EALREADY] 862 Connection already in progress. A connection request is already in progress for the specified 863 socket. 864 [EBADF] 865 Bad file descriptor. A file descriptor argument is out of range, refers to no open file, or a 866 read (write) request is made to a file that is only open for writing (reading). 867 [EBADMSG] 868 XSR Bad message. During a read( ), getmsg( ), getpmsg( ), or ioctl( ) I_RECVFD request to a | 869 STREAMS device, a message arrived at the head of the STREAM that is inappropriate for 870 the function receiving the message. 871 read( ) Message waiting to be read on a STREAM is not a data message. | 872 getmsg( ) or getpmsg( ) | 873 A file descriptor was received instead of a control message. | 874 ioctl( ) Control or data information was received instead of a file descriptor when 875 I_RECVFD was specified. 876 or: 877 Bad Message. The implementation has detected a corrupted message. 472 Technical Standard (2001) (Draft April 16, 2001) General Information Error Numbers 878 [EBUSY] 879 Resource busy. An attempt was made to make use of a system resource that is not currently 880 available, as it is being used by another process in a manner that would have conflicted with 881 the request being made by this process. 882 [ECANCELED] 883 Operation canceled. The associated asynchronous operation was canceled before 884 completion. 885 [ECHILD] 886 No child process. A wait( ) or waitpid( ) function was executed by a process that had no 887 existing or unwaited-for child process. 888 [ECONNABORTED] 889 Connection aborted. The connection has been aborted. 890 [ECONNREFUSED] 891 Connection refused. An attempt to connect to a socket was refused because there was no 892 process listening or because the queue of connection requests was full and the underlying 893 protocol does not support retransmissions. 894 [ECONNRESET] 895 Connection reset. The connection was forcibly closed by the peer. 896 [EDEADLK] 897 Resource deadlock would occur. An attempt was made to lock a system resource that 898 would have resulted in a deadlock situation. 899 [EDESTADDRREQ] 900 Destination address required. No bind address was established. 901 [EDOM] 902 Domain error. An input argument is outside the defined domain of the mathematical 903 function (defined in the ISO C standard). 904 [EDQUOT] 905 Reserved. 906 [EEXIST] 907 File exists. An existing file was mentioned in an inappropriate context; for example, as a 908 new link name in the link( ) function. 909 [EFAULT] 910 Bad address. The system detected an invalid address in attempting to use an argument of a 911 call. The reliable detection of this error cannot be guaranteed, and when not detected may 912 result in the generation of a signal, indicating an address violation, which is sent to the 913 process. 914 [EFBIG] 915 File too large. The size of a file would exceed the maximum file size of an implementation or 916 offset maximum established in the corresponding file description. 917 [EHOSTUNREACH] 918 Host is unreachable. The destination host cannot be reached (probably because the host is 919 down or a remote router cannot reach it). 920 [EIDRM] 921 Identifier removed. Returned during XSI interprocess communication if an identifier has 922 been removed from the system. System Interfaces, Issue 6 473 Error Numbers General Information 923 [EILSEQ] 924 Illegal byte sequence. A wide-character code has been detected that does not correspond to 925 a valid character, or a byte sequence does not form a valid wide-character code (defined in 926 the ISO C standard). 927 [EINPROGRESS] 928 Operation in progress. This code is used to indicate that an asynchronous operation has not 929 yet completed. 930 or: 931 O_NONBLOCK is set for the socket file descriptor and the connection cannot be 932 immediately established. 933 [EINTR] 934 Interrupted function call. An asynchronous signal was caught by the process during the 935 execution of an interruptible function. If the signal handler performs a normal return, the 936 interrupted function call may return this condition (see the Base Definitions volume of 937 IEEE Std 1003.1-200x, ). 938 [EINVAL] 939 Invalid argument. Some invalid argument was supplied; for example, specifying an 940 undefined signal in a signal( ) function or a kill( ) function. 941 [EIO] 942 Input/output error. Some physical input or output error has occurred. This error may be 943 reported on a subsequent operation on the same file descriptor. Any other error-causing 944 operation on the same file descriptor may cause the [EIO] error indication to be lost. 945 [EISCONN] 946 Socket is connected. The specified socket is already connected. 947 [EISDIR] 948 Is a directory. An attempt was made to open a directory with write mode specified. 949 [ELOOP] 950 Symbolic link loop. A loop exists in symbolic links encountered during pathname | 951 resolution. This error may also be returned if more than {SYMLOOP_MAX} symbolic links | 952 are encountered during pathname resolution. | 953 [EMFILE] 954 Too many open files. An attempt was made to open more than the maximum number of 955 {OPEN_MAX} file descriptors allowed in this process. 956 [EMLINK] 957 Too many links. An attempt was made to have the link count of a single file exceed 958 {LINK_MAX}. 959 [EMSGSIZE] 960 Message too large. A message sent on a transport provider was larger than an internal 961 message buffer or some other network limit. 962 or: 963 Inappropriate message buffer length. 964 [EMULTIHOP] 965 Reserved. 474 Technical Standard (2001) (Draft April 16, 2001) General Information Error Numbers 966 [ENAMETOOLONG] 967 Filename too long. The length of a pathname exceeds {PATH_MAX}, or a pathname | 968 component is longer than {NAME_MAX}. This error may also occur when pathname | 969 substitution, as a result of encountering a symbolic link during pathname resolution, results | 970 in a pathname string the size of which exceeds {PATH_MAX}. | 971 [ENETDOWN] 972 Network is down. The local network interface used to reach the destination is down. 973 [ENETRESET] 974 The connection was aborted by the network. 975 [ENETUNREACH] 976 Network unreachable. No route to the network is present. 977 [ENFILE] 978 Too many files open in system. Too many files are currently open in the system. The system 979 has reached its predefined limit for simultaneously open files and temporarily cannot accept 980 requests to open another one. 981 [ENOBUFS] 982 No buffer space available. Insufficient buffer resources were available in the system to 983 perform the socket operation. 984 XSR [ENODATA] 985 No message available. No message is available on the STREAM head read queue. 986 [ENODEV] 987 No such device. An attempt was made to apply an inappropriate function to a device; for 988 example, trying to read a write-only device such as a printer. 989 [ENOENT] 990 No such file or directory. A component of a specified pathname does not exist, or the | 991 pathname is an empty string. | 992 [ENOEXEC] 993 Executable file format error. A request is made to execute a file that, although it has the 994 appropriate permissions, is not in the format required by the implementation for executable 995 files. 996 [ENOLCK] 997 No locks available. A system-imposed limit on the number of simultaneous file and record 998 locks has been reached and no more are currently available. 999 [ENOLINK] 1000 Reserved. 1001 [ENOMEM] 1002 Not enough space. The new process image requires more memory than is allowed by the 1003 hardware or system-imposed memory management constraints. 1004 [ENOMSG] 1005 No message of the desired type. The message queue does not contain a message of the 1006 required type during XSI interprocess communication. 1007 [ENOPROTOOPT] 1008 Protocol not available. The protocol option specified to setsockopt( ) is not supported by the 1009 implementation. System Interfaces, Issue 6 475 Error Numbers General Information 1010 [ENOSPC] 1011 No space left on a device. During the write( ) function on a regular file or when extending a 1012 directory, there is no free space left on the device. 1013 XSR [ENOSR] 1014 No STREAM resources. Insufficient STREAMS memory resources are available to perform a 1015 STREAMS-related function. This is a temporary condition; it may be recovered from if other 1016 processes release resources. 1017 XSR [ENOSTR] 1018 Not a STREAM. A STREAM function was attempted on a file descriptor that was not 1019 associated with a STREAMS device. 1020 [ENOSYS] 1021 Function not implemented. An attempt was made to use a function that is not available in 1022 this implementation. 1023 [ENOTCONN] 1024 Socket not connected. The socket is not connected. 1025 [ENOTDIR] 1026 Not a directory. A component of the specified pathname exists, but it is not a directory, | 1027 when a directory was expected. 1028 [ENOTEMPTY] 1029 Directory not empty. A directory other than an empty directory was supplied when an 1030 empty directory was expected. 1031 [ENOTSOCK] 1032 Not a socket. The file descriptor does not refer to a socket. 1033 [ENOTSUP] 1034 Not supported. The implementation does not support this feature of the Realtime Option 1035 Group. 1036 [ENOTTY] 1037 Inappropriate I/O control operation. A control function has been attempted for a file or 1038 special file for which the operation is inappropriate. 1039 [ENXIO] 1040 No such device or address. Input or output on a special file refers to a device that does not 1041 exist, or makes a request beyond the capabilities of the device. It may also occur when, for 1042 example, a tape drive is not on-line. 1043 [EOPNOTSUPP] 1044 Operation not supported on socket. The type of socket (address family or protocol) does not 1045 support the requested operation. 1046 [EOVERFLOW] 1047 Value too large to be stored in data type. An operation was attempted which would | 1048 generate a value that is outside the range of values that can be represented in the relevant | 1049 data type or that are allowed for a given data item. | 1050 [EPERM] 1051 Operation not permitted. An attempt was made to perform an operation limited to 1052 processes with appropriate privileges or to the owner of a file or other resource. 1053 [EPIPE] 1054 Broken pipe. A write was attempted on a socket, pipe, or FIFO for which there is no process 476 Technical Standard (2001) (Draft April 16, 2001) General Information Error Numbers 1055 to read the data. 1056 [EPROTO] 1057 Protocol error. Some protocol error occurred. This error is device-specific, but is generally 1058 not related to a hardware failure. 1059 [EPROTONOSUPPORT] 1060 Protocol not supported. The protocol is not supported by the address family, or the protocol 1061 is not supported by the implementation. 1062 [EPROTOTYPE] 1063 Protocol wrong type for socket. The socket type is not supported by the protocol. 1064 [ERANGE] 1065 Result too large or too small. The result of the function is too large (overflow) or too small 1066 (underflow) to be represented in the available space (defined in the ISO C standard). 1067 [EROFS] 1068 Read-only file system. An attempt was made to modify a file or directory on a file system 1069 that is read-only. 1070 [ESPIPE] 1071 Invalid seek. An attempt was made to access the file offset associated with a pipe or FIFO. 1072 [ESRCH] 1073 No such process. No process can be found corresponding to that specified by the given 1074 process ID. 1075 [ESTALE] 1076 Reserved. 1077 XSR [ETIME] 1078 STREAM ioctl( ) timeout. The timer set for a STREAMS ioctl( ) call has expired. The cause of 1079 this error is device-specific and could indicate either a hardware or software failure, or a 1080 timeout value that is too short for the specific operation. The status of the ioctl( ) operation | 1081 is unspecified. | 1082 [ETIMEDOUT] 1083 Connection timed out. The connection to a remote machine has timed out. If the connection 1084 timed out during execution of the function that reported this error (as opposed to timing 1085 out prior to the function being called), it is unspecified whether the function has completed 1086 some or all of the documented behavior associated with a successful completion of the 1087 function. 1088 or: 1089 Operation timed out. The time limit associated with the operation was exceeded before the 1090 operation completed. 1091 [ETXTBSY] 1092 Text file busy. An attempt was made to execute a pure-procedure program that is currently 1093 open for writing, or an attempt has been made to open for writing a pure-procedure 1094 program that is being executed. 1095 [EWOULDBLOCK] 1096 Operation would block. An operation on a socket marked as non-blocking has encountered 1097 a situation such as no data available that otherwise would have caused the function to 1098 suspend execution. System Interfaces, Issue 6 477 Error Numbers General Information 1099 A conforming implementation may assign the same values for [EWOULDBLOCK] and 1100 [EAGAIN]. 1101 [EXDEV] 1102 Improper link. A link to a file on another file system was attempted. 1103 2.3.1 Additional Error Numbers 1104 Additional implementation-defined error numbers may be defined in . 1105 2.4 Signal Concepts 1106 2.4.1 Signal Generation and Delivery 1107 A signal is said to be generated for (or sent to) a process or thread when the event that causes the 1108 signal first occurs. Examples of such events include detection of hardware faults, timer 1109 RTS expiration, signals generated via the sigevent structure and terminal activity, as well as 1110 RTS invocations of the kill( ) and sigqueue( ) functions. In some circumstances, the same event 1111 generates signals for multiple processes. 1112 At the time of generation, a determination shall be made whether the signal has been generated 1113 for the process or for a specific thread within the process. Signals which are generated by some 1114 action attributable to a particular thread, such as a hardware fault, shall be generated for the 1115 thread that caused the signal to be generated. Signals that are generated in association with a 1116 process ID or process group ID or an asynchronous event, such as terminal activity, shall be 1117 generated for the process. 1118 Each process has an action to be taken in response to each signal defined by the system (see 1119 Section 2.4.3 (on page 480)). A signal is said to be delivered to a process when the appropriate 1120 action for the process and signal is taken. A signal is said to be accepted by a process when the 1121 signal is selected and returned by one of the sigwait( ) functions. 1122 During the time between the generation of a signal and its delivery or acceptance, the signal is 1123 said to be pending. Ordinarily, this interval cannot be detected by an application. However, a 1124 signal can be blocked from delivery to a thread. If the action associated with a blocked signal is 1125 anything other than to ignore the signal, and if that signal is generated for the thread, the signal 1126 shall remain pending until it is unblocked, it is accepted when it is selected and returned by a 1127 call to the sigwait( ) function, or the action associated with it is set to ignore the signal. Signals 1128 generated for the process shall be delivered to exactly one of those threads within the process 1129 which is in a call to a sigwait( ) function selecting that signal or has not blocked delivery of the 1130 signal. If there are no threads in a call to a sigwait( ) function selecting that signal, and if all 1131 threads within the process block delivery of the signal, the signal shall remain pending on the 1132 process until a thread calls a sigwait( ) function selecting that signal, a thread unblocks delivery 1133 of the signal, or the action associated with the signal is set to ignore the signal. If the action 1134 associated with a blocked signal is to ignore the signal and if that signal is generated for the 1135 process, it is unspecified whether the signal is discarded immediately upon generation or 1136 remains pending. 1137 Each thread has a signal mask that defines the set of signals currently blocked from delivery to it. | 1138 The signal mask for a thread shall be initialized from that of its parent or creating thread, or from | 1139 the corresponding thread in the parent process if the thread was created as the result of a call to | 1140 fork( ). The sigaction( ), sigprocmask( ), and sigsuspend( ) functions control the manipulation of the 1141 signal mask. 478 Technical Standard (2001) (Draft April 16, 2001) General Information Signal Concepts 1142 The determination of which action is taken in response to a signal is made at the time the signal 1143 is delivered, allowing for any changes since the time of generation. This determination is 1144 independent of the means by which the signal was originally generated. If a subsequent 1145 occurrence of a pending signal is generated, it is implementation-defined as to whether the 1146 RTS signal is delivered or accepted more than once in circumstances other than those in which 1147 queuing is required under the Realtime Signals Extension option. The order in which multiple, 1148 simultaneously pending signals outside the range SIGRTMIN to SIGRTMAX are delivered to or 1149 accepted by a process is unspecified. 1150 When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated for a process, any 1151 pending SIGCONT signals for that process shall be discarded. Conversely, when SIGCONT is 1152 generated for a process, all pending stop signals for that process shall be discarded. When 1153 SIGCONT is generated for a process that is stopped, the process shall be continued, even if the 1154 SIGCONT signal is blocked or ignored. If SIGCONT is blocked and not ignored, it shall remain 1155 pending until it is either unblocked or a stop signal is generated for the process. 1156 An implementation shall document any condition not specified by this volume of 1157 IEEE Std 1003.1-200x under which the implementation generates signals. 1158 2.4.2 Realtime Signal Generation and Delivery 1159 RTS This section describes extensions to support realtime signal generation and delivery. This 1160 functionality is dependent on support of the Realtime Signals Extension option (and the rest of 1161 this section is not further shaded for this option). 1162 Some signal-generating functions, such as high-resolution timer expiration, asynchronous I/O 1163 completion, interprocess message arrival, and the sigqueue( ) function, support the specification 1164 of an application-defined value, either explicitly as a parameter to the function or in a sigevent 1165 structure parameter. The sigevent structure is defined in and contains at least the | 1166 following members: | 1167 _____________________________________________________________________ 1168 _ Member Type Member Name Description ____________________________________________________________________ 1169 int sigev_notify Notification type. 1170 int sigev_signo Signal number. 1171 union sigval sigev_value Signal value. 1172 void(*)(unsigned sigval) sigev_notify_function Notification function. 1173 _ (pthread_attr_t*) sigev_notify_attributes Notification attributes. ____________________________________________________________________ 1174 The sigev_notify member specifies the notification mechanism to use when an asynchronous 1175 event occurs. This volume of IEEE Std 1003.1-200x defines the following values for the 1176 sigev_notify member: 1177 SIGEV_NONE No asynchronous notification shall be delivered when the event of 1178 interest occurs. 1179 SIGEV_SIGNAL The signal specified in sigev_signo shall be generated for the process when 1180 the event of interest occurs. If the implementation supports the Realtime 1181 Signals Extension option and if the SA_SIGINFO flag is set for that signal 1182 number, then the signal shall be queued to the process and the value 1183 specified in sigev_value shall be the si_value component of the generated 1184 signal. If SA_SIGINFO is not set for that signal number, it is unspecified 1185 whether the signal is queued and what value, if any, is sent. 1186 SIGEV_THREAD A notification function shall be called to perform notification. System Interfaces, Issue 6 479 Signal Concepts General Information 1187 An implementation may define additional notification mechanisms. 1188 The sigev_signo member specifies the signal to be generated. The sigev_value member is the 1189 application-defined value to be passed to the signal-catching function at the time of the signal 1190 delivery or to be returned at signal acceptance as the si_value member of the siginfo_t structure. 1191 The sigval union is defined in and contains at least the following members: | 1192 _____________________________________________________ 1193 _ Member Type Member Name Description ____________________________________________________ 1194 int sival_int Integer signal value. 1195 _ void* sival_ptr Pointer signal value. ____________________________________________________ 1196 The sival_int member shall be used when the application-defined value is of type int; the 1197 sival_ptr member shall be used when the application-defined value is a pointer. 1198 When a signal is generated by the sigqueue( ) function or any signal-generating function that 1199 supports the specification of an application-defined value, the signal shall be marked pending 1200 and, if the SA_SIGINFO flag is set for that signal, the signal shall be queued to the process along 1201 with the application-specified signal value. Multiple occurrences of signals so generated are 1202 queued in FIFO order. It is unspecified whether signals so generated are queued when the 1203 SA_SIGINFO flag is not set for that signal. 1204 Signals generated by the kill( ) function or other events that cause signals to occur, such as 1205 detection of hardware faults, alarm( ) timer expiration, or terminal activity, and for which the 1206 implementation does not support queuing, shall have no effect on signals already queued for the 1207 same signal number. 1208 When multiple unblocked signals, all in the range SIGRTMIN to SIGRTMAX, are pending, the 1209 behavior shall be as if the implementation delivers the pending unblocked signal with the lowest 1210 signal number within that range. No other ordering of signal delivery is specified. 1211 If, when a pending signal is delivered, there are additional signals queued to that signal number, 1212 the signal shall remain pending. Otherwise, the pending indication shall be reset. 1213 Multi-threaded programs can use an alternate event notification mechanism. When a 1214 notification is processed, and the sigev_notify member of the sigevent structure has the value 1215 SIGEV_THREAD, the function sigev_notify_function is called with parameter sigev_value. 1216 The function shall be executed in an environment as if it were the start_routine for a newly 1217 created thread with thread attributes specified by sigev_notify_attributes. If sigev_notify_attributes 1218 is NULL, the behavior shall be as if the thread were created with the detachstate attribute set to 1219 PTHREAD_CREATE_DETACHED. Supplying an attributes structure with a detachstate attribute 1220 of PTHREAD_CREATE_JOINABLE results in undefined behavior. The signal mask of this 1221 thread is implementation-defined. 1222 2.4.3 Signal Actions 1223 There are three types of action that can be associated with a signal: SIG_DFL, SIG_IGN, or a 1224 pointer to a function. Initially, all signals shall be set to SIG_DFL or SIG_IGN prior to entry of 1225 the main( ) routine (see the exec functions). The actions prescribed by these values are as follows: 1226 SIG_DFL Signal-specific default action. 1227 The default actions for the signals defined in this volume of IEEE Std 1003.1-200x 1228 RTS are specified under . If the Realtime Signals Extension option is 1229 supported, the default actions for the realtime signals in the range SIGRTMIN to 1230 SIGRTMAX shall be to terminate the process abnormally. 480 Technical Standard (2001) (Draft April 16, 2001) General Information Signal Concepts 1231 If the default action is to stop the process, the execution of that process is 1232 temporarily suspended. When a process stops, a SIGCHLD signal shall be 1233 generated for its parent process, unless the parent process has set the 1234 SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are 1235 sent to the process shall not be delivered until the process is continued, except 1236 SIGKILL which always terminates the receiving process. A process that is a 1237 member of an orphaned process group shall not be allowed to stop in response to 1238 the SIGTSTP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of 1239 these signals would stop such a process, the signal shall be discarded. 1240 Setting a signal action to SIG_DFL for a signal that is pending, and whose default 1241 action is to ignore the signal (for example, SIGCHLD), shall cause the pending 1242 signal to be discarded, whether or not it is blocked. 1243 The default action for SIGCONT is to resume execution at the point where the 1244 RTS process was stopped, after first handling any pending unblocked signals. If the 1245 Realtime Signals Extension option is supported, any queued values pending shall 1246 be discarded and the resources used to queue them shall be released and returned | 1247 to the system for other use. When a stopped process is continued, a SIGCHLD | 1248 signal may be generated for its parent process, unless the parent process has set | 1249 the SA_NOCLDSTOP flag. | 1250 SIG_IGN Ignore signal. 1251 Delivery of the signal shall have no effect on the process. The behavior of a process 1252 RTS is undefined after it ignores a SIGFPE, SIGILL, SIGSEGV, or SIGBUS signal that 1253 RTS was not generated by kill( ),sigqueue( ),or raise( ). 1254 The system shall not allow the action for the signals SIGKILL or SIGSTOP to be set 1255 to SIG_IGN. 1256 Setting a signal action to SIG_IGN for a signal that is pending shall cause the 1257 pending signal to be discarded, whether or not it is blocked. 1258 If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is 1259 XSI unspecified, except as specified below. 1260 If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the 1261 calling processes shall not be transformed into zombie processes when they 1262 terminate. If the calling process subsequently waits for its children, and the process 1263 has no unwaited-for children that were transformed into zombie processes, it shall 1264 block until all of its children terminate, and wait( ), waitid( ), and waitpid( ) shall fail 1265 and set errno to [ECHILD]. 1266 RTS If the Realtime Signals Extension option is supported, any queued values pending 1267 shall be discarded and the resources used to queue them shall be released and 1268 made available to queue other signals. 1269 pointer to a function 1270 Catch signal. 1271 On delivery of the signal, the receiving process is to execute the signal-catching 1272 function at the specified address. After returning from the signal-catching function, 1273 the receiving process shall resume execution at the point at which it was 1274 interrupted. 1275 If the SA_SIGINFO flag for the signal is cleared, the signal-catching function shall 1276 be entered as a C-language function call as follows: System Interfaces, Issue 6 481 Signal Concepts General Information 1277 void func(int signo); 1278 XSI|RTS If the SA_SIGINFO flag for the signal is set, the signal-catching function shall be 1279 entered as a C-language function call as follows: 1280 void func(int signo, siginfo_t *info, void *context); 1281 where func is the specified signal-catching function, signo is the signal number of 1282 the signal being delivered, and info is a pointer to a siginfo_t structure defined in 1283 containing at least the following members: 1284 ____________________________________________________ 1285 _ Member Type Member Name Description ___________________________________________________ 1286 int si_signo Signal number. 1287 int si_code Cause of the signal. 1288 _ union sigval si_value Signal value. ___________________________________________________ 1289 The si_signo member shall contain the signal number. This shall be the same as the 1290 signo parameter. The si_code member shall contain a code identifying the cause of 1291 the signal. The following values are defined for si_code: 1292 SI_USER The signal was sent by the kill( ) function. The implementation 1293 may set si_code to SI_USER if the signal was sent by the raise( ) or 1294 abort( ) functions or any similar functions provided as 1295 implementation extensions. 1296 RTS SI_QUEUE The signal was sent by the sigqueue( ) function. 1297 RTS SI_TIMER The signal was generated by the expiration of a timer set by 1298 timer_settime( ). 1299 RTS SI_ASYNCIO The signal was generated by the completion of an asynchronous 1300 I/O request. 1301 RTS SI_MESGQ The signal was generated by the arrival of a message on an 1302 empty message queue. 1303 If the signal was not generated by one of the functions or events listed above, the 1304 si_code shall be set to an implementation-defined value that is not equal to any of 1305 the values defined above. 1306 RTS If the Realtime Signals Extension is supported, and si_code is one of SI_QUEUE, 1307 SI_TIMER, SI_ASYNCIO, or SI_MESGQ, then si_value shall contain the 1308 application-specified signal value. Otherwise, the contents of si_value are 1309 undefined. 1310 The behavior of a process is undefined after it returns normally from a signal- 1311 XSI catching function for a SIGBUS, SIGFPE, SIGILL, or SIGSEGV signal that was not 1312 RTS generated by kill( ),sigqueue( ),or raise( ). 1313 The system shall not allow a process to catch the signals SIGKILL and SIGSTOP. 1314 If a process establishes a signal-catching function for the SIGCHLD signal while it 1315 has a terminated child process for which it has not waited, it is unspecified 1316 whether a SIGCHLD signal is generated to indicate that child process. 1317 When signal-catching functions are invoked asynchronously with process 1318 execution, the behavior of some of the functions defined by this volume of 1319 IEEE Std 1003.1-200x is unspecified if they are called from a signal-catching 1320 function. 482 Technical Standard (2001) (Draft April 16, 2001) General Information Signal Concepts 1321 The following table defines a set of functions that shall be either reentrant or non- 1322 interruptible by signals and shall be async-signal-safe. Therefore applications may 1323 invoke them, without restriction, from signal-catching functions: 1324 Notes to Reviewers 1325 This section with side shading will not appear in the final copy. - Ed. 1326 The contents of the following tables need to be reviewed. 1327 _Exit( ) fdatasync( ) posix_trace_event( ) sigsuspend( ) 1328 _exit( ) fork( ) raise( ) stat( ) 1329 access( ) fpathconf( ) read( ) symlink( ) 1330 aio_error( ) fstat( ) readlink( ) sysconf( ) 1331 aio_return( ) fsync( ) rename( ) tcdrain( ) 1332 aio_suspend( ) ftruncate( ) rmdir( ) tcflow( ) 1333 alarm( ) getegid( ) sem_post( ) tcflush( ) 1334 cfgetispeed( ) geteuid( ) setgid( ) tcgetattr( ) 1335 cfgetospeed( ) getgid( ) setpgid( ) tcgetpgrp( ) 1336 cfsetispeed( ) getgroups( ) setsid( ) tcsendbreak( ) 1337 cfsetospeed( ) getpgrp( ) setuid( ) tcsetattr( ) 1338 chdir( ) getpid( ) sigaction( ) tcsetpgrp( ) 1339 chmod( ) getppid( ) sigaddset( ) time( ) 1340 chown( ) getuid( ) sigdelset( ) timer_getoverrun( ) 1341 clock_gettime( ) kill( ) sigemptyset( ) timer_gettime( ) 1342 close( ) link( ) sigfillset( ) timer_settime( ) 1343 creat( ) lseek( ) sigismember( ) times( ) 1344 dup( ) lstat( ) sleep( ) umask( ) 1345 dup2( ) mkdir( ) signal( ) uname( ) 1346 execle( ) mkfifo( ) sigpause( ) unlink( ) 1347 execve( ) open( ) sigpending( ) utime( ) 1348 fchmod( ) pathconf( ) sigprocmask( ) wait( ) 1349 fchown( ) pause( ) sigqueue( ) waitpid( ) 1350 fcntl( ) pipe( ) sigset( ) write( ) 1351 All functions not in the above table are considered to be unsafe with respect to 1352 signals. In the presence of signals, all functions defined by this volume of 1353 IEEE Std 1003.1-200x shall behave as defined when called from or interrupted by a 1354 signal-catching function, with a single exception: when a signal interrupts an 1355 unsafe function and the signal-catching function calls an unsafe function, the 1356 behavior is undefined. 1357 When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or 1358 continue, the entire process shall be terminated, stopped, or continued, respectively. System Interfaces, Issue 6 483 Signal Concepts General Information 1359 2.4.4 Signal Effects on Other Functions 1360 Signals affect the behavior of certain functions defined by this volume of IEEE Std 1003.1-200x if 1361 delivered to a process while it is executing such a function. If the action of the signal is to 1362 terminate the process, the process shall be terminated and the function shall not return. If the 1363 action of the signal is to stop the process, the process shall stop until continued or terminated. 1364 Generation of a SIGCONT signal for the process shall cause the process to be continued, and the 1365 original function shall continue at the point the process was stopped. If the action of the signal is 1366 to invoke a signal-catching function, the signal-catching function shall be invoked; in this case 1367 the original function is said to be interrupted by the signal. If the signal-catching function 1368 executes a return statement, the behavior of the interrupted function shall be as described 1369 individually for that function, except as noted for unsafe functions. Signals that are ignored shall 1370 not affect the behavior of any function; signals that are blocked shall not affect the behavior of 1371 any function until they are unblocked and then delivered, except as specified for the sigpending( ) 1372 and sigwait( ) functions. 1373 2.5 Standard I/O Streams 1374 A stream is associated with an external file (which may be a physical device) by opening a file, 1375 which may involve creating a new file. Creating an existing file causes its former contents to be 1376 discarded if necessary. If a file can support positioning requests, (such as a disk file, as opposed 1377 to a terminal), then a file position indicator associated with the stream is positioned at the start 1378 (byte number 0) of the file, unless the file is opened with append mode, in which case it is 1379 implementation-defined whether the file position indicator is initially positioned at the 1380 beginning or end of the file. The file position indicator is maintained by subsequent reads, 1381 writes, and positioning requests, to facilitate an orderly progression through the file. All input 1382 takes place as if bytes were read by successive calls to fgetc( ); all output takes place as if bytes 1383 were written by successive calls to fputc( ). 1384 When a stream is unbuffered, bytes are intended to appear from the source or at the destination 1385 as soon as possible; otherwise, bytes may be accumulated and transmitted as a block. When a 1386 stream is fully buffered, bytes are intended to be transmitted as a block when a buffer is filled. 1387 When a stream is line buffered, bytes are intended to be transmitted as a block when a newline 1388 byte is encountered. Furthermore, bytes are intended to be transmitted as a block when a buffer 1389 is filled, when input is requested on an unbuffered stream, or when input is requested on a line- 1390 buffered stream that requires the transmission of bytes. Support for these characteristics is 1391 implementation-defined, and may be affected via setbuf( ) and setvbuf( ). 1392 A file may be disassociated from a controlling stream by closing the file. Output streams are 1393 flushed (any unwritten buffer contents are transmitted) before the stream is disassociated from 1394 the file. The value of a pointer to a FILE object is unspecified after the associated file is closed | 1395 (including the standard streams). | 1396 A file may be subsequently reopened, by the same or another program execution, and its 1397 contents reclaimed or modified (if it can be repositioned at its start). If the main( ) function 1398 returns to its original caller, or if the exit( ) function is called, all open files are closed (hence all 1399 output streams are flushed) before program termination. Other paths to program termination, 1400 such as calling abort( ), need not close all files properly. 1401 The address of the FILE object used to control a stream may be significant; a copy of a FILE 1402 object need not necessarily serve in place of the original. 1403 At program start-up, three streams are predefined and need not be opened explicitly: standard 1404 input (for reading conventional input), standard output (for writing conventional output), and 484 Technical Standard (2001) (Draft April 16, 2001) General Information Standard I/O Streams 1405 standard error (for writing diagnostic output). When opened, the standard error stream is not 1406 fully buffered; the standard input and standard output streams are fully buffered if and only if 1407 the stream can be determined not to refer to an interactive device. 1408 2.5.1 Interaction of File Descriptors and Standard I/O Streams 1409 CX This section describes the interaction of file descriptors and standard I/O streams. This 1410 functionality is an extension to the ISO C standard (and the rest of this section is not further CX 1411 shaded). 1412 An open file description may be accessed through a file descriptor, which is created using 1413 functions such as open( ) or pipe( ), or through a stream, which is created using functions such as 1414 fopen( ) or popen( ). Either a file descriptor or a stream is called a handle on the open file 1415 description to which it refers; an open file description may have several handles. 1416 Handles can be created or destroyed by explicit user action, without affecting the underlying 1417 open file description. Some of the ways to create them include fcntl( ), dup( ), fdopen( ), fileno( ), 1418 and fork( ). They can be destroyed by at least fclose( ), close( ), and the exec functions. 1419 A file descriptor that is never used in an operation that could affect the file offset (for example, 1420 read( ), write( ), or lseek( )) is not considered a handle for this discussion, but could give rise to one 1421 (for example, as a consequence of fdopen( ), dup( ), or fork( )). This exception does not include the 1422 file descriptor underlying a stream, whether created with fopen( ) or fdopen( ), so long as it is not 1423 used directly by the application to affect the file offset. The read( ) and write( ) functions 1424 implicitly affect the file offset; lseek( ) explicitly affects it. 1425 The result of function calls involving any one handle (the active handle) is defined elsewhere in 1426 this volume of IEEE Std 1003.1-200x, but if two or more handles are used, and any one of them is 1427 a stream, the application shall ensure that their actions are coordinated as described below. If 1428 this is not done, the result is undefined. 1429 A handle which is a stream is considered to be closed when either an fclose( ) or freopen( ) is 1430 executed on it (the result of freopen( ) is a new stream, which cannot be a handle on the same 1431 open file description as its previous value), or when the process owning that stream terminates 1432 with exit( ) or abort( ). A file descriptor is closed by close( ), _exit( ), or the exec functions when 1433 FD_CLOEXEC is set on that file descriptor. 1434 For a handle to become the active handle, the application shall ensure that the actions below are 1435 performed between the last use of the handle (the current active handle) and the first use of the 1436 second handle (the future active handle). The second handle then becomes the active handle. All 1437 activity by the application affecting the file offset on the first handle shall be suspended until it 1438 again becomes the active file handle. (If a stream function has as an underlying function one that 1439 affects the file offset, the stream function shall be considered to affect the file offset.) 1440 The handles need not be in the same process for these rules to apply. 1441 Note that after a fork( ), two handles exist where one existed before. The application shall ensure 1442 that, if both handles can ever be accessed, they are both in a state where the other could become 1443 the active handle first. The application shall prepare for a fork( ) exactly as if it were a change of 1444 active handle. (If the only action performed by one of the processes is one of the exec functions or 1445 _exit( ) (not exit( )), the handle is never accessed in that process.) 1446 For the first handle, the first applicable condition below applies. After the actions required 1447 below are taken, if the handle is still open, the application can close it. 1448 * If it is a file descriptor, no action is required. System Interfaces, Issue 6 485 Standard I/O Streams General Information 1449 * If the only further action to be performed on any handle to this open file descriptor is to close 1450 it, no action need be taken. 1451 * If it is a stream which is unbuffered, no action need be taken. 1452 * If it is a stream which is line buffered, and the last byte written to the stream was a newline 1453 (that is, as if a: 1454 putc('\n') 1455 was the most recent operation on that stream), no action need be taken. 1456 * If it is a stream which is open for writing or appending (but not also open for reading), the 1457 application shall either perform an fflush( ), or the stream shall be closed. 1458 * If the stream is open for reading and it is at the end of the file (feof( ) is true), no action need 1459 be taken. 1460 * If the stream is open with a mode that allows reading and the underlying open file 1461 description refers to a device that is capable of seeking, the application shall either perform 1462 an fflush( ), or the stream shall be closed. 1463 Otherwise, the result is undefined. 1464 For the second handle: 1465 * If any previous active handle has been used by a function that explicitly changed the file 1466 offset, except as required above for the first handle, the application shall perform an lseek( ) or 1467 fseek( ) (as appropriate to the type of handle) to an appropriate location. 1468 If the active handle ceases to be accessible before the requirements on the first handle, above, 1469 have been met, the state of the open file description becomes undefined. This might occur during 1470 functions such as a fork( ) or _exit( ). 1471 The exec functions make inaccessible all streams that are open at the time they are called, 1472 independent of which streams or file descriptors may be available to the new process image. 1473 When these rules are followed, regardless of the sequence of handles used, implementations 1474 shall ensure that an application, even one consisting of several processes, shall yield correct 1475 results: no data shall be lost or duplicated when writing, and all data shall be written in order, 1476 except as requested by seeks. It is implementation-defined whether, and under what conditions, 1477 all input is seen exactly once. 1478 If the rules above are not followed, the result is unspecified. 1479 Each function that operates on a stream is said to have zero or more underlying functions. This 1480 means that the stream function shares certain traits with the underlying functions, but does not 1481 require that there be any relation between the implementations of the stream function and its 1482 underlying functions. 1483 2.5.2 Stream Orientation and Encoding Rules 1484 For conformance to the ISO/IEC 9899: 1999 standard, the definition of a stream includes an 1485 orientation. After a stream is associated with an external file, but before any operations are 1486 performed on it, the stream is without orientation. Once a wide-character input/output function 1487 has been applied to a stream without orientation, the stream shall become wide-oriented. 1488 Similarly, once a byte input/output function has been applied to a stream without orientation, 1489 the stream shall become byte-oriented. Only a call to the freopen( ) function or the fwide( ) function 1490 can otherwise alter the orientation of a stream. 486 Technical Standard (2001) (Draft April 16, 2001) General Information Standard I/O Streams 1491 A successful call to freopen( ) shall remove any orientation. The three predefined streams standard 1492 input, standard output, and standard error shall be unoriented at program start-up. 1493 Byte input/output functions cannot be applied to a wide-oriented stream, and wide-character 1494 input/output functions cannot be applied to a byte-oriented stream. The remaining stream 1495 operations shall not affect and shall not be affected by a stream's orientation, except for the 1496 following additional restrictions: 1497 * Binary wide-oriented streams have the file positioning restrictions ascribed to both text and 1498 binary streams. 1499 * For wide-oriented streams, after a successful call to a file-positioning function that leaves the 1500 file position indicator prior to the end-of-file, a wide-character output function can overwrite 1501 a partial character; any file contents beyond the byte(s) written are henceforth undefined. 1502 Each wide-oriented stream has an associated mbstate_t object that stores the current parse state 1503 of the stream. A successful call to fgetpos( ) shall store a representation of the value of this 1504 mbstate_t object as part of the value of the fpos_t object. A later successful call to fsetpos( ) using 1505 the same stored fpos_t value shall restore the value of the associated mbstate_t object as well as 1506 the position within the controlled stream. 1507 Implementations that support multiple encoding rules associate an encoding rule with the 1508 stream. The encoding rule shall be determined by the setting of the LC_CTYPE category in the 1509 current locale at the time when the stream becomes wide-oriented. If a wide-character 1510 input/output function is applied to a byte-oriented stream, the encoding rule used is undefined. 1511 As with the stream's orientation, the encoding rule associated with a stream cannot be changed 1512 once it has been set, except by a successful call to freopen( ) which clears the encoding rule and 1513 resets the orientation to unoriented. 1514 Although both text and binary wide-oriented streams are conceptually sequences of wide 1515 characters, the external file associated with a wide-oriented stream is a sequence of (possibly 1516 multi-byte) characters generalized as follows: 1517 * Multi-byte encodings within files may contain embedded null bytes (unlike multi-byte 1518 encodings valid for use internal to the program). 1519 * A file need not begin nor end in the initial shift state. 1520 Moreover, the encodings used for characters may differ among files. Both the nature and choice 1521 of such encodings are implementation-defined. 1522 The wide-character input functions read characters from the stream and convert them to wide 1523 characters as if they were read by successive calls to the fgetwc( ) function. Each conversion shall 1524 occur as if by a call to the mbrtowc( ) function, with the conversion state described by the stream's 1525 CX own mbstate_t object, except the encoding rule associated with the stream is used instead of the 1526 encoding rule implied by the LC_CTYPE category of the current locale. 1527 The wide-character output functions convert wide characters to (possibly multi-byte) characters 1528 and write them to the stream as if they were written by successive calls to the fputwc( ) function. 1529 Each conversion shall occur as if by a call to the wcrtomb( ) function, with the conversion state 1530 CX described by the stream's own mbstate_t object, except the encoding rule associated with the 1531 stream is used instead of the encoding rule implied by the LC_CTYPE category of the current 1532 locale. 1533 An encoding error shall occur if the character sequence presented to the underlying mbrtowc( ) 1534 function does not form a valid (generalized) character, or if the code value passed to the 1535 underlying wcrtomb( ) function does not correspond to a valid (generalized) character. The 1536 wide-character input/output functions and the byte input/output functions store the value of System Interfaces, Issue 6 487 Standard I/O Streams General Information 1537 the macro [EILSEQ] in errno if and only if an encoding error occurs. 1538 2.6 STREAMS 1539 XSR STREAMS functionality is provided on implementations supporting the XSI STREAMS Option 1540 Group. This functionality is dependent on support of the XSI STREAMS option (and the rest of 1541 this section is not further shaded for this option). 1542 STREAMS provides a uniform mechanism for implementing networking services and other 1543 character-based I/O. The STREAMS function provides direct access to protocol modules. 1544 STREAMS modules are unspecified objects. Access to STREAMS modules is provided by 1545 interfaces in IEEE Std 1003.1-200x. Creation of STREAMS modules is outside the scope of 1546 IEEE Std 1003.1-200x. 1547 A STREAM is typically a full-duplex connection between a process and an open device or 1548 pseudo-device. However, since pipes may be STREAMS-based, a STREAM can be a full-duplex 1549 connection between two processes. The STREAM itself exists entirely within the implementation 1550 and provides a general character I/O function for processes. It optionally includes one or more 1551 intermediate processing modules that are interposed between the process end of the STREAM 1552 (STREAM head) and a device driver at the end of the STREAM (STREAM end). 1553 STREAMS I/O is based on messages. There are three types of message: | 1554 * Data messages containing actual data for input or output 1555 * Control data containing instructions for the STREAMS modules and underlying 1556 implementation 1557 * Other messages, which include file descriptors 1558 The interface between the STREAM and the rest of the implementation is provided by a set of | 1559 functions at the STREAM head. When a process calls write( ), writev( ), putmsg( ), putpmsg( ), or | 1560 ioctl( ), messages are sent down the STREAM, and read( ), readv( ), getmsg( ), or getpmsg( ) accepts | 1561 data from the STREAM and passes it to a process. Data intended for the device at the 1562 downstream end of the STREAM is packaged into messages and sent downstream, while data 1563 and signals from the device are composed into messages by the device driver and sent upstream 1564 to the STREAM head. 1565 When a STREAMS-based device is opened, a STREAM shall be created that contains the | 1566 STREAM head and the STREAM end (driver). If pipes are STREAMS-based in an | 1567 implementation, when a pipe is created, two STREAMS shall be created, each containing a | 1568 STREAM head. Other modules are added to the STREAM using ioctl( ). New modules are | 1569 ``pushed'' onto the STREAM one at a time in last-in, first-out (LIFO) style, as though the 1570 STREAM was a push-down stack. 1571 Priority 1572 Message types are classified according to their queuing priority and may be normal (non- 1573 priority), priority, or high-priority messages. A message belongs to a particular priority band that 1574 determines its ordering when placed on a queue. Normal messages have a priority band of 0 and | 1575 shall always be placed at the end of the queue following all other messages in the queue. High- | 1576 priority messages are always placed at the head of a queue, but shall be discarded if there is | 1577 already a high-priority message in the queue. Their priority band shall be ignored; they are | 1578 high-priority by virtue of their type. Priority messages have a priority band greater than 0. | 1579 Priority messages are always placed after any messages of the same or higher priority. High- | 1580 priority and priority messages are used to send control and data information outside the normal | 488 Technical Standard (2001) (Draft April 16, 2001) General Information STREAMS 1581 flow of control. By convention, high-priority messages shall not be affected by flow control. | 1582 Normal and priority messages have separate flow controls. | 1583 Message Parts 1584 A process may access STREAMS messages that contain a data part, control part, or both. The 1585 data part is that information which is transmitted over the communication medium and the 1586 control information is used by the local STREAMS modules. The other types of messages are 1587 used between modules and are not accessible to processes. Messages containing only a data part 1588 are accessible via putmsg( ), putpmsg( ), getmsg( ), getpmsg( ), read( ), readv( ), write( ), or writev( ). | 1589 Messages containing a control part with or without a data part are accessible via calls to 1590 putmsg( ), putpmsg( ), getmsg( ), or getpmsg( ). 1591 2.6.1 Accessing STREAMS 1592 A process accesses STREAMS-based files using the standard functions close( ), ioctl( ), getmsg( ), 1593 getpmsg( ), open( ), pipe( ), poll( ), putmsg( ), putpmsg( ), read( ), or write( ). Refer to the applicable 1594 function definitions for general properties and errors. 1595 Calls to ioctl( ) shall perform control functions on the STREAM associated with the file descriptor | 1596 fildes. The control functions may be performed by the STREAM head, a STREAMS module, or | 1597 the STREAMS driver for the STREAM. | 1598 STREAMS modules and drivers can detect errors, sending an error message to the STREAM | 1599 head, thus causing subsequent functions to fail and set errno to the value specified in the 1600 message. In addition, STREAMS modules and drivers can elect to fail a particular ioctl( ) request 1601 alone by sending a negative acknowledgement message to the STREAM head. This shall cause | 1602 just the pending ioctl( ) request to fail and set errno to the value specified in the message. | 1603 2.7 XSI Interprocess Communication 1604 XSI This section describes extensions to support interprocess communication. This functionality is 1605 dependent on support of the XSI Extension (and the rest of this section is not further shaded for 1606 this option). 1607 The following message passing, semaphore, and shared memory services form an XSI 1608 interprocess communication facility. Certain aspects of their operation are common, and are 1609 described below. 1610 ________________________________ 1611 _ IPC Functions _______________________________ 1612 msgctl( ) semctl( ) shmctl( ) 1613 msgget( ) semget( ) shmdt( ) 1614 msgrcv( ) semop( ) shmget( ) 1615 msgsnd( ) shmat( ) _ _______________________________ 1616 Another interprocess communication facility is provided by functions in the Realtime Option 1617 Group; see Section 2.8 (on page 491). System Interfaces, Issue 6 489 XSI Interprocess Communication General Information 1618 2.7.1 IPC General Description 1619 Each individual shared memory segment, message queue, and semaphore set shall be identified | 1620 by a unique positive integer, called, respectively, a shared memory identifier, shmid, a | 1621 semaphore identifier, semid, and a message queue identifier, msqid. The identifiers shall be | 1622 returned by calls to shmget( ), semget( ), and msgget( ), respectively. | 1623 Associated with each identifier is a data structure which contains data related to the operations 1624 which may be or may have been performed; see the Base Definitions volume of 1625 IEEE Std 1003.1-200x, , , and for their descriptions. 1626 Each of the data structures contains both ownership information and an ipc_perm structure (see 1627 the Base Definitions volume of IEEE Std 1003.1-200x, ) which are used in conjunction 1628 to determine whether or not read/write (read/alter for semaphores) permissions should be 1629 granted to processes using the IPC facilities. The mode member of the ipc_perm structure acts as 1630 a bit field which determines the permissions. 1631 The values of the bits are given below in octal notation. 1632 _______________________ 1633 _ Bit Meaning ______________________ 1634 0400 Read by user. 1635 0200 Write by user. 1636 0040 Read by group. 1637 0020 Write by group. 1638 0004 Read by others. 1639 _ 0002 Write by others. ______________________ 1640 The name of the ipc_perm structure is shm_perm, sem_perm, or msg_perm, depending on which 1641 service is being used. In each case, read and write/alter permissions shall be granted to a process | 1642 if one or more of the following are true ("xxx" is replaced by shm, sem, or msg, as appropriate): | 1643 * The process has appropriate privileges. 1644 * The effective user ID of the process matches xxx_perm.cuid or xxx_perm.uid in the data 1645 structure associated with the IPC identifier, and the appropriate bit of the user field in 1646 xxx_perm.mode is set. 1647 * The effective user ID of the process does not match xxx_perm.cuid or xxx_perm.uid but the 1648 effective group ID of the process matches xxx_perm.cgid or xxx_perm.gid in the data structure 1649 associated with the IPC identifier, and the appropriate bit of the group field in xxx_perm.mode 1650 is set. 1651 * The effective user ID of the process does not match xxx_perm.cuid or xxx_perm.uid and the 1652 effective group ID of the process does not match xxx_perm.cgid or xxx_perm.gid in the data 1653 structure associated with the IPC identifier, but the appropriate bit of the other field in 1654 xxx_perm.mode is set. 1655 Otherwise, the permission shall be denied. | 490 Technical Standard (2001) (Draft April 16, 2001) General Information Realtime 1656 2.8 Realtime 1657 This section defines functions to support the source portability of applications with realtime 1658 requirements. The presence of many of these functions is dependent on support for 1659 implementation options described in the text. 1660 The specific functional areas included in this section and their scope include the following. Full 1661 definitions of these terms can be found in the Base Definitions volume of IEEE Std 1003.1-200x, 1662 Chapter 3, Definitions. 1663 * Semaphores 1664 * Process Memory Locking 1665 * Memory Mapped Files and Shared Memory Objects 1666 * Priority Scheduling 1667 * Realtime Signal Extension 1668 * Timers 1669 * Interprocess Communication 1670 * Synchronized Input and Output 1671 * Asynchronous Input and Output 1672 All the realtime functions defined in this volume of IEEE Std 1003.1-200x are portable, although 1673 some of the numeric parameters used by an implementation may have hardware dependencies. 1674 2.8.1 Realtime Signals 1675 RTS Realtime signal generation and delivery is dependent on support for the Realtime Signals 1676 Extension option. 1677 See Section 2.4.2 (on page 479). 1678 2.8.2 Asynchronous I/O 1679 AIO The functionality described in this section is dependent on support of the Asynchronous Input 1680 and Output option (and the rest of this section is not further shaded for this option). 1681 An asynchronous I/O control block structure aiocb is used in many asynchronous I/O 1682 functions. It is defined in the Base Definitions volume of IEEE Std 1003.1-200x, and has 1683 at least the following members: ___________________________________________________________ 1684 _ Member Type Member Name Description __________________________________________________________ 1685 int aio_fildes File descriptor. 1686 off_t aio_offset File offset. 1687 volatile void* aio_buf Location of buffer. 1688 size_t aio_nbytes Length of transfer. 1689 int aio_reqprio Request priority offset. 1690 struct sigevent aio_sigevent Signal number and value. 1691 _ int aio_lio_opcode Operation to be performed. __________________________________________________________ 1692 The aio_fildes element is the file descriptor on which the asynchronous operation is performed. 1693 If O_APPEND is not set for the file descriptor aio_fildes and if aio_fildes is associated with a 1694 device that is capable of seeking, then the requested operation takes place at the absolute 1695 position in the file as given by aio_offset , as if lseek( ) were called immediately prior to the System Interfaces, Issue 6 491 Realtime General Information 1696 operation with an offset argument equal to aio_offset and a whence argument equal to SEEK_SET. 1697 If O_APPEND is set for the file descriptor, or if aio_fildes is associated with a device that is 1698 incapable of seeking, write operations append to the file in the same order as the calls were 1699 made, with the following exception: under implementation-defined circumstances, such as 1700 operation on a multi-processor or when requests of differing priorities are submitted at the same 1701 time, the ordering restriction may be relaxed. Since there is no way for a strictly conforming 1702 application to determine whether this relaxation applies, all strictly conforming applications 1703 which rely on ordering of output shall be written in such a way that they will operate correctly if 1704 the relaxation applies. After a successful call to enqueue an asynchronous I/O operation, the 1705 value of the file offset for the file is unspecified. The aio_nbytes and aio_buf elements are the same 1706 as the nbyte and buf arguments defined by read( ) and write( ), respectively. 1707 If _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined, then 1708 asynchronous I/O is queued in priority order, with the priority of each asynchronous operation 1709 based on the current scheduling priority of the calling process. The aio_reqprio member can be 1710 used to lower (but not raise) the asynchronous I/O operation priority and is within the range 1711 zero through {AIO_PRIO_DELTA_MAX}, inclusive. Unless both _POSIX_PRIORITIZED_IO and 1712 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing asynchronous I/O 1713 requests is unspecified. When both _POSIX_PRIORITIZED_IO and 1714 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing of requests submitted 1715 by processes whose schedulers are not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC is 1716 unspecified. The priority of an asynchronous request is computed as (process scheduling 1717 priority) minus aio_reqprio. The priority assigned to each asynchronous I/O request is an 1718 indication of the desired order of execution of the request relative to other asynchronous I/O 1719 requests for this file. If _POSIX_PRIORITIZED_IO is defined, requests issued with the same 1720 priority to a character special file are processed by the underlying device in FIFO order; the order 1721 of processing of requests of the same priority issued to files that are not character special files is 1722 unspecified. Numerically higher priority values indicate requests of higher priority. The value of 1723 aio_reqprio has no effect on process scheduling priority. When prioritized asynchronous I/O 1724 requests to the same file are blocked waiting for a resource required for that I/O operation, the 1725 higher-priority I/O requests shall be granted the resource before lower-priority I/O requests are 1726 granted the resource. The relative priority of asynchronous I/O and synchronous I/O is 1727 implementation-defined. If _POSIX_PRIORITIZED_IO is defined, the implementation shall 1728 define for which files I/O prioritization is supported. 1729 The aio_sigevent determines how the calling process shall be notified upon I/O completion, as 1730 specified in Section 2.4.1 (on page 478). If aio_sigevent.sigev_notify is SIGEV_NONE, then no 1731 signal shall be posted upon I/O completion, but the error status for the operation and the return 1732 status for the operation shall be set appropriately. 1733 The aio_lio_opcode field is used only by the lio_listio ( ) call. The lio_listio ( ) call allows multiple 1734 asynchronous I/O operations to be submitted at a single time. The function takes as an 1735 argument an array of pointers to aiocb structures. Each aiocb structure indicates the operation to 1736 be performed (read or write) via the aio_lio_opcode field. 1737 The address of the aiocb structure is used as a handle for retrieving the error status and return 1738 status of the asynchronous operation while it is in progress. 1739 The aiocb structure and the data buffers associated with the asynchronous I/O operation are 1740 being used by the system for asynchronous I/O while, and only while, the error status of the 1741 asynchronous operation is equal to [EINPROGRESS]. Applications shall not modify the aiocb 1742 structure while the structure is being used by the system for asynchronous I/O. 1743 The return status of the asynchronous operation is the number of bytes transferred by the I/O 1744 operation. If the error status is set to indicate an error completion, then the return status is set to 492 Technical Standard (2001) (Draft April 16, 2001) General Information Realtime 1745 the return value that the corresponding read( ), write( ), or fsync( ) call would have returned. 1746 When the error status is not equal to [EINPROGRESS], the return status shall reflect the return 1747 status of the corresponding synchronous operation. 1748 2.8.3 Memory Management 1749 2.8.3.1 Memory Locking 1750 ML The functionality described in this section is dependent on support of the Process Memory 1751 Locking option (and the rest of this section is not further shaded for this option). 1752 Range memory locking operations are defined in terms of pages. Implementations may restrict 1753 the size and alignment of range lockings to be on page-size boundaries. The page size, in bytes, 1754 is the value of the configurable system variable {PAGESIZE}. If an implementation has no 1755 restrictions on size or alignment, it may specify a 1-byte page size. 1756 Memory locking guarantees the residence of portions of the address space. It is 1757 implementation-defined whether locking memory guarantees fixed translation between virtual 1758 addresses (as seen by the process) and physical addresses. Per-process memory locks are not 1759 inherited across a fork( ), and all memory locks owned by a process are unlocked upon exec or 1760 process termination. Unmapping of an address range removes any memory locks established on 1761 that address range by this process. 1762 2.8.3.2 Memory Mapped Files 1763 MF The functionality described in this section is dependent on support of the Memory Mapped Files 1764 option (and the rest of this section is not further shaded for this option). 1765 Range memory mapping operations are defined in terms of pages. Implementations may 1766 restrict the size and alignment of range mappings to be on page-size boundaries. The page size, 1767 in bytes, is the value of the configurable system variable {PAGESIZE}. If an implementation has 1768 no restrictions on size or alignment, it may specify a 1-byte page size. 1769 Memory mapped files provide a mechanism that allows a process to access files by directly 1770 incorporating file data into its address space. Once a file is mapped into a process address space, 1771 the data can be manipulated as memory. If more than one process maps a file, its contents are 1772 shared among them. If the mappings allow shared write access, then data written into the 1773 memory object through the address space of one process appears in the address spaces of all 1774 processes that similarly map the same portion of the memory object. 1775 SHM Shared memory objects are named regions of storage that may be independent of the file system 1776 and can be mapped into the address space of one or more processes to allow them to share the 1777 associated memory. 1778 SHM An unlink( ) of a file or shm_unlink( ) of a shared memory object,while causing the removal of the 1779 name, does not unmap any mappings established for the object. Once the name has been 1780 removed, the contents of the memory object are preserved as long as it is referenced. The 1781 memory object remains referenced as long as a process has the memory object open or has some 1782 area of the memory object mapped. System Interfaces, Issue 6 493 Realtime General Information 1783 2.8.3.3 Memory Protection 1784 MPR MF The functionality described in this section is dependent on support of the Memory Protection 1785 and Memory Mapped Files option (and the rest of this section is not further shaded for these 1786 options). 1787 When an object is mapped, various application accesses to the mapped region may result in 1788 signals. In this context, SIGBUS is used to indicate an error using the mapped object, and 1789 SIGSEGV is used to indicate a protection violation or misuse of an address: 1790 * A mapping may be restricted to disallow some types of access. 1791 * Write attempts to memory that was mapped without write access, or any access to memory 1792 mapped PROT_NONE, shall result in a SIGSEGV signal. 1793 * References to unmapped addresses shall result in a SIGSEGV signal. 1794 * Reference to whole pages within the mapping, but beyond the current length of the object, 1795 shall result in a SIGBUS signal. 1796 * The size of the object is unaffected by access beyond the end of the object (even if a SIGBUS is 1797 not generated). 1798 2.8.3.4 Typed Memory Objects 1799 TYM The functionality described in this section is dependent on support of the Typed Memory 1800 Objects option (and the rest of this section is not further shaded for this option). 1801 Implementations may support the Typed Memory Objects option without supporting the 1802 Memory Mapped Files option or the Shared Memory Objects option. Typed memory objects are 1803 implementation-configurable named storage pools accessible from one or more processors in a 1804 system, each via one or more ports, such as backplane buses, LANs, I/O channels, and so on. 1805 Each valid combination of a storage pool and a port is identified through a name that is defined 1806 at system configuration time, in an implementation-defined manner; the name may be 1807 independent of the file system. Using this name, a typed memory object can be opened and 1808 mapped into process address space. For a given storage pool and port, it is necessary to support 1809 both dynamic allocation from the pool as well as mapping at an application-supplied offset 1810 within the pool; when dynamic allocation has been performed, subsequent deallocation must be 1811 supported. Lastly, accessing typed memory objects from different ports requires a method for 1812 obtaining the offset and length of contiguous storage of a region of typed memory (dynamically 1813 allocated or not); this allows typed memory to be shared among processes and/or processors 1814 while being accessed from the desired port. 1815 2.8.4 Process Scheduling 1816 PS The functionality described in this section is dependent on support of the Process Scheduling 1817 option (and the rest of this section is not further shaded for this option). 1818 Scheduling Policies 1819 The scheduling semantics described in this volume of IEEE Std 1003.1-200x are defined in terms 1820 of a conceptual model that contains a set of thread lists. No implementation structures are 1821 necessarily implied by the use of this conceptual model. It is assumed that no time elapses 1822 during operations described using this model, and therefore no simultaneous operations are 1823 possible. This model discusses only processor scheduling for runnable threads, but it should be 1824 noted that greatly enhanced predictability of realtime applications results if the sequencing of 1825 other resources takes processor scheduling policy into account. 494 Technical Standard (2001) (Draft April 16, 2001) General Information Realtime 1826 There is, conceptually, one thread list for each priority. A runnable thread will be on the thread | 1827 list for that thread's priority. Multiple scheduling policies shall be provided. Each non-empty | 1828 thread list is ordered, contains a head as one end of its order, and a tail as the other. The purpose 1829 of a scheduling policy is to define the allowable operations on this set of lists (for example, 1830 moving threads between and within lists). 1831 Each process shall be controlled by an associated scheduling policy and priority. These 1832 parameters may be specified by explicit application execution of the sched_setscheduler( ) or 1833 sched_setparam( ) functions. 1834 Each thread shall be controlled by an associated scheduling policy and priority. These 1835 parameters may be specified by explicit application execution of the pthread_setschedparam( ) 1836 function. 1837 Associated with each policy is a priority range. Each policy definition shall specify the minimum 1838 priority range for that policy. The priority ranges for each policy may but need not overlap the 1839 priority ranges of other policies. 1840 A conforming implementation shall select the thread that is defined as being at the head of the 1841 highest priority non-empty thread list to become a running thread, regardless of its associated 1842 policy. This thread is then removed from its thread list. 1843 Four scheduling policies are specifically required. Other implementation-defined scheduling 1844 policies may be defined. The following symbols are defined in the Base Definitions volume of 1845 IEEE Std 1003.1-200x, : 1846 SCHED_FIFO First in, first out (FIFO) scheduling policy. 1847 SCHED_RR Round robin scheduling policy. 1848 SS SCHED_SPORADIC Sporadic server scheduling policy. 1849 SCHED_OTHER Another scheduling policy. 1850 The values of these symbols shall be distinct. 1851 SCHED_FIFO 1852 Conforming implementations shall include a scheduling policy called the FIFO scheduling 1853 policy. 1854 Threads scheduled under this policy are chosen from a thread list that is ordered by the time its 1855 threads have been on the list without being executed; generally, the head of the list is the thread 1856 that has been on the list the longest time, and the tail is the thread that has been on the list the 1857 shortest time. 1858 Under the SCHED_FIFO policy, the modification of the definitional thread lists is as follows: 1859 1. When a running thread becomes a preempted thread, it becomes the head of the thread list 1860 for its priority. 1861 2. When a blocked thread becomes a runnable thread, it becomes the tail of the thread list for 1862 its priority. 1863 3. When a running thread calls the sched_setscheduler( ) function, the process specified in the 1864 function call is modified to the specified policy and the priority specified by the param 1865 argument. 1866 4. When a running thread calls the sched_setparam( ) function, the priority of the process 1867 specified in the function call is modified to the priority specified by the param argument. System Interfaces, Issue 6 495 Realtime General Information 1868 5. When a running thread calls the pthread_setschedparam( ) function, the thread specified in 1869 the function call is modified to the specified policy and the priority specified by the param 1870 argument. 1871 6. When a running thread calls the pthread_setschedprio( ) function, the thread specified in the | 1872 function call is modified to the priority specified by the prio argument. | 1873 7. If a thread whose policy or priority has been modified other than by pthread_setschedprio( ) | 1874 is a running thread or is runnable, it then becomes the tail of the thread list for its new | 1875 priority. | 1876 8. If a thread whose policy or priority has been modified by pthread_setschedprio( ) is a | 1877 running thread or is runnable, the effect on its position in the thread list depends on the | 1878 direction of the modification, as follows: | 1879 a. If the priority is raised, the thread becomes the tail of the thread list. | 1880 b. If the priority is unchanged, the thread does not change position in the thread list. | 1881 c. If the priority is lowered, the thread becomes the head of the thread list. | 1882 9. When a running thread issues the sched_yield( ) function, the thread becomes the tail of the | 1883 thread list for its priority. 1884 10. At no other time is the position of a thread with this scheduling policy within the thread 1885 lists affected. 1886 For this policy, valid priorities shall be within the range returned by the sched_get_priority_max( ) 1887 and sched_get_priority_min( ) functions when SCHED_FIFO is provided as the parameter. 1888 Conforming implementations shall provide a priority range of at least 32 priorities for this 1889 policy. 1890 SCHED_RR 1891 Conforming implementations shall include a scheduling policy called the round robin scheduling | 1892 policy. This policy shall be identical to the SCHED_FIFO policy with the additional condition | 1893 that when the implementation detects that a running thread has been executing as a running 1894 thread for a time period of the length returned by the sched_rr_get_interval( ) function or longer, 1895 the thread shall become the tail of its thread list and the head of that thread list shall be removed 1896 and made a running thread. 1897 The effect of this policy is to ensure that if there are multiple SCHED_RR threads at the same 1898 priority, one of them does not monopolize the processor. An application should not rely only on 1899 the use of SCHED_RR to ensure application progress among multiple threads if the application 1900 includes threads using the SCHED_FIFO policy at the same or higher priority levels or 1901 SCHED_RR threads at a higher priority level. 1902 A thread under this policy that is preempted and subsequently resumes execution as a running 1903 thread completes the unexpired portion of its round robin interval time period. 1904 For this policy, valid priorities shall be within the range returned by the sched_get_priority_max( ) 1905 and sched_get_priority_min( ) functions when SCHED_RR is provided as the parameter. 1906 Conforming implementations shall provide a priority range of at least 32 priorities for this 1907 policy. 496 Technical Standard (2001) (Draft April 16, 2001) General Information Realtime 1908 SCHED_SPORADIC 1909 SS|TSP The functionality described in this section is dependent on support of the Process Sporadic 1910 Server or Thread Sporadic Server options (and the rest of this section is not further shaded for 1911 these options). 1912 If _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER is defined, the 1913 implementation shall include a scheduling policy identified by the value SCHED_SPORADIC. 1914 The sporadic server policy is based primarily on two parameters: the replenishment period and the 1915 available execution capacity. The replenishment period is given by the sched_ss_repl_period 1916 member of the sched_param structure. The available execution capacity is initialized to the 1917 value given by the sched_ss_init_budget member of the same parameter. The sporadic server 1918 policy is identical to the SCHED_FIFO policy with some additional conditions that cause the 1919 thread's assigned priority to be switched between the values specified by the sched_priority and 1920 sched_ss_low_priority members of the sched_param structure. 1921 The priority assigned to a thread using the sporadic server scheduling policy is determined in 1922 the following manner: if the available execution capacity is greater than zero and the number of 1923 pending replenishment operations is strictly less than sched_ss_max_repl, the thread is assigned 1924 the priority specified by sched_priority; otherwise, the assigned priority shall be 1925 sched_ss_low_priority. If the value of sched_priority is less than or equal to the value of 1926 sched_ss_low_priority, the results are undefined. When active, the thread shall belong to the 1927 thread list corresponding to its assigned priority level, according to the mentioned priority 1928 assignment. The modification of the available execution capacity and, consequently of the 1929 assigned priority, is done as follows: 1930 1. When the thread at the head of the sched_priority list becomes a running thread, its 1931 execution time shall be limited to at most its available execution capacity, plus the 1932 resolution of the execution time clock used for this scheduling policy. This resolution shall 1933 be implementation-defined. 1934 2. Each time the thread is inserted at the tail of the list associated with sched_priority- 1935 because as a blocked thread it became runnable with priority sched_priority or because a 1936 replenishment operation was performed-the time at which this operation is done is 1937 posted as the activation_time. 1938 3. When the running thread with assigned priority equal to sched_priority becomes a 1939 preempted thread, it becomes the head of the thread list for its priority, and the execution 1940 time consumed is subtracted from the available execution capacity. If the available 1941 execution capacity would become negative by this operation, it shall be set to zero. 1942 4. When the running thread with assigned priority equal to sched_priority becomes a blocked 1943 thread, the execution time consumed is subtracted from the available execution capacity, 1944 and a replenishment operation is scheduled, as described in 6 and 7. If the available 1945 execution capacity would become negative by this operation, it shall be set to zero. 1946 5. When the running thread with assigned priority equal to sched_priority reaches the limit 1947 imposed on its execution time, it becomes the tail of the thread list for 1948 sched_ss_low_priority, the execution time consumed is subtracted from the available 1949 execution capacity (which becomes zero), and a replenishment operation is scheduled, as 1950 described in 6 and 7. 1951 6. Each time a replenishment operation is scheduled, the amount of execution capacity to be 1952 replenished, replenish_amount, is set equal to the execution time consumed by the thread 1953 since the activation_time. The replenishment is scheduled to occur at activation_time plus 1954 sched_ss_repl_period. If the scheduled time obtained is before the current time, the System Interfaces, Issue 6 497 Realtime General Information 1955 replenishment operation is carried out immediately. Several replenishment operations may 1956 be pending at the same time, each of which will be serviced at its respective scheduled 1957 time. With the above rules, the number of replenishment operations simultaneously 1958 pending for a given thread that is scheduled under the sporadic server policy shall not be 1959 greater than sched_ss_max_repl. 1960 7. A replenishment operation consists of adding the corresponding replenish_amount to the 1961 available execution capacity at the scheduled time. If, as a consequence of this operation, 1962 the execution capacity would become larger than sched_ss_initial_budget, it shall be 1963 rounded down to a value equal to sched_ss_initial_budget. Additionally, if the thread was 1964 runnable or running, and had assigned priority equal to sched_ss_low_priority, then it 1965 becomes the tail of the thread list for sched_priority. 1966 Execution time is defined in Section 2.2.2 (on page 464). 1967 For this policy, changing the value of a CPU-time clock via clock_settime( ) shall have no effect on 1968 its behavior. 1969 For this policy, valid priorities shall be within the range returned by the sched_get_priority_min( ) 1970 and sched_get_priority_max( ) functions when SCHED_SPORADIC is provided as the parameter. 1971 Conforming implementations shall provide a priority range of at least 32 distinct priorities for 1972 this policy. 1973 SCHED_OTHER 1974 Conforming implementations shall include one scheduling policy identified as SCHED_OTHER 1975 (which may execute identically with either the FIFO or round robin scheduling policy). The 1976 effect of scheduling threads with the SCHED_OTHER policy in a system in which other threads 1977 SS are executing under SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC is implementation- 1978 defined. 1979 This policy is defined to allow strictly conforming applications to be able to indicate in a 1980 portable manner that they no longer need a realtime scheduling policy. 1981 For threads executing under this policy, the implementation shall use only priorities within the 1982 range returned by the sched_get_priority_max( ) and sched_get_priority_min( ) functions when 1983 SCHED_OTHER is provided as the parameter. 1984 2.8.5 Clocks and Timers 1985 TMR The functionality described in this section is dependent on support of the Timers option (and the 1986 rest of this section is not further shaded for this option). 1987 The header defines the types and manifest constants used by the timing facility. 1988 Time Value Specification Structures 1989 Many of the timing facility functions accept or return time value specifications. A time value 1990 structure timespec specifies a single time value and includes at least the following members: 1991 _______________________________________________ 1992 _ Member Type Member Name Description ______________________________________________ 1993 time_t tv_sec Seconds. 1994 _ long tv_nsec Nanoseconds. ______________________________________________ 1995 The tv_nsec member is only valid if greater than or equal to zero, and less than the number of 1996 nanoseconds in a second (1,000 million). The time interval described by this structure is (tv_sec * 1997 109 + tv_nsec) nanoseconds. 498 Technical Standard (2001) (Draft April 16, 2001) General Information Realtime 1998 A time value structure itimerspec specifies an initial timer value and a repetition interval for use 1999 by the per-process timer functions. This structure includes at least the following members: 2000 ___________________________________________________ 2001 _ Member Type Member Name Description __________________________________________________ 2002 struct timespec it_interval Timer period. 2003 _ struct timespec it_value Timer expiration. __________________________________________________ 2004 If the value described by it_value is non-zero, it indicates the time to or time of the next timer 2005 expiration (for relative and absolute timer values, respectively). If the value described by it_value 2006 is zero, the timer shall be disarmed. 2007 If the value described by it_interval is non-zero, it specifies an interval which shall be used in | 2008 reloading the timer when it expires; that is, a periodic timer is specified. If the value described by | 2009 it_interval is zero, the timer is disarmed after its next expiration; that is, a one-shot timer is 2010 specified. 2011 Timer Event Notification Control Block 2012 RTS Per-process timers may be created that notify the process of timer expirations by queuing a 2013 realtime extended signal. The sigevent structure, defined in the Base Definitions volume of 2014 IEEE Std 1003.1-200x, , is used in creating such a timer. The sigevent structure 2015 contains the signal number and an application-specific data value which shall be used when | 2016 notifying the calling process of timer expiration events. | 2017 Manifest Constants 2018 The following constants are defined in the Base Definitions volume of IEEE Std 1003.1-200x, 2019 : 2020 CLOCK_REALTIME The identifier for the system-wide realtime clock. 2021 TIMER_ABSTIME Flag indicating time is absolute with respect to the clock associated 2022 with a timer. 2023 MON CLOCK_MONOTONIC The identifier for the system-wide monotonic clock, which is defined 2024 as a clock whose value cannot be set via clock_settime( ) and which 2025 cannot have backward clock jumps. The maximum possible clock 2026 jump is implementation-defined. 2027 MON The maximum allowable resolution for CLOCK_REALTIME and CLOCK_MONOTONIC clocks 2028 and all time services based on these clocks is represented by {_POSIX_CLOCKRES_MIN} and 2029 shall be defined as 20ms (1/50 of a second). Implementations may support smaller values of 2030 resolution for these clocks to provide finer granularity time bases. The actual resolution 2031 supported by an implementation for a specific clock is obtained using the clock_getres( ) function. 2032 If the actual resolution supported for a time service based on one of these clocks differs from the 2033 resolution supported for that clock, the implementation shall document this difference. 2034 MON The minimum allowable maximum value for CLOCK_REALTIME and CLOCK_MONOTONIC 2035 clocks and all absolute time services based on them is the same as that defined by the ISO C 2036 standard for the time_t type. If the maximum value supported by a time service based on one of 2037 these clocks differs from the maximum value supported by that clock, the implementation shall 2038 document this difference. System Interfaces, Issue 6 499 Realtime General Information 2039 Execution Time Monitoring 2040 CPT If _POSIX_CPUTIME is defined, process CPU-time clocks shall be supported in addition to the 2041 clocks described in Manifest Constants (on page 499). 2042 TCT If _POSIX_THREAD_CPUTIME is defined, thread CPU-time clocks shall be supported. 2043 CPT|TCT CPU-time clocks measure execution or CPU time, which is defined in the Base Definitions 2044 volume of IEEE Std 1003.1-200x, Section 3.117, CPU Time (Execution Time). The mechanism 2045 used to measure execution time is described in the Base Definitions volume of | 2046 IEEE Std 1003.1-200x, Section 4.9, Measurement of Execution Time. | 2047 CPT If _POSIX_CPUTIME is defined, the following constant of the type clockid_t is defined in | 2048 : 2049 CLOCK_PROCESS_CPUTIME_ID 2050 When this value of the type clockid_t is used in a clock( ) or timer*( ) function call, it is 2051 interpreted as the identifier of the CPU-time clock associated with the process making the 2052 function call. 2053 2054 TCT If _POSIX_THREAD_CPUTIME is defined, the following constant of the type clockid_t is | 2055 defined in : | 2056 CLOCK_THREAD_CPUTIME_ID 2057 When this value of the type clockid_t is used in a clock( ) or timer*( ) function call, it is 2058 interpreted as the identifier of the CPU-time clock associated with the thread making the 2059 function call. 2060 2.9 Threads 2061 THR The functionality described in this section is dependent on support of the Threads option (and 2062 the rest of this section is not further shaded for this option). 2063 This section defines functionality to support multiple flows of control, called threads, within a 2064 process. For the definition of threads, see the Base Definitions volume of IEEE Std 1003.1-200x, 2065 Section 3.393, Thread. 2066 The specific functional areas covered by threads and their scope include: 2067 * Thread management: the creation, control, and termination of multiple flows of control in the 2068 same process under the assumption of a common shared address space 2069 * Synchronization primitives optimized for tightly coupled operation of multiple control flows 2070 in a common, shared address space 2071 2.9.1 Thread-Safety 2072 All functions defined by this volume of IEEE Std 1003.1-200x shall be thread-safe, except that the 2073 following functions1 need not be thread-safe. 2074 __________________ 2075 1. The functions in the table are not shaded to denote applicable options. Individual reference pages should be consulted. 500 Technical Standard (2001) (Draft April 16, 2001) General Information Threads 2076 asctime( ) ecvt( ) gethostent( ) getutxline( ) putenv( ) ||| 2077 basename( ) encrypt( ) getlogin( ) gmtime( ) pututxline( ) ||| 2078 catgets( ) endgrent( ) getnetbyaddr( ) hcreate( ) rand( ) | 2079 crypt( ) endpwent( ) getnetbyname( ) hdestroy( ) readdir( ) 2080 ctime( ) endutxent( ) getnetent( ) hsearch( ) setenv( ) 2081 dbm_clearerr( ) fcvt( ) getopt( ) inet_ntoa( ) setgrent( ) 2082 dbm_close( ) ftw( ) getprotobyname( ) l64a( ) setkey( ) | 2083 dbm_delete( ) gcvt( ) getprotobynumber( ) lgamma( ) setpwent( ) | 2084 dbm_error( ) getc_unlocked( ) getprotoent( ) localeconv( ) setutxent( ) 2085 dbm_fetch( ) getchar_unlocked( ) getpwent( ) localtime( ) strerror( ) 2086 dbm_firstkey( ) getdate( ) getpwnam( ) lrand48( ) strtok( ) 2087 dbm_nextkey( ) getenv( ) getpwuid( ) mrand48( ) ttyname( ) 2088 dbm_open( ) getgrent( ) getservbyname( ) nftw( ) unsetenv( ) | 2089 dbm_store( ) getgrgid( ) getservbyport( ) nl_langinfo ( ) wcstombs( ) | 2090 dirname( ) getgrnam( ) getservent( ) ptsname( ) wctomb( ) 2091 dlerror( ) gethostbyaddr( ) getutxent( ) putc_unlocked( ) 2092 drand48( ) gethostbyname( ) getutxid( ) putchar_unlocked( ) 2093 The ctermid( ) and tmpnam( ) functions need not be thread-safe if passed a NULL argument. The | 2094 wcrtomb( ) and wcsrtombs( ) functions need not be thread-safe if passed a NULL ps argument. 2095 Implementations shall provide internal synchronization as necessary in order to satisfy this 2096 requirement. 2097 2.9.2 Thread IDs 2098 Although implementations may have thread IDs that are unique in a system, applications 2099 should only assume that thread IDs are usable and unique within a single process. The effect of 2100 calling any of the functions defined in this volume of IEEE Std 1003.1-200x and passing as an 2101 argument the thread ID of a thread from another process is unspecified. A conforming 2102 implementation is free to reuse a thread ID after the thread terminates if it was created with the 2103 detachstate attribute set to PTHREAD_CREATE_DETACHED or if pthread_detach( ) or 2104 pthread_join( ) has been called for that thread. If a thread is detached, its thread ID is invalid for 2105 use as an argument in a call to pthread_detach( ) or pthread_join( ). 2106 2.9.3 Thread Mutexes 2107 A thread that has blocked shall not prevent any unblocked thread that is eligible to use the same 2108 processing resources from eventually making forward progress in its execution. Eligibility for 2109 processing resources is determined by the scheduling policy. 2110 A thread shall become the owner of a mutex, m, when one of the following occurs: | 2111 * It returns successfully from pthread_mutex_lock( ) with m as the mutex argument. 2112 * It returns successfully from pthread_mutex_trylock( ) with m as the mutex argument. 2113 TMO * It returns successfully from pthread_mutex_timedwait( ) with m as the mutex argument. 2114 * It returns (successfully or not) from pthread_cond_wait( ) with m as the mutex argument 2115 (except as explicitly indicated otherwise for certain errors). 2116 * It returns (successfully or not) from pthread_cond_timedwait( ) with m as the mutex argument 2117 (except as explicitly indicated otherwise for certain errors). 2118 The thread shall remain the owner of m until one of the following occurs: | System Interfaces, Issue 6 501 Threads General Information 2119 * It executes pthread_mutex_unlock( ) with m as the mutex argument 2120 * It blocks in a call to pthread_cond_wait( ) with m as the mutex argument. 2121 * It blocks in a call to pthread_cond_timedwait( ) with m as the mutex argument. 2122 The implementation shall behave as if at all times there is at most one owner of any mutex. | 2123 A thread that becomes the owner of a mutex is said to have acquired the mutex and the mutex is 2124 said to have become locked; when a thread gives up ownership of a mutex it is said to have 2125 released the mutex and the mutex is said to have become unlocked. 2126 2.9.4 Thread Scheduling 2127 TPS The functionality described in this section is dependent on support of the Thread Execution 2128 Scheduling option (and the rest of this section is not further shaded for this option). 2129 Thread Scheduling Attributes 2130 In support of the scheduling function, threads have attributes which are accessed through the 2131 pthread_attr_t thread creation attributes object. 2132 The contentionscope attribute defines the scheduling contention scope of the thread to be either 2133 PTHREAD_SCOPE_PROCESS or PTHREAD_SCOPE_SYSTEM. 2134 The inheritsched attribute specifies whether a newly created thread is to inherit the scheduling 2135 attributes of the creating thread or to have its scheduling values set according to the other 2136 scheduling attributes in the pthread_attr_t object. 2137 The schedpolicy attribute defines the scheduling policy for the thread. The schedparam attribute 2138 defines the scheduling parameters for the thread. The interaction of threads having different 2139 policies within a process is described as part of the definition of those policies. 2140 If the Thread Execution Scheduling option is defined, and the schedpolicy attribute specifies one 2141 of the priority-based policies defined under this option, the schedparam attribute contains the 2142 scheduling priority of the thread. A conforming implementation ensures that the priority value 2143 in schedparam is in the range associated with the scheduling policy when the thread attributes 2144 object is used to create a thread, or when the scheduling attributes of a thread are dynamically 2145 modified. The meaning of the priority value in schedparam is the same as that of priority. 2146 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, the schedparam attribute supports four 2147 new members that are used for the sporadic server scheduling policy. These members are 2148 sched_ss_low_priority, sched_ss_repl_period, sched_ss_init_budget, and sched_ss_max_repl. The 2149 meaning of these attributes is the same as in the definitions that appear under Section 2.8.4 (on 2150 page 494). 2151 When a process is created, its single thread has a scheduling policy and associated attributes 2152 equal to the process' policy and attributes. The default scheduling contention scope value is 2153 implementation-defined. The default values of other scheduling attributes are implementation- 2154 defined. 502 Technical Standard (2001) (Draft April 16, 2001) General Information Threads 2155 Thread Scheduling Contention Scope 2156 The scheduling contention scope of a thread defines the set of threads with which the thread 2157 competes for use of the processing resources. The scheduling operation selects at most one 2158 thread to execute on each processor at any point in time and the thread's scheduling attributes 2159 (for example, priority), whether under process scheduling contention scope or system scheduling 2160 contention scope, are the parameters used to determine the scheduling decision. 2161 The scheduling contention scope, in the context of scheduling a mixed scope environment, 2162 affects threads as follows: 2163 * A thread created with PTHREAD_SCOPE_SYSTEM scheduling contention scope contends 2164 for resources with all other threads in the same scheduling allocation domain relative to their 2165 system scheduling attributes. The system scheduling attributes of a thread created with 2166 PTHREAD_SCOPE_SYSTEM scheduling contention scope are the scheduling attributes with 2167 which the thread was created. The system scheduling attributes of a thread created with 2168 PTHREAD_SCOPE_PROCESS scheduling contention scope are the implementation-defined 2169 mapping into system attribute space of the scheduling attributes with which the thread was 2170 created. 2171 * Threads created with PTHREAD_SCOPE_PROCESS scheduling contention scope contend 2172 directly with other threads within their process that were created with 2173 PTHREAD_SCOPE_PROCESS scheduling contention scope. The contention is resolved 2174 based on the threads' scheduling attributes and policies. It is unspecified how such threads 2175 are scheduled relative to threads in other processes or threads with 2176 PTHREAD_SCOPE_SYSTEM scheduling contention scope. 2177 * Conforming implementations shall support the PTHREAD_SCOPE_PROCESS scheduling 2178 contention scope, the PTHREAD_SCOPE_SYSTEM scheduling contention scope, or both. 2179 Scheduling Allocation Domain 2180 Implementations shall support scheduling allocation domains containing one or more 2181 processors. It should be noted that the presence of multiple processors does not automatically 2182 indicate a scheduling allocation domain size greater than one. Conforming implementations on 2183 multi-processors may map all or any subset of the CPUs to one or multiple scheduling allocation 2184 domains, and could define these scheduling allocation domains on a per-thread, per-process, or 2185 per-system basis, depending on the types of applications intended to be supported by the 2186 implementation. The scheduling allocation domain is independent of scheduling contention 2187 scope, as the scheduling contention scope merely defines the set of threads with which a thread 2188 contends for processor resources, while scheduling allocation domain defines the set of 2189 processors for which it contends. The semantics of how this contention is resolved among 2190 threads for processors is determined by the scheduling policies of the threads. 2191 The choice of scheduling allocation domain size and the level of application control over 2192 scheduling allocation domains is implementation-defined. Conforming implementations may 2193 change the size of scheduling allocation domains and the binding of threads to scheduling 2194 allocation domains at any time. 2195 For application threads with scheduling allocation domains of size equal to one, the scheduling 2196 rules defined for SCHED_FIFO and SCHED_RR shall be used; see Scheduling Policies (on page 2197 494). All threads with system scheduling contention scope, regardless of the processes in which 2198 they reside, compete for the processor according to their priorities. Threads with process 2199 scheduling contention scope compete only with other threads with process scheduling 2200 contention scope within their process. System Interfaces, Issue 6 503 Threads General Information 2201 For application threads with scheduling allocation domains of size greater than one, the rules 2202 TSP defined for SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC shall be used in an 2203 implementation-defined manner. Each thread with system scheduling contention scope 2204 competes for the processors in its scheduling allocation domain in an implementation-defined 2205 manner according to its priority. Threads with process scheduling contention scope are 2206 scheduled relative to other threads within the same scheduling contention scope in the process. 2207 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, the rules defined for SCHED_SPORADIC 2208 in Scheduling Policies (on page 494) shall be used in an implementation-defined manner for 2209 application threads whose scheduling allocation domain size is greater than one. 2210 Scheduling Documentation 2211 If _POSIX_PRIORITY_SCHEDULING is defined, then any scheduling policies beyond 2212 TSP SCHED_OTHER, SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC, as well as the effects of 2213 the scheduling policies indicated by these other values, and the attributes required in order to 2214 support such a policy, are implementation-defined. Furthermore, the implementation shall 2215 document the effect of all processor scheduling allocation domain values supported for these 2216 policies. 2217 2.9.5 Thread Cancelation 2218 The thread cancelation mechanism allows a thread to terminate the execution of any other 2219 thread in the process in a controlled manner. The target thread (that is, the one that is being 2220 canceled) is allowed to hold cancelation requests pending in a number of ways and to perform 2221 application-specific cleanup processing when the notice of cancelation is acted upon. 2222 Cancelation is controlled by the cancelation control functions. Each thread maintains its own 2223 cancelability state. Cancelation may only occur at cancelation points or when the thread is 2224 asynchronously cancelable. 2225 The thread cancelation mechanism described in this section depends upon programs having set 2226 deferred cancelability state, which is specified as the default. Applications shall also carefully 2227 follow static lexical scoping rules in their execution behavior. For example, use of setjmp( ), 2228 return, goto, and so on, to leave user-defined cancelation scopes without doing the necessary 2229 scope pop operation results in undefined behavior. 2230 Use of asynchronous cancelability while holding resources which potentially need to be released 2231 may result in resource loss. Similarly, cancelation scopes may only be safely manipulated 2232 (pushed and popped) when the thread is in the deferred or disabled cancelability states. 2233 2.9.5.1 Cancelability States 2234 The cancelability state of a thread determines the action taken upon receipt of a cancelation 2235 request. The thread may control cancelation in a number of ways. 2236 Each thread maintains its own cancelability state, which may be encoded in two bits: 2237 1. Cancelability-Enable: When cancelability is PTHREAD_CANCEL_DISABLE (as defined in 2238 the Base Definitions volume of IEEE Std 1003.1-200x, ), cancelation requests 2239 against the target thread are held pending. By default, cancelability is set to 2240 PTHREAD_CANCEL_ENABLE (as defined in ). 2241 2. Cancelability Type: When cancelability is enabled and the cancelability type is 2242 PTHREAD_CANCEL_ASYNCHRONOUS (as defined in ), new or pending 2243 cancelation requests may be acted upon at any time. When cancelability is enabled and the 2244 cancelability type is PTHREAD_CANCEL_DEFERRED (as defined in ), 504 Technical Standard (2001) (Draft April 16, 2001) General Information Threads 2245 cancelation requests are held pending until a cancelation point (see below) is reached. If 2246 cancelability is disabled, the setting of the cancelability type has no immediate effect as all 2247 cancelation requests are held pending; however, once cancelability is enabled again the 2248 new type is in effect. The cancelability type is PTHREAD_CANCEL_DEFERRED in all 2249 newly created threads including the thread in which main( ) was first invoked. 2250 2.9.5.2 Cancelation Points 2251 Cancelation points shall occur when a thread is executing the following functions: | 2252 accept( ) mq_timedsend( ) putpmsg( ) sigsuspend( ) 2253 aio_suspend( ) msgrcv( ) pwrite( ) sigtimedwait( ) 2254 clock_nanosleep( ) msgsnd( ) read( ) sigwait( ) 2255 close( ) msync( ) readv( ) sigwaitinfo ( ) 2256 connect( ) nanosleep( ) recv( ) sleep( ) 2257 creat( ) open( ) recvfrom( ) system( ) 2258 fcntl( )2 pause( ) recvmsg( ) tcdrain( ) 2259 fsync( ) poll( ) select( ) usleep( ) 2260 getmsg( ) pread( ) sem_timedwait( ) wait( ) 2261 getpmsg( ) pthread_cond_timedwait( ) sem_wait( ) waitid( ) 2262 lockf( ) pthread_cond_wait( ) send( ) waitpid( ) 2263 mq_receive( ) pthread_join( ) sendmsg( ) write( ) 2264 mq_send( ) pthread_testcancel( ) sendto( ) writev( ) 2265 mq_timedreceive( ) putmsg( ) sigpause( ) 2266 __________________ 2267 2. When the cmd argument is F_SETLKW. System Interfaces, Issue 6 505 Threads General Information 2268 A cancelation point may also occur when a thread is executing the following functions: 2269 catclose( ) ftell( ) getwc( ) pthread_rwlock_wrlock( ) 2270 catgets( ) ftello( ) getwchar( ) putc( ) 2271 catopen( ) ftw( ) getwd( ) putc_unlocked( ) 2272 closedir( ) fwprintf( ) glob( ) putchar( ) 2273 closelog( ) fwrite( ) iconv_close( ) putchar_unlocked( ) 2274 ctermid( ) fwscanf( ) iconv_open( ) puts( ) 2275 dbm_close( ) getc( ) ioctl( ) pututxline( ) 2276 dbm_delete( ) getc_unlocked( ) lseek( ) putwc( ) 2277 dbm_fetch( ) getchar( ) mkstemp( ) putwchar( ) 2278 dbm_nextkey( ) getchar_unlocked( ) nftw( ) readdir( ) 2279 dbm_open( ) getcwd( ) opendir( ) readdir_r( ) 2280 dbm_store( ) getdate( ) openlog( ) remove( ) 2281 dlclose( ) getgrent( ) pclose( ) rename( ) 2282 dlopen( ) getgrgid( ) perror( ) rewind( ) 2283 endgrent( ) getgrgid_r( ) popen( ) rewinddir( ) 2284 endhostent( ) getgrnam( ) posix_fadvise ( ) scanf( ) 2285 endnetent( ) getgrnam_r( ) posix_fallocate( ) seekdir( ) 2286 endprotoent( ) gethostbyaddr( ) posix_madvise( ) semop( ) 2287 endpwent( ) gethostbyname( ) posix_spawn( ) setgrent( ) 2288 endservent( ) gethostent( ) posix_spawnp( ) sethostent( ) 2289 endutxent( ) gethostname( ) posix_trace_clear( ) setnetent( ) 2290 fclose( ) getlogin( ) posix_trace_close( ) setprotoent( ) 2291 fcntl( )3 getlogin_r( ) posix_trace_create( ) setpwent( ) 2292 fflush( ) getnetbyaddr( ) posix_trace_create_withlog( ) setservent( ) 2293 fgetc( ) getnetbyname( ) posix_trace_eventtypelist_getnext_id( ) setutxent( ) 2294 fgetpos( ) getnetent( ) posix_trace_eventtypelist_rewind( ) strerror( ) 2295 fgets( ) getprotobyname( ) posix_trace_flush( ) syslog( ) 2296 fgetwc( ) getprotobynumber( ) posix_trace_get_attr( ) tmpfile( ) 2297 fgetws( ) getprotoent( ) posix_trace_get_filter( ) tmpnam( ) 2298 fopen( ) getpwent( ) posix_trace_get_status( ) ttyname( ) 2299 fprintf( ) getpwnam( ) posix_trace_getnext_event( ) ttyname_r( ) 2300 fputc( ) getpwnam_r( ) posix_trace_open( ) ungetc( ) 2301 fputs( ) getpwuid( ) posix_trace_rewind( ) ungetwc( ) 2302 fputwc( ) getpwuid_r( ) posix_trace_set_filter( ) unlink( ) 2303 fputws( ) gets( ) posix_trace_shutdown( ) vfprintf( ) 2304 fread( ) getservbyname( ) posix_trace_timedgetnext_event( ) vfwprintf( ) 2305 freopen( ) getservbyport( ) posix_typed_mem_open( ) vprintf( ) 2306 fscanf( ) getservent( ) printf( ) vwprintf( ) 2307 fseek( ) getutxent( ) pthread_rwlock_rdlock( ) wprintf( ) 2308 fseeko( ) getutxid( ) pthread_rwlock_timedrdlock( ) wscanf( ) 2309 fsetpos( ) getutxline( ) pthread_rwlock_timedwrlock( ) 2310 An implementation shall not introduce cancelation points into any other functions specified in 2311 this volume of IEEE Std 1003.1-200x. 2312 __________________ 2313 3. For any value of the cmd argument. 506 Technical Standard (2001) (Draft April 16, 2001) General Information Threads 2314 The side effects of acting upon a cancelation request while suspended during a call of a function 2315 are the same as the side effects that may be seen in a single-threaded program when a call to a 2316 function is interrupted by a signal and the given function returns [EINTR]. Any such side effects 2317 occur before any cancelation cleanup handlers are called. 2318 Whenever a thread has cancelability enabled and a cancelation request has been made with that 2319 thread as the target, and the thread then calls any function that is a cancelation point (such as 2320 pthread_testcancel( ) or read( )), the cancelation request shall be acted upon before the function 2321 returns. If a thread has cancelability enabled and a cancelation request is made with the thread 2322 as a target while the thread is suspended at a cancelation point, the thread shall be awakened 2323 and the cancelation request shall be acted upon. However, if the thread is suspended at a 2324 cancelation point and the event for which it is waiting occurs before the cancelation request is 2325 acted upon, it is unspecified whether the cancelation request is acted upon or whether the 2326 cancelation request remains pending and the thread resumes normal execution. 2327 2.9.5.3 Thread Cancelation Cleanup Handlers 2328 Each thread maintains a list of cancelation cleanup handlers. The programmer uses the 2329 pthread_cleanup_push( ) and pthread_cleanup_pop( ) functions to place routines on and remove 2330 routines from this list. 2331 When a cancelation request is acted upon, the routines in the list are invoked one by one in LIFO 2332 sequence; that is, the last routine pushed onto the list (Last In) is the first to be invoked (First 2333 Out). The thread invokes the cancelation cleanup handler with cancelation disabled until the last 2334 cancelation cleanup handler returns. When the cancelation cleanup handler for a scope is 2335 invoked, the storage for that scope remains valid. If the last cancelation cleanup handler returns, 2336 thread execution is terminated and a status of PTHREAD_CANCELED is made available to any 2337 threads joining with the target. The symbolic constant PTHREAD_CANCELED expands to a 2338 constant expression of type (void *) whose value matches no pointer to an object in memory nor 2339 the value NULL. 2340 The cancelation cleanup handlers are also invoked when the thread calls pthread_exit( ). 2341 A side effect of acting upon a cancelation request while in a condition variable wait is that the 2342 mutex is re-acquired before calling the first cancelation cleanup handler. In addition, the thread 2343 is no longer considered to be waiting for the condition and the thread shall not have consumed 2344 any pending condition signals on the condition. 2345 A cancelation cleanup handler cannot exit via longjmp( ) or siglongjmp( ). 2346 2.9.5.4 Async-Cancel Safety 2347 The pthread_cancel( ), pthread_setcancelstate( ), and pthread_setcanceltype( ) functions are defined to 2348 be async-cancel safe. 2349 No other functions in this volume of IEEE Std 1003.1-200x are required to be async-cancel-safe. System Interfaces, Issue 6 507 Threads General Information 2350 2.9.6 Thread Read-Write Locks 2351 Multiple readers, single writer (read-write) locks allow many threads to have simultaneous 2352 read-only access to data while allowing only one thread to have exclusive write access at any 2353 given time. They are typically used to protect data that is read more frequently than it is 2354 changed. 2355 One or more readers acquire read access to the resource by performing a read lock operation on 2356 the associated read-write lock. A writer acquires exclusive write access by performing a write 2357 lock operation. Basically, all readers exclude any writers and a writer excludes all readers and 2358 any other writers. 2359 A thread that has blocked on a read-write lock (for example, has not yet returned from a 2360 pthread_rwlock_rdlock( ) or pthread_rwlock_wrlock( ) call) shall not prevent any unblocked thread 2361 that is eligible to use the same processing resources from eventually making forward progress in 2362 its execution. Eligibility for processing resources shall be determined by the scheduling policy. 2363 Read-write locks can be used to synchronize threads in the current process and other processes if 2364 they are allocated in memory that is writable and shared among the cooperating processes and 2365 have been initialized for this behavior. 2366 2.9.7 Thread Interactions with Regular File Operations 2367 All of the functions chmod( ), close( ), fchmod( ), fcntl( ), fstat( ), ftruncate( ), lseek( ), open( ), read( ), 2368 readlink( ), stat( ), symlink( ), and write( ) shall be atomic with respect to each other in the effects 2369 specified in IEEE Std 1003.1-200x when they operate on regular files. If two threads each call one 2370 of these functions, each call shall either see all of the specified effects of the other call, or none of 2371 them. 2372 2.10 Sockets 2373 A socket is an endpoint for communication using the facilities described in this section. A socket 2374 is created with a specific socket type, described in Section 2.10.6 (on page 509), and is associated 2375 with a specific protocol, detailed in Section 2.10.3 (on page 509). A socket is accessed via a file 2376 descriptor obtained when the socket is created. | 2377 2.10.1 Address Families | 2378 All network protocols are associated with a specific address family. An address family provides | 2379 basic services to the protocol implementation to allow it to function within a specific network | 2380 environment. These services may include packet fragmentation and reassembly, routing, | 2381 addressing, and basic transport. An address family is normally comprised of a number of | 2382 protocols, one per socket type. Each protocol is characterized by an abstract socket type. It is not | 2383 required that an address family support all socket types. An address family may contain | 2384 multiple protocols supporting the same socket abstraction. | 2385 Section 2.10.17 (on page 516), Section 2.10.19 (on page 517), and Section 2.10.20 (on page 517), 2386 respectively, describe the use of sockets for local UNIX connections, for Internet protocols based 2387 on IPv4, and for Internet protocols based on IPv6. | 508 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2388 2.10.2 Addressing 2389 An address family defines the format of a socket address. All network addresses are described | 2390 using a general structure, called a sockaddr, as defined in the Base Definitions volume of 2391 IEEE Std 1003.1-200x, . However, each address family imposes finer and more 2392 specific structure, generally defining a structure with fields specific to the address family. The 2393 field sa_family in the sockaddr structure contains the address family identifier, specifying the 2394 format of the sa_data area. The size of the sa_data area is unspecified. | 2395 2.10.3 Protocols | 2396 A protocol supports one of the socket abstractions detailed in Section 2.10.6. Selecting a protocol | 2397 involves specifying the address family, socket type, and protocol number to the socket( ) | 2398 function. Certain semantics of the basic socket abstractions are protocol-specific. All protocols | 2399 are expected to support the basic model for their particular socket type, but may, in addition, | 2400 provide non-standard facilities or extensions to a mechanism. | 2401 2.10.4 Routing 2402 Sockets provides packet routing facilities. A routing information database is maintained, which 2403 is used in selecting the appropriate network interface when transmitting packets. 2404 2.10.5 Interfaces 2405 Each network interface in a system corresponds to a path through which messages can be sent 2406 and received. A network interface usually has a hardware device associated with it, though 2407 certain interfaces such as the loopback interface, do not. 2408 2.10.6 Socket Types 2409 A socket is created with a specific type, which defines the communication semantics and which 2410 RS allows the selection of an appropriate communication protocol. Four types are defined: 2411 SOCK_RAW, SOCK_STREAM, SOCK_SEQPACKET, and SOCK_DGRAM. Implementations 2412 may specify additional socket types. 2413 The SOCK_STREAM socket type provides reliable, sequenced, full-duplex octet streams 2414 between the socket and a peer to which the socket is connected. A socket of type 2415 SOCK_STREAM must be in a connected state before any data may be sent or received. Record 2416 boundaries are not maintained; data sent on a stream socket using output operations of one size 2417 may be received using input operations of smaller or larger sizes without loss of data. Data may 2418 be buffered; successful return from an output function does not imply that the data has been 2419 delivered to the peer or even transmitted from the local system. If data cannot be successfully 2420 transmitted within a given time then the connection is considered broken, and subsequent 2421 operations shall fail. A SIGPIPE signal is raised if a thread sends on a broken stream (one that is 2422 no longer connected). Support for an out-of-band data transmission facility is protocol-specific. 2423 The SOCK_SEQPACKET socket type is similar to the SOCK_STREAM type, and is also 2424 connection-oriented. The only difference between these types is that record boundaries are 2425 maintained using the SOCK_SEQPACKET type. A record can be sent using one or more output 2426 operations and received using one or more input operations, but a single operation never 2427 transfers parts of more than one record. Record boundaries are visible to the receiver via the 2428 MSG_EOR flag in the received message flags returned by the recvmsg( ) function. It is protocol- 2429 specific whether a maximum record size is imposed. 2430 The SOCK_DGRAM socket type supports connectionless data transfer which is not necessarily | 2431 acknowledged or reliable. Datagrams may be sent to the address specified (possibly multicast or | System Interfaces, Issue 6 509 Sockets General Information 2432 broadcast) in each output operation, and incoming datagrams may be received from multiple | 2433 sources. The source address of each datagram is available when receiving the datagram. An | 2434 application may also pre-specify a peer address, in which case calls to output functions shall | 2435 send to the pre-specified peer. If a peer has been specified, only datagrams from that peer shall | 2436 be received. A datagram must be sent in a single output operation, and must be received in a | 2437 single input operation. The maximum size of a datagram is protocol-specific; with some | 2438 protocols, the limit is implementation-defined. Output datagrams may be buffered within the | 2439 system; thus, a successful return from an output function does not guarantee that a datagram is | 2440 actually sent or received. However, implementations should attempt to detect any errors | 2441 possible before the return of an output function, reporting any error by an unsuccessful return | 2442 value. | 2443 RS The SOCK_RAW socket type is similar to the SOCK_DGRAM type. It differs in that it is 2444 normally used with communication providers that underlie those used for the other socket 2445 types. For this reason, the creation of a socket with type SOCK_RAW shall require appropriate 2446 privilege. The format of datagrams sent and received with this socket type generally include 2447 specific protocol headers, and the formats are protocol-specific and implementation-defined. 2448 2.10.7 Socket I/O Mode 2449 The I/O mode of a socket is described by the O_NONBLOCK file status flag which pertains to 2450 the open file description for the socket. This flag is initially off when a socket is created, but may 2451 be set and cleared by the use of the F_SETFL command of the fcntl( ) function. 2452 When the O_NONBLOCK flag is set, functions that would normally block until they are 2453 complete shall either return immediately with an error, or shall complete asynchronously to the 2454 execution of the calling process. Data transfer operations (the read( ), write( ), send( ), and recv( ) 2455 functions) shall complete immediately, transfer only as much as is available, and then return 2456 without blocking, or return an error indicating that no transfer could be made without blocking. 2457 The connect( ) function initiates a connection and shall return without blocking when 2458 O_NONBLOCK is set; it shall return the error [EINPROGRESS] to indicate that the connection 2459 was initiated successfully, but that it has not yet completed. 2460 2.10.8 Socket Owner 2461 The owner of a socket is unset when a socket is created. The owner may be set to a process ID or 2462 process group ID using the F_SETOWN command of the fcntl( ) function. 2463 2.10.9 Socket Queue Limits 2464 The transmit and receive queue sizes for a socket are set when the socket is created. The default 2465 sizes used are both protocol-specific and implementation-defined. The sizes may be changed 2466 using the setsockopt( ) function. 2467 2.10.10 Pending Error 2468 Errors may occur asynchronously, and be reported to the socket in response to input from the 2469 network protocol. The socket stores the pending error to be reported to a user of the socket at the 2470 next opportunity. The error is returned in response to a subsequent send( ), recv( ), or getsockopt( ) 2471 operation on the socket, and the pending error is then cleared. 510 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2472 2.10.11 Socket Receive Queue 2473 A socket has a receive queue that buffers data when it is received by the system until it is 2474 removed by a receive call. Depending on the type of the socket and the communication provider, 2475 the receive queue may also contain ancillary data such as the addressing and other protocol data 2476 associated with the normal data in the queue, and may contain out-of-band or expedited data. 2477 The limit on the queue size includes any normal, out-of-band data, datagram source addresses, 2478 and ancillary data in the queue. The description in this section applies to all sockets, even though 2479 some elements cannot be present in some instances. 2480 The contents of a receive buffer are logically structured as a series of data segments with 2481 associated ancillary data and other information. A data segment may contain normal data or 2482 out-of-band data, but never both. A data segment may complete a record if the protocol 2483 supports records (always true for types SOCK_SEQPACKET and SOCK_DGRAM). A record 2484 may be stored as more than one segment; the complete record might never be present in the 2485 receive buffer at one time, as a portion might already have been returned to the application, and 2486 another portion might not yet have been received from the communications provider. A data 2487 segment may contain ancillary protocol data, which is logically associated with the segment. 2488 Ancillary data is received as if it were queued along with the first normal data octet in the 2489 segment (if any). A segment may contain ancillary data only, with no normal or out-of-band 2490 data. For the purposes of this section, a datagram is considered to be a data segment that 2491 terminates a record, and that includes a source address as a special type of ancillary data. Data 2492 segments are placed into the queue as data is delivered to the socket by the protocol. Normal 2493 data segments are placed at the end of the queue as they are delivered. If a new segment 2494 contains the same type of data as the preceding segment and includes no ancillary data, and if 2495 the preceding segment does not terminate a record, the segments are logically merged into a 2496 single segment. 2497 The receive queue is logically terminated if an end-of-file indication has been received or a 2498 connection has been terminated. A segment shall be considered to be terminated if another 2499 segment follows it in the queue, if the segment completes a record, or if an end-of-file or other 2500 connection termination has been reported. The last segment in the receive queue shall also be 2501 considered to be terminated while the socket has a pending error to be reported. 2502 A receive operation shall never return data or ancillary data from more than one segment. 2503 2.10.12 Socket Out-of-Band Data State 2504 The handling of received out-of-band data is protocol-specific. Out-of-band data may be placed 2505 in the socket receive queue, either at the end of the queue or before all normal data in the queue. 2506 In this case, out-of-band data is returned to an application program by a normal receive call. 2507 Out-of-band data may also be queued separately rather than being placed in the socket receive 2508 queue, in which case it shall be returned only in response to a receive call that requests out-of- 2509 band data. It is protocol-specific whether an out-of-band data mark is placed in the receive 2510 queue to demarcate data preceding the out-of-band data and following the out-of-band data. An 2511 out-of-band data mark is logically an empty data segment that cannot be merged with other 2512 segments in the queue. An out-of-band data mark is never returned in response to an input 2513 operation. The sockatmark( ) function can be used to test whether an out-of-band data mark is the 2514 first element in the queue. If an out-of-band data mark is the first element in the queue when an 2515 input function is called without the MSG_PEEK option, the mark is removed from the queue and 2516 the following data (if any) is processed as if the mark had not been present. System Interfaces, Issue 6 511 Sockets General Information 2517 2.10.13 Connection Indication Queue 2518 Sockets that are used to accept incoming connections maintain a queue of outstanding 2519 connection indications. This queue is a list of connections that are awaiting acceptance by the 2520 application; see listen( ). 2521 2.10.14 Signals 2522 One category of event at the socket interface is the generation of signals. These signals report 2523 protocol events or process errors relating to the state of the socket. The generation or delivery of 2524 a signal does not change the state of the socket, although the generation of the signal may have 2525 been caused by a state change. 2526 The SIGPIPE signal shall be sent to a thread that attempts to send data on a socket that is no 2527 longer able to send. In addition, the send operation fails with the error [EPIPE]. 2528 If a socket has an owner, the SIGURG signal is sent to the owner of the socket when it is notified 2529 of expedited or out-of-band data. The socket state at this time is protocol-dependent, and the 2530 status of the socket is specified in Section 2.10.17 (on page 516), Section 2.10.19 (on page 517), 2531 and Section 2.10.20 (on page 517). Depending on the protocol, the expedited data may or may 2532 not have arrived at the time of signal generation. 2533 2.10.15 Asynchronous Errors 2534 If any of the following conditions occur asynchronously for a socket, the corresponding value 2535 listed below shall become the pending error for the socket: 2536 [ECONNABORTED] 2537 The connection was aborted locally. 2538 [ECONNREFUSED] 2539 For a connection-mode socket attempting a non-blocking connection, the attempt to connect 2540 was forcefully rejected. For a connectionless-mode socket, an attempt to deliver a datagram 2541 was forcefully rejected. 2542 [ECONNRESET] 2543 The peer has aborted the connection. 2544 [EHOSTDOWN] 2545 The destination host has been determined to be down or disconnected. 2546 [EHOSTUNREACH] 2547 The destination host is not reachable. 2548 [EMSGSIZE] 2549 For a connectionless-mode socket, the size of a previously sent datagram prevented 2550 delivery. 2551 [ENETDOWN] 2552 The local network connection is not operational. 2553 [ENETRESET] 2554 The connection was aborted by the network. 2555 [ENETUNREACH] 2556 The destination network is not reachable. 512 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2557 2.10.16 Use of Options 2558 There are a number of socket options which either specialize the behavior of a socket or provide 2559 useful information. These options may be set at different protocol levels and are always present 2560 at the uppermost ``socket'' level. 2561 Socket options are manipulated by two functions, getsockopt( ) and setsockopt( ). These functions 2562 allow an application program to customize the behavior and characteristics of a socket to 2563 provide the desired effect. 2564 All of the options have default values. The type and meaning of these values is defined by the 2565 protocol level to which they apply. Instead of using the default values, an application program 2566 may choose to customize one or more of the options. However, in the bulk of cases, the default 2567 values are sufficient for the application. 2568 Some of the options are used to enable or disable certain behavior within the protocol modules 2569 (for example, turn on debugging) while others may be used to set protocol-specific information 2570 (for example, IP time-to-live on all the application's outgoing packets). As each of the options is 2571 introduced, its effect on the underlying protocol modules is described. 2572 Table 2-1 shows the value for the socket level. 2573 Table 2-1 Value of Level for Socket Options _______________________________________________________ 2574 _ Name Description ______________________________________________________ 2575 _ SOL_SOCKET Options are intended for the sockets level. ______________________________________________________ 2576 Table 2-2 (on page 514) lists those options present at the socket level; that is, when the level 2577 parameter of the getsockopt( ) or setsockopt( ) function is SOL_SOCKET, the types of the option 2578 value parameters associated with each option, and a brief synopsis of the meaning of the option 2579 value parameter. Unless otherwise noted, each may be examined with getsockopt( ) and set with 2580 setsockopt( ) on all types of socket. System Interfaces, Issue 6 513 Sockets General Information 2581 Table 2-2 Socket-Level Options 2582 __________________________________________________________________________________ 2583 _ Option Parameter Type Parameter Meaning _________________________________________________________________________________ 2584 SO_BROADCAST int Non-zero requests permission to transmit ||| 2585 broadcast datagrams (SOCK_DGRAM sockets | 2586 only). | 2587 SO_DEBUG int Non-zero requests debugging in underlying || 2588 protocol modules. | 2589 SO_DONTROUTE int Non-zero requests bypass of normal routing; || 2590 route based on destination address only. | 2591 SO_ERROR int Requests and clears pending error information || 2592 on the socket (getsockopt( ) only). | 2593 SO_KEEPALIVE int Non-zero requests periodic transmission of || 2594 keepalive messages (protocol-specific). | 2595 SO_LINGER struct linger Specify actions to be taken for queued, unsent || 2596 data on close(): linger on/off and linger time in | 2597 seconds. | 2598 SO_OOBINLINE int Non-zero requests that out-of-band data be || 2599 placed into normal data input queue as received. | 2600 SO_RCVBUF int Size of receive buffer (in bytes). || 2601 SO_RCVLOWAT int Minimum amount of data to return to || 2602 application for input operations (in bytes). | 2603 SO_RCVTIMEO struct timeval Timeout value for a socket receive operation. || 2604 SO_REUSEADDR int Non-zero requests reuse of local addresses in || 2605 bind( ) (protocol-specific). | 2606 SO_SNDBUF int Size of send buffer (in bytes). || 2607 SO_SNDLOWAT int Minimum amount of data to send for output || 2608 operations (in bytes). | 2609 SO_SNDTIMEO struct timeval Timeout value for a socket send operation. || 2610 SO_TYPE int Identify socket type (getsockopt( ) only). || _ _________________________________________________________________________________ ||||| 2611 The SO_BROADCAST option requests permission to send broadcast datagrams on the socket. | 2612 Support for SO_BROADCAST is protocol-specific. The default for SO_BROADCAST is that the | 2613 ability to send broadcast datagrams on a socket is disabled. | 2614 The SO_DEBUG option enables debugging in the underlying protocol modules. This can be | 2615 useful for tracing the behavior of the underlying protocol modules during normal system | 2616 operation. The semantics of the debug reports are implementation-defined. The default value for | 2617 SO_DEBUG is for debugging to be turned off. | 2618 The SO_DONTROUTE option requests that outgoing messages bypass the standard routing | 2619 facilities. The destination must be on a directly-connected network, and messages are directed to | 2620 the appropriate network interface according to the destination address. It is protocol-specific | 2621 whether this option has any effect and how the outgoing network interface is chosen. Support | 2622 for this option with each protocol is implementation-defined. | 2623 The SO_ERROR option is used only on getsockopt( ). When this option is specified, getsockopt( ) | 2624 shall return any pending error on the socket and clear the error status. It shall return a value of 0 2625 if there is no pending error. SO_ERROR may be used to check for asynchronous errors on 2626 connected connectionless-mode sockets or for other types of asynchronous errors. SO_ERROR 2627 has no default value. 514 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2628 The SO_KEEPALIVE option enables the periodic transmission of messages on a connected | 2629 socket. The behavior of this option is protocol-specific. The default value for SO_KEEPALIVE is | 2630 zero, specifying that this capability is turned off. | 2631 The SO_LINGER option controls the action of the interface when unsent messages are queued 2632 on a socket and a close( ) is performed. The details of this option are protocol-specific. The 2633 default value for SO_LINGER is zero, or off, for the l_onoff element of the option value and zero 2634 seconds for the linger time specified by the l_linger element. 2635 The SO_OOBINLINE option is valid only on protocols that support out-of-band data. The | 2636 SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue | 2637 as received; it is then accessible using the read( ) or recv( ) functions without the MSG_OOB flag | 2638 set. The default for SO_OOBINLINE is off; that is, for out-of-band data not to be placed in the 2639 normal data input queue. 2640 The SO_RCVBUF option requests that the buffer space allocated for receive operations on this | 2641 socket be set to the value, in bytes, of the option value. Applications may wish to increase buffer | 2642 size for high volume connections, or may decrease buffer size to limit the possible backlog of | 2643 incoming data. The default value for the SO_RCVBUF option value is implementation-defined, | 2644 and may vary by protocol. | 2645 The maximum value for the option for a socket may be obtained by the use of the fpathconf( ) 2646 function, using the value _PC_SOCK_MAXBUF. 2647 The SO_RCVLOWAT option sets the minimum number of bytes to process for socket input | 2648 operations. In general, receive calls block until any (non-zero) amount of data is received, then | 2649 return the smaller of the amount available or the amount requested. The default value for | 2650 SO_RCVLOWAT is 1, and does not affect the general case. If SO_RCVLOWAT is set to a larger | 2651 value, blocking receive calls normally wait until they have received the smaller of the low water | 2652 mark value or the requested amount. Receive calls may still return less than the low water mark | 2653 if an error occurs, a signal is caught, or the type of data next in the receive queue is different | 2654 from that returned (for example, out-of-band data). As mentioned previously, the default value | 2655 for SO_RCVLOWAT is 1 byte. It is implementation-defined whether the SO_RCVLOWAT option | 2656 can be set. | 2657 The SO_RCVTIMEO option is an option to set a timeout value for input operations. It accepts a | 2658 timeval structure with the number of seconds and microseconds specifying the limit on how 2659 long to wait for an input operation to complete. If a receive operation has blocked for this much 2660 time without receiving additional data, it shall return with a partial count or errno shall be set to 2661 [EWOULDBLOCK] if no data were received. The default for this option is the value zero, which 2662 indicates that a receive operation will not timeout. It is implementation-defined whether the 2663 SO_RCVTIMEO option can be set. 2664 The SO_REUSEADDR option indicates that the rules used in validating addresses supplied in a | 2665 bind( ) should allow reuse of local addresses. Operation of this option is protocol-specific. The 2666 default value for SO_REUSEADDR is off; that is, reuse of local addresses is not permitted. 2667 The SO_SNDBUF option requests that the buffer space allocated for send operations on this | 2668 socket be set to the value, in bytes, of the option value. The default value for the SO_SNDBUF | 2669 option value is implementation-defined, and may vary by protocol. The maximum value for the | 2670 option for a socket may be obtained by the use of the fpathconf( ) function, using the value | 2671 _PC_SOCK_MAXBUF. 2672 The SO_SNDLOWAT option sets the minimum number of bytes to process for socket output | 2673 operations. Most output operations process all of the data supplied by the call, delivering data to | 2674 the protocol for transmission and blocking as necessary for flow control. Non-blocking output | 2675 operations process as much data as permitted subject to flow control without blocking, but | System Interfaces, Issue 6 515 Sockets General Information 2676 process no data if flow control does not allow the smaller of the send low water mark value or | 2677 the entire request to be processed. A select( ) operation testing the ability to write to a socket shall | 2678 return true only if the send low water mark could be processed. The default value for 2679 SO_SNDLOWAT is implementation-defined and protocol-specific. It is implementation-defined 2680 whether the SO_SNDLOWAT option can be set. 2681 The SO_SNDTIMEO option is an option to set a timeout value for the amount of time that an | 2682 output function shall block because flow control prevents data from being sent. As noted in | 2683 Table 2-2 (on page 514), the option value is a timeval structure with the number of seconds and 2684 microseconds specifying the limit on how long to wait for an output operation to complete. If a 2685 send operation has blocked for this much time, it shall return with a partial count or errno set to 2686 [EWOULDBLOCK] if no data were sent. The default for this option is the value zero, which 2687 indicates that a send operation will not timeout. It is implementation-defined whether the 2688 SO_SNDTIMEO option can be set. 2689 The SO_TYPE option is used only on getsockopt( ). When this option is specified, getsockopt( ) | 2690 shall return the type of the socket (for example, SOCK_STREAM). This option is useful to 2691 servers that inherit sockets on start-up. SO_TYPE has no default value. 2692 2.10.17 Use of Sockets for Local UNIX Connections 2693 Support for UNIX domain sockets is mandatory. 2694 UNIX domain sockets provide process-to-process communication in a single system. 2695 2.10.17.1 Headers 2696 The symbolic constant AF_UNIX defined in the header is used to identify the | 2697 UNIX domain address family. The header contains other definitions used in | 2698 connection with UNIX domain sockets. See the Base Definitions volume of IEEE Std 1003.1-200x, 2699 Chapter 13, Headers. 2700 The sockaddr_storage structure defined in shall be large enough to 2701 accommodate a sockaddr_un structure (see the header defined in the Base 2702 Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers) and shall be aligned at an 2703 appropriate boundary so that pointers to it can be cast as pointers to sockaddr_un structures 2704 and used to access the fields of those structures without alignment problems. When a 2705 sockaddr_storage structure is cast as a sockaddr_un structure, the ss_family field maps onto the 2706 sun_family field. 2707 2.10.18 Use of Sockets over Internet Protocols 2708 When a socket is created in the Internet family with a protocol value of zero, the implementation 2709 shall use the protocol listed below for the type of socket created. | 2710 SOCK_STREAM IPPROTO_TCP. | 2711 SOCK_DGRAM IPPROTO_UDP. | 2712 RS SOCK_RAW IPPROTO_RAW. | 2713 SOCK_SEQPACKET Unspecified. 2714 RS A raw interface to IP is available by creating an Internet socket of type SOCK_RAW. The default 2715 protocol for type SOCK_RAW shall be identified in the IP header with the value 2716 IPPROTO_RAW. Applications should not use the default protocol when creating a socket with 2717 type SOCK_RAW, but should identify a specific protocol by value. The ICMP control protocol is 2718 accessible from a raw socket by specifying a value of IPPROTO_ICMP for protocol. 516 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2719 2.10.19 Use of Sockets over Internet Protocols Based on IPv4 2720 Support for sockets over Internet protocols based on IPv4 is mandatory. 2721 2.10.19.1 Headers 2722 The symbolic constant AF_INET defined in the header is used to identify the | 2723 IPv4 Internet address family. The header contains other definitions used in | 2724 connection with IPv4 Internet sockets. See the Base Definitions volume of IEEE Std 1003.1-200x, 2725 Chapter 13, Headers. 2726 The sockaddr_storage structure defined in shall be large enough to 2727 accommodate a sockaddr_in structure (see the header defined in the Base 2728 Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers) and shall be aligned at an 2729 appropriate boundary so that pointers to it can be cast as pointers to sockaddr_in structures and 2730 used to access the fields of those structures without alignment problems. When a 2731 sockaddr_storage structure is cast as a sockaddr_in structure, the ss_family field maps onto the 2732 sin_family field. 2733 2.10.20 Use of Sockets over Internet Protocols Based on IPv6 2734 IP6 This section describes extensions to support sockets over Internet protocols based on IPv6. This 2735 functionality is dependent on support of the IPV6 option (and the rest of this section is not 2736 further shaded for this option). 2737 To enable smooth transition from IPv4 to IPv6, the features defined in this section may, in certain 2738 circumstances, also be used in connection with IPv4; see Section 2.10.20.2 (on page 518). 2739 2.10.20.1 Addressing 2740 IPv6 overcomes the addressing limitations of previous versions by using 128-bit addresses 2741 instead of 32-bit addresses. The IPv6 address architecture is described in RFC 2373. 2742 There are three kinds of IPv6 address: 2743 Unicast 2744 Identifies a single interface. 2745 A unicast address can be global, link-local (designed for use on a single link), or site-local 2746 (designed for systems not connected to the Internet). Link-local and site-local addresses 2747 need not be globally unique. 2748 Anycast 2749 Identifies a set of interfaces such that a packet sent to the address can be delivered to any 2750 member of the set. 2751 An anycast address is similar to a unicast address; the nodes to which an anycast address is 2752 assigned must be explicitly configured to know that it is an anycast address. 2753 Multicast 2754 Identifies a set of interfaces such that a packet sent to the address should be delivered to 2755 every member of the set. 2756 An application can send multicast datagrams by simply specifying an IPv6 multicast 2757 address in the address argument of sendto( ). To receive multicast datagrams, an application 2758 must join the multicast group (using setsockopt( ) with IPV6_JOIN_GROUP) and must bind 2759 to the socket the UDP port on which datagrams will be received. Some applications should 2760 also bind the multicast group address to the socket, to prevent other datagrams destined to 2761 that port from being delivered to the socket. System Interfaces, Issue 6 517 Sockets General Information 2762 A multicast address can be global, node-local, link-local, site-local, or organization-local. 2763 The following special IPv6 addresses are defined: 2764 Unspecified 2765 An address that is not assigned to any interface and is used to indicate the absence of an 2766 address. 2767 Loopback 2768 A unicast address that is not assigned to any interface and can be used by a node to send 2769 packets to itself. 2770 Two sets of IPv6 addresses are defined to correspond to IPv4 addresses: 2771 IPv4-compatible addresses 2772 These are assigned to nodes that support IPv6 and can be used when traffic is ``tunneled'' 2773 through IPv4. 2774 IPv4-mapped addresses 2775 These are used to represent IPv4 addresses in IPv6 address format; see Section 2.10.20.2. 2776 Note that the unspecified address and the loopback address must not be treated as IPv4- 2777 compatible addresses. 2778 2.10.20.2 Compatibility with IPv4 2779 The API provides the ability for IPv6 applications to interoperate with applications using IPv4, 2780 by using IPv4-mapped IPv6 addresses. These addresses can be generated automatically by the 2781 getaddrinfo( ) function when the specified host has only IPv4 addresses. 2782 Applications may use AF_INET6 sockets to open TCP connections to IPv4 nodes, or send UDP 2783 packets to IPv4 nodes, by simply encoding the destination's IPv4 address as an IPv4-mapped 2784 IPv6 address, and passing that address, within a sockaddr_in6 structure, in the connect( ), 2785 sendto( ) or sendmsg( ) function. When applications use AF_INET6 sockets to accept TCP 2786 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the system shall return 2787 the peer's address to the application in the accept( ), recvfrom( ), recvmsg( ), or getpeername( ) 2788 function using a sockaddr_in6 structure encoded this way. If a node has an IPv4 address, then 2789 the implementation may allow applications to communicate using that address via an 2790 AF_INET6 socket. In such a case, the address will be represented at the API by the 2791 corresponding IPv4-mapped IPv6 address. Also, the implementation may allow an AF_INET6 2792 socket bound to in6addr_any to receive inbound connections and packets destined to one of the 2793 node's IPv4 addresses. 2794 An application may use AF_INET6 sockets to bind to a node's IPv4 address by specifying the 2795 address as an IPv4-mapped IPv6 address in a sockaddr_in6 structure in the bind( ) function. For 2796 an AF_INET6 socket bound to a node's IPv4 address, the system shall return the address in the 2797 getsockname( ) function as an IPv4-mapped IPv6 address in a sockaddr_in6 structure. 2798 2.10.20.3 Interface Identification 2799 Each local interface is assigned a unique positive integer as a numeric index. Indexes start at 1; 2800 zero is not used. There may be gaps so that there is no current interface for a particular positive 2801 index. Each interface also has a unique implementation-defined name. 518 Technical Standard (2001) (Draft April 16, 2001) General Information Sockets 2802 2.10.20.4 Options 2803 The following options apply at the IPPROTO_IPV6 level: 2804 IPV6_JOIN_GROUP 2805 When set via setsockopt( ), it joins the application to a multicast group on an interface 2806 (identified by its index) and addressed by a given multicast address, enabling packets sent 2807 to that address to be read via the socket. If the interface index is specified as zero, the 2808 system selects the interface (for example, by looking up the address in a routing table and 2809 using the resulting interface). 2810 An attempt to read this option using getsockopt( ) shall result in an [EOPNOTSUPP] error. 2811 The value of this option is an ipv6_mreq structure. 2812 IPV6_LEAVE_GROUP 2813 When set via setsockopt( ), it removes the application from the multicast group on an 2814 interface (identified by its index) and addressed by a given multicast address. 2815 An attempt to read this option using getsockopt( ) shall result in an [EOPNOTSUPP] error. 2816 The value of this option is an ipv6_mreq structure. 2817 IPV6_MULTICAST_HOPS 2818 The value of this option is the hop limit for outgoing multicast IPv6 packets sent via the 2819 socket. Its possible values are the same as those of IPV6_UNICAST_HOPS. If the 2820 IPV6_MULTICAST_HOPS option is not set, a value of 1 is assumed. This option can be set 2821 via setsockopt( ) and read via getsockopt( ). 2822 IPV6_MULTICAST_IF 2823 The index of the interface to be used for outgoing multicast packets. It can be set via 2824 setsockopt( ) and read via getsockopt( ). 2825 IPV6_MULTICAST_LOOP 2826 This option controls whether outgoing multicast packets should be delivered back to the 2827 local application when the sending interface is itself a member of the destination multicast 2828 group. If it is set to 1 they are delivered. If it is set to 0 they are not. Other values result in an 2829 [EINVAL] error. This option can be set via setsockopt( ) and read via getsockopt( ). 2830 IPV6_UNICAST_HOPS 2831 The value of this option is the hop limit for outgoing unicast IPv6 packets sent via the 2832 socket. If the option is not set, or is set to -1, the system selects a default value. Attempts to 2833 set a value less than -1 or greater than 255 shall result in an [EINVAL] error. This option can 2834 be set via setsockopt( ) and read via getsockopt( ). | 2835 IPV6_V6ONLY | 2836 This socket option restricts AF_INET6 sockets to IPv6 communications only. AF_INET6 | 2837 sockets may be used for both IPv4 and IPv6 communications. Some applications may want | 2838 to restrict their use of an AF_INET6 socket to IPv6 communications only. For these | 2839 applications, the IPv6_V6ONLY socket option is defined. When this option is turned on, the | 2840 socket can be used to send and receive IPv6 packets only. This is an IPPROTO_IPV6-level | 2841 option. This option takes an int value. This is a Boolean option. By default, this option is | 2842 turned off. | 2843 An [EOPNOTSUPP] error shall result if IPV6_JOIN_GROUP or IPV6_LEAVE_GROUP is used 2844 with getsockopt( ). System Interfaces, Issue 6 519 Sockets General Information 2845 2.10.20.5 Headers 2846 The symbolic constant AF_INET6 is defined in the header to identify the IPv6 | 2847 Internet address family. See the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 13, 2848 Headers. 2849 The sockaddr_storage structure defined in shall be large enough to 2850 accommodate a sockaddr_in6 structure (see the header defined in the Base 2851 Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers) and shall be aligned at an 2852 appropriate boundary so that pointers to it can be cast as pointers to sockaddr_in6 structures 2853 and used to access the fields of those structures without alignment problems. When a 2854 sockaddr_storage structure is cast as a sockaddr_in6 structure, the ss_family field maps onto the 2855 sin6_family field. 2856 The , , and headers contain other definitions used in 2857 connection with IPv6 Internet sockets; see the Base Definitions volume of IEEE Std 1003.1-200x, 2858 Chapter 13, Headers. 2859 2.11 Tracing 2860 TRC This section describes extensions to support tracing of user applications. This functionality is 2861 dependent on support of the Trace option (and the rest of this section is not further shaded for 2862 this option). 2863 The tracing facilities defined in IEEE Std 1003.1-200x allow a process to select a set of trace event 2864 types, to activate a trace stream of the selected trace events as they occur in the flow of 2865 execution, and to retrieve the recorded trace events. 2866 The tracing operation relies on three logically different components: the traced process, the 2867 controller process, and the analyzer process. During the execution of the traced process, when a 2868 trace point is reached, a trace event is recorded into the trace streams created for that process in 2869 which the associated trace event type identifier is not being filtered out. The controller process 2870 controls the operation of recording the trace events into the trace stream. It shall be able to: 2871 * Initialize the attributes of a trace stream 2872 * Create the trace stream (for a specified traced process) using those attributes 2873 * Start and stop tracing for the trace stream 2874 * Filter the type of trace events to be recorded, if the Trace Event Filter option is supported 2875 * Shut a trace stream down 2876 These operations can be done for an active trace stream. The analyzer process retrieves the 2877 traced events either at runtime, when the trace stream has not yet been shut down, but is still 2878 recording trace events; or after opening a trace log that had been previously recorded and shut 2879 down. These three logically different operations can be performed by the same process, or can be 2880 distributed into different processes. 2881 A trace stream identifier can be created by a call to posix_trace_create( ), 2882 posix_trace_create_withlog( ), or posix_trace_open( ). The posix_trace_create( ) and 2883 posix_trace_create_withlog( ) functions should be used by a controller process. The 2884 posix_trace_open( ) should be used by an analyzer process. 2885 The tracing functions can serve different purposes. One purpose is debugging the possibly pre- 2886 instrumented code, while another is post-mortem fault analysis. These two potential uses differ 2887 in that the first requires pre-filtering capabilities to avoid overwhelming the trace stream and 520 Technical Standard (2001) (Draft April 16, 2001) General Information Tracing 2888 permits focusing on expected information; while the second needs comprehensive trace 2889 capabilities in order to be able to record all types of information. 2890 The events to be traced belong to two classes: 2891 1. User trace events (generated by the application instrumentation) 2892 2. System trace events (generated by the operating system) 2893 The trace interface defines several system trace event types associated with control of and 2894 operation of the trace stream. This small set of system trace events includes the minimum 2895 required to interpret correctly the trace event information present in the stream. Other desirable 2896 system trace events for some particular application profile may be implemented and are 2897 encouraged; for example, process and thread scheduling, signal occurrence, and so on. 2898 Each traced process shall have a mapping of the trace event names to trace event type identifiers 2899 that have been defined for that process. Each active trace stream shall have a mapping that 2900 incorporates all the trace event type identifiers predefined by the trace system plus all the 2901 mappings of trace event names to trace event type identifiers of the processes that are being 2902 traced into that trace stream. These mappings are defined from the instrumented application by 2903 calling the posix_trace_eventid_open( ) function and from the controller process by calling the 2904 posix_trace_trid_eventid_open( ) function. For a pre-recorded trace stream, the list of trace event 2905 types is obtained from the pre-recorded trace log. 2906 The st_ctime and st_mtime fields of a file associated with an active trace stream shall be marked 2907 for update every time any of the tracing operations modifies that file. 2908 The st_atime field of a file associated with a trace stream shall be marked for update every time 2909 any of the tracing operations causes data to be read from that file. 2910 Results are undefined if the application performs any operation on a file descriptor associated 2911 with an active or pre-recorded trace stream until posix_trace_shutdown( ) or posix_trace_close( ) is 2912 called for that trace stream. 2913 The main purpose of this option is to define a complete set of functions and concepts that allow | 2914 a conforming application to be traced from creation to termination, whatever its realtime | 2915 constraints and properties. | 2916 2.11.1 Tracing Data Definitions 2917 2.11.1.1 Structures 2918 The header shall define the posix_trace_status_info and posix_trace_event_info structures 2919 described below. Implementations may add extensions to these structures. 2920 posix_trace_status_info Structure 2921 To facilitate control of a trace stream, information about the current state of an active trace 2922 stream can be obtained dynamically. This structure is returned by a call to the 2923 posix_trace_get_status( ) function. 2924 The posix_trace_status_info structure defined in shall contain at least the following 2925 members: System Interfaces, Issue 6 521 Tracing General Information 2926 ________________________________________________________________________________ 2927 _Member Type Member Name Description _______________________________________________________________________________ 2928 int posix_stream_status The operating mode of the trace stream. 2929 int posix_stream_full_status The full status of the trace stream. 2930 int posix_stream_overrun_status Indicates whether trace events were 2931 lost in the trace stream. ________________________________________________________________________________ 2932 If the Trace Log option is supported in addition to the Trace option, the posix_trace_status_info 2933 structure defined in shall contain at least the following additional members: 2934 _____________________________________________________________________________ 2935 _Member Type Member Name Description ____________________________________________________________________________ 2936 int posix_stream_flush_status Indicates whether a flush is in progress. 2937 int posix_stream_flush_error Indicates whether any error occurred 2938 during the last flush operation. 2939 int posix_log_overrun_status Indicates whether trace events were 2940 lost in the trace log. 2941 _ int posix_log_full_status The full status of the trace log. ____________________________________________________________________________ 2942 The posix_stream_status member indicates the operating mode of the trace stream and shall have 2943 one of the following values defined by manifest constants in the header: 2944 POSIX_TRACE_RUNNING 2945 Tracing is in progress; that is, the trace stream is accepting trace events. 2946 POSIX_TRACE_SUSPENDED 2947 The trace stream is not accepting trace events. The tracing operation has not yet started or 2948 has stopped, either following a posix_trace_stop( ) function call or because the trace resources 2949 are exhausted. 2950 The posix_stream_full_status member indicates the full status of the trace stream, and it shall have 2951 one of the following values defined by manifest constants in the header: 2952 POSIX_TRACE_FULL 2953 The space in the trace stream for trace events is exhausted. 2954 POSIX_TRACE_NOT_FULL 2955 There is still space available in the trace stream. 2956 The combination of the posix_stream_status and posix_stream_full_status members also indicates 2957 the actual status of the stream. The status shall be interpreted as follows: 2958 POSIX_TRACE_RUNNING and POSIX_TRACE_NOT_FULL 2959 This status combination indicates that tracing is in progress, and there is space available for 2960 recording more trace events. 2961 POSIX_TRACE_RUNNING and POSIX_TRACE_FULL 2962 This status combination indicates that tracing is in progress and that the trace stream is full 2963 of trace events. This status combination cannot occur unless the stream-full-policy is set to 2964 POSIX_TRACE_LOOP. The trace stream contains trace events recorded during a moving 2965 time window of prior trace events, and some older trace events may have been overwritten 2966 and thus lost. 2967 POSIX_TRACE_SUSPENDED and POSIX_TRACE_NOT_FULL 2968 This status combination indicates that tracing has not yet been started, has been stopped by 2969 the posix_trace_stop( ) function, or has been cleared by the posix_trace_clear( ) function. 522 Technical Standard (2001) (Draft April 16, 2001) General Information Tracing 2970 POSIX_TRACE_SUSPENDED and POSIX_TRACE_FULL 2971 This status combination indicates that tracing has been stopped by the implementation 2972 because the stream-full-policy attribute was POSIX_TRACE_UNTIL_FULL and trace 2973 resources were exhausted, or that the trace stream was stopped by the function 2974 posix_trace_stop( ) at a time when trace resources were exhausted. 2975 The posix_stream_overrun_status member indicates whether trace events were lost in the trace 2976 stream, and shall have one of the following values defined by manifest constants in the 2977 header: 2978 POSIX_TRACE_OVERRUN 2979 At least one trace event was lost and thus was not recorded in the trace stream. 2980 POSIX_TRACE_NO_OVERRUN 2981 No trace events were lost. 2982 When the corresponding trace stream is created, the posix_stream_overrun_status member shall be 2983 set to POSIX_TRACE_NO_OVERRUN. 2984 Whenever an overrun occurs, posix_stream_overrun_status member shall be set to 2985 POSIX_TRACE_OVERRUN. 2986 An overrun occurs when: 2987 * The policy is POSIX_TRACE_LOOP and a recorded trace event is overwritten. 2988 * The policy is POSIX_TRACE_UNTIL_FULL and the trace stream is full when a trace event is 2989 generated. 2990 * If the Trace Log option is supported, the policy is POSIX_TRACE_FLUSH and at least one 2991 trace event is lost while flushing the trace stream to the trace log. 2992 The posix_stream_overrun_status member is reset to zero after its value is read. 2993 If the Trace Log option is supported in addition to the Trace option, the posix_stream_flush_status, 2994 posix_stream_flush_error, posix_log_overrun_status, and posix_log_full_status members are defined 2995 as follows; otherwise, they are undefined. 2996 The posix_stream_flush_status member indicates whether a flush operation is being performed 2997 and shall have one of the following values defined by manifest constants in the header 2998 : 2999 POSIX_TRACE_FLUSHING 3000 The trace stream is currently being flushed to the trace log. 3001 POSIX_TRACE_NOT_FLUSHING 3002 No flush operation is in progress. 3003 The posix_stream_flush_status member shall be set to POSIX_TRACE_FLUSHING if a flush 3004 operation is in progress either due to a call to the posix_trace_flush( ) function (explicit or caused 3005 by a trace stream shutdown operation) or because the trace stream has become full with the 3006 stream-full-policy attribute set to POSIX_TRACE_FLUSH. The posix_stream_flush_status member 3007 shall be set to POSIX_TRACE_NOT_FLUSHING if no flush operation is in progress. 3008 The posix_stream_flush_error member shall be set to zero if no error occurred during flushing. If 3009 an error occurred during a previous flushing operation, the posix_stream_flush_error member 3010 shall be set to the value of the first error that occurred. If more than one error occurs while 3011 flushing, error values after the first shall be discarded. The posix_stream_flush_error member is 3012 reset to zero after its value is read. System Interfaces, Issue 6 523 Tracing General Information 3013 The posix_log_overrun_status member indicates whether trace events were lost in the trace log, 3014 and shall have one of the following values defined by manifest constants in the 3015 header: 3016 POSIX_TRACE_OVERRUN 3017 At least one trace event was lost. 3018 POSIX_TRACE_NO_OVERRUN 3019 No trace events were lost. 3020 When the corresponding trace stream is created, the posix_log_overrun_status member shall be set 3021 to POSIX_TRACE_NO_OVERRUN. Whenever an overrun occurs, this status shall be set to 3022 POSIX_TRACE_OVERRUN. The posix_log_overrun_status member is reset to zero after its value 3023 is read. 3024 The posix_log_full_status member indicates the full status of the trace log, and it shall have one of 3025 the following values defined by manifest constants in the header: 3026 POSIX_TRACE_FULL 3027 The space in the trace log is exhausted. 3028 POSIX_TRACE_NOT_FULL 3029 There is still space available in the trace log. 3030 The posix_log_full_status member is only meaningful if the log-full-policy attribute is either 3031 POSIX_TRACE_UNTIL_FULL or POSIX_TRACE_LOOP. 3032 For an active trace stream without log, that is created by the posix_trace_create( ) function, the 3033 posix_log_overrun_status member shall be set to POSIX_TRACE_NO_OVERRUN and the 3034 posix_log_full_status member shall be set to POSIX_TRACE_NOT_FULL. 3035 posix_trace_event_info Structure 3036 The trace event structure posix_trace_event_info contains the information for one recorded 3037 trace event. This structure is returned by the set of functions posix_trace_getnext_event( ), 3038 posix_trace_timedgetnext_event( ), and posix_trace_trygetnext_event( ). 3039 The posix_trace_event_info structure defined in shall contain at least the following 3040 members: 3041 ____________________________________________________________________________________ 3042 _ Member Type Member Name Description ___________________________________________________________________________________ 3043 trace_event_id_t posix_event_id Trace event type identification. 3044 pid_t posix_pid Process ID of the process that generated the 3045 trace event. 3046 void * posix_prog_address Address at which the trace point was invoked. 3047 int posix_truncation_status Status about the truncation of the data 3048 associated with this trace event. 3049 _ struct timespec posix_timestamp Time at which the trace event was generated. ___________________________________________________________________________________ 3050 In addition, if the Trace option and the Threads option are both supported, the 3051 posix_trace_event_info structure defined in shall contain the following additional 3052 member: 524 Technical Standard (2001) (Draft April 16, 2001) General Information Tracing 3053 _______________________________________________________ 3054 _ Member Type Member Name Description ______________________________________________________ 3055 pthread_t posix_thread_id Thread ID of the thread 3056 that generated the trace 3057 event. _ ______________________________________________________ 3058 The posix_event_id member represents the identification of the trace event type and its value is 3059 not directly defined by the user. This identification is returned by a call to one of the following 3060 functions: posix_trace_trid_eventid_open( ), posix_trace_eventtypelist_getnext_id( ), or 3061 posix_trace_eventid_open( ). The name of the trace event type can be obtained by calling 3062 posix_trace_eventid_get_name( ). 3063 The posix_pid is the process identifier of the traced process which generated the trace event. If 3064 the posix_event_id member is one of the implementation-defined system trace events and that 3065 trace event is not associated with any process, the posix_pid member shall be set to zero. 3066 For a user trace event, the posix_prog_address member is the process mapped address of the point 3067 at which the associated call to the posix_trace_event( ) function was made. For a system trace 3068 event, if the trace event is caused by a system service explicitly called by the application, the 3069 posix_prog_address member shall be the address of the process at the point where the call to that 3070 system service was made. 3071 The posix_truncation_status member defines whether the data associated with a trace event has 3072 been truncated at the time the trace event was generated, or at the time the trace event was read 3073 from the trace stream, or (if the Trace Log option is supported) from the trace log (see the event 3074 argument from the posix_trace_getnext_event( ) function). The posix_truncation_status member 3075 shall have one of the following values defined by manifest constants in the header: 3076 POSIX_TRACE_NOT_TRUNCATED 3077 All the traced data is available. 3078 POSIX_TRACE_TRUNCATED_RECORD 3079 Data was truncated at the time the trace event was generated. 3080 POSIX_TRACE_TRUNCATED_READ 3081 Data was truncated at the time the trace event was read from a trace stream or a trace log 3082 because the reader's buffer was too small. This truncation status overrides the 3083 POSIX_TRACE_TRUNCATED_RECORD status. 3084 The posix_timestamp member shall be the time at which the trace event was generated. The clock 3085 used is implementation-defined, but the resolution of this clock can be retrieved by a call to the 3086 posix_trace_attr_getclockres( ) function. 3087 If the Threads option is supported in addition to the Trace option: 3088 * The posix_thread_id member is the identifier of the thread that generated the trace event. If 3089 the posix_event_id member is one of the implementation-defined system trace events and that 3090 trace event is not associated with any thread, the posix_thread_id member shall be set to zero. 3091 Otherwise, this member is undefined. 3092 2.11.1.2 Trace Stream Attributes 3093 Trace streams have attributes that compose the posix_trace_attr_t trace stream attributes object. 3094 This object shall contain at least the following attributes: 3095 * The generation-version attribute identifies the origin and version of the trace system. System Interfaces, Issue 6 525 Tracing General Information 3096 * The trace-name attribute is a character string defined by the trace controller, and that 3097 identifies the trace stream. 3098 * The creation-time attribute represents the time of the creation of the trace stream. 3099 * The clock-resolution attribute defines the clock resolution of the clock used to generate 3100 timestamps. 3101 * The stream-min-size attribute defines the minimum size in bytes of the trace stream strictly 3102 reserved for the trace events. 3103 * The stream-full-policy attribute defines the policy followed when the trace stream is full; its 3104 value is POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or POSIX_TRACE_FLUSH. 3105 * The max-data-size attribute defines the maximum record size in bytes of a trace event. 3106 In addition, if the Trace option and the Trace Inherit option are both supported, the 3107 posix_trace_attr_t trace stream creation attributes object shall contain at least the following 3108 attributes: 3109 * The inheritance attribute specifies whether a newly created trace stream will inherit tracing in 3110 its parent's process trace stream. It is either POSIX_TRACE_INHERITED or 3111 POSIX_TRACE_CLOSE_FOR_CHILD. 3112 In addition, if the Trace option and the Trace Log option are both supported, the 3113 posix_trace_attr_t trace stream creation attributes object shall contain at least the following 3114 attribute: 3115 * If the file type corresponding to the trace log supports the POSIX_TRACE_LOOP or the 3116 POSIX_TRACE_UNTIL_FULL policies, the log-max-size attribute defines the maximum size 3117 in bytes of the trace log associated with an active trace stream. Other stream data-for 3118 example, trace attribute values-shall not be included in this size. 3119 * The log-full-policy attribute defines the policy of a trace log associated with an active trace 3120 stream to be POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or 3121 POSIX_TRACE_APPEND. 3122 2.11.2 Trace Event Type Definitions 3123 2.11.2.1 System Trace Event Type Definitions 3124 The following system trace event types, defined in the header, track the invocation of 3125 the trace operations: 3126 * POSIX_TRACE_START shall be associated with a trace start operation. 3127 * POSIX_TRACE_STOP shall be associated with a trace stop operation. 3128 * if the Trace Event Filter option is supported, POSIX_TRACE_FILTER shall be associated with 3129 a trace event type filter change operation. 3130 The following system trace event types, defined in the header, report operational trace 3131 events: 3132 * POSIX_TRACE_OVERFLOW shall mark the beginning of a trace overflow condition. 3133 * POSIX_TRACE_RESUME shall mark the end of a trace overflow condition. 3134 * If the Trace Log option is supported, POSIX_TRACE_FLUSH_START shall mark the 3135 beginning of a flush operation. 526 Technical Standard (2001) (Draft April 16, 2001) General Information Tracing 3136 * If the Trace Log option is supported, POSIX_TRACE_FLUSH_STOP shall mark the end of a 3137 flush operation. 3138 * If an implementation-defined trace error condition is reported, it shall be marked 3139 POSIX_TRACE_ERROR. 3140 The interpretation of a trace stream or a trace log by a trace analyzer process relies on the 3141 information recorded for each trace event, and also on system trace events that indicate the 3142 invocation of trace control operations and trace system operational trace events. 3143 The POSIX_TRACE_START and POSIX_TRACE_STOP trace events specify the time windows 3144 during which the trace stream is running. 3145 The POSIX_TRACE_STOP trace event with an associated data that is equal to zero indicates 3146 a call of the function posix_trace_stop( ). 3147 The POSIX_TRACE_STOP trace event with an associated data that is different from zero 3148 indicates an automatic stop of the trace stream (see posix_trace_attr_getstreamfullpolicy( ) 3149 defined in the System Interfaces volume of IEEE Std 1003.1-200x). 3150 The POSIX_TRACE_FILTER trace event indicates that a trace event type filter value changed 3151 while the trace stream was running. 3152 The POSIX_TRACE_ERROR serves to inform the analyzer process that an implementation- 3153 defined internal error of the trace system occurred. 3154 The POSIX_TRACE_OVERFLOW trace event shall be reported with a timestamp equal to the 3155 timestamp of the first trace event overwritten. This is an indication that some generated trace 3156 events have been lost. 3157 The POSIX_TRACE_RESUME trace event shall be reported with a timestamp equal to the 3158 timestamp of the first valid trace event reported after the overflow condition ends and shall be 3159 reported before this first valid trace event. This is an indication that the trace system is reliably 3160 recording trace events after an overflow condition. 3161 Each of these trace event types shall be defined by a constant trace event name and a 3162 trace_event_id_t constant; trace event data is associated with some of these trace events. 3163 If the Trace option is supported and the Trace Event Filter option and the Trace Log option are 3164 not supported, the following predefined system trace events in Table 2-3 shall be defined: 3165 Table 2-3 Trace Option: System Trace Events ____________________________________________________________________ 3166 Event Name Constant _ Associated Data _________________ 3167 _ Data Type ___________________________________________________________________ 3168 posix_trace_error POSIX_TRACE_ERROR _ error _________________ || 3169 _ int ___________________________________________________________________ 3170 _ posix_trace_start POSIX_TRACE_START None. ___________________________________________________________________ || 3171 posix_trace_stop POSIX_TRACE_STOP _ auto _________________ || 3172 _ int ___________________________________________________________________ 3173 _ posix_trace_overflow POSIX_TRACE_OVERFLOW None. ___________________________________________________________________ || 3174 _ posix_trace_resume POSIX_TRACE_RESUME None. ___________________________________________________________________ || 3175 If the Trace option and the Trace Event Filter option are both supported, and if the Trace Log 3176 option is not supported, the following predefined system trace events in Table 2-4 (on page 528) 3177 shall be defined: System Interfaces, Issue 6 527 Tracing General Information 3178 Table 2-4 Trace and Trace Event Filter Options: System Trace Events _____________________________________________________________________ 3179 Event Name Constant _ Associated Data _________________ 3180 _ Data Type ____________________________________________________________________ 3181 posix_trace_error POSIX_TRACE_ERROR _ error _________________ || 3182 _ int ____________________________________________________________________ 3183 posix_trace_start POSIX_TRACE_START _ event_filter _________________ || 3184 _ trace_event_set_t ____________________________________________________________________ 3185 posix_trace_stop POSIX_TRACE_STOP _ auto _________________ | | 3186 _ int ____________________________________________________________________ 3187 posix_trace_filter POSIX_TRACE_FILTER old_event_filter | 3188 _ new_event_filter _________________ | 3189 _ trace_event_set_t ____________________________________________________________________ 3190 _ posix_trace_overflow POSIX_TRACE_OVERFLOW None. ____________________________________________________________________ || 3191 _ posix_trace_resume POSIX_TRACE_RESUME None. ____________________________________________________________________ || 3192 If the Trace option and the Trace Log option are both supported, and if the Trace Event Filter 3193 option is not supported, the following predefined system trace events in Table 2-5 shall be 3194 defined: 3195 Table 2-5 Trace and Trace Log Options: System Trace Events ________________________________________________________________________ 3196 Event Name Constant _ Associated Data _________________ 3197 _ Data Type _______________________________________________________________________ 3198 posix_trace_error POSIX_TRACE_ERROR error | 3199 - | 3200 _ int _______________________________________________________________________ 3201 _ posix_trace_start POSIX_TRACE_START None. _______________________________________________________________________ || 3202 posix_trace_stop POSIX_TRACE_STOP _ auto _________________ || 3203 _ int _______________________________________________________________________ 3204 _ posix_trace_overflow POSIX_TRACE_OVERFLOW None. _______________________________________________________________________ || 3205 _ posix_trace_resume POSIX_TRACE_RESUME None. _______________________________________________________________________ || 3206 _ posix_trace_flush_start POSIX_TRACE_FLUSH_START None. _______________________________________________________________________ || 3207 _ posix_trace_flush_stop POSIX_TRACE_FLUSH_STOP None. _______________________________________________________________________ || 3208 If the Trace option, the Trace Event Filter option, and the Trace Log option are all supported, the 3209 following predefined system trace events in Table 2-6 (on page 529) shall be defined: 528 Technical Standard (2001) (Draft April 16, 2001) General Information Tracing 3210 Table 2-6 Trace, Trace Log, and Trace Event Filter Options: System Trace Events ________________________________________________________________________ 3211 Event Name Constant _ Associated Data _________________ 3212 Data Type ________________________________________________________________________ 3213 posix_trace_error POSIX_TRACE_ERROR _ error _________________ || 3214 int ________________________________________________________________________ 3215 posix_trace_start POSIX_TRACE_START _ event_filter _________________ || 3216 trace_event_set_t ________________________________________________________________________ 3217 posix_trace_stop POSIX_TRACE_STOP _ auto _________________ | | 3218 int ________________________________________________________________________ 3219 posix_trace_filter POSIX_TRACE_FILTER old_event_filter | 3220 _ new_event_filter _________________ | 3221 trace_event_set_t ________________________________________________________________________ 3222 posix_trace_overflow POSIX_TRACE_OVERFLOW None. ________________________________________________________________________ || 3223 posix_trace_resume POSIX_TRACE_RESUME None. ________________________________________________________________________ || 3224 posix_trace_flush_start POSIX_TRACE_FLUSH_START None. ________________________________________________________________________ || 3225 posix_trace_flush_stop POSIX_TRACE_FLUSH_STOP None. ________________________________________________________________________ || 3226 2.11.2.2 User Trace Event Type Definitions 3227 The user trace event POSIX_TRACE_UNNAMED_USEREVENT is defined in the | 3228 header. If the limit of per-process user trace event names represented by 3229 {TRACE_USER_EVENT_MAX} has already been reached, this predefined user event shall be 3230 returned when the application tries to register more events than allowed. The data associated 3231 with this trace event is application-defined. 3232 The following predefined user trace event in Table 2-7 shall be defined: 3233 Table 2-7 Trace Option: User Trace Event _________________________________________________________________________ 3234 _ Event Name Constant ________________________________________________________________________ 3235 _ posix_trace_unnamed_userevent POSIX_TRACE_UNNAMED_USEREVENT ________________________________________________________________________ || 3236 2.11.3 Trace Functions 3237 The trace interface is built and structured to improve portability through use of trace data of 3238 opaque type. The object-oriented approach for the manipulation of trace attributes and trace 3239 event type identifiers requires definition of many constructor and selector functions which 3240 operate on these opaque types. Also, the trace interface must support several different tracing 3241 roles. To facilitate reading the trace interface, the trace functions are grouped into small 3242 functional sets supporting the three different roles: 3243 * A trace controller process requires functions to set up and customize all the resources needed 3244 to run a trace stream, including: 3245 - Attribute initialization and destruction (posix_trace_attr_init( )) 3246 - Identification information manipulation (posix_trace_attr_getgenversion( )) 3247 - Trace system behavior modification (posix_trace_attr_getinherited( )) 3248 - Trace stream and trace log size set (posix_trace_attr_getmaxusereventsize( )) System Interfaces, Issue 6 529 Tracing General Information 3249 - Trace stream creation, flush, and shutdown (posix_trace_create( )) 3250 - Trace stream and trace log clear (posix_trace_clear( )) 3251 - Trace event type identifier manipulation (posix_trace_trid_eventid_open( )) 3252 - Trace event type identifier list exploration (posix_trace_eventtypelist_getnext_id( )) 3253 - Trace event type set manipulation (posix_trace_eventset_empty( )) 3254 - Trace event type filter set (posix_trace_set_filter( )) 3255 - Trace stream start and stop (posix_trace_start( )) 3256 - Trace stream information and status read (posix_trace_get_attr( )) 3257 * A traced process requires functions to instrument trace points: 3258 - Trace event type identifiers definition and trace points insertion (posix_trace_event( )) 3259 * A trace analyzer process requires functions to retrieve information from a trace stream and 3260 trace log: 3261 - Identification information read (posix_trace_attr_getgenversion( )) 3262 - Trace system behavior information read (posix_trace_attr_getinherited( )) 3263 - Trace stream and trace log size get (posix_trace_attr_getmaxusereventsize( )) 3264 - Trace event type identifier manipulation (posix_trace_trid_eventid_open( )) 3265 - Trace event type identifier list exploration (posix_trace_eventtypelist_getnext_id( )) 3266 - Trace log open, rewind, and close (posix_trace_open( )) 3267 - Trace stream information and status read (posix_trace_get_attr( )) 3268 - trace event read (posix_trace_getnext_event( )) 3269 2.12 Data Types 3270 All of the data types used by various functions are defined by the implementation. The 3271 following table describes some of these types. Other types referenced in the description of a 3272 function, not mentioned here, can be found in the appropriate header for that function. 3273 ___________________________________________________________________________________ 3274 _ Defined Type Description __________________________________________________________________________________ 3275 cc_t Type used for terminal special characters. 3276 clock_t Arithmetic type used for processor times, as defined in the ISO C 3277 standard. 3278 clockid_t Used for clock ID type in some timer functions. 3279 dev_t Arithmetic type used for device numbers. 3280 DIR Type representing a directory stream. 3281 div_t Structure type returned by the div( ) function. 3282 FILE Structure containing information about a file. 3283 glob_t Structure type used in pathname pattern matching. | 3284 _ fpos_t Type containing all information needed to specify uniquely every __________________________________________________________________________________ | 530 Technical Standard (2001) (Draft April 16, 2001) General Information Data Types 3285 ___________________________________________________________________________________ 3286 _ Defined Type Description __________________________________________________________________________________ 3287 position within a file. 3288 gid_t Arithmetic type used for group IDs. 3289 iconv_t Type used for conversion descriptors. 3290 id_t Arithmetic type used as a general identifier; can be used to contain 3291 at least the largest of a pid_t, uid_t, or gid_t. 3292 ino_t Arithmetic type used for file serial numbers. 3293 key_t Arithmetic type used for XSI interprocess communication. 3294 ldiv_t Structure type returned by the ldiv( ) function. 3295 mode_t Arithmetic type used for file attributes. 3296 mqd_t Used for message queue descriptors. 3297 nfds_t Integer type used for the number of file descriptors. 3298 nlink_t Arithmetic type used for link counts. 3299 off_t Signed arithmetic type used for file sizes. 3300 pid_t Signed arithmetic type used for process and process group IDs. 3301 pthread_attr_t Used to identify a thread attribute object. 3302 pthread_cond_t Used for condition variables. 3303 pthread_condattr_t Used to identify a condition attribute object. 3304 pthread_key_t Used for thread-specific data keys. 3305 pthread_mutex_t Used for mutexes. 3306 pthread_mutexattr_t Used to identify a mutex attribute object. 3307 pthread_once_t Used for dynamic package initialization. 3308 pthread_rwlock_t Used for read-write locks. 3309 pthread_rwlockattr_t Used for read-write lock attributes. 3310 pthread_t Used to identify a thread. 3311 ptrdiff_t Signed integer type of the result of subtracting two pointers. 3312 regex_t Structure type used in regular expression matching. 3313 regmatch_t Structure type used in regular expression matching. 3314 rlim_t Unsigned arithmetic type used for limit values, to which objects of 3315 type int and off_t can be cast without loss of value. 3316 sem_t Type used in performing semaphore operations. 3317 sig_atomic_t Integer type of an object that can be accessed as an atomic 3318 entity, even in the presence of asynchronous interrupts. 3319 sigset_t Integer or structure type of an object used to represent sets 3320 of signals. 3321 size_t Unsigned integer type used for size of objects. 3322 speed_t Type used for terminal baud rates. 3323 ssize_t Arithmetic type used for a count of bytes or an error indication. 3324 suseconds_t Signed arithmetic type used for time in microseconds. 3325 tcflag_t Type used for terminal modes. 3326 time_t Arithmetic type used for time in seconds, as defined in the ISO C 3327 standard. 3328 timer_t Used for timer ID returned by the timer_create( ) function. 3329 uid_t Arithmetic type used for user IDs. 3330 useconds_t Integer type used for time in microseconds. 3331 va_list Type used for traversing variable argument lists. 3332 wchar_t Integer type whose range of values can represent distinct codes for 3333 _ all members of the largest extended character set specified by the __________________________________________________________________________________ System Interfaces, Issue 6 531 Data Types General Information 3334 ___________________________________________________________________________________ 3335 _ Defined Type Description __________________________________________________________________________________ 3336 supported locales. 3337 wctype_t Scalar type which represents a character class descriptor. 3338 wint_t Integer type capable of storing any valid value of wchar_t or 3339 WEOF. 3340 _ wordexp_t Structure type used in word expansion. __________________________________________________________________________________ 3341 | 532 Technical Standard (2001) (Draft April 16, 2001) Chapter 3 System Interfaces 3342 3343 This chapter describes the functions, macros, and external variables to support applications 3344 portability at the C-language source level. System Interfaces, Issue 6 533 FD_CLR( ) System Interfaces 3345 NAME 3346 FD_CLR - macros for synchronous I/O multiplexing 3347 SYNOPSIS 3348 #include 3349 FD_CLR(int fd, fd_set *fdset); 3350 FD_ISSET(int fd, fd_set *fdset); 3351 FD_SET(int fd, fd_set *fdset); 3352 FD_ZERO(fd_set *fdset); 3353 DESCRIPTION 3354 Refer to pselect( ). | 534 Technical Standard (2001) (Draft April 16, 2001) System Interfaces _Exit( ) 3355 NAME 3356 _Exit, _exit - terminate a process 3357 SYNOPSIS 3358 #include 3359 void _Exit(int status); 3360 void _exit(int status); 3361 DESCRIPTION 3362 Refer to exit( ). System Interfaces, Issue 6 535 _longjmp( ) System Interfaces 3363 NAME 3364 _longjmp, _setjmp - non-local goto 3365 SYNOPSIS 3366 XSI #include 3367 void _longjmp(jmp_buf env, int val); 3368 int _setjmp(jmp_buf env); 3369 3370 DESCRIPTION 3371 The _longjmp( ) and _setjmp( ) functions shall be equivalent to longjmp( ) and setjmp( ), | 3372 respectively, with the additional restriction that _longjmp( ) and _setjmp( ) shall not manipulate | 3373 the signal mask. | 3374 If _longjmp( ) is called even though env was never initialized by a call to _setjmp( ), or when the 3375 last such call was in a function that has since returned, the results are undefined. 3376 RETURN VALUE 3377 Refer to longjmp( ) and setjmp( ). 3378 ERRORS 3379 No errors are defined. 3380 EXAMPLES 3381 None. 3382 APPLICATION USAGE 3383 If _longjmp( ) is executed and the environment in which _setjmp( ) was executed no longer exists, 3384 errors can occur. The conditions under which the environment of the _setjmp( ) no longer exists 3385 include exiting the function that contains the _setjmp( ) call, and exiting an inner block with 3386 temporary storage. This condition might not be detectable, in which case the _longjmp( ) occurs 3387 and, if the environment no longer exists, the contents of the temporary storage of an inner block 3388 are unpredictable. This condition might also cause unexpected process termination. If the 3389 function has returned, the results are undefined. 3390 Passing longjmp( ) a pointer to a buffer not created by setjmp( ), passing _longjmp( ) a pointer to a 3391 buffer not created by _setjmp( ), passing siglongjmp( ) a pointer to a buffer not created by 3392 sigsetjmp( ), or passing any of these three functions a buffer that has been modified by the user 3393 can cause all the problems listed above, and more. 3394 The _longjmp( ) and _setjmp( ) functions are included to support programs written to historical 3395 system interfaces. New applications should use siglongjmp( ) and sigsetjmp( ) respectively. 3396 RATIONALE 3397 None. 3398 FUTURE DIRECTIONS 3399 The _longjmp( ) and _setjmp( ) functions may be marked LEGACY in a future version. 3400 SEE ALSO 3401 longjmp( ), setjmp( ), siglongjmp( ), sigsetjmp( ), the Base Definitions volume of 3402 IEEE Std 1003.1-200x, 3403 CHANGE HISTORY 3404 First released in Issue 4, Version 2. 536 Technical Standard (2001) (Draft April 16, 2001) System Interfaces _longjmp( ) 3405 Issue 5 3406 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 537 _setjmp( ) System Interfaces 3407 NAME 3408 _setjmp - set jump point for a non-local goto 3409 SYNOPSIS 3410 XSI #include 3411 int _setjmp(jmp_buf env); 3412 3413 DESCRIPTION 3414 Refer to _longjmp( ). 538 Technical Standard (2001) (Draft April 16, 2001) System Interfaces _tolower( ) 3415 NAME 3416 _tolower - transliterate uppercase characters to lowercase 3417 SYNOPSIS 3418 XSI #include 3419 int _tolower(int c); 3420 3421 DESCRIPTION 3422 The _tolower( ) macro shall be equivalent to tolower(c) except that the application shall ensure 3423 that the argument c is an uppercase letter. 3424 RETURN VALUE 3425 Upon successful completion, _tolower( ) shall return the lowercase letter corresponding to the 3426 argument passed. 3427 ERRORS 3428 No errors are defined. 3429 EXAMPLES 3430 None. 3431 APPLICATION USAGE 3432 None. 3433 RATIONALE 3434 None. 3435 FUTURE DIRECTIONS 3436 None. 3437 SEE ALSO 3438 tolower( ), isupper( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 3439 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 3440 CHANGE HISTORY 3441 First released in Issue 1. Derived from Issue 1 of the SVID. 3442 Issue 6 3443 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 539 _toupper( ) System Interfaces 3444 NAME 3445 _toupper - transliterate lowercase characters to uppercase 3446 SYNOPSIS 3447 XSI #include 3448 int _toupper(int c); 3449 3450 DESCRIPTION 3451 The _toupper( ) macro shall be equivalent to toupper( ) except that the application shall ensure 3452 that the argument c is a lowercase letter. 3453 RETURN VALUE 3454 Upon successful completion, _toupper( ) shall return the uppercase letter corresponding to the 3455 argument passed. 3456 ERRORS 3457 No errors are defined. 3458 EXAMPLES 3459 None. 3460 APPLICATION USAGE 3461 None. 3462 RATIONALE 3463 None. 3464 FUTURE DIRECTIONS 3465 None. 3466 SEE ALSO 3467 islower( ), toupper( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 3468 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 3469 CHANGE HISTORY 3470 First released in Issue 1. Derived from Issue 1 of the SVID. 3471 Issue 6 3472 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 540 Technical Standard (2001) (Draft April 16, 2001) System Interfaces a64l( ) 3473 NAME 3474 a64l, l64a - convert between a 32-bit integer and a radix-64 ASCII string 3475 SYNOPSIS 3476 XSI #include 3477 long a64l(const char *s); 3478 char *l64a(long value); 3479 3480 DESCRIPTION 3481 These functions maintain numbers stored in radix-64 ASCII characters. This is a notation by | 3482 which 32-bit integers can be represented by up to six characters; each character represents a digit 3483 in radix-64 notation. If the type long contains more than 32 bits, only the low-order 32 bits shall 3484 be used for these operations. 3485 The characters used to represent digits are '.' (dot) for 0, '/' for 1, '0' through '9' for [2,11], | 3486 'A' through 'Z' for [12,37], and 'a' through 'z' for [38,63]. | 3487 The a64l( ) function shall take a pointer to a radix-64 representation, in which the first digit is the | 3488 least significant, and return the corresponding long value. If the string pointed to by s contains | 3489 more than six characters, a64l( ) shall use the first six. If the first six characters of the string 3490 contain a null terminator, a64l( ) shall use only characters preceding the null terminator. The 3491 a64l( ) function shall scan the character string from left to right with the least significant digit on | 3492 the left, decoding each character as a 6-bit radix-64 number. If the type long contains more than | 3493 32 bits, the resulting value is sign-extended. The behavior of a64l( ) is unspecified if s is a null 3494 pointer or the string pointed to by s was not generated by a previous call to l64a( ). 3495 The l64a( ) function shall take a long argument and return a pointer to the corresponding radix- 3496 64 representation. The behavior of l64a( ) is unspecified if value is negative. 3497 The value returned by l64a( ) may be a pointer into a static buffer. Subsequent calls to l64a( ) may 3498 overwrite the buffer. 3499 The l64a( ) function need not be reentrant. A function that is not required to be reentrant is not 3500 required to be thread-safe. 3501 RETURN VALUE 3502 Upon successful completion, a64l( ) shall return the long value resulting from conversion of the 3503 input string. If a string pointed to by s is an empty string, a64l( ) shall return 0L. 3504 The l64a( ) function shall return a pointer to the radix-64 representation. If value is 0L, l64a( ) shall 3505 return a pointer to an empty string. 3506 ERRORS 3507 No errors are defined. 3508 EXAMPLES 3509 None. 3510 APPLICATION USAGE 3511 If the type long contains more than 32 bits, the result of a64l(l64a(x)) is x in the low-order 32 bits. 3512 RATIONALE 3513 This is not the same encoding as used by either encoding variant of the uuencode utility. System Interfaces, Issue 6 541 a64l( ) System Interfaces 3514 FUTURE DIRECTIONS 3515 None. 3516 SEE ALSO 3517 strtoul( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell and Utilities 3518 volume of IEEE Std 1003.1-200x, uuencode 3519 CHANGE HISTORY 3520 First released in Issue 4, Version 2. 3521 Issue 5 3522 Moved from X/OPEN UNIX extension to BASE. 3523 Normative text previously in the APPLICATION USAGE section moved to the DESCRIPTION. 3524 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 542 Technical Standard (2001) (Draft April 16, 2001) System Interfaces abort( ) 3525 NAME 3526 abort - generate an abnormal process abort 3527 SYNOPSIS 3528 #include 3529 void abort(void); 3530 DESCRIPTION 3531 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3532 conflict between the requirements described here and the ISO C standard is unintentional. This 3533 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 3534 The abort( ) function shall cause abnormal process termination to occur, unless the signal 3535 SIGABRT is being caught and the signal handler does not return. 3536 CX The abnormal termination processing shall include at least the effect of fclose( ) on all open 3537 streams and the default actions defined for SIGABRT. 3538 XSI On XSI-conformant systems, in addition the abnormal termination processing shall include the 3539 effect of fclose( ) on message catalog descriptors. 3540 The SIGABRT signal shall be sent to the calling process as if by means of raise( ) with the 3541 argument SIGABRT. 3542 CX The status made available to wait( ) or waitpid( ) by abort( ) shall be that of a process terminated | 3543 by the SIGABRT signal. The abort( ) function shall override blocking or ignoring the SIGABRT | 3544 signal. | 3545 RETURN VALUE 3546 The abort( ) function shall not return. 3547 ERRORS 3548 No errors are defined. 3549 EXAMPLES 3550 None. 3551 APPLICATION USAGE 3552 Catching the signal is intended to provide the application writer with a portable means to abort 3553 processing, free from possible interference from any implementation-defined functions. 3554 RATIONALE 3555 None. 3556 FUTURE DIRECTIONS 3557 None. 3558 SEE ALSO 3559 exit( ), kill( ), raise( ), signal( ), wait( ), waitpid( ), the Base Definitions volume of 3560 IEEE Std 1003.1-200x, 3561 CHANGE HISTORY 3562 First released in Issue 1. Derived from Issue 1 of the SVID. 3563 Issue 6 3564 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 543 abs( ) System Interfaces 3565 NAME 3566 abs - return an integer absolute value 3567 SYNOPSIS 3568 #include 3569 int abs(int i); 3570 DESCRIPTION 3571 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3572 conflict between the requirements described here and the ISO C standard is unintentional. This 3573 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 3574 The abs( ) function shall compute the absolute value of its integer operand, i. If the result cannot 3575 be represented, the behavior is undefined. 3576 RETURN VALUE 3577 The abs( ) function shall return the absolute value of its integer operand. 3578 ERRORS 3579 No errors are defined. 3580 EXAMPLES 3581 None. 3582 APPLICATION USAGE 3583 In two's-complement representation, the absolute value of the negative integer with largest 3584 magnitude {INT_MIN} might not be representable. 3585 RATIONALE 3586 None. 3587 FUTURE DIRECTIONS 3588 None. 3589 SEE ALSO 3590 fabs( ), labs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 3591 CHANGE HISTORY 3592 First released in Issue 1. Derived from Issue 1 of the SVID. 3593 Issue 6 3594 Extensions beyond the ISO C standard are now marked. 544 Technical Standard (2001) (Draft April 16, 2001) System Interfaces accept( ) 3595 NAME 3596 accept - accept a new connection on a socket 3597 SYNOPSIS 3598 #include 3599 int accept(int socket, struct sockaddr *restrict address, 3600 socklen_t *restrict address_len); 3601 DESCRIPTION 3602 The accept( ) function shall extract the first connection on the queue of pending connections, 3603 create a new socket with the same socket type protocol and address family as the specified 3604 socket, and allocate a new file descriptor for that socket. 3605 The accept( ) function takes the following arguments: 3606 socket Specifies a socket that was created with socket( ), has been bound to an address 3607 with bind( ), and has issued a successful call to listen( ). 3608 address Either a null pointer, or a pointer to a sockaddr structure where the address of 3609 the connecting socket shall be returned. 3610 address_len Points to a socklen_t structure which on input specifies the length of the 3611 supplied sockaddr structure, and on output specifies the length of the stored 3612 address. 3613 If address is not a null pointer, the address of the peer for the accepted connection shall be stored 3614 in the sockaddr structure pointed to by address, and the length of this address shall be stored in 3615 the object pointed to by address_len. 3616 If the actual length of the address is greater than the length of the supplied sockaddr structure, 3617 the stored address shall be truncated. 3618 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 3619 stored in the object pointed to by address is unspecified. 3620 If the listen queue is empty of connection requests and O_NONBLOCK is not set on the file 3621 descriptor for the socket, accept( ) shall block until a connection is present. If the listen( ) queue is 3622 empty of connection requests and O_NONBLOCK is set on the file descriptor for the socket, 3623 accept( ) shall fail and set errno to [EAGAIN] or [EWOULDBLOCK]. 3624 The accepted socket cannot itself accept more connections. The original socket remains open and 3625 can accept more connections. 3626 RETURN VALUE 3627 Upon successful completion, accept( ) shall return the non-negative file descriptor of the accepted 3628 socket. Otherwise, -1 shall be returned and errno set to indicate the error. 3629 ERRORS 3630 The accept( ) function shall fail if: 3631 [EAGAIN] or [EWOULDBLOCK] 3632 O_NONBLOCK is set for the socket file descriptor and no connections are 3633 present to be accepted. 3634 [EBADF] The socket argument is not a valid file descriptor. 3635 [ECONNABORTED] 3636 A connection has been aborted. System Interfaces, Issue 6 545 accept( ) System Interfaces 3637 [EINTR] The accept( ) function was interrupted by a signal that was caught before a 3638 valid connection arrived. 3639 [EINVAL] The socket is not accepting connections. 3640 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 3641 [ENFILE] The maximum number of file descriptors in the system are already open. 3642 [ENOTSOCK] The socket argument does not refer to a socket. 3643 [EOPNOTSUPP] The socket type of the specified socket does not support accepting 3644 connections. 3645 The accept( ) function may fail if: 3646 [ENOBUFS] No buffer space is available. 3647 [ENOMEM] There was insufficient memory available to complete the operation. 3648 XSR [EPROTO] A protocol error has occurred; for example, the STREAMS protocol stack has 3649 not been initialized. 3650 EXAMPLES 3651 None. 3652 APPLICATION USAGE 3653 When a connection is available, select( ) indicates that the file descriptor for the socket is ready 3654 for reading. 3655 RATIONALE 3656 None. 3657 FUTURE DIRECTIONS 3658 None. 3659 SEE ALSO 3660 bind( ), connect( ), listen( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 3661 3662 CHANGE HISTORY 3663 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 3664 The restrict keyword is added to the accept( ) prototype for alignment with the 3665 ISO/IEC 9899: 1999 standard. 546 Technical Standard (2001) (Draft April 16, 2001) System Interfaces access( ) 3666 NAME 3667 access - determine accessibility of a file 3668 SYNOPSIS 3669 #include 3670 int access(const char *path, int amode); 3671 DESCRIPTION 3672 The access( ) function shall check the file named by the pathname pointed to by the path | 3673 argument for accessibility according to the bit pattern contained in amode, using the real user ID 3674 in place of the effective user ID and the real group ID in place of the effective group ID. 3675 The value of amode is either the bitwise-inclusive OR of the access permissions to be checked 3676 (R_OK, W_OK, X_OK) or the existence test (F_OK). 3677 If any access permissions are checked, each shall be checked individually, as described in the 3678 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 3, Definitions. If the process has 3679 appropriate privileges, an implementation may indicate success for X_OK even if none of the 3680 execute file permission bits are set. 3681 RETURN VALUE 3682 If the requested access is permitted, access( ) succeeds and shall return 0; otherwise, -1 shall be 3683 returned and errno shall be set to indicate the error. 3684 ERRORS 3685 The access( ) function shall fail if: 3686 [EACCES] Permission bits of the file mode do not permit the requested access, or search 3687 permission is denied on a component of the path prefix. 3688 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 3689 argument. 3690 [ENAMETOOLONG] 3691 The length of the path argument exceeds {PATH_MAX} or a pathname | 3692 component is longer than {NAME_MAX}. | 3693 [ENOENT] A component of path does not name an existing file or path is an empty string. 3694 [ENOTDIR] A component of the path prefix is not a directory. 3695 [EROFS] Write access is requested for a file on a read-only file system. 3696 The access( ) function may fail if: 3697 [EINVAL] The value of the amode argument is invalid. 3698 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 3699 resolution of the path argument. 3700 [ENAMETOOLONG] 3701 As a result of encountering a symbolic link in resolution of the path argument, | 3702 the length of the substituted pathname string exceeded {PATH_MAX}. | 3703 [ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being 3704 executed. System Interfaces, Issue 6 547 access( ) System Interfaces 3705 EXAMPLES 3706 Testing for the Existence of a File 3707 The following example tests whether a file named myfile exists in the /tmp directory. 3708 #include 3709 ... 3710 int result; 3711 const char *filename = "/tmp/myfile"; 3712 result = access (filename, F_OK); 3713 APPLICATION USAGE 3714 Additional values of amode other than the set defined in the description may be valid; for 3715 example, if a system has extended access controls. 3716 RATIONALE 3717 In early proposals, some inadequacies in the access( ) function led to the creation of an eaccess( ) 3718 function because: 3719 1. Historical implementations of access( ) do not test file access correctly when the process' 3720 real user ID is superuser. In particular, they always return zero when testing execute 3721 permissions without regard to whether the file is executable. 3722 2. The superuser has complete access to all files on a system. As a consequence, programs 3723 started by the superuser and switched to the effective user ID with lesser privileges cannot 3724 use access( ) to test their file access permissions. 3725 However, the historical model of eaccess( ) does not resolve problem (1), so this volume of 3726 IEEE Std 1003.1-200x now allows access( ) to behave in the desired way because several 3727 implementations have corrected the problem. It was also argued that problem (2) is more easily 3728 solved by using open( ), chdir( ), or one of the exec functions as appropriate and responding to the 3729 error, rather than creating a new function that would not be as reliable. Therefore, eaccess( ) is not 3730 included in this volume of IEEE Std 1003.1-200x. 3731 The sentence concerning appropriate privileges and execute permission bits reflects the two 3732 possibilities implemented by historical implementations when checking superuser access for 3733 X_OK. | 3734 New implementations are discouraged from returning X_OK unless at least one execution | 3735 permission bit is set. | 3736 FUTURE DIRECTIONS 3737 None. 3738 SEE ALSO 3739 chmod( ), stat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 3740 CHANGE HISTORY 3741 First released in Issue 1. Derived from Issue 1 of the SVID. 3742 Issue 6 3743 The following new requirements on POSIX implementations derive from alignment with the | 3744 Single UNIX Specification: 3745 * The [ELOOP] mandatory error condition is added. 3746 * A second [ENAMETOOLONG] is added as an optional error condition. 548 Technical Standard (2001) (Draft April 16, 2001) System Interfaces access( ) 3747 * The [ETXTBSY] optional error condition is added. 3748 The following changes were made to align with the IEEE P1003.1a draft standard: 3749 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 549 acos( ) System Interfaces 3750 NAME 3751 acos, acosf, acosl - arc cosine functions 3752 SYNOPSIS 3753 #include 3754 double acos(double x); 3755 float acosf(float x); 3756 long double acosl(long double x); 3757 DESCRIPTION 3758 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3759 conflict between the requirements described here and the ISO C standard is unintentional. This 3760 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 3761 These functions shall compute the principal value of the arc cosine of their argument x. The 3762 value of x should be in the range [-1,1]. 3763 An application wishing to check for error situations should set errno to zero and call 3764 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 3765 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 3766 zero, an error has occurred. 3767 RETURN VALUE 3768 Upon successful completion, these functions shall return the arc cosine of x, in the range [0, ] 3769 radians. 3770 MX For finite values of x not in the range [-1,1], a domain error shall occur, and either a NaN (if 3771 supported), or an implementation-defined value shall be returned. 3772 MX If x is NaN, a NaN shall be returned. 3773 If x is +1, +0 shall be returned. 3774 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 3775 defined value shall be returned. 3776 ERRORS 3777 These functions shall fail if: 3778 MX Domain Error The x argument is finite and is not in the range [-1,1], or is ±Inf. 3779 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 3780 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 3781 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 3782 shall be raised. | 3783 EXAMPLES 3784 None. 3785 APPLICATION USAGE 3786 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 3787 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 3788 RATIONALE 3789 None. 550 Technical Standard (2001) (Draft April 16, 2001) System Interfaces acos( ) 3790 FUTURE DIRECTIONS 3791 None. 3792 SEE ALSO 3793 cos( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 3794 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 3795 CHANGE HISTORY 3796 First released in Issue 1. Derived from Issue 1 of the SVID. 3797 Issue 5 3798 The DESCRIPTION is updated to indicate how an application should check for an error. This 3799 text was previously published in the APPLICATION USAGE section. 3800 Issue 6 3801 The acosf( ) and acosl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 3802 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 3803 revised to align with the ISO/IEC 9899: 1999 standard. 3804 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 3805 marked. System Interfaces, Issue 6 551 acosf( ) System Interfaces 3806 NAME 3807 acosf - arc cosine functions 3808 SYNOPSIS 3809 #include 3810 float acosf(float x); 3811 DESCRIPTION 3812 Refer to acos( ). 552 Technical Standard (2001) (Draft April 16, 2001) System Interfaces acosh( ) 3813 NAME 3814 acosh, acoshf, acoshl, - inverse hyperbolic cosine functions 3815 SYNOPSIS 3816 #include 3817 double acosh(double x); 3818 float acoshf(float x); 3819 long double acoshl(long double x); 3820 DESCRIPTION 3821 CX The functionality described on this reference page is aligned with the ISO C standard. Any 3822 conflict between the requirements described here and the ISO C standard is unintentional. This 3823 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 3824 These functions shall compute the inverse hyperbolic cosine of their argument x. 3825 An application wishing to check for error situations should set errno to zero and call 3826 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 3827 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 3828 zero, an error has occurred. 3829 RETURN VALUE 3830 Upon successful completion, these functions shall return the inverse hyperbolic cosine of their 3831 argument. 3832 MX For finite values of x < 1, a domain error shall occur, and either a NaN (if supported), or an 3833 implementation-defined value shall be returned. 3834 MX If x is NaN, a NaN shall be returned. 3835 If x is +1, +0 shall be returned. 3836 If x is +Inf, +Inf shall be returned. 3837 If x is -Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 3838 defined value shall be returned. 3839 ERRORS 3840 These functions shall fail if: 3841 MX Domain Error The x argument is finite and less than +1.0, or is -Inf. 3842 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 3843 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 3844 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 3845 shall be raised. | 3846 EXAMPLES 3847 None. 3848 APPLICATION USAGE 3849 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 3850 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 3851 RATIONALE 3852 None. System Interfaces, Issue 6 553 acosh( ) System Interfaces 3853 FUTURE DIRECTIONS 3854 None. 3855 SEE ALSO 3856 cosh( ), feclearexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 3857 4.18, Treatment of Error Conditions for Mathematical Functions, | 3858 CHANGE HISTORY 3859 First released in Issue 4, Version 2. 3860 Issue 5 3861 Moved from X/OPEN UNIX extension to BASE. 3862 Issue 6 3863 The acosh( ) function is no longer marked as an extension. 3864 The acoshf( ), and acoshl( ) functions are added for alignment with the ISO/IEC 9899: 1999 3865 standard. 3866 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 3867 revised to align with the ISO/IEC 9899: 1999 standard. 3868 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 3869 marked. 554 Technical Standard (2001) (Draft April 16, 2001) System Interfaces acosl( ) 3870 NAME 3871 acosl - arc cosine functions 3872 SYNOPSIS 3873 #include 3874 long double acosl(long double x); 3875 DESCRIPTION 3876 Refer to acos( ). System Interfaces, Issue 6 555 aio_cancel( ) System Interfaces 3877 NAME 3878 aio_cancel - cancel an asynchronous I/O request (REALTIME) 3879 SYNOPSIS 3880 AIO #include 3881 int aio_cancel(int fildes, struct aiocb *aiocbp); 3882 3883 DESCRIPTION 3884 The aio_cancel( ) function shall attempt to cancel one or more asynchronous I/O requests 3885 currently outstanding against file descriptor fildes. The aiocbp argument points to the 3886 asynchronous I/O control block for a particular request to be canceled. If aiocbp is NULL, then 3887 all outstanding cancelable asynchronous I/O requests against fildes shall be canceled. 3888 Normal asynchronous notification shall occur for asynchronous I/O operations that are 3889 successfully canceled. If there are requests that cannot be canceled, then the normal 3890 asynchronous completion process shall take place for those requests when they are completed. 3891 For requested operations that are successfully canceled, the associated error status shall be set to 3892 [ECANCELED] and the return status shall be -1. For requested operations that are not 3893 successfully canceled, the aiocbp shall not be modified by aio_cancel( ). 3894 If aiocbp is not NULL, then if fildes does not have the same value as the file descriptor with which 3895 the asynchronous operation was initiated, unspecified results occur. 3896 Which operations are cancelable is implementation-defined. 3897 RETURN VALUE 3898 The aio_cancel( ) function shall return the value AIO_CANCELED to the calling process if the 3899 requested operation(s) were canceled. The value AIO_NOTCANCELED shall be returned if at 3900 least one of the requested operation(s) cannot be canceled because it is in progress. In this case, 3901 the state of the other operations, if any, referenced in the call to aio_cancel( ) is not indicated by 3902 the return value of aio_cancel( ). The application may determine the state of affairs for these 3903 operations by using aio_error( ). The value AIO_ALLDONE is returned if all of the operations 3904 have already completed. Otherwise, the function shall return -1 and set errno to indicate the 3905 error. 3906 ERRORS 3907 The aio_cancel( ) function shall fail if: 3908 [EBADF] The fildes argument is not a valid file descriptor. 3909 EXAMPLES 3910 None. 3911 APPLICATION USAGE 3912 The aio_cancel( ) function is part of the Asynchronous Input and Output option and need not be 3913 available on all implementations. 3914 RATIONALE 3915 None. 3916 FUTURE DIRECTIONS 3917 None. 556 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_cancel( ) 3918 SEE ALSO 3919 aio_read( ), aio_write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 3920 CHANGE HISTORY 3921 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 3922 Issue 6 3923 The [ENOSYS] error condition has been removed as stubs need not be provided if an 3924 implementation does not support the Asynchronous Input and Output option. 3925 The APPLICATION USAGE section is added. System Interfaces, Issue 6 557 aio_error( ) System Interfaces 3926 NAME 3927 aio_error - retrieve errors status for an asynchronous I/O operation (REALTIME) 3928 SYNOPSIS 3929 AIO #include 3930 int aio_error(const struct aiocb *aiocbp); 3931 3932 DESCRIPTION 3933 The aio_error( ) function shall return the error status associated with the aiocb structure 3934 referenced by the aiocbp argument. The error status for an asynchronous I/O operation is the 3935 SIO errno value that would be set by the corresponding read( ), write( ), fdatasync( ), or fsync( ) 3936 operation. If the operation has not yet completed, then the error status shall be equal to 3937 [EINPROGRESS]. 3938 RETURN VALUE 3939 If the asynchronous I/O operation has completed successfully, then 0 shall be returned. If the 3940 asynchronous operation has completed unsuccessfully, then the error status, as described for 3941 SIO read( ), write( ), fdatasync( ), and fsync( ), shall be returned. If the asynchronous I/O operation has 3942 not yet completed, then [EINPROGRESS] shall be returned. 3943 ERRORS 3944 The aio_error( ) function may fail if: 3945 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose 3946 return status has not yet been retrieved. 3947 EXAMPLES 3948 None. 3949 APPLICATION USAGE 3950 The aio_error( ) function is part of the Asynchronous Input and Output option and need not be 3951 available on all implementations. 3952 RATIONALE 3953 None. 3954 FUTURE DIRECTIONS 3955 None. 3956 SEE ALSO 3957 aio_cancel( ), aio_fsync( ), aio_read( ), aio_return( ), aio_write( ), close( ), exec, exit( ), fork( ), lio_listio ( ), 3958 lseek( ), read( ), the Base Definitions volume of IEEE Std 1003.1-200x, 3959 CHANGE HISTORY 3960 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 3961 Issue 6 3962 The [ENOSYS] error condition has been removed as stubs need not be provided if an 3963 implementation does not support the Asynchronous Input and Output option. 3964 The APPLICATION USAGE section is added. 558 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_fsync( ) 3965 NAME 3966 aio_fsync - asynchronous file synchronization (REALTIME) 3967 SYNOPSIS 3968 AIO #include 3969 int aio_fsync(int op, struct aiocb *aiocbp); 3970 3971 DESCRIPTION 3972 The aio_fsync( ) function shall asynchronously force all I/O operations associated with the file | 3973 indicated by the file descriptor aio_fildes member of the aiocb structure referenced by the aiocbp | 3974 argument and queued at the time of the call to aio_fsync( ) to the synchronized I/O completion 3975 state. The function call shall return when the synchronization request has been initiated or 3976 queued to the file or device (even when the data cannot be synchronized immediately). 3977 If op is O_DSYNC, all currently queued I/O operations shall be completed as if by a call to 3978 fdatasync( ); that is, as defined for synchronized I/O data integrity completion. If op is O_SYNC, 3979 all currently queued I/O operations shall be completed as if by a call to fsync( ); that is, as 3980 defined for synchronized I/O file integrity completion. If the aio_fsync( ) function fails, or if the 3981 operation queued by aio_fsync( ) fails, then, as for fsync( ) and fdatasync( ), outstanding I/O 3982 operations are not guaranteed to have been completed. 3983 If aio_fsync( ) succeeds, then it is only the I/O that was queued at the time of the call to 3984 aio_fsync( ) that is guaranteed to be forced to the relevant completion state. The completion of 3985 subsequent I/O on the file descriptor is not guaranteed to be completed in a synchronized 3986 fashion. 3987 The aiocbp argument refers to an asynchronous I/O control block. The aiocbp value may be used | 3988 as an argument to aio_error( ) and aio_return( ) in order to determine the error status and return 3989 status, respectively, of the asynchronous operation while it is proceeding. When the request is 3990 queued, the error status for the operation is [EINPROGRESS]. When all data has been 3991 successfully transferred, the error status shall be reset to reflect the success or failure of the 3992 operation. If the operation does not complete successfully, the error status for the operation shall 3993 be set to indicate the error. The aio_sigevent member determines the asynchronous notification to 3994 occur as specified in Section 2.4.1 (on page 478) when all operations have achieved synchronized 3995 I/O completion. All other members of the structure referenced by aiocbp are ignored. If the 3996 control block referenced by aiocbp becomes an illegal address prior to asynchronous I/O 3997 completion, then the behavior is undefined. 3998 If the aio_fsync( ) function fails or the aiocbp indicates an error condition, data is not guaranteed 3999 to have been successfully transferred. 4000 RETURN VALUE 4001 The aio_fsync( ) function shall return the value 0 to the calling process if the I/O operation is 4002 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4003 the error. 4004 ERRORS 4005 The aio_fsync( ) function shall fail if: 4006 [EAGAIN] The requested asynchronous operation was not queued due to temporary 4007 resource limitations. 4008 [EBADF] The aio_fildes member of the aiocb structure referenced by the aiocbp argument 4009 is not a valid file descriptor open for writing. System Interfaces, Issue 6 559 aio_fsync( ) System Interfaces 4010 [EINVAL] This implementation does not support synchronized I/O for this file. 4011 [EINVAL] A value of op other than O_DSYNC or O_SYNC was specified. 4012 In the event that any of the queued I/O operations fail, aio_fsync( ) shall return the error 4013 condition defined for read( ) and write( ). The error is returned in the error status for the 4014 asynchronous fsync( ) operation, which can be retrieved using aio_error( ). 4015 EXAMPLES 4016 None. 4017 APPLICATION USAGE 4018 The aio_fsync( ) function is part of the Asynchronous Input and Output option and need not be 4019 available on all implementations. 4020 RATIONALE 4021 None. 4022 FUTURE DIRECTIONS 4023 None. 4024 SEE ALSO 4025 fcntl( ), fdatasync( ), fsync( ), open( ), read( ), write( ), the Base Definitions volume of 4026 IEEE Std 1003.1-200x, 4027 CHANGE HISTORY 4028 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4029 Issue 6 4030 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4031 implementation does not support the Asynchronous Input and Output option. 4032 The APPLICATION USAGE section is added. 560 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_read( ) 4033 NAME 4034 aio_read - asynchronous read from a file (REALTIME) 4035 SYNOPSIS 4036 AIO #include 4037 int aio_read(struct aiocb *aiocbp); 4038 4039 DESCRIPTION 4040 The aio_read( ) function shall read aiocbp->aio_nbytes from the file associated with aiocbp- | 4041 >aio_fildes into the buffer pointed to by aiocbp->aio_buf. The function call shall return when the | 4042 read request has been initiated or queued to the file or device (even when the data cannot be | 4043 delivered immediately). | 4044 PIO If prioritized I/O is supported for this file, then the asynchronous operation shall be submitted | 4045 at a priority equal to the scheduling priority of the process minus aiocbp->aio_reqprio. | 4046 The aiocbp value may be used as an argument to aio_error( ) and aio_return( ) in order to 4047 determine the error status and return status, respectively, of the asynchronous operation while it 4048 is proceeding. If an error condition is encountered during queuing, the function call shall return 4049 without having initiated or queued the request. The requested operation takes place at the 4050 absolute position in the file as given by aio_offset , as if lseek( ) were called immediately prior to 4051 the operation with an offset equal to aio_offset and a whence equal to SEEK_SET. After a 4052 successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file 4053 is unspecified. 4054 The aiocbp->aio_lio_opcode field shall be ignored by aio_read( ). 4055 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp->aio_buf or 4056 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 4057 completion, then the behavior is undefined. 4058 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 4059 SIO If synchronized I/O is enabled on the file associated with aiocbp->aio_fildes, the behavior of this 4060 function shall be according to the definitions of synchronized I/O data integrity completion and 4061 synchronized I/O file integrity completion. 4062 For any system action that changes the process memory space while an asynchronous I/O is 4063 outstanding to the address range being changed, the result of that action is undefined. 4064 For regular files, no data transfer shall occur past the offset maximum established in the open 4065 file description associated with aiocbp->aio_fildes. 4066 RETURN VALUE 4067 The aio_read( ) function shall return the value zero to the calling process if the I/O operation is 4068 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4069 the error. 4070 ERRORS 4071 The aio_read( ) function shall fail if: 4072 [EAGAIN] The requested asynchronous I/O operation was not queued due to system 4073 resource limitations. 4074 Each of the following conditions may be detected synchronously at the time of the call to 4075 aio_read( ), or asynchronously. If any of the conditions below are detected synchronously, the 4076 aio_read( ) function shall return -1 and set errno to the corresponding value. If any of the 4077 conditions below are detected asynchronously, the return status of the asynchronous operation System Interfaces, Issue 6 561 aio_read( ) System Interfaces 4078 is set to -1, and the error status of the asynchronous operation is set to the corresponding value. 4079 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for reading. 4080 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid, aiocbp- 4081 >aio_reqprio is not a valid value, or aiocbp->aio_nbytes is an invalid value. 4082 In the case that the aio_read( ) successfully queues the I/O operation but the operation is 4083 subsequently canceled or encounters an error, the return status of the asynchronous operation is 4084 one of the values normally returned by the read( ) function call. In addition, the error status of 4085 the asynchronous operation is set to one of the error statuses normally set by the read( ) function 4086 call, or one of the following values: 4087 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for reading. 4088 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit 4089 aio_cancel( ) request. 4090 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid. 4091 The following condition may be detected synchronously or asynchronously: 4092 [EOVERFLOW] The file is a regular file, aiobcp->aio_nbytes is greater than 0, and the starting 4093 offset in aiobcp->aio_offset is before the end-of-file and is at or beyond the offset 4094 maximum in the open file description associated with aiocbp->aio_fildes. 4095 EXAMPLES 4096 None. 4097 APPLICATION USAGE 4098 The aio_read( ) function is part of the Asynchronous Input and Output option and need not be 4099 available on all implementations. 4100 RATIONALE 4101 None. 4102 FUTURE DIRECTIONS 4103 None. 4104 SEE ALSO 4105 aio_cancel( ), aio_error( ), lio_listio ( ), aio_return( ), aio_write( ), close( ), exec, exit( ), fork( ), lseek( ), 4106 read( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4107 CHANGE HISTORY 4108 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4109 Large File Summit extensions are added. 4110 Issue 6 4111 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4112 implementation does not support the Asynchronous Input and Output option. 4113 The APPLICATION USAGE section is added. | 562 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_read( ) 4114 The following new requirements on POSIX implementations derive from alignment with the | 4115 Single UNIX Specification: 4116 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 4117 description. This change is to support large files. 4118 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 4119 large files. System Interfaces, Issue 6 563 aio_return( ) System Interfaces 4120 NAME 4121 aio_return - retrieve return status of an asynchronous I/O operation (REALTIME) 4122 SYNOPSIS 4123 AIO #include 4124 ssize_t aio_return(struct aiocb *aiocbp); 4125 4126 DESCRIPTION 4127 The aio_return( ) function shall return the return status associated with the aiocb structure 4128 referenced by the aiocbp argument. The return status for an asynchronous I/O operation is the 4129 value that would be returned by the corresponding read( ), write( ), or fsync( ) function call. If the 4130 error status for the operation is equal to [EINPROGRESS], then the return status for the 4131 operation is undefined. The aio_return( ) function may be called exactly once to retrieve the 4132 return status of a given asynchronous operation; thereafter, if the same aiocb structure is used in 4133 a call to aio_return( ) or aio_error( ), an error may be returned. When the aiocb structure referred 4134 to by aiocbp is used to submit another asynchronous operation, then aio_return( ) may be 4135 successfully used to retrieve the return status of that operation. 4136 RETURN VALUE 4137 If the asynchronous I/O operation has completed, then the return status, as described for read( ), 4138 write( ), and fsync( ), shall be returned. If the asynchronous I/O operation has not yet completed, 4139 the results of aio_return( ) are undefined. 4140 ERRORS 4141 The aio_return( ) function may fail if: 4142 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose 4143 return status has not yet been retrieved. 4144 EXAMPLES 4145 None. 4146 APPLICATION USAGE 4147 The aio_return( ) function is part of the Asynchronous Input and Output option and need not be 4148 available on all implementations. 4149 RATIONALE 4150 None. 4151 FUTURE DIRECTIONS 4152 None. 4153 SEE ALSO 4154 aio_cancel( ), aio_error( ), aio_fsync( ), aio_read( ), aio_write( ), close( ), exec, exit( ), fork( ), lio_listio ( ), 4155 lseek( ), read( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4156 CHANGE HISTORY 4157 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4158 Issue 6 4159 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4160 implementation does not support the Asynchronous Input and Output option. 4161 The APPLICATION USAGE section is added. 4162 The [EINVAL] error condition is updated as a ``may fail''. This is for consistency with the 4163 DESCRIPTION. 564 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_suspend( ) 4164 NAME 4165 aio_suspend - wait for an asynchronous I/O request (REALTIME) 4166 SYNOPSIS 4167 AIO #include 4168 int aio_suspend(const struct aiocb * const list[], int nent, 4169 const struct timespec *timeout); 4170 4171 DESCRIPTION 4172 The aio_suspend( ) function shall suspend the calling thread until at least one of the asynchronous 4173 I/O operations referenced by the list argument has completed, until a signal interrupts the 4174 function, or, if timeout is not NULL, until the time interval specified by timeout has passed. If any 4175 of the aiocb structures in the list correspond to completed asynchronous I/O operations (that is, 4176 the error status for the operation is not equal to [EINPROGRESS]) at the time of the call, the 4177 function shall return without suspending the calling thread. The list argument is an array of 4178 pointers to asynchronous I/O control blocks. The nent argument indicates the number of 4179 elements in the array. Each aiocb structure pointed to has been used in initiating an 4180 asynchronous I/O request via aio_read( ), aio_write( ), or lio_listio ( ). This array may contain 4181 NULL pointers, which are ignored. If this array contains pointers that refer to aiocb structures 4182 that have not been used in submitting asynchronous I/O, the effect is undefined. 4183 If the time interval indicated in the timespec structure pointed to by timeout passes before any of 4184 the I/O operations referenced by list are completed, then aio_suspend( ) shall return with an 4185 MON error. If the Monotonic Clock option is supported, the clock that shall be used to measure this 4186 time interval shall be the CLOCK_MONOTONIC clock. 4187 RETURN VALUE 4188 If the aio_suspend( ) function returns after one or more asynchronous I/O operations have 4189 completed, the function shall return zero. Otherwise, the function shall return a value of -1 and 4190 set errno to indicate the error. 4191 The application may determine which asynchronous I/O completed by scanning the associated 4192 error and return status using aio_error( ) and aio_return( ), respectively. 4193 ERRORS 4194 The aio_suspend( ) function shall fail if: 4195 [EAGAIN] No asynchronous I/O indicated in the list referenced by list completed in the 4196 time interval indicated by timeout. 4197 [EINTR] A signal interrupted the aio_suspend( ) function. Note that, since each 4198 asynchronous I/O operation may possibly provoke a signal when it 4199 completes, this error return may be caused by the completion of one (or more) 4200 of the very I/O operations being awaited. 4201 EXAMPLES 4202 None. 4203 APPLICATION USAGE 4204 The aio_suspend( ) function is part of the Asynchronous Input and Output option and need not 4205 be available on all implementations. 4206 RATIONALE 4207 None. System Interfaces, Issue 6 565 aio_suspend( ) System Interfaces 4208 FUTURE DIRECTIONS 4209 None. 4210 SEE ALSO 4211 aio_read( ), aio_write( ), lio_listio ( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4212 CHANGE HISTORY 4213 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4214 Issue 6 4215 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4216 implementation does not support the Asynchronous Input and Output option. 4217 The APPLICATION USAGE section is added. 4218 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that the 4219 CLOCK_MONOTONIC clock, if supported, is used. 566 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_write( ) 4220 NAME 4221 aio_write - asynchronous write to a file (REALTIME) 4222 SYNOPSIS 4223 AIO #include 4224 int aio_write(struct aiocb *aiocbp); 4225 4226 DESCRIPTION 4227 The aio_write( ) function shall write aiocbp->aio_nbytes to the file associated with aiocbp->aio_fildes | 4228 from the buffer pointed to by aiocbp->aio_buf. The function shall return when the write request | 4229 has been initiated or, at a minimum, queued to the file or device. | 4230 PIO If prioritized I/O is supported for this file, then the asynchronous operation shall be submitted 4231 at a priority equal to the scheduling priority of the process minus aiocbp->aio_reqprio. 4232 The aiocbp may be used as an argument to aio_error( ) and aio_return( ) in order to determine the 4233 error status and return status, respectively, of the asynchronous operation while it is proceeding. 4234 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp->aio_buf or 4235 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 4236 completion, then the behavior is undefined. 4237 If O_APPEND is not set for the file descriptor aio_fildes , then the requested operation shall take | 4238 place at the absolute position in the file as given by aio_offset , as if lseek( ) were called | 4239 immediately prior to the operation with an offset equal to aio_offset and a whence equal to 4240 SEEK_SET. If O_APPEND is set for the file descriptor, write operations append to the file in the 4241 same order as the calls were made. After a successful call to enqueue an asynchronous I/O 4242 operation, the value of the file offset for the file is unspecified. 4243 The aiocbp->aio_lio_opcode field shall be ignored by aio_write( ). 4244 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 4245 SIO If synchronized I/O is enabled on the file associated with aiocbp->aio_fildes, the behavior of this 4246 function shall be according to the definitions of synchronized I/O data integrity completion, and 4247 synchronized I/O file integrity completion. 4248 For any system action that changes the process memory space while an asynchronous I/O is 4249 outstanding to the address range being changed, the result of that action is undefined. 4250 For regular files, no data transfer shall occur past the offset maximum established in the open 4251 file description associated with aiocbp->aio_fildes. 4252 RETURN VALUE 4253 The aio_write( ) function shall return the value zero to the calling process if the I/O operation is 4254 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 4255 the error. 4256 ERRORS 4257 The aio_write( ) function shall fail if: 4258 [EAGAIN] The requested asynchronous I/O operation was not queued due to system 4259 resource limitations. 4260 Each of the following conditions may be detected synchronously at the time of the call to 4261 aio_write( ), or asynchronously. If any of the conditions below are detected synchronously, the 4262 aio_write( ) function shall return -1 and set errno to the corresponding value. If any of the 4263 conditions below are detected asynchronously, the return status of the asynchronous operation System Interfaces, Issue 6 567 aio_write( ) System Interfaces 4264 shall be set to -1, and the error status of the asynchronous operation is set to the corresponding 4265 value. 4266 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for writing. 4267 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid, aiocbp- 4268 >aio_reqprio is not a valid value, or aiocbp->aio_nbytes is an invalid value. 4269 In the case that the aio_write( ) successfully queues the I/O operation, the return status of the 4270 asynchronous operation shall be one of the values normally returned by the write( ) function call. 4271 If the operation is successfully queued but is subsequently canceled or encounters an error, the 4272 error status for the asynchronous operation contains one of the values normally set by the 4273 write( ) function call, or one of the following: 4274 [EBADF] The aiocbp->aio_fildes argument is not a valid file descriptor open for writing. 4275 [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid. 4276 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit 4277 aio_cancel( ) request. 4278 The following condition may be detected synchronously or asynchronously: 4279 [EFBIG] The file is a regular file, aiobcp->aio_nbytes is greater than 0, and the starting 4280 offset in aiobcp->aio_offset is at or beyond the offset maximum in the open file 4281 description associated with aiocbp->aio_fildes. 4282 EXAMPLES 4283 None. 4284 APPLICATION USAGE 4285 The aio_write( ) function is part of the Asynchronous Input and Output option and need not be 4286 available on all implementations. 4287 RATIONALE 4288 None. 4289 FUTURE DIRECTIONS 4290 None. 4291 SEE ALSO 4292 aio_cancel( ), aio_error( ), aio_read( ), aio_return( ), close( ), exec, exit( ), fork( ), lio_listio ( ), lseek( ), 4293 write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4294 CHANGE HISTORY 4295 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 4296 Large File Summit extensions are added. 4297 Issue 6 4298 The [ENOSYS] error condition has been removed as stubs need not be provided if an 4299 implementation does not support the Asynchronous Input and Output option. 4300 The APPLICATION USAGE section is added. 4301 The following new requirements on POSIX implementations derive from alignment with the 4302 Single UNIX Specification: 4303 * In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 4304 past the offset maximum established in the open file description associated with aiocbp- 4305 >aio_fildes. 568 Technical Standard (2001) (Draft April 16, 2001) System Interfaces aio_write( ) 4306 * The [EFBIG] error is added as part of the large file support extensions. System Interfaces, Issue 6 569 alarm( ) System Interfaces 4307 NAME 4308 alarm - schedule an alarm signal 4309 SYNOPSIS 4310 #include 4311 unsigned alarm(unsigned seconds); 4312 DESCRIPTION 4313 The alarm( ) function shall cause the system to generate a SIGALRM signal for the process after 4314 the number of realtime seconds specified by seconds have elapsed. Processor scheduling delays 4315 may prevent the process from handling the signal as soon as it is generated. 4316 If seconds is 0, a pending alarm request, if any, is canceled. 4317 Alarm requests are not stacked; only one SIGALRM generation can be scheduled in this manner. 4318 If the SIGALRM signal has not yet been generated, the call shall result in rescheduling the time 4319 at which the SIGALRM signal is generated. 4320 XSI Interactions between alarm( ) and any of setitimer( ), ualarm( ), or usleep( ) are unspecified. 4321 RETURN VALUE 4322 If there is a previous alarm( ) request with time remaining, alarm( ) shall return a non-zero value 4323 that is the number of seconds until the previous request would have generated a SIGALRM 4324 signal. Otherwise, alarm( ) shall return 0. 4325 ERRORS 4326 The alarm( ) function is always successful, and no return value is reserved to indicate an error. 4327 EXAMPLES 4328 None. 4329 APPLICATION USAGE 4330 The fork( ) function clears pending alarms in the child process. A new process image created by 4331 one of the exec functions inherits the time left to an alarm signal in the old process' image. 4332 Application writers should note that the type of the argument seconds and the return value of 4333 alarm( ) is unsigned. That means that a Strictly Conforming POSIX System Interfaces 4334 Application cannot pass a value greater than the minimum guaranteed value for {UINT_MAX}, 4335 which the ISO C standard sets as 65 535, and any application passing a larger value is restricting 4336 its portability. A different type was considered, but historical implementations, including those 4337 with a 16-bit int type, consistently use either unsigned or int. 4338 Application writers should be aware of possible interactions when the same process uses both 4339 the alarm( ) and sleep( ) functions. 4340 RATIONALE 4341 Many historical implementations (including Version 7 and System V) allow an alarm to occur up 4342 to a second early. Other implementations allow alarms up to half a second or one clock tick 4343 early or do not allow them to occur early at all. The latter is considered most appropriate, since it 4344 gives the most predictable behavior, especially since the signal can always be delayed for an 4345 indefinite amount of time due to scheduling. Applications can thus choose the seconds argument 4346 as the minimum amount of time they wish to have elapse before the signal. 4347 The term realtime here and elsewhere (sleep( ), times( )) is intended to mean ``wall clock'' time as 4348 common English usage, and has nothing to do with ``realtime operating systems''. It is in 4349 contrast to virtual time, which could be misinterpreted if just time were used. 4350 In some implementations, including 4.3 BSD, very large values of the seconds argument are 4351 silently rounded down to an implementation-defined maximum value. This maximum is large 570 Technical Standard (2001) (Draft April 16, 2001) System Interfaces alarm( ) 4352 enough (on the order of several months) that the effect is not noticeable. 4353 There were two possible choices for alarm generation in multi-threaded applications: generation 4354 for the calling thread or generation for the process. The first option would not have been 4355 particularly useful since the alarm state is maintained on a per-process basis and the alarm that 4356 is established by the last invocation of alarm( ) is the only one that would be active. 4357 Furthermore, allowing generation of an asynchronous signal for a thread would have introduced 4358 an exception to the overall signal model. This requires a compelling reason in order to be 4359 justified. 4360 FUTURE DIRECTIONS 4361 None. 4362 SEE ALSO 4363 alarm( ), exec, fork( ), getitimer( ), pause( ), sigaction( ), sleep( ), ualarm( ), usleep( ), the Base 4364 Definitions volume of IEEE Std 1003.1-200x, , 4365 CHANGE HISTORY 4366 First released in Issue 1. Derived from Issue 1 of the SVID. 4367 Issue 6 4368 The following new requirements on POSIX implementations derive from alignment with the 4369 Single UNIX Specification: 4370 * The DESCRIPTION is updated to indicate that interactions with the setitimer( ), ualarm( ), and 4371 usleep( ) functions are unspecified. System Interfaces, Issue 6 571 asctime( ) System Interfaces 4372 NAME 4373 asctime, asctime_r - convert date and time to a string 4374 SYNOPSIS 4375 #include 4376 char *asctime(const struct tm *timeptr); 4377 TSF char *asctime_r(const struct tm *restrict tm, char *restrict buf); 4378 4379 DESCRIPTION 4380 CX For asctime( ): The functionality described on this reference page is aligned with the ISO C | 4381 standard. Any conflict between the requirements described here and the ISO C standard is 4382 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4383 The asctime( ) function shall convert the broken-down time in the structure pointed to by timeptr 4384 into a string in the form: 4385 Sun Sep 16 01:03:52 1973\n\0 4386 using the equivalent of the following algorithm: 4387 char *asctime(const struct tm *timeptr) 4388 { 4389 static char wday_name[7][3] = { 4390 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" 4391 }; 4392 static char mon_name[12][3] = { 4393 "Jan", "Feb", "Mar", "Apr", "May", "Jun", 4394 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" 4395 }; 4396 static char result[26]; 4397 sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n", 4398 wday_name[timeptr->tm_wday], 4399 mon_name[timeptr->tm_mon], 4400 timeptr->tm_mday, timeptr->tm_hour, 4401 timeptr->tm_min, timeptr->tm_sec, 4402 1900 + timeptr->tm_year); 4403 return result; 4404 } 4405 The tm structure is defined in the header. | 4406 CX The asctime( ), ctime( ), gmtime( ), and localtime( ) functions shall return values in one of two static 4407 objects: a broken-down time structure and an array of type char. Execution of any of the 4408 functions may overwrite the information returned in either of these objects by any of the other 4409 functions. 4410 The asctime( ) function need not be reentrant. A function that is not required to be reentrant is not 4411 required to be thread-safe. 4412 TSF The asctime_r( ) function shall convert the broken-down time in the structure pointed to by tm 4413 into a string (of the same form as that returned by asctime( )) that is placed in the user-supplied 4414 buffer pointed to by buf (which shall contain at least 26 bytes) and then return buf. 572 Technical Standard (2001) (Draft April 16, 2001) System Interfaces asctime( ) 4415 RETURN VALUE 4416 Upon successful completion, asctime( ) shall return a pointer to the string. 4417 TSF Upon successful completion, asctime_r( ) shall return a pointer to a character string containing 4418 the date and time. This string is pointed to by the argument buf. If the function is unsuccessful, 4419 it shall return NULL. 4420 ERRORS 4421 No errors are defined. 4422 EXAMPLES 4423 None. 4424 APPLICATION USAGE 4425 Values for the broken-down time structure can be obtained by calling gmtime( ) or localtime( ). 4426 This function is included for compatibility with older implementations, and does not support 4427 localized date and time formats. Applications should use strftime( ) to achieve maximum 4428 portability. 4429 The asctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 4430 of possibly using a static data area that may be overwritten by each call. 4431 RATIONALE 4432 None. 4433 FUTURE DIRECTIONS 4434 None. 4435 SEE ALSO 4436 clock( ), ctime( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), 4437 the Base Definitions volume of IEEE Std 1003.1-200x, 4438 CHANGE HISTORY 4439 First released in Issue 1. Derived from Issue 1 of the SVID. 4440 Issue 5 4441 Normative text previously in the APPLICATION USAGE section is moved to the 4442 DESCRIPTION. 4443 The asctime_r( ) function is included for alignment with the POSIX Threads Extension. 4444 A note indicating that the asctime( ) function need not be reentrant is added to the 4445 DESCRIPTION. 4446 Issue 6 4447 The asctime_r( ) function is marked as part of the Thread-Safe Functions option. 4448 Extensions beyond the ISO C standard are now marked. 4449 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 4450 its avoidance of possibly using a static data area. 4451 The DESCRIPTION of asctime_r( ) is updated to describe the format of the string returned. 4452 The restrict keyword is added to the asctime_r( ) prototype for alignment with the 4453 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 573 asin( ) System Interfaces 4454 NAME 4455 asin, asinf, asinl - arc sine function 4456 SYNOPSIS 4457 #include 4458 double asin(double x); 4459 float asinf(float x); 4460 long double asinl(long double x); 4461 DESCRIPTION 4462 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4463 conflict between the requirements described here and the ISO C standard is unintentional. This 4464 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4465 These functions shall compute the principal value of the arc sine of their argument x. The value 4466 of x should be in the range [-1,1]. 4467 An application wishing to check for error situations should set errno to zero and call 4468 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 4469 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 4470 zero, an error has occurred. 4471 RETURN VALUE 4472 Upon successful completion, these functions shall return the arc sine of x, in the range 4473 [- /2, /2] radians. 4474 MX For finite values of x not in the range [-1,1], a domain error shall occur, and either a NaN (if 4475 supported), or an implementation-defined value shall be returned. 4476 MX If x is NaN, a NaN shall be returned. 4477 If x is ±0, x shall be returned. 4478 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 4479 defined value shall be returned. 4480 If x is subnormal, a range error may occur and x should be returned. 4481 ERRORS 4482 These functions shall fail if: 4483 MX Domain Error The x argument is finite and is not in the range [-1,1], or is ±Inf. 4484 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4485 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 4486 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 4487 shall be raised. | 4488 These functions may fail if: 4489 MX Range Error The value of x is subnormal. 4490 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4491 then errno shall be set to [ERANGE]. If the integer expression | 4492 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 4493 floating-point exception shall be raised. | 574 Technical Standard (2001) (Draft April 16, 2001) System Interfaces asin( ) 4494 EXAMPLES 4495 None. 4496 APPLICATION USAGE 4497 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 4498 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 4499 RATIONALE 4500 None. 4501 FUTURE DIRECTIONS 4502 None. 4503 SEE ALSO 4504 feclearexcept( ), fetestexcept( ), isnan( ), sin( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 4505 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 4506 CHANGE HISTORY 4507 First released in Issue 1. Derived from Issue 1 of the SVID. 4508 Issue 5 4509 The DESCRIPTION is updated to indicate how an application should check for an error. This 4510 text was previously published in the APPLICATION USAGE section. 4511 Issue 6 4512 The asinf( ) and asinl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 4513 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 4514 revised to align with the ISO/IEC 9899: 1999 standard. 4515 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 4516 marked. System Interfaces, Issue 6 575 asinf( ) System Interfaces 4517 NAME 4518 asinf - arc sine function 4519 SYNOPSIS 4520 #include 4521 float asinf(float x); 4522 DESCRIPTION 4523 Refer to asin( ). 576 Technical Standard (2001) (Draft April 16, 2001) System Interfaces asinfh( ) 4524 NAME 4525 asinfh, asinfl - inverse hyperbolic sine functions 4526 SYNOPSIS 4527 #include 4528 float asinhf(float x); 4529 long double asinhl(long double x); 4530 DESCRIPTION 4531 Refer to asinh( ). System Interfaces, Issue 6 577 asinh( ) System Interfaces 4532 NAME 4533 asinh, asinfh, asinfl - inverse hyperbolic sine functions 4534 SYNOPSIS 4535 #include 4536 double asinh(double x); 4537 float asinhf(float x); 4538 long double asinhl(long double x); 4539 DESCRIPTION 4540 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4541 conflict between the requirements described here and the ISO C standard is unintentional. This 4542 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4543 These functions shall compute the inverse hyperbolic sine of their argument x. 4544 An application wishing to check for error situations should set errno to zero and call 4545 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 4546 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 4547 zero, an error has occurred. 4548 RETURN VALUE 4549 Upon successful completion, these functions shall return the inverse hyperbolic sine, of their 4550 argument. 4551 MX If x is NaN, a NaN shall be returned. 4552 If x is ±0, or ±Inf, x shall be returned. 4553 If x is subnormal, a range error may occur and x should be returned. 4554 ERRORS 4555 These functions may fail if: 4556 MX Range Error The value of x is subnormal. 4557 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4558 then errno shall be set to [ERANGE]. If the integer expression | 4559 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 4560 floating-point exception shall be raised. | 4561 EXAMPLES 4562 None. 4563 APPLICATION USAGE 4564 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 4565 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 4566 RATIONALE 4567 None. 4568 FUTURE DIRECTIONS 4569 None. 4570 SEE ALSO 4571 feclearexcept( ), fetestexcept( ), sinh( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 4572 4.18, Treatment of Error Conditions for Mathematical Functions, | 578 Technical Standard (2001) (Draft April 16, 2001) System Interfaces asinh( ) 4573 CHANGE HISTORY 4574 First released in Issue 4, Version 2. 4575 Issue 5 4576 Moved from X/OPEN UNIX extension to BASE. 4577 Issue 6 4578 The asinh( ) function is no longer marked as an extension. 4579 The asinhf( ), and asinhl( ) functions are added for alignment with the ISO/IEC 9899: 1999 4580 standard. 4581 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 4582 revised to align with the ISO/IEC 9899: 1999 standard. 4583 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 4584 marked. System Interfaces, Issue 6 579 asinl( ) System Interfaces 4585 NAME 4586 asinl - arc sine function 4587 SYNOPSIS 4588 #include 4589 long double asinl(long double x); 4590 DESCRIPTION 4591 Refer to asin( ). 580 Technical Standard (2001) (Draft April 16, 2001) System Interfaces assert( ) 4592 NAME 4593 assert - insert program diagnostics 4594 SYNOPSIS 4595 #include 4596 void assert(scalar expression); 4597 DESCRIPTION 4598 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4599 conflict between the requirements described here and the ISO C standard is unintentional. This 4600 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4601 The assert( ) macro shall insert diagnostics into programs; it shall expand to a void expression. | 4602 When it is executed, if expression (which shall have a scalar type) is false (that is, compares equal 4603 to 0), assert( ) shall write information about the particular call that failed on stderr and shall call 4604 abort( ). 4605 The information written about the call that failed shall include the text of the argument, the 4606 name of the source file, the source file line number, and the name of the enclosing function, the 4607 latter are, respectively, the values of the preprocessing macros _ _FILE_ _ and _ _LINE_ _ and of 4608 the identifier _ _func_ _. 4609 Forcing a definition of the name NDEBUG, either from the compiler command line or with the 4610 preprocessor control statement #define NDEBUG ahead of the #include statement, 4611 shall stop assertions from being compiled into the program. 4612 RETURN VALUE 4613 The assert( ) macro shall not return a value. 4614 ERRORS 4615 No errors are defined. 4616 EXAMPLES 4617 None. 4618 APPLICATION USAGE 4619 None. 4620 RATIONALE 4621 None. 4622 FUTURE DIRECTIONS 4623 None. 4624 SEE ALSO 4625 abort( ), the Base Definitions volume of IEEE Std 1003.1-200x, , stderr 4626 CHANGE HISTORY 4627 First released in Issue 1. Derived from Issue 1 of the SVID. 4628 Issue 6 4629 The prototype for the expression argument to assert( ) is changed from int to scalar for alignment 4630 with the ISO/IEC 9899: 1999 standard. 4631 The DESCRIPTION of assert( ) is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 581 atan( ) System Interfaces 4632 NAME 4633 atan, atanf, atanl - arc tangent function 4634 SYNOPSIS 4635 #include 4636 double atan(double x); 4637 float atanf(float x); 4638 long double atanl(long double x); 4639 DESCRIPTION 4640 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4641 conflict between the requirements described here and the ISO C standard is unintentional. This 4642 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4643 These functions shall compute the principal value of the arc tangent of their argument x. 4644 An application wishing to check for error situations should set errno to zero and call 4645 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 4646 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 4647 zero, an error has occurred. 4648 RETURN VALUE 4649 Upon successful completion, these functions shall return the arc tangent of x in the range 4650 [- /2, /2] radians. 4651 MX If x is NaN, a NaN shall be returned. 4652 If x is ±0 x shall be returned. 4653 If x is ±Inf, ± /2 shall be returned. 4654 If x is subnormal, a range error may occur and x should be returned. 4655 ERRORS 4656 These functions may fail if: 4657 MX Range Error The value of x is subnormal. 4658 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4659 then errno shall be set to [ERANGE]. If the integer expression | 4660 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 4661 floating-point exception shall be raised. | 4662 EXAMPLES 4663 None. 4664 APPLICATION USAGE 4665 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 4666 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 4667 RATIONALE 4668 None. 4669 FUTURE DIRECTIONS 4670 None. 4671 SEE ALSO 4672 atan2( ), feclearexcept( ), fetestexcept( ), isnan( ), tan( ), the Base Definitions volume of | 4673 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 4674 582 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atan( ) 4675 CHANGE HISTORY 4676 First released in Issue 1. Derived from Issue 1 of the SVID. 4677 Issue 5 4678 The DESCRIPTION is updated to indicate how an application should check for an error. This 4679 text was previously published in the APPLICATION USAGE section. 4680 Issue 6 4681 The atanf( ) and atanl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 4682 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 4683 revised to align with the ISO/IEC 9899: 1999 standard. 4684 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 4685 marked. System Interfaces, Issue 6 583 atan2( ) System Interfaces 4686 NAME 4687 atan2, atan2f, atan2l - arc tangent functions 4688 SYNOPSIS 4689 #include 4690 double atan2(double y, double x); 4691 float atan2f(float y, float x); 4692 long double atan2l(long double y, long double x); 4693 DESCRIPTION 4694 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4695 conflict between the requirements described here and the ISO C standard is unintentional. This 4696 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4697 These functions shall compute the principal value of the arc tangent of y/x, using the signs of 4698 both arguments to determine the quadrant of the return value. 4699 An application wishing to check for error situations should set errno to zero and call 4700 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 4701 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 4702 zero, an error has occurred. 4703 RETURN VALUE 4704 Upon successful completion, these functions shall return the arc tangent of y/x in the range 4705 [- , ] radians. 4706 If y is ±0 and x is < 0, ± shall be returned. 4707 If y is ±0 and x is > 0, ±0 shall be returned. 4708 If y is < 0 and x is ±0, - /2 shall be returned. 4709 If y is > 0 and x is ±0, /2 shall be returned. 4710 If x is 0, a pole error shall not occur. 4711 MX If either x or y is NaN, a NaN shall be returned. 4712 If the result underflows, a range error may occur and y/x should be returned. 4713 If y is ±0 and x is -0, ± shall be returned. 4714 If y is ±0 and x is +0, ±0 shall be returned. 4715 For finite values of ±y > 0, if x is -Inf, ± shall be returned. 4716 For finite values of ±y > 0, if x is +Inf, ±0 shall be returned. 4717 For finite values of x, if y is ±Inf, ± /2 shall be returned. 4718 If y is ±Inf and x is -Inf, ±3 /4 shall be returned. 4719 If y is ±Inf and x is +Inf, ± /4 shall be returned. 4720 If both arguments are 0, a domain error shall not occur. 4721 ERRORS 4722 These functions may fail if: 4723 MX Range Error The result underflows. 4724 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4725 then errno shall be set to [ERANGE]. If the integer expression | 584 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atan2( ) 4726 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 4727 floating-point exception shall be raised. | 4728 EXAMPLES 4729 None. 4730 APPLICATION USAGE 4731 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 4732 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 4733 RATIONALE 4734 None. 4735 FUTURE DIRECTIONS 4736 None. 4737 SEE ALSO 4738 atan( ), feclearexcept( ), fetestexcept( ), isnan( ), tan( ), the Base Definitions volume of | 4739 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 4740 4741 CHANGE HISTORY 4742 First released in Issue 1. Derived from Issue 1 of the SVID. 4743 Issue 5 4744 The DESCRIPTION is updated to indicate how an application should check for an error. This 4745 text was previously published in the APPLICATION USAGE section. 4746 Issue 6 4747 The atan2f( ) and atan2l( ) functions are added for alignment with the ISO/IEC 9899: 1999 4748 standard. 4749 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 4750 revised to align with the ISO/IEC 9899: 1999 standard. 4751 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 4752 marked. System Interfaces, Issue 6 585 atanf( ) System Interfaces 4753 NAME 4754 atanf - arc tangent function 4755 SYNOPSIS 4756 #include 4757 float atanf(float x); 4758 DESCRIPTION 4759 Refer to atan( ). 586 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atanh( ) 4760 NAME 4761 atanh, atanhf, atanhl - inverse hyperbolic tangent functions 4762 SYNOPSIS 4763 #include 4764 double atanh(double x); 4765 float atanhf(float x); 4766 long double atanhl(long double x); 4767 DESCRIPTION 4768 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4769 conflict between the requirements described here and the ISO C standard is unintentional. This 4770 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4771 These functions shall compute the inverse hyperbolic tangent of their argument x. 4772 An application wishing to check for error situations should set errno to zero and call 4773 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 4774 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 4775 zero, an error has occurred. 4776 RETURN VALUE 4777 Upon successful completion, these functions shall return the inverse hyperbolic tangent of their 4778 argument. 4779 If x is ±1, a pole error shall occur, and atanh( ), atanhf( ), and atanhl( ) shall return the value of the 4780 macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively, with the same sign as the 4781 correct value of the function. 4782 MX For finite |x|>1, a domain error shall occur, and either a NaN (if supported), or an 4783 implementation-defined value shall be returned. 4784 MX If x is NaN, a NaN shall be returned. 4785 If x is ±0, x shall be returned. 4786 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 4787 defined value shall be returned. 4788 If x is subnormal, a range error may occur and x should be returned. 4789 ERRORS 4790 These functions shall fail if: 4791 MX Domain Error The x argument is finite and not in the range [-1,1], or is ±Inf. 4792 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4793 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 4794 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 4795 shall be raised. | 4796 Pole Error The x argument is ±1. 4797 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4798 then errno shall be set to [ERANGE]. If the integer expression | 4799 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 4800 zero floating-point exception shall be raised. | 4801 These functions may fail if: System Interfaces, Issue 6 587 atanh( ) System Interfaces 4802 MX Range Error The value of x is subnormal. 4803 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 4804 then errno shall be set to [ERANGE]. If the integer expression | 4805 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 4806 floating-point exception shall be raised. | 4807 EXAMPLES 4808 None. 4809 APPLICATION USAGE 4810 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 4811 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 4812 RATIONALE 4813 None. 4814 FUTURE DIRECTIONS 4815 None. 4816 SEE ALSO 4817 feclearexcept( ), fetestexcept( ), tanh( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 4818 4.18, Treatment of Error Conditions for Mathematical Functions, | 4819 CHANGE HISTORY 4820 First released in Issue 4, Version 2. 4821 Issue 5 4822 Moved from X/OPEN UNIX extension to BASE. 4823 Issue 6 4824 The atanh( ) function is no longer marked as an extension. 4825 The atanhf( ), and atanhl( ) functions are added for alignment with the ISO/IEC 9899: 1999 4826 standard. 4827 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 4828 revised to align with the ISO/IEC 9899: 1999 standard. 4829 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 4830 marked. 588 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atanl( ) 4831 NAME 4832 atanl - arc tangent function 4833 SYNOPSIS 4834 #include 4835 long double atanl(long double x); 4836 DESCRIPTION 4837 Refer to atan( ). System Interfaces, Issue 6 589 atexit( ) System Interfaces 4838 NAME 4839 atexit - register a function to run at process termination 4840 SYNOPSIS 4841 #include 4842 int atexit(void (*func)(void)); 4843 DESCRIPTION 4844 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4845 conflict between the requirements described here and the ISO C standard is unintentional. This 4846 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4847 The atexit( ) function shall register the function pointed to by func, to be called without | 4848 arguments at normal program termination. At normal program termination, all functions 4849 registered by the atexit( ) function shall be called, in the reverse order of their registration, except 4850 that a function is called after any previously registered functions that had already been called at 4851 the time it was registered. Normal termination occurs either by a call to exit( ) or a return from 4852 main( ). 4853 At least 32 functions can be registered with atexit( ). 4854 CX After a successful call to any of the exec functions, any functions previously registered by atexit( ) 4855 shall no longer be registered. 4856 RETURN VALUE 4857 Upon successful completion, atexit( ) shall return 0; otherwise, it shall return a non-zero value. 4858 ERRORS 4859 No errors are defined. 4860 EXAMPLES 4861 None. 4862 APPLICATION USAGE 4863 The functions registered by a call to atexit( ) must return to ensure that all registered functions 4864 are called. 4865 The application should call sysconf( ) to obtain the value of {ATEXIT_MAX}, the number of 4866 functions that can be registered. There is no way for an application to tell how many functions 4867 have already been registered with atexit( ). 4868 RATIONALE 4869 None. 4870 FUTURE DIRECTIONS 4871 None. 4872 SEE ALSO 4873 exit( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4874 CHANGE HISTORY 4875 First released in Issue 4. Derived from the ANSI C standard. 4876 Issue 6 4877 Extensions beyond the ISO C standard are now marked. 4878 The DESCRIPTION is updated for alignment with the ISO/IEC 9899: 1999 standard. 590 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atof( ) 4879 NAME 4880 atof - convert a string to double-precision number 4881 SYNOPSIS 4882 #include 4883 double atof(const char *str); 4884 DESCRIPTION 4885 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4886 conflict between the requirements described here and the ISO C standard is unintentional. This 4887 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4888 The call atof(str) shall be equivalent to: 4889 strtod(str,(char **)NULL), 4890 except that the handling of errors may differ. If the value cannot be represented, the behavior is 4891 undefined. 4892 RETURN VALUE 4893 The atof( ) function shall return the converted value if the value can be represented. 4894 ERRORS 4895 No errors are defined. 4896 EXAMPLES 4897 None. 4898 APPLICATION USAGE 4899 The atof( ) function is subsumed by strtod( ) but is retained because it is used extensively in 4900 existing code. If the number is not known to be in range, strtod( ) should be used because atof( ) is 4901 not required to perform any error checking. 4902 RATIONALE 4903 None. 4904 FUTURE DIRECTIONS 4905 None. 4906 SEE ALSO 4907 strtod( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4908 CHANGE HISTORY 4909 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 591 atoi( ) System Interfaces 4910 NAME 4911 atoi - convert a string to an integer 4912 SYNOPSIS 4913 #include 4914 int atoi(const char *str); 4915 DESCRIPTION 4916 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4917 conflict between the requirements described here and the ISO C standard is unintentional. This 4918 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4919 The call atoi(str) shall be equivalent to: 4920 (int) strtol(str, (char **)NULL, 10) 4921 except that the handling of errors may differ. If the value cannot be represented, the behavior is 4922 undefined. 4923 RETURN VALUE 4924 The atoi( ) function shall return the converted value if the value can be represented. 4925 ERRORS 4926 No errors are defined. 4927 EXAMPLES 4928 Converting an Argument 4929 The following example checks for proper usage of the program. If there is an argument and the 4930 decimal conversion of this argument (obtained using atoi( )) is greater than 0, then the program 4931 has a valid number of minutes to wait for an event. 4932 #include 4933 #include 4934 ... 4935 int minutes_to_event; 4936 ... 4937 if (argc < 2 || ((minutes_to_event = atoi (argv[1]))) <= 0) { 4938 fprintf(stderr, "Usage: %s minutes\n", argv[0]); exit(1); 4939 } 4940 ... 4941 APPLICATION USAGE 4942 The atoi( ) function is subsumed by strtol( ) but is retained because it is used extensively in 4943 existing code. If the number is not known to be in range, strtol( ) should be used because atoi( ) is 4944 not required to perform any error checking. 4945 RATIONALE 4946 None. 4947 FUTURE DIRECTIONS 4948 None. 4949 SEE ALSO 4950 strtol( ), the Base Definitions volume of IEEE Std 1003.1-200x, 592 Technical Standard (2001) (Draft April 16, 2001) System Interfaces atoi( ) 4951 CHANGE HISTORY 4952 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 593 atol( ) System Interfaces 4953 NAME 4954 atol, atoll - convert a string to a long integer 4955 SYNOPSIS 4956 #include 4957 long atol(const char *str); 4958 long long atoll(const char *nptr); 4959 DESCRIPTION 4960 CX The functionality described on this reference page is aligned with the ISO C standard. Any 4961 conflict between the requirements described here and the ISO C standard is unintentional. This 4962 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 4963 The call atol(str) shall be equivalent to: 4964 strtol(str, (char **)NULL, 10) 4965 The call atoll(str) shall be equivalent to: 4966 strtoll(nptr, (char **)NULL, 10) 4967 except that the handling of errors may differ. If the value cannot be represented, the behavior is 4968 undefined. 4969 RETURN VALUE 4970 These functions shall return the converted value if the value can be represented. 4971 ERRORS 4972 No errors are defined. 4973 EXAMPLES 4974 None. 4975 APPLICATION USAGE 4976 The atol( ) function is subsumed by strtol( ) but is retained because it is used extensively in 4977 existing code. If the number is not known to be in range, strtol( ) should be used because atol( ) is 4978 not required to perform any error checking. 4979 RATIONALE 4980 None. 4981 FUTURE DIRECTIONS 4982 None. 4983 SEE ALSO 4984 strtol( ), the Base Definitions volume of IEEE Std 1003.1-200x, 4985 CHANGE HISTORY 4986 First released in Issue 1. Derived from Issue 1 of the SVID. 4987 Issue 6 4988 The atoll( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. 594 Technical Standard (2001) (Draft April 16, 2001) System Interfaces basename( ) 4989 NAME 4990 basename - return the last component of a pathname | 4991 SYNOPSIS 4992 XSI #include 4993 char *basename(char *path); 4994 4995 DESCRIPTION 4996 The basename( ) function shall take the pathname pointed to by path and return a pointer to the | 4997 final component of the pathname, deleting any trailing '/' characters. | 4998 If the string consists entirely of the '/' character, basename( ) shall return a pointer to the string 4999 "/". If the string is exactly "//", it is implementation-defined whether '/' or "//" is 5000 returned. 5001 If path is a null pointer or points to an empty string, basename( ) shall return a pointer to the 5002 string ".". 5003 The basename( ) function may modify the string pointed to by path, and may return a pointer to 5004 static storage that may then be overwritten by a subsequent call to basename( ). 5005 The basename( ) function need not be reentrant. A function that is not required to be reentrant is 5006 not required to be thread-safe. 5007 RETURN VALUE 5008 The basename( ) function shall return a pointer to the final component of path. 5009 ERRORS 5010 No errors are defined. 5011 EXAMPLES 5012 Using basename( ) 5013 The following program fragment returns a pointer to the value lib, which is the base name of 5014 /usr/lib. 5015 #include 5016 ... 5017 char *name = "/usr/lib"; 5018 char *base; 5019 base = basename(name); 5020 ... 5021 Sample Input and Output Strings for basename( ) 5022 In the following table, the input string is the value pointed to by path, and the output string is 5023 the return value of the basename( ) function. ______________________________ 5024 _ Input String Output String _____________________________ 5025 "/usr/lib" "lib" 5026 "/usr/" "usr" 5027 _ "/" "/" _____________________________ System Interfaces, Issue 6 595 basename( ) System Interfaces 5028 APPLICATION USAGE 5029 None. 5030 RATIONALE 5031 None. 5032 FUTURE DIRECTIONS 5033 None. 5034 SEE ALSO 5035 dirname( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell and 5036 Utilities volume of IEEE Std 1003.1-200x, basename 5037 CHANGE HISTORY 5038 First released in Issue 4, Version 2. 5039 Issue 5 5040 Moved from X/OPEN UNIX extension to BASE. 5041 Normative text previously in the APPLICATION USAGE section is moved to the 5042 DESCRIPTION. 5043 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 5044 Issue 6 5045 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 596 Technical Standard (2001) (Draft April 16, 2001) System Interfaces bcmp( ) 5046 NAME 5047 bcmp - memory operations (LEGACY) 5048 SYNOPSIS 5049 XSI #include 5050 int bcmp(const void *s1, const void *s2, size_t n); 5051 5052 DESCRIPTION 5053 The bcmp( ) function shall compare the first n bytes of the area pointed to by s1 with the area 5054 pointed to by s2. 5055 RETURN VALUE 5056 The bcmp( ) function shall return 0 if s1 and s2 are identical; otherwise, it shall return non-zero. 5057 Both areas are assumed to be n bytes long. If the value of n is 0, bcmp( ) shall return 0. 5058 ERRORS 5059 No errors are defined. 5060 EXAMPLES 5061 None. 5062 APPLICATION USAGE 5063 memcmp( ) is preferred over this function. 5064 For maximum portability, it is recommended to replace the function call to bcmp( ) as follows: 5065 #define bcmp(b1,b2,len) memcmp((b1), (b2), (size_t)(len)) 5066 RATIONALE 5067 None. 5068 FUTURE DIRECTIONS 5069 This function may be withdrawn in a future version. 5070 SEE ALSO 5071 memcmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5072 CHANGE HISTORY 5073 First released in Issue 4, Version 2. 5074 Issue 5 5075 Moved from X/OPEN UNIX extension to BASE. 5076 Issue 6 5077 This function is marked LEGACY. System Interfaces, Issue 6 597 bcopy( ) System Interfaces 5078 NAME 5079 bcopy - memory operations (LEGACY) 5080 SYNOPSIS 5081 XSI #include 5082 void bcopy(const void *s1, void *s2, size_t n); 5083 5084 DESCRIPTION 5085 The bcopy( ) function shall copy n bytes from the area pointed to by s1 to the area pointed to by 5086 s2. 5087 The bytes are copied correctly even if the area pointed to by s1 overlaps the area pointed to by 5088 s2. 5089 RETURN VALUE 5090 The bcopy( ) function shall not return a value. 5091 ERRORS 5092 No errors are defined. 5093 EXAMPLES 5094 None. 5095 APPLICATION USAGE 5096 memmove( ) is preferred over this function. 5097 The following are approximately equivalent (note the order of the arguments): 5098 bcopy(s1,s2,n) = memmove(s2,s1,n) 5099 For maximum portability, it is recommended to replace the function call to bcopy( ) as follows: 5100 #define bcopy(b1,b2,len) (memmove((b2), (b1), (len)), (void) 0) 5101 RATIONALE 5102 None. 5103 FUTURE DIRECTIONS 5104 This function may be withdrawn in a future version. 5105 SEE ALSO 5106 memmove( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5107 CHANGE HISTORY 5108 First released in Issue 4, Version 2. 5109 Issue 5 5110 Moved from X/OPEN UNIX extension to BASE. 5111 Issue 6 5112 This function is marked LEGACY. 598 Technical Standard (2001) (Draft April 16, 2001) System Interfaces bind( ) 5113 NAME 5114 bind - bind a name to a socket 5115 SYNOPSIS 5116 #include 5117 int bind(int socket, const struct sockaddr *address, 5118 socklen_t address_len); 5119 DESCRIPTION 5120 The bind( ) function shall assign a local socket address address to a socket identified by descriptor 5121 socket that has no local socket address assigned. Sockets created with the socket( ) function are 5122 initially unnamed; they are identified only by their address family. 5123 The bind( ) function takes the following arguments: 5124 socket Specifies the file descriptor of the socket to be bound. 5125 address Points to a sockaddr structure containing the address to be bound to the 5126 socket. The length and format of the address depend on the address family of 5127 the socket. 5128 address_len Specifies the length of the sockaddr structure pointed to by the address 5129 argument. 5130 The socket specified by socket may require the process to have appropriate privileges to use the 5131 bind( ) function. 5132 RETURN VALUE 5133 Upon successful completion, bind( ) shall return 0; otherwise, -1 shall be returned and errno set 5134 to indicate the error. 5135 ERRORS 5136 The bind( ) function shall fail if: 5137 [EADDRINUSE] 5138 The specified address is already in use. 5139 [EADDRNOTAVAIL] 5140 The specified address is not available from the local machine. 5141 [EAFNOSUPPORT] 5142 The specified address is not a valid address for the address family of the 5143 specified socket. 5144 [EBADF] The socket argument is not a valid file descriptor. 5145 [EINVAL] The socket is already bound to an address, and the protocol does not support 5146 binding to a new address; or the socket has been shut down. 5147 [ENOTSOCK] The socket argument does not refer to a socket. 5148 [EOPNOTSUPP] The socket type of the specified socket does not support binding to an 5149 address. 5150 If the address family of the socket is AF_UNIX, then bind( ) shall fail if: 5151 [EACCES] A component of the path prefix denies search permission, or the requested 5152 name requires writing in a directory with a mode that denies write 5153 permission. System Interfaces, Issue 6 599 bind( ) System Interfaces 5154 [EDESTADDRREQ] or [EISDIR] 5155 The address argument is a null pointer. 5156 [EIO] An I/O error occurred. 5157 [ELOOP] A loop exists in symbolic links encountered during resolution of the pathname | 5158 in address. | 5159 [ENAMETOOLONG] 5160 A component of a pathname exceeded {NAME_MAX} characters, or an entire | 5161 pathname exceeded {PATH_MAX} characters. | 5162 [ENOENT] A component of the pathname does not name an existing file or the pathname | 5163 is an empty string. | 5164 [ENOTDIR] A component of the path prefix of the pathname in address is not a directory. | 5165 [EROFS] The name would reside on a read-only file system. 5166 The bind( ) function may fail if: 5167 [EACCES] The specified address is protected and the current user does not have 5168 permission to bind to it. 5169 [EINVAL] The address_len argument is not a valid length for the address family. 5170 [EISCONN] The socket is already connected. 5171 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 5172 resolution of the pathname in address. | 5173 [ENAMETOOLONG] 5174 Pathname resolution of a symbolic link produced an intermediate result | 5175 whose length exceeds {PATH_MAX}. 5176 [ENOBUFS] Insufficient resources were available to complete the call. 5177 EXAMPLES 5178 None. 5179 APPLICATION USAGE 5180 An application program can retrieve the assigned socket name with the getsockname( ) function. 5181 RATIONALE 5182 None. 5183 FUTURE DIRECTIONS 5184 None. 5185 SEE ALSO 5186 connect( ), getsockname( ), listen( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5187 5188 CHANGE HISTORY 5189 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 600 Technical Standard (2001) (Draft April 16, 2001) System Interfaces bsd_signal( ) 5190 NAME 5191 bsd_signal - simplified signal facilities 5192 SYNOPSIS 5193 OB XSI #include 5194 void (*bsd_signal(int sig, void (*func)(int)))(int); 5195 5196 DESCRIPTION 5197 The bsd_signal( ) function provides a partially compatible interface for programs written to 5198 historical system interfaces (see APPLICATION USAGE). 5199 The function call bsd_signal(sig, func) shall be equivalent to the following: | 5200 void (*bsd_signal(int sig, void (*func)(int)))(int) 5201 { 5202 struct sigaction act, oact; 5203 act.sa_handler = func; 5204 act.sa_flags = SA_RESTART; 5205 sigemptyset(&act.sa_mask); 5206 sigaddset(&act.sa_mask, sig); 5207 if (sigaction(sig, &act, &oact) == -1) 5208 return(SIG_ERR); 5209 return(oact.sa_handler); 5210 } 5211 The handler function should be declared: 5212 void handler(int sig); 5213 where sig is the signal number. The behavior is undefined if func is a function that takes more 5214 than one argument, or an argument of a different type. 5215 RETURN VALUE 5216 Upon successful completion, bsd_signal( ) shall return the previous action for sig. Otherwise, 5217 SIG_ERR shall be returned and errno shall be set to indicate the error. 5218 ERRORS 5219 Refer to sigaction( ). 5220 EXAMPLES 5221 None. 5222 APPLICATION USAGE 5223 This function is a direct replacement for the BSD signal( ) function for simple applications that 5224 are installing a single-argument signal handler function. If a BSD signal handler function is being 5225 installed that expects more than one argument, the application has to be modified to use 5226 sigaction( ). The bsd_signal( ) function differs from signal( ) in that the SA_RESTART flag is set 5227 and the SA_RESETHAND is clear when bsd_signal( ) is used. The state of these flags is not 5228 specified for signal( ). 5229 It is recommended that new applications use the sigaction( ) function. 5230 RATIONALE 5231 None. System Interfaces, Issue 6 601 bsd_signal( ) System Interfaces 5232 FUTURE DIRECTIONS 5233 None. 5234 SEE ALSO 5235 sigaction( ), sigaddset( ), sigemptyset( ), signal( ), the Base Definitions volume of 5236 IEEE Std 1003.1-200x, 5237 CHANGE HISTORY 5238 First released in Issue 4, Version 2. 5239 Issue 5 5240 Moved from X/OPEN UNIX extension to BASE. 5241 Issue 6 5242 This function is marked obsolescent. 602 Technical Standard (2001) (Draft April 16, 2001) System Interfaces bsearch( ) 5243 NAME 5244 bsearch - binary search a sorted table 5245 SYNOPSIS 5246 #include 5247 void *bsearch(const void *key, const void *base, size_t nel, 5248 size_t width, int (*compar)(const void *, const void *)); 5249 DESCRIPTION 5250 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5251 conflict between the requirements described here and the ISO C standard is unintentional. This 5252 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5253 The bsearch( ) function shall search an array of nel objects, the initial element of which is pointed | 5254 to by base, for an element that matches the object pointed to by key. The size of each element in 5255 the array is specified by width. 5256 The comparison function pointed to by compar shall be called with two arguments that point to | 5257 the key object and to an array element, in that order. | 5258 The application shall ensure that the function returns an integer less than, equal to, or greater 5259 than 0 if the key object is considered, respectively, to be less than, to match, or to be greater than 5260 the array element. The application shall ensure that the array consists of all the elements that 5261 compare less than, all the elements that compare equal to, and all the elements that compare 5262 greater than the key object, in that order. 5263 RETURN VALUE 5264 The bsearch( ) function shall return a pointer to a matching member of the array, or a null pointer 5265 if no match is found. If two or more members compare equal, which member is returned is 5266 unspecified. 5267 ERRORS 5268 No errors are defined. 5269 EXAMPLES 5270 The example below searches a table containing pointers to nodes consisting of a string and its 5271 length. The table is ordered alphabetically on the string in the node pointed to by each entry. 5272 The code fragment below reads in strings and either finds the corresponding node and prints out 5273 the string and its length, or prints an error message. 5274 #include 5275 #include 5276 #include 5277 #define TABSIZE 1000 5278 struct node { /* These are stored in the table. */ 5279 char *string; 5280 int length; 5281 }; 5282 struct node table[TABSIZE]; /* Table to be searched. */ 5283 . 5284 . 5285 . 5286 { 5287 struct node *node_ptr, node; 5288 /* routine to compare 2 nodes */ System Interfaces, Issue 6 603 bsearch( ) System Interfaces 5289 int node_compare(const void *, const void *); 5290 char str_space[20]; /* Space to read string into. */ 5291 . 5292 . 5293 . 5294 node.string = str_space; 5295 while (scanf("%s", node.string) != EOF) { 5296 node_ptr = (struct node *)bsearch((void *)(&node), 5297 (void *)table, TABSIZE, 5298 sizeof(struct node), node_compare); 5299 if (node_ptr != NULL) { 5300 (void)printf("string = %20s, length = %d\n", 5301 node_ptr->string, node_ptr->length); 5302 } else { 5303 (void)printf("not found: %s\n", node.string); 5304 } 5305 } 5306 } 5307 /* 5308 This routine compares two nodes based on an 5309 alphabetical ordering of the string field. 5310 */ 5311 int 5312 node_compare(const void *node1, const void *node2) 5313 { 5314 return strcoll(((const struct node *)node1)->string, 5315 ((const struct node *)node2)->string); 5316 } 5317 APPLICATION USAGE 5318 The pointers to the key and the element at the base of the table should be of type pointer-to- 5319 element. 5320 The comparison function need not compare every byte, so arbitrary data may be contained in 5321 the elements in addition to the values being compared. 5322 In practice, the array is usually sorted according to the comparison function. 5323 RATIONALE 5324 None. 5325 FUTURE DIRECTIONS 5326 None. 5327 SEE ALSO 5328 hcreate( ), lsearch( ), qsort( ), tsearch( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5329 5330 CHANGE HISTORY 5331 First released in Issue 1. Derived from Issue 1 of the SVID. 5332 Issue 6 5333 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 604 Technical Standard (2001) (Draft April 16, 2001) System Interfaces btowc( ) 5334 NAME 5335 btowc - single byte to wide character conversion 5336 SYNOPSIS 5337 #include 5338 #include 5339 wint_t btowc(int c); 5340 DESCRIPTION 5341 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5342 conflict between the requirements described here and the ISO C standard is unintentional. This 5343 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5344 The btowc( ) function shall determine whether c constitutes a valid (one-byte) character in the 5345 initial shift state. 5346 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 5347 RETURN VALUE 5348 The btowc( ) function shall return WEOF if c has the value EOF or if (unsigned char) c does not 5349 constitute a valid (one-byte) character in the initial shift state. Otherwise, it shall return the 5350 wide-character representation of that character. 5351 ERRORS 5352 No errors are defined. 5353 EXAMPLES 5354 None. 5355 APPLICATION USAGE 5356 None. 5357 RATIONALE 5358 None. 5359 FUTURE DIRECTIONS 5360 None. 5361 SEE ALSO 5362 wctob( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5363 CHANGE HISTORY 5364 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 5365 (E). System Interfaces, Issue 6 605 bzero( ) System Interfaces 5366 NAME 5367 bzero - memory operations (LEGACY) 5368 SYNOPSIS 5369 XSI #include 5370 void bzero(void *s, size_t n); 5371 5372 DESCRIPTION 5373 The bzero( ) function shall place n zero-valued bytes in the area pointed to by s. 5374 RETURN VALUE 5375 The bzero( ) function shall not return a value. 5376 ERRORS 5377 No errors are defined. 5378 EXAMPLES 5379 None. 5380 APPLICATION USAGE 5381 memset( ) is preferred over this function. 5382 For maximum portability, it is recommended to replace the function call to bzero( ) as follows: 5383 #define bzero(b,len) (memset((b), '\0', (len)), (void) 0) 5384 RATIONALE 5385 None. 5386 FUTURE DIRECTIONS 5387 This function may be withdrawn in a future version. 5388 SEE ALSO 5389 memset( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5390 CHANGE HISTORY 5391 First released in Issue 4, Version 2. 5392 Issue 5 5393 Moved from X/OPEN UNIX extension to BASE. 5394 Issue 6 5395 This function is marked LEGACY. 606 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cabs( ) 5396 NAME 5397 cabs, cabsf, cabsl - return a complex absolute value 5398 SYNOPSIS 5399 #include 5400 double cabs(double complex z); 5401 float cabsf(float complex z); 5402 long double cabsl(long double complex z); 5403 DESCRIPTION 5404 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5405 conflict between the requirements described here and the ISO C standard is unintentional. This 5406 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5407 These functions shall compute the complex absolute value (also called norm, modulus, or 5408 magnitude) of z. 5409 RETURN VALUE 5410 These functions shall return the complex absolute value. 5411 ERRORS 5412 No errors are defined. 5413 EXAMPLES 5414 None. 5415 APPLICATION USAGE 5416 None. 5417 RATIONALE 5418 None. 5419 FUTURE DIRECTIONS 5420 None. 5421 SEE ALSO 5422 The Base Definitions volume of IEEE Std 1003.1-200x, 5423 CHANGE HISTORY 5424 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 607 cacos( ) System Interfaces 5425 NAME 5426 cacos, cacosf, cacosl - complex arc cosine functions 5427 SYNOPSIS 5428 #include 5429 double complex cacos(double complex z); 5430 float complex cacosf(float complex z); 5431 long double complex cacosl(long double complex z); 5432 DESCRIPTION 5433 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5434 conflict between the requirements described here and the ISO C standard is unintentional. This 5435 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5436 These functions shall compute the complex arc cosine of z, with branch cuts outside the interval 5437 [-1, +1] along the real axis. 5438 RETURN VALUE 5439 These functions shall return the complex arc cosine value, in the range of a strip mathematically 5440 unbounded along the imaginary axis and in the interval [0, ] along the real axis. 5441 ERRORS 5442 No errors are defined. 5443 EXAMPLES 5444 None. 5445 APPLICATION USAGE 5446 None. 5447 RATIONALE 5448 None. 5449 FUTURE DIRECTIONS 5450 None. 5451 SEE ALSO 5452 ccos( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5453 CHANGE HISTORY 5454 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 608 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cacosf( ) 5455 NAME 5456 cacosf - complex arc cosine functions 5457 SYNOPSIS 5458 #include 5459 float complex cacosf(float complex z); 5460 DESCRIPTION 5461 Refer to cacos( ). System Interfaces, Issue 6 609 cacosh( ) System Interfaces 5462 NAME 5463 cacosh, cacoshf, cacoshl - complex arc hyperbolic cosine functions 5464 SYNOPSIS 5465 #include 5466 double complex cacosh(double complex z); 5467 float complex cacoshf(float complex z); 5468 long double complex cacoshl(long double complex z); 5469 DESCRIPTION 5470 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5471 conflict between the requirements described here and the ISO C standard is unintentional. This 5472 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5473 These functions shall compute the complex arc hyperbolic cosine of z, with a branch cut at 5474 values less than 1 along the real axis. 5475 RETURN VALUE 5476 These functions shall return the complex arc hyperbolic cosine value, in the range of a half-strip 5477 of non-negative values along the real axis and in the interval [-i , +i ] along the imaginary axis. 5478 ERRORS 5479 No errors are defined. 5480 EXAMPLES 5481 None. 5482 APPLICATION USAGE 5483 None. 5484 RATIONALE 5485 None. 5486 FUTURE DIRECTIONS 5487 None. 5488 SEE ALSO 5489 ccosh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5490 CHANGE HISTORY 5491 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 610 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cacosl( ) 5492 NAME 5493 cacosl - complex arc cosine functions 5494 SYNOPSIS 5495 #include 5496 long double complex cacosl(long double complex z); 5497 DESCRIPTION 5498 Refer to cacos( ). System Interfaces, Issue 6 611 calloc( ) System Interfaces 5499 NAME 5500 calloc - a memory allocator 5501 SYNOPSIS 5502 #include 5503 void *calloc(size_t nelem, size_t elsize); 5504 DESCRIPTION 5505 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5506 conflict between the requirements described here and the ISO C standard is unintentional. This 5507 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5508 The calloc( ) function shall allocate unused space for an array of nelem elements each of whose | 5509 size in bytes is elsize. The space shall be initialized to all bits 0. | 5510 The order and contiguity of storage allocated by successive calls to calloc( ) is unspecified. The | 5511 pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to | 5512 a pointer to any type of object and then used to access such an object or an array of such objects | 5513 in the space allocated (until the space is explicitly freed or reallocated). Each such allocation 5514 shall yield a pointer to an object disjoint from any other object. The pointer returned shall point | 5515 to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null | 5516 pointer shall be returned. If the size of the space requested is 0, the behavior is implementation- | 5517 defined: the value returned shall be either a null pointer or a unique pointer. | 5518 RETURN VALUE 5519 Upon successful completion with both nelem and elsize non-zero, calloc( ) shall return a pointer to 5520 the allocated space. If either nelem or elsize is 0, then either a null pointer or a unique pointer 5521 value that can be successfully passed to free( ) shall be returned. Otherwise, it shall return a null 5522 CX pointer and set errno to indicate the error. 5523 ERRORS 5524 The calloc( ) function shall fail if: 5525 CX [ENOMEM] Insufficient memory is available. 5526 EXAMPLES 5527 None. 5528 APPLICATION USAGE 5529 There is now no requirement for the implementation to support the inclusion of . 5530 RATIONALE 5531 None. 5532 FUTURE DIRECTIONS 5533 None. 5534 SEE ALSO 5535 free( ), malloc( ), realloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5536 CHANGE HISTORY 5537 First released in Issue 1. Derived from Issue 1 of the SVID. 5538 Issue 6 5539 Extensions beyond the ISO C standard are now marked. 5540 The following new requirements on POSIX implementations derive from alignment with the 5541 Single UNIX Specification: 612 Technical Standard (2001) (Draft April 16, 2001) System Interfaces calloc( ) 5542 * The setting of errno and the [ENOMEM] error condition are mandatory if an insufficient 5543 memory condition occurs. System Interfaces, Issue 6 613 carg( ) System Interfaces 5544 NAME 5545 carg, cargf, cargl - complex argument functions 5546 SYNOPSIS 5547 #include 5548 double carg(double complex z); 5549 float cargf(float complex z); 5550 long double cargl(long double complex z); 5551 DESCRIPTION 5552 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5553 conflict between the requirements described here and the ISO C standard is unintentional. This 5554 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5555 These functions shall compute the argument (also called phase angle) of z, with a branch cut 5556 along the negative real axis. 5557 RETURN VALUE 5558 These functions shall return the value of the argument in the interval [- , + ]. 5559 ERRORS 5560 No errors are defined. 5561 EXAMPLES 5562 None. 5563 APPLICATION USAGE 5564 None. 5565 RATIONALE 5566 None. 5567 FUTURE DIRECTIONS 5568 None. 5569 SEE ALSO 5570 cimag( ), conj( ), cproj( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5571 CHANGE HISTORY 5572 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 614 Technical Standard (2001) (Draft April 16, 2001) System Interfaces casin( ) 5573 NAME 5574 casin, casinf, casinl - complex arc sine functions 5575 SYNOPSIS 5576 #include 5577 double complex casin(double complex z); 5578 float complex casinf(float complex z); 5579 long double complex casinl(long double complex z); 5580 DESCRIPTION 5581 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5582 conflict between the requirements described here and the ISO C standard is unintentional. This 5583 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5584 These functions shall compute the complex arc sine of z, with branch cuts outside the interval 5585 [-1, +1] along the real axis. 5586 RETURN VALUE 5587 These functions shall return the complex arc sine value, in the range of a strip mathematically 5588 unbounded along the imaginary axis and in the interval [- /2, + /2] along the real axis. 5589 ERRORS 5590 No errors are defined. 5591 EXAMPLES 5592 None. 5593 APPLICATION USAGE 5594 None. 5595 RATIONALE 5596 None. 5597 FUTURE DIRECTIONS 5598 None. 5599 SEE ALSO 5600 csin( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5601 CHANGE HISTORY 5602 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 615 casinf( ) System Interfaces 5603 NAME 5604 casinf - complex arc sine functions 5605 SYNOPSIS 5606 #include 5607 float complex casinf(float complex z); 5608 DESCRIPTION 5609 Refer to casin( ). 616 Technical Standard (2001) (Draft April 16, 2001) System Interfaces casinh( ) 5610 NAME 5611 casinh, casinhf, casinhl - complex arc hyperbolic sine functions 5612 SYNOPSIS 5613 #include 5614 double complex casinh(double complex z); 5615 float complex casinhf(float complex z); 5616 long double complex casinhl(long double complex z); 5617 DESCRIPTION 5618 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5619 conflict between the requirements described here and the ISO C standard is unintentional. This 5620 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5621 These functions shall compute the complex arc hyperbolic sine of z, with branch cuts outside the 5622 interval [-i, +i] along the imaginary axis. 5623 RETURN VALUE 5624 These functions shall return the complex arc hyperbolic sine value, in the range of a strip 5625 mathematically unbounded along the real axis and in the interval [-i /2, +i /2] along the 5626 imaginary axis. 5627 ERRORS 5628 No errors are defined. 5629 EXAMPLES 5630 None. 5631 APPLICATION USAGE 5632 None. 5633 RATIONALE 5634 None. 5635 FUTURE DIRECTIONS 5636 None. 5637 SEE ALSO 5638 csinh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5639 CHANGE HISTORY 5640 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 617 casinl( ) System Interfaces 5641 NAME 5642 casinl - complex arc sine functions 5643 SYNOPSIS 5644 #include 5645 long double complex casinl(long double complex z); 5646 DESCRIPTION 5647 Refer to casin( ). 618 Technical Standard (2001) (Draft April 16, 2001) System Interfaces catan( ) 5648 NAME 5649 catan, catanf, catanl - complex arc tangent functions 5650 SYNOPSIS 5651 #include 5652 double complex catan(double complex z); 5653 float complex catanf(float complex z); 5654 long double complex catanl(long double complex z); 5655 DESCRIPTION 5656 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5657 conflict between the requirements described here and the ISO C standard is unintentional. This 5658 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5659 These functions shall compute the complex arc tangent of z, with branch cuts outside the 5660 interval [-i, +i] along the imaginary axis. 5661 RETURN VALUE 5662 These functions shall return the complex arc tangent value, in the range of a strip 5663 mathematically unbounded along the imaginary axis and in the interval [- /2, + /2] along the 5664 real axis. 5665 ERRORS 5666 No errors are defined. 5667 EXAMPLES 5668 None. 5669 APPLICATION USAGE 5670 None. 5671 RATIONALE 5672 None. 5673 FUTURE DIRECTIONS 5674 None. 5675 SEE ALSO 5676 ctan( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5677 CHANGE HISTORY 5678 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 619 catanf( ) System Interfaces 5679 NAME 5680 catanf - complex arc tangent functions 5681 SYNOPSIS 5682 #include 5683 float complex catanf(float complex z); 5684 DESCRIPTION 5685 Refer to catan( ). 620 Technical Standard (2001) (Draft April 16, 2001) System Interfaces catanh( ) 5686 NAME 5687 catanh, catanhf, catanhl - complex arc hyperbolic tangent functions 5688 SYNOPSIS 5689 #include 5690 double complex catanh(double complex z); 5691 float complex catanhf(float complex z); 5692 long double complex catanhl(long double complex z); 5693 DESCRIPTION 5694 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5695 conflict between the requirements described here and the ISO C standard is unintentional. This 5696 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5697 These functions shall compute the complex arc hyperbolic tangent of z, with branch cuts outside 5698 the interval [-1, +1] along the real axis. 5699 RETURN VALUE 5700 These functions shall return the complex arc hyperbolic tangent value, in the range of a strip 5701 mathematically unbounded along the real axis and in the interval [-i /2, +i /2] along the 5702 imaginary axis. 5703 ERRORS 5704 No errors are defined. 5705 EXAMPLES 5706 None. 5707 APPLICATION USAGE 5708 None. 5709 RATIONALE 5710 None. 5711 FUTURE DIRECTIONS 5712 None. 5713 SEE ALSO 5714 ctanh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5715 CHANGE HISTORY 5716 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 621 catanl( ) System Interfaces 5717 NAME 5718 catanl - complex arc tangent functions 5719 SYNOPSIS 5720 #include 5721 long double complex catanl(long double complex z); 5722 DESCRIPTION 5723 Refer to catan( ). 622 Technical Standard (2001) (Draft April 16, 2001) System Interfaces catclose( ) 5724 NAME 5725 catclose - close a message catalog descriptor 5726 SYNOPSIS 5727 XSI #include 5728 int catclose(nl_catd catd); 5729 5730 DESCRIPTION 5731 The catclose( ) function shall close the message catalog identified by catd. If a file descriptor is 5732 used to implement the type nl_catd, that file descriptor shall be closed. 5733 RETURN VALUE 5734 Upon successful completion, catclose( ) shall return 0; otherwise, -1 shall be returned, and errno 5735 set to indicate the error. 5736 ERRORS 5737 The catclose( ) function may fail if: 5738 [EBADF] The catalog descriptor is not valid. 5739 [EINTR] The catclose( ) function was interrupted by a signal. 5740 EXAMPLES 5741 None. 5742 APPLICATION USAGE 5743 None. 5744 RATIONALE 5745 None. 5746 FUTURE DIRECTIONS 5747 None. 5748 SEE ALSO 5749 catgets( ), catopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5750 CHANGE HISTORY 5751 First released in Issue 2. System Interfaces, Issue 6 623 catgets( ) System Interfaces 5752 NAME 5753 catgets - read a program message 5754 SYNOPSIS 5755 XSI #include 5756 char *catgets(nl_catd catd, int set_id, int msg_id, const char *s); 5757 5758 DESCRIPTION 5759 The catgets( ) function shall attempt to read message msg_id, in set set_id, from the message | 5760 catalog identified by catd. The catd argument is a message catalog descriptor returned from an 5761 earlier call to catopen( ). The s argument points to a default message string which shall be 5762 returned by catgets( ) if it cannot retrieve the identified message. 5763 The catgets( ) function need not be reentrant. A function that is not required to be reentrant is not 5764 required to be thread-safe. 5765 RETURN VALUE 5766 If the identified message is retrieved successfully, catgets( ) shall return a pointer to an internal 5767 buffer area containing the null-terminated message string. If the call is unsuccessful for any 5768 reason, s shall be returned and errno may be set to indicate the error. 5769 ERRORS 5770 The catgets( ) function may fail if: 5771 [EBADF] The catd argument is not a valid message catalog descriptor open for reading. 5772 [EBADMSG] The message identified by set_id and msg_id in the specified message catalog 5773 did not satisfy implementation-defined security criteria. 5774 [EINTR] The read operation was terminated due to the receipt of a signal, and no data 5775 was transferred. 5776 [EINVAL] The message catalog identified by catd is corrupted. 5777 [ENOMSG] The message identified by set_id and msg_id is not in the message catalog. 5778 EXAMPLES 5779 None. 5780 APPLICATION USAGE 5781 None. 5782 RATIONALE 5783 None. 5784 FUTURE DIRECTIONS 5785 None. 5786 SEE ALSO 5787 catclose( ), catopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5788 CHANGE HISTORY 5789 First released in Issue 2. 5790 Issue 5 5791 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 624 Technical Standard (2001) (Draft April 16, 2001) System Interfaces catgets( ) 5792 Issue 6 5793 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. System Interfaces, Issue 6 625 catopen( ) System Interfaces 5794 NAME 5795 catopen - open a message catalog 5796 SYNOPSIS 5797 XSI #include 5798 nl_catd catopen(const char *name, int oflag); 5799 5800 DESCRIPTION 5801 The catopen( ) function shall open a message catalog and return a message catalog descriptor. 5802 The name argument specifies the name of the message catalog to be opened. If name contains a 5803 '/', then name specifies a complete name for the message catalog. Otherwise, the environment 5804 variable NLSPATH is used with name substituted for the %N conversion specification (see the 5805 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables). If 5806 NLSPATH exists in the environment when the process starts, then if the process has appropriate 5807 privileges, the behavior of catopen( ) is undefined. If NLSPATH does not exist in the environment, | 5808 or if a message catalog cannot be found in any of the components specified by NLSPATH, then | 5809 an implementation-defined default path shall be used. This default may be affected by the | 5810 setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the LANG environment 5811 variable if oflag is 0. 5812 A message catalog descriptor shall remain valid in a process until that process closes it, or a | 5813 successful call to one of the exec functions. A change in the setting of the LC_MESSAGES 5814 category may invalidate existing open catalogs. 5815 If a file descriptor is used to implement message catalog descriptors, the FD_CLOEXEC flag 5816 shall be set; see . 5817 If the value of the oflag argument is 0, the LANG environment variable is used to locate the 5818 catalog without regard to the LC_MESSAGES category. If the oflag argument is 5819 NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the message catalog (see the 5820 Base Definitions volume of IEEE Std 1003.1-200x, Section 8.2, Internationalization Variables). 5821 RETURN VALUE 5822 Upon successful completion, catopen( ) shall return a message catalog descriptor for use on 5823 subsequent calls to catgets( ) and catclose( ). Otherwise, catopen( ) shall return (nl_catd) -1 and set 5824 errno to indicate the error. 5825 ERRORS 5826 The catopen( ) function may fail if: 5827 [EACCES] Search permission is denied for the component of the path prefix of the 5828 message catalog or read permission is denied for the message catalog. 5829 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 5830 [ENAMETOOLONG] 5831 The length of a pathname of the message catalog exceeds {PATH_MAX} or a | 5832 pathname component is longer than {NAME_MAX}. | 5833 [ENAMETOOLONG] 5834 Pathname resolution of a symbolic link produced an intermediate result | 5835 whose length exceeds {PATH_MAX}. 5836 [ENFILE] Too many files are currently open in the system. 5837 [ENOENT] The message catalog does not exist or the name argument points to an empty 5838 string. 626 Technical Standard (2001) (Draft April 16, 2001) System Interfaces catopen( ) 5839 [ENOMEM] Insufficient storage space is available. 5840 [ENOTDIR] A component of the path prefix of the message catalog is not a directory. 5841 EXAMPLES 5842 None. 5843 APPLICATION USAGE 5844 Some implementations of catopen( ) use malloc( ) to allocate space for internal buffer areas. The 5845 catopen( ) function may fail if there is insufficient storage space available to accommodate these 5846 buffers. 5847 Conforming applications must assume that message catalog descriptors are not valid after a call | 5848 to one of the exec functions. 5849 Application writers should be aware that guidelines for the location of message catalogs have 5850 not yet been developed. Therefore they should take care to avoid conflicting with catalogs used 5851 by other applications and the standard utilities. 5852 RATIONALE 5853 None. 5854 FUTURE DIRECTIONS 5855 None. 5856 SEE ALSO 5857 catclose( ), catgets( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 5858 , the Shell and Utilities volume of IEEE Std 1003.1-200x 5859 CHANGE HISTORY 5860 First released in Issue 2. System Interfaces, Issue 6 627 cbrt( ) System Interfaces 5861 NAME 5862 cbrt, cbrtf, cbrtl - cube root functions 5863 SYNOPSIS 5864 #include 5865 double cbrt(double x); 5866 float cbrtf(float x); 5867 long double cbrtl(long double x); 5868 DESCRIPTION 5869 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5870 conflict between the requirements described here and the ISO C standard is unintentional. This 5871 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5872 These functions shall compute the real cube root of their argument x. 5873 RETURN VALUE 5874 Upon successful completion, these functions shall return the cube root of x. 5875 MX If x is NaN, a NaN shall be returned. 5876 If x is ±0, or ±Inf, x shall be returned. 5877 ERRORS 5878 No errors are defined. 5879 EXAMPLES 5880 None. 5881 APPLICATION USAGE 5882 None. 5883 RATIONALE 5884 For some applications, a true cube root function, which returns negative results for negative 5885 arguments, is more appropriate than pow(x, 1.0/3.0), which returns a NaN for x less than 0. 5886 FUTURE DIRECTIONS 5887 None. 5888 SEE ALSO 5889 The Base Definitions volume of IEEE Std 1003.1-200x, 5890 CHANGE HISTORY 5891 First released in Issue 4, Version 2. 5892 Issue 5 5893 Moved from X/OPEN UNIX extension to BASE. 5894 Issue 6 5895 The cbrt( ) function is no longer marked as an extension. 5896 The cbrtf( ) and cbrtl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 5897 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 5898 revised to align with the ISO/IEC 9899: 1999 standard. 5899 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 5900 marked. 628 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ccos( ) 5901 NAME 5902 ccos, ccosf, ccosl - complex cosine functions 5903 SYNOPSIS 5904 #include 5905 double complex ccos(double complex z); 5906 float complex ccosf(float complex z); 5907 long double complex ccosl(long double complex z); 5908 DESCRIPTION 5909 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5910 conflict between the requirements described here and the ISO C standard is unintentional. This 5911 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5912 These functions shall compute the complex cosine of z. 5913 RETURN VALUE 5914 These functions shall return the complex cosine value. 5915 ERRORS 5916 No errors are defined. 5917 EXAMPLES 5918 None. 5919 APPLICATION USAGE 5920 None. 5921 RATIONALE 5922 None. 5923 FUTURE DIRECTIONS 5924 None. 5925 SEE ALSO 5926 cacos( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5927 CHANGE HISTORY 5928 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 629 ccosf( ) System Interfaces 5929 NAME 5930 ccosf - complex cosine functions 5931 SYNOPSIS 5932 #include 5933 float complex ccosf(float complex z); 5934 DESCRIPTION 5935 Refer to ccos( ). 630 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ccosh( ) 5936 NAME 5937 ccosh, ccoshf, ccoshl - complex hyperbolic cosine functions 5938 SYNOPSIS 5939 #include 5940 double complex ccosh(double complex z); 5941 float complex ccoshf(float complex z); 5942 long double complex ccoshl(long double complex z); 5943 DESCRIPTION 5944 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5945 conflict between the requirements described here and the ISO C standard is unintentional. This 5946 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5947 These functions shall compute the complex hyperbolic cosine of z. 5948 RETURN VALUE 5949 These functions shall return the complex hyperbolic cosine value. 5950 ERRORS 5951 No errors are defined. 5952 EXAMPLES 5953 None. 5954 APPLICATION USAGE 5955 None. 5956 RATIONALE 5957 None. 5958 FUTURE DIRECTIONS 5959 None. 5960 SEE ALSO 5961 cacosh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 5962 CHANGE HISTORY 5963 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 631 ccosl( ) System Interfaces 5964 NAME 5965 ccosl - complex cosine functions 5966 SYNOPSIS 5967 #include 5968 long double complex ccosl(long double complex z); 5969 DESCRIPTION 5970 Refer to ccos( ). 632 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ceil( ) 5971 NAME 5972 ceil, ceilf, ceill - ceiling value function 5973 SYNOPSIS 5974 #include 5975 double ceil(double x); 5976 float ceilf(float x); 5977 long double ceill(long double x); 5978 DESCRIPTION 5979 CX The functionality described on this reference page is aligned with the ISO C standard. Any 5980 conflict between the requirements described here and the ISO C standard is unintentional. This 5981 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 5982 These functions shall compute the smallest integral value not less than x. 5983 An application wishing to check for error situations should set errno to zero and call 5984 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 5985 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 5986 zero, an error has occurred. 5987 RETURN VALUE 5988 Upon successful completion, ceil( ), ceilf( ), and ceill( ) shall return the smallest integral value not 5989 less than x, expressed as a type double, float, or long double, respectively. 5990 MX If x is NaN, a NaN shall be returned. 5991 If x is ±0, or ±Inf, x shall be returned. 5992 XSI If the correct value would cause overflow, a range error shall occur and ceil( ), ceilf( ), and ceill( ) 5993 shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 5994 ERRORS 5995 These functions shall fail if: 5996 XSI Range Error The result overflows. 5997 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 5998 then errno shall be set to [ERANGE]. If the integer expression | 5999 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 6000 floating-point exception shall be raised. | 6001 EXAMPLES 6002 None. 6003 APPLICATION USAGE 6004 The integral value returned by these functions need not be expressible as an int or long. The 6005 return value should be tested before assigning it to an integer type to avoid the undefined results 6006 of an integer overflow. 6007 The ceil( ) function can only overflow when the floating-point representation has 6008 DBL_MANT_DIG > DBL_MAX_EXP. 6009 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 6010 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. System Interfaces, Issue 6 633 ceil( ) System Interfaces 6011 RATIONALE 6012 None. 6013 FUTURE DIRECTIONS 6014 None. 6015 SEE ALSO 6016 feclearexcept( ), fetestexcept( ), floor( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 6017 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 6018 CHANGE HISTORY 6019 First released in Issue 1. Derived from Issue 1 of the SVID. 6020 Issue 5 6021 The DESCRIPTION is updated to indicate how an application should check for an error. This 6022 text was previously published in the APPLICATION USAGE section. 6023 Issue 6 6024 The ceilf( ) and ceill( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 6025 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 6026 revised to align with the ISO/IEC 9899: 1999 standard. 6027 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 6028 marked. 634 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cexp( ) 6029 NAME 6030 cexp, cexpf, cexpl - complex exponential functions 6031 SYNOPSIS 6032 #include 6033 double complex cexp(double complex z); 6034 float complex cexpf(float complex z); 6035 long double complex cexpl(long double complex z); 6036 DESCRIPTION 6037 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6038 conflict between the requirements described here and the ISO C standard is unintentional. This 6039 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 6040 These functions shall compute the complex exponent of z, defined as ez. 6041 RETURN VALUE 6042 These functions shall return the complex exponential value of z. 6043 ERRORS 6044 No errors are defined. 6045 EXAMPLES 6046 None. 6047 APPLICATION USAGE 6048 None. 6049 RATIONALE 6050 None. 6051 FUTURE DIRECTIONS 6052 None. 6053 SEE ALSO 6054 clog( ), the Base Definitions volume of IEEE Std 1003.1-200x, 6055 CHANGE HISTORY 6056 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 635 cfgetispeed( ) System Interfaces 6057 NAME 6058 cfgetispeed - get input baud rate 6059 SYNOPSIS 6060 #include 6061 speed_t cfgetispeed(const struct termios *termios_p); 6062 DESCRIPTION 6063 The cfgetispeed( ) function shall extract the input baud rate from the termios structure to which 6064 the termios_p argument points. 6065 This function shall return exactly the value in the termios data structure, without interpretation. 6066 RETURN VALUE 6067 Upon successful completion, cfgetispeed( ) shall return a value of type speed_t representing the 6068 input baud rate. 6069 ERRORS 6070 No errors are defined. 6071 EXAMPLES 6072 None. 6073 APPLICATION USAGE 6074 None. 6075 RATIONALE 6076 The term baud is used historically here, but is not technically correct. This is properly ``bits per 6077 second'', which may not be the same as baud. However, the term is used because of the 6078 historical usage and understanding. 6079 The cfgetospeed( ), cfgetispeed( ), cfsetospeed( ), and cfsetispeed( ) functions do not take arguments as 6080 numbers, but rather as symbolic names. There are two reasons for this: 6081 1. Historically, numbers were not used because of the way the rate was stored in the data 6082 structure. This is retained even though a function is now used. 6083 2. More importantly, only a limited set of possible rates is at all portable, and this constrains 6084 the application to that set. 6085 There is nothing to prevent an implementation to accept, as an extension, a number (such as 126) 6086 if it wished, and because the encoding of the Bxxx symbols is not specified, this can be done so 6087 no ambiguity is introduced. 6088 Setting the input baud rate to zero was a mechanism to allow for split baud rates. Clarifications 6089 in this volume of IEEE Std 1003.1-200x have made it possible to determine whether split rates are 6090 supported and to support them without having to treat zero as a special case. Since this 6091 functionality is also confusing, it has been declared obsolescent. The 0 argument referred to is 6092 the literal constant 0, not the symbolic constant B0. This volume of IEEE Std 1003.1-200x does 6093 not preclude B0 from being defined as the value 0; in fact, implementations would likely benefit 6094 from the two being equivalent. This volume of IEEE Std 1003.1-200x does not fully specify 6095 whether the previous cfsetispeed( ) value is retained after a tcgetattr( ) as the actual value or as | 6096 zero. Therefore, conforming applications should always set both the input speed and output | 6097 speed when setting either. 6098 In historical implementations, the baud rate information is traditionally kept in c_cflag. 6099 Applications should be written to presume that this might be the case (and thus not blindly copy 6100 c_cflag), but not to rely on it in case it is in some other field of the structure. Setting the c_cflag 6101 field absolutely after setting a baud rate is a non-portable action because of this. In general, the 636 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cfgetispeed( ) 6102 unused parts of the flag fields might be used by the implementation and should not be blindly 6103 copied from the descriptions of one terminal device to another. 6104 FUTURE DIRECTIONS 6105 None. 6106 SEE ALSO 6107 cfgetospeed( ), cfsetispeed( ), cfsetospeed( ), tcgetattr( ), the Base Definitions volume of 6108 IEEE Std 1003.1-200x, , the Base Definitions volume of IEEE Std 1003.1-200x, 6109 Chapter 11, General Terminal Interface 6110 CHANGE HISTORY 6111 First released in Issue 3. 6112 Entry included for alignment with the POSIX.1-1988 standard. System Interfaces, Issue 6 637 cfgetospeed( ) System Interfaces 6113 NAME 6114 cfgetospeed - get output baud rate 6115 SYNOPSIS 6116 #include 6117 speed_t cfgetospeed(const struct termios *termios_p); 6118 DESCRIPTION 6119 The cfgetospeed( ) function shall extract the output baud rate from the termios structure to which 6120 the termios_p argument points. 6121 This function shall return exactly the value in the termios data structure, without interpretation. 6122 RETURN VALUE 6123 Upon successful completion, cfgetospeed( ) shall return a value of type speed_t representing the 6124 output baud rate. 6125 ERRORS 6126 No errors are defined. 6127 EXAMPLES 6128 None. 6129 APPLICATION USAGE 6130 None. 6131 RATIONALE 6132 Refer to cfgetispeed( ). 6133 FUTURE DIRECTIONS 6134 None. 6135 SEE ALSO 6136 cfgetispeed( ), cfsetispeed( ), cfsetospeed( ), tcgetattr( ), the Base Definitions volume of 6137 IEEE Std 1003.1-200x, , the Base Definitions volume of IEEE Std 1003.1-200x, 6138 Chapter 11, General Terminal Interface 6139 CHANGE HISTORY 6140 First released in Issue 3. 6141 Entry included for alignment with the POSIX.1-1988 standard. 638 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cfsetispeed( ) 6142 NAME 6143 cfsetispeed - set input baud rate 6144 SYNOPSIS 6145 #include 6146 int cfsetispeed(struct termios *termios_p, speed_t speed); 6147 DESCRIPTION 6148 The cfsetispeed( ) function shall set the input baud rate stored in the structure pointed to by 6149 termios_p to speed. 6150 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 6151 to tcsetattr( ) with the same termios structure. Similarly, errors resulting from attempts to set 6152 baud rates not supported by the terminal device need not be detected until the tcsetattr( ) 6153 function is called. 6154 RETURN VALUE 6155 Upon successful completion, cfsetispeed( ) shall return 0; otherwise, -1 shall be returned, and 6156 errno may be set to indicate the error. 6157 ERRORS 6158 The cfsetispeed( ) function may fail if: 6159 [EINVAL] The speed value is not a valid baud rate. 6160 [EINVAL] The value of speed is outside the range of possible speed values as specified in 6161 . 6162 EXAMPLES 6163 None. 6164 APPLICATION USAGE 6165 None. 6166 RATIONALE 6167 Refer to cfgetispeed( ). 6168 FUTURE DIRECTIONS 6169 None. 6170 SEE ALSO 6171 cfgetispeed( ), cfgetospeed( ), cfsetospeed( ), tcsetattr( ), the Base Definitions volume of 6172 IEEE Std 1003.1-200x, , the Base Definitions volume of IEEE Std 1003.1-200x, 6173 Chapter 11, General Terminal Interface 6174 CHANGE HISTORY 6175 First released in Issue 3. 6176 Entry included for alignment with the POSIX.1-1988 standard. 6177 Issue 6 6178 The following new requirements on POSIX implementations derive from alignment with the 6179 Single UNIX Specification: 6180 * The optional setting of errno and the [EINVAL] error conditions are added. System Interfaces, Issue 6 639 cfsetospeed( ) System Interfaces 6181 NAME 6182 cfsetospeed - set output baud rate 6183 SYNOPSIS 6184 #include 6185 int cfsetospeed(struct termios *termios_p, speed_t speed); 6186 DESCRIPTION 6187 The cfsetospeed( ) function shall set the output baud rate stored in the structure pointed to by 6188 termios_p to speed. 6189 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 6190 to tcsetattr( ) with the same termios structure. Similarly, errors resulting from attempts to set 6191 baud rates not supported by the terminal device need not be detected until the tcsetattr( ) 6192 function is called. 6193 RETURN VALUE 6194 Upon successful completion, cfsetospeed( ) shall return 0; otherwise, it shall return -1 and errno 6195 may be set to indicate the error. 6196 ERRORS 6197 The cfsetospeed( ) function may fail if: 6198 [EINVAL] The speed value is not a valid baud rate. 6199 [EINVAL] The value of speed is outside the range of possible speed values as specified in 6200 . 6201 EXAMPLES 6202 None. 6203 APPLICATION USAGE 6204 None. 6205 RATIONALE 6206 Refer to cfgetispeed( ). 6207 FUTURE DIRECTIONS 6208 None. 6209 SEE ALSO 6210 cfgetispeed( ), cfgetospeed( ), cfsetispeed( ), tcsetattr( ), the Base Definitions volume of 6211 IEEE Std 1003.1-200x, , the Base Definitions volume of IEEE Std 1003.1-200x, 6212 Chapter 11, General Terminal Interface 6213 CHANGE HISTORY 6214 First released in Issue 3. 6215 Entry included for alignment with the POSIX.1-1988 standard. 6216 Issue 6 6217 The following new requirements on POSIX implementations derive from alignment with the 6218 Single UNIX Specification: 6219 * The optional setting of errno and the [EINVAL] error conditions are added. 640 Technical Standard (2001) (Draft April 16, 2001) System Interfaces chdir( ) 6220 NAME 6221 chdir - change working directory 6222 SYNOPSIS 6223 #include 6224 int chdir(const char *path); 6225 DESCRIPTION 6226 The chdir( ) function shall cause the directory named by the pathname pointed to by the path | 6227 argument to become the current working directory; that is, the starting point for path searches | 6228 for pathnames not beginning with '/'. | 6229 RETURN VALUE 6230 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, the current 6231 working directory shall remain unchanged, and errno shall be set to indicate the error. 6232 ERRORS 6233 The chdir( ) function shall fail if: 6234 [EACCES] Search permission is denied for any component of the pathname. | 6235 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 6236 argument. 6237 [ENAMETOOLONG] 6238 The length of the path argument exceeds {PATH_MAX} or a pathname | 6239 component is longer than {NAME_MAX}. | 6240 [ENOENT] A component of path does not name an existing directory or path is an empty 6241 string. 6242 [ENOTDIR] A component of the pathname is not a directory. | 6243 The chdir( ) function may fail if: 6244 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6245 resolution of the path argument. 6246 [ENAMETOOLONG] 6247 As a result of encountering a symbolic link in resolution of the path argument, | 6248 the length of the substituted pathname string exceeded {PATH_MAX}. | 6249 EXAMPLES 6250 Changing the Current Working Directory 6251 The following example makes the value pointed to by directory, /tmp, the current working 6252 directory. 6253 #include 6254 ... 6255 char *directory = "/tmp"; 6256 int ret; 6257 ret = chdir (directory); System Interfaces, Issue 6 641 chdir( ) System Interfaces 6258 APPLICATION USAGE 6259 None. 6260 RATIONALE 6261 The chdir( ) function only affects the working directory of the current process. 6262 FUTURE DIRECTIONS 6263 None. 6264 SEE ALSO 6265 getcwd( ), the Base Definitions volume of IEEE Std 1003.1-200x, 6266 CHANGE HISTORY 6267 First released in Issue 1. Derived from Issue 1 of the SVID. 6268 Issue 6 6269 The APPLICATION USAGE section is added. 6270 The following new requirements on POSIX implementations derive from alignment with the | 6271 Single UNIX Specification: 6272 * The [ELOOP] mandatory error condition is added. 6273 * A second [ENAMETOOLONG] is added as an optional error condition. 6274 The following changes were made to align with the IEEE P1003.1a draft standard: 6275 * The [ELOOP] optional error condition is added. 642 Technical Standard (2001) (Draft April 16, 2001) System Interfaces chmod( ) 6276 NAME 6277 chmod - change mode of a file 6278 SYNOPSIS 6279 #include 6280 int chmod(const char *path, mode_t mode); 6281 DESCRIPTION 6282 XSI The chmod( ) function shall change S_ISUID, S_ISGID, S_ISVTX, and the file permission bits of | 6283 the file named by the pathname pointed to by the path argument to the corresponding bits in the | 6284 mode argument. The application shall ensure that the effective user ID of the process matches the 6285 owner of the file or the process has appropriate privileges in order to do this. 6286 XSI S_ISUID, S_ISGID, S_ISVTX,and the file permission bits are described in . 6287 If the calling process does not have appropriate privileges, and if the group ID of the file does 6288 not match the effective group ID or one of the supplementary group IDs and if the file is a 6289 regular file, bit S_ISGID (set-group-ID on execution) in the file's mode shall be cleared upon 6290 successful return from chmod( ). 6291 Additional implementation-defined restrictions may cause the S_ISUID and S_ISGID bits in 6292 mode to be ignored. 6293 The effect on file descriptors for files open at the time of a call to chmod( ) is implementation- 6294 defined. 6295 Upon successful completion, chmod( ) shall mark for update the st_ctime field of the file. 6296 RETURN VALUE 6297 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 6298 indicate the error. If -1 is returned, no change to the file mode occurs. 6299 ERRORS 6300 The chmod( ) function shall fail if: 6301 [EACCES] Search permission is denied on a component of the path prefix. 6302 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 6303 argument. 6304 [ENAMETOOLONG] 6305 The length of the path argument exceeds {PATH_MAX} or a pathname | 6306 component is longer than {NAME_MAX}. | 6307 [ENOTDIR] A component of the path prefix is not a directory. 6308 [ENOENT] A component of path does not name an existing file or path is an empty string. 6309 [EPERM] The effective user ID does not match the owner of the file and the process 6310 does not have appropriate privileges. 6311 [EROFS] The named file resides on a read-only file system. 6312 The chmod( ) function may fail if: 6313 [EINTR] A signal was caught during execution of the function. 6314 [EINVAL] The value of the mode argument is invalid. 6315 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6316 resolution of the path argument. System Interfaces, Issue 6 643 chmod( ) System Interfaces 6317 [ENAMETOOLONG] 6318 As a result of encountering a symbolic link in resolution of the path argument, | 6319 the length of the substituted pathname strings exceeded {PATH_MAX}. | 6320 EXAMPLES 6321 Setting Read Permissions for User, Group, and Others 6322 The following example sets read permissions for the owner, group, and others. 6323 #include 6324 const char *path; 6325 ... 6326 chmod(path, S_IRUSR|S_IRGRP|S_IROTH); 6327 Setting Read, Write, and Execute Permissions for the Owner Only 6328 The following example sets read, write, and execute permissions for the owner, and no 6329 permissions for group and others. 6330 #include 6331 const char *path; 6332 ... 6333 chmod(path, S_IRWXU); 6334 Setting Different Permissions for Owner, Group, and Other 6335 The following example sets owner permissions for CHANGEFILE to read, write, and execute, 6336 group permissions to read and execute, and other permissions to read. 6337 #include 6338 #define CHANGEFILE "/etc/myfile" 6339 ... 6340 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); 6341 Setting and Checking File Permissions 6342 The following example sets the file permission bits for a file named /home/cnd/mod1, then calls 6343 the stat( ) function to verify the permissions. 6344 #include 6345 #include 6346 int status; 6347 struct stat buffer 6348 ... 6349 chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); 6350 status = stat("home/cnd/mod1", &buffer;); 6351 APPLICATION USAGE 6352 In order to ensure that the S_ISUID and S_ISGID bits are set, an application requiring this should 6353 use stat( ) after a successful chmod( ) to verify this. 6354 Any file descriptors currently open by any process on the file could possibly become invalid if 6355 the mode of the file is changed to a value which would deny access to that process. One 644 Technical Standard (2001) (Draft April 16, 2001) System Interfaces chmod( ) 6356 situation where this could occur is on a stateless file system. This behavior will not occur in a 6357 conforming environment. 6358 RATIONALE 6359 This volume of IEEE Std 1003.1-200x specifies that the S_ISGID bit is cleared by chmod( ) on a 6360 regular file under certain conditions. This is specified on the assumption that regular files may 6361 be executed, and the system should prevent users from making executable setgid( ) files perform 6362 with privileges that the caller does not have. On implementations that support execution of 6363 other file types, the S_ISGID bit should be cleared for those file types under the same 6364 circumstances. 6365 Implementations that use the S_ISUID bit to indicate some other function (for example, 6366 mandatory record locking) on non-executable files need not clear this bit on writing. They 6367 should clear the bit for executable files and any other cases where the bit grants special powers 6368 to processes that change the file contents. Similar comments apply to the S_ISGID bit. 6369 FUTURE DIRECTIONS 6370 None. 6371 SEE ALSO 6372 chown( ), mkdir( ), mkfifo( ), open( ), stat( ), statvfs( ), the Base Definitions volume of 6373 IEEE Std 1003.1-200x, , 6374 CHANGE HISTORY 6375 First released in Issue 1. Derived from Issue 1 of the SVID. 6376 Issue 6 6377 The following new requirements on POSIX implementations derive from alignment with the | 6378 Single UNIX Specification: 6379 * The requirement to include has been removed. Although was 6380 required for conforming implementations of previous POSIX specifications, it was not 6381 required for UNIX applications. 6382 * The [EINVAL] and [EINTR] optional error conditions are added. 6383 * A second [ENAMETOOLONG] is added as an optional error condition. 6384 The following changes were made to align with the IEEE P1003.1a draft standard: 6385 * The [ELOOP] optional error condition is added. 6386 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 645 chown( ) System Interfaces 6387 NAME 6388 chown - change owner and group of a file 6389 SYNOPSIS 6390 #include 6391 int chown(const char *path, uid_t owner, gid_t group); 6392 DESCRIPTION 6393 The chown( ) function shall change the user and group ownership of a file. | 6394 The path argument points to a pathname naming a file. The user ID and group ID of the named | 6395 file shall be set to the numeric values contained in owner and group, respectively. | 6396 Only processes with an effective user ID equal to the user ID of the file or with appropriate 6397 privileges may change the ownership of a file. If _POSIX_CHOWN_RESTRICTED is in effect for 6398 path: 6399 * Changing the user ID is restricted to processes with appropriate privileges. 6400 * Changing the group ID is permitted to a process with an effective user ID equal to the user 6401 ID of the file, but without appropriate privileges, if and only if owner is equal to the file's user 6402 ID or (uid_t)-1 and group is equal either to the calling process' effective group ID or to one of 6403 its supplementary group IDs. 6404 If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of 6405 the file mode are set, and the process does not have appropriate privileges, the set-user-ID 6406 (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode shall be cleared upon successful 6407 return from chown( ). If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, 6408 or S_IXOTH bits of the file mode are set, and the process has appropriate privileges, it is 6409 implementation-defined whether the set-user-ID and set-group-ID bits are altered. If the chown( ) 6410 function is successfully invoked on a file that is not a regular file and one or more of the 6411 S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, the set-user-ID and set-group-ID 6412 bits may be cleared. 6413 If owner or group is specified as (uid_t)-1 or (gid_t)-1, respectively, the corresponding ID of the | 6414 file shall not be changed. If both owner and group are -1, the times need not be updated. | 6415 Upon successful completion, chown( ) shall mark for update the st_ctime field of the file. 6416 RETURN VALUE 6417 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 6418 indicate the error. If -1 is returned, no changes are made in the user ID and group ID of the file. 6419 ERRORS 6420 The chown( ) function shall fail if: 6421 [EACCES] Search permission is denied on a component of the path prefix. 6422 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 6423 argument. 6424 [ENAMETOOLONG] 6425 The length of the path argument exceeds {PATH_MAX} or a pathname | 6426 component is longer than {NAME_MAX}. | 6427 [ENOTDIR] A component of the path prefix is not a directory. 6428 [ENOENT] A component of path does not name an existing file or path is an empty string. 646 Technical Standard (2001) (Draft April 16, 2001) System Interfaces chown( ) 6429 [EPERM] The effective user ID does not match the owner of the file, or the calling 6430 process does not have appropriate privileges and 6431 _POSIX_CHOWN_RESTRICTED indicates that such privilege is required. 6432 [EROFS] The named file resides on a read-only file system. 6433 The chown( ) function may fail if: 6434 [EIO] An I/O error occurred while reading or writing to the file system. 6435 [EINTR] The chown( ) function was interrupted by a signal which was caught. 6436 [EINVAL] The owner or group ID supplied is not a value supported by the 6437 implementation. 6438 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 6439 resolution of the path argument. 6440 [ENAMETOOLONG] 6441 As a result of encountering a symbolic link in resolution of the path argument, | 6442 the length of the substituted pathname string exceeded {PATH_MAX}. | 6443 EXAMPLES 6444 None. 6445 APPLICATION USAGE 6446 Although chown( ) can be used on some implementations by the file owner to change the owner | 6447 and group to any desired values, the only portable use of this function is to change the group of | 6448 a file to the effective GID of the calling process or to a member of its group set. | 6449 RATIONALE 6450 System III and System V allow a user to give away files; that is, the owner of a file may change 6451 its user ID to anything. This is a serious problem for implementations that are intended to meet 6452 government security regulations. Version 7 and 4.3 BSD permit only the superuser to change the 6453 user ID of a file. Some government agencies (usually not ones concerned directly with security) 6454 find this limitation too confining. This volume of IEEE Std 1003.1-200x uses may to permit secure 6455 implementations while not disallowing System V. 6456 System III and System V allow the owner of a file to change the group ID to anything. Version 7 6457 permits only the superuser to change the group ID of a file. 4.3 BSD permits the owner to 6458 change the group ID of a file to its effective group ID or to any of the groups in the list of 6459 supplementary group IDs, but to no others. 6460 The POSIX.1-1990 standard requires that the chown( ) function invoked by a non-appropriate 6461 privileged process clear the S_ISGID and the S_ISUID bits for regular files, and permits them to 6462 be cleared for other types of files. This is so that changes in accessibility do not accidentally 6463 cause files to become security holes. Unfortunately, requiring these bits to be cleared on non- 6464 executable data files also clears the mandatory file locking bit (shared with S_ISGID), which is 6465 an extension on many implementations (it first appeared in System V). These bits should only be 6466 required to be cleared on regular files that have one or more of their execute bits set. 6467 FUTURE DIRECTIONS 6468 None. 6469 SEE ALSO 6470 chmod( ), pathconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 6471 System Interfaces, Issue 6 647 chown( ) System Interfaces 6472 CHANGE HISTORY 6473 First released in Issue 1. Derived from Issue 1 of the SVID. 6474 Issue 6 6475 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 6476 * The wording describing the optional dependency on _POSIX_CHOWN_RESTRICTED is 6477 restored. 6478 * The [EPERM] error is restored as an error dependent on _POSIX_CHOWN_RESTRICTED. | 6479 This is since its operand is a pathname and applications should be aware that the error may | 6480 not occur for that pathname if the file system does not support | 6481 _POSIX_CHOWN_RESTRICTED. | 6482 The following new requirements on POSIX implementations derive from alignment with the 6483 Single UNIX Specification: 6484 * The requirement to include has been removed. Although was 6485 required for conforming implementations of previous POSIX specifications, it was not 6486 required for UNIX applications. 6487 * The value for owner of (uid_t)-1 allows the use of -1 by the owner of a file to change the 6488 group ID only. A corresponding change is made for group. | 6489 * The [ELOOP] mandatory error condition is added. 6490 * The [EIO] and [EINTR] optional error conditions are added. 6491 * A second [ENAMETOOLONG] is added as an optional error condition. 6492 The following changes were made to align with the IEEE P1003.1a draft standard: 6493 * Clarification is added that the S_ISUID and S_ISGID bits do not need to be cleared when the 6494 process has appropriate privileges. 6495 * The [ELOOP] optional error condition is added. 648 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cimag( ) 6496 NAME 6497 cimag, cimagf, cimagl - complex imaginary functions 6498 SYNOPSIS 6499 #include 6500 double cimag(double complex z); 6501 float cimagf(float complex z); 6502 long double cimagl(long double complex z); 6503 DESCRIPTION 6504 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6505 conflict between the requirements described here and the ISO C standard is unintentional. This 6506 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 6507 These functions shall compute the imaginary part of z. 6508 RETURN VALUE 6509 These functions shall return the imaginary part value (as a real). 6510 ERRORS 6511 No errors are defined. 6512 EXAMPLES 6513 None. 6514 APPLICATION USAGE 6515 For a variable z of complex type: 6516 z == creal(z) + cimag(z)*I 6517 RATIONALE 6518 None. 6519 FUTURE DIRECTIONS 6520 None. 6521 SEE ALSO 6522 carg( ), conj( ), cproj( ), creal( ), the Base Definitions volume of IEEE Std 1003.1-200x, 6523 CHANGE HISTORY 6524 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 649 clearerr( ) System Interfaces 6525 NAME 6526 clearerr - clear indicators on a stream 6527 SYNOPSIS 6528 #include 6529 void clearerr(FILE *stream); 6530 DESCRIPTION 6531 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6532 conflict between the requirements described here and the ISO C standard is unintentional. This 6533 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 6534 The clearerr( ) function shall clear the end-of-file and error indicators for the stream to which 6535 stream points. 6536 RETURN VALUE 6537 The clearerr( ) function shall not return a value. 6538 ERRORS 6539 No errors are defined. 6540 EXAMPLES 6541 None. 6542 APPLICATION USAGE 6543 None. 6544 RATIONALE 6545 None. 6546 FUTURE DIRECTIONS 6547 None. 6548 SEE ALSO 6549 The Base Definitions volume of IEEE Std 1003.1-200x, 6550 CHANGE HISTORY 6551 First released in Issue 1. Derived from Issue 1 of the SVID. 650 Technical Standard (2001) (Draft April 16, 2001) System Interfaces clock( ) 6552 NAME 6553 clock - report CPU time used 6554 SYNOPSIS 6555 #include 6556 clock_t clock(void); 6557 DESCRIPTION 6558 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6559 conflict between the requirements described here and the ISO C standard is unintentional. This 6560 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 6561 The clock( ) function shall return the implementation's best approximation to the processor time 6562 used by the process since the beginning of an implementation-defined era related only to the 6563 process invocation. 6564 RETURN VALUE 6565 To determine the time in seconds, the value returned by clock( ) should be divided by the value 6566 XSI of the macro CLOCKS_PER_SEC. CLOCKS_PER_SEC is defined to be one million in . | 6567 If the processor time used is not available or its value cannot be represented, the function shall 6568 return the value (clock_t)-1. 6569 ERRORS 6570 No errors are defined. 6571 EXAMPLES 6572 None. 6573 APPLICATION USAGE 6574 In order to measure the time spent in a program, clock( ) should be called at the start of the 6575 program and its return value subtracted from the value returned by subsequent calls. The value 6576 returned by clock( ) is defined for compatibility across systems that have clocks with different 6577 resolutions. The resolution on any particular system need not be to microsecond accuracy. 6578 The value returned by clock( ) may wrap around on some implementations. For example, on a | 6579 machine with 32-bit values for clock_t, it wraps after 2 147 seconds or 36 minutes. | 6580 RATIONALE 6581 None. 6582 FUTURE DIRECTIONS 6583 None. 6584 SEE ALSO 6585 asctime( ), ctime( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), 6586 the Base Definitions volume of IEEE Std 1003.1-200x, 6587 CHANGE HISTORY 6588 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 651 clock_getcpuclockid( ) System Interfaces 6589 NAME 6590 clock_getcpuclockid - access a process CPU-time clock (ADVANCED REALTIME) 6591 SYNOPSIS 6592 CPT #include 6593 int clock_getcpuclockid(pid_t pid, clockid_t *clock_id); 6594 6595 DESCRIPTION 6596 The clock_getcpuclockid( ) function shall return the clock ID of the CPU-time clock of the process 6597 specified by pid. If the process described by pid exists and the calling process has permission, 6598 the clock ID of this clock shall be returned in clock_id. 6599 If pid is zero, the clock_getcpuclockid( ) function shall return the clock ID of the CPU-time clock of 6600 the process making the call, in clock_id. 6601 The conditions under which one process has permission to obtain the CPU-time clock ID of 6602 other processes are implementation-defined. 6603 RETURN VALUE 6604 Upon successful completion, clock_getcpuclockid( ) shall return zero; otherwise, an error number 6605 shall be returned to indicate the error. 6606 ERRORS 6607 The clock_getcpuclockid( ) function shall fail if: 6608 [EPERM] The requesting process does not have permission to access the CPU-time 6609 clock for the process. 6610 The clock_getcpuclockid( ) function may fail if: 6611 [ESRCH] No process can be found corresponding to the process specified by pid. 6612 EXAMPLES 6613 None. 6614 APPLICATION USAGE 6615 The clock_getcpuclockid( ) function is part of the Process CPU-Time Clocks option and need not 6616 be provided on all implementations. 6617 RATIONALE 6618 None. 6619 FUTURE DIRECTIONS 6620 None. 6621 SEE ALSO 6622 clock_getres( ), timer_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 6623 CHANGE HISTORY 6624 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 6625 In the SYNOPSIS, the inclusion of is no longer required. 652 Technical Standard (2001) (Draft April 16, 2001) System Interfaces clock_getres( ) 6626 NAME 6627 clock_getres, clock_gettime, clock_settime - clock and timer functions (REALTIME) 6628 SYNOPSIS 6629 TMR #include 6630 int clock_getres(clockid_t clock_id, struct timespec *res); 6631 int clock_gettime(clockid_t clock_id, struct timespec *tp); 6632 int clock_settime(clockid_t clock_id, const struct timespec *tp); 6633 6634 DESCRIPTION 6635 The clock_getres( ) function shall return the resolution of any clock. Clock resolutions are | 6636 implementation-defined and cannot be set by a process. If the argument res is not NULL, the | 6637 resolution of the specified clock shall be stored in the location pointed to by res. If res is NULL, 6638 the clock resolution is not returned. If the time argument of clock_settime( ) is not a multiple of res, 6639 then the value is truncated to a multiple of res. 6640 The clock_gettime( ) function shall return the current value tp for the specified clock, clock_id. 6641 The clock_settime( ) function shall set the specified clock, clock_id, to the value specified by tp. 6642 Time values that are between two consecutive non-negative integer multiples of the resolution | 6643 of the specified clock shall be truncated down to the smaller multiple of the resolution. | 6644 A clock may be system-wide (that is, visible to all processes) or per-process (measuring time that 6645 is meaningful only within a process). All implementations shall support a clock_id of | 6646 CLOCK_REALTIME as defined in . This clock represents the realtime clock for the | 6647 system. For this clock, the values returned by clock_gettime( ) and specified by clock_settime( ) 6648 represent the amount of time (in seconds and nanoseconds) since the Epoch. An implementation 6649 may also support additional clocks. The interpretation of time values for these clocks is 6650 unspecified. 6651 If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock 6652 shall be used to determine the time of expiration for absolute time services based upon the 6653 CLOCK_REALTIME clock. This applies to the time at which armed absolute timers expire. If the 6654 absolute time requested at the invocation of such a time service is before the new value of the 6655 clock, the time service shall expire immediately as if the clock had reached the requested time 6656 normally. 6657 Setting the value of the CLOCK_REALTIME clock via clock_settime( ) shall have no effect on 6658 threads that are blocked waiting for a relative time service based upon this clock, including the 6659 nanosleep( ) function; nor on the expiration of relative timers based upon this clock. 6660 Consequently, these time services shall expire when the requested relative interval elapses, 6661 independently of the new or old value of the clock. 6662 MON If the Monotonic Clock option is supported, all implementations shall support a clock_id of 6663 CLOCK_MONOTONIC defined in . This clock represents the monotonic clock for the 6664 system. For this clock, the value returned by clock_gettime( ) represents the amount of time (in 6665 seconds and nanoseconds) since an unspecified point in the past (for example, system start-up 6666 time, or the Epoch). This point does not change after system start-up time. The value of the 6667 CLOCK_MONOTONIC clock cannot be set via clock_settime( ). This function shall fail if it is 6668 invoked with a clock_id argument of CLOCK_MONOTONIC. 6669 The effect of setting a clock via clock_settime( ) on armed per-process timers associated with a 6670 clock other than CLOCK_REALTIME is implementation-defined. 6671 CS If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock 6672 shall be used to determine the time at which the system shall awaken a thread blocked on an System Interfaces, Issue 6 653 clock_getres( ) System Interfaces 6673 absolute clock_nanosleep( ) call based upon the CLOCK_REALTIME clock. If the absolute time 6674 requested at the invocation of such a time service is before the new value of the clock, the call 6675 shall return immediately as if the clock had reached the requested time normally. 6676 Setting the value of the CLOCK_REALTIME clock via clock_settime( ) shall have no effect on any 6677 thread that is blocked on a relative clock_nanosleep( ) call. Consequently, the call shall return 6678 when the requested relative interval elapses, independently of the new or old value of the clock. 6679 The appropriate privilege to set a particular clock is implementation-defined. 6680 CPT If _POSIX_CPUTIME is defined, implementations shall support clock ID values obtained by 6681 invoking clock_getcpuclockid( ), which represent the CPU-time clock of a given process. 6682 Implementations shall also support the special clockid_t value 6683 CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of the calling process 6684 when invoking one of the clock_*( ) or timer_*( ) functions. For these clock IDs, the values 6685 returned by clock_gettime( ) and specified by clock_settime( ) represent the amount of execution 6686 time of the process associated with the clock. Changing the value of a CPU-time clock via 6687 clock_settime( ) shall have no effect on the behavior of the sporadic server scheduling policy (see 6688 Scheduling Policies (on page 494)). 6689 TCT If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock ID values 6690 obtained by invoking pthread_getcpuclockid( ), which represent the CPU-time clock of a given 6691 thread. Implementations shall also support the special clockid_t value 6692 CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of the calling thread 6693 when invoking one of the clock_*( ) or timer_*( ) functions. For these clock IDs, the values 6694 returned by clock_gettime( ) and specified by clock_settime( ) shall represent the amount of | 6695 execution time of the thread associated with the clock. Changing the value of a CPU-time clock | 6696 via clock_settime( ) shall have no effect on the behavior of the sporadic server scheduling policy | 6697 (see Scheduling Policies (on page 494)). 6698 RETURN VALUE 6699 A return value of 0 shall indicate that the call succeeded. A return value of -1 shall indicate that 6700 an error occurred, and errno shall be set to indicate the error. 6701 ERRORS 6702 The clock_getres( ), clock_gettime( ), and clock_settime( ) functions shall fail if: 6703 [EINVAL] The clock_id argument does not specify a known clock. 6704 The clock_settime( ) function shall fail if: 6705 [EINVAL] The tp argument to clock_settime( ) is outside the range for the given clock ID. 6706 [EINVAL] The tp argument specified a nanosecond value less than zero or greater than 6707 or equal to 1 000 million. 6708 MON [EINVAL] The value of the clock_id argument is CLOCK_MONOTONIC. 6709 The clock_settime( ) function may fail if: 6710 [EPERM] The requesting process does not have the appropriate privilege to set the 6711 specified clock. 654 Technical Standard (2001) (Draft April 16, 2001) System Interfaces clock_getres( ) 6712 EXAMPLES 6713 None. 6714 APPLICATION USAGE 6715 These functions are part of the Timers option and need not be available on all implementations. 6716 Note that the absolute value of the monotonic clock is meaningless (because its origin is 6717 arbitrary), and thus there is no need to set it. Furthermore, realtime applications can rely on the 6718 fact that the value of this clock is never set and, therefore, that time intervals measured with this 6719 clock will not be affected by calls to clock_settime( ). 6720 RATIONALE 6721 None. 6722 FUTURE DIRECTIONS 6723 None. 6724 SEE ALSO 6725 clock_getcpuclockid( ), clock_nanosleep( ), ctime( ), mq_timedreceive( ), mq_timedsend( ), nanosleep( ), 6726 pthread_mutex_timedlock( ), sem_timedwait( ), time( ), timer_create( ), timer_getoverrun( ), the Base 6727 Definitions volume of IEEE Std 1003.1-200x, 6728 CHANGE HISTORY 6729 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 6730 Issue 6 6731 The [ENOSYS] error condition has been removed as stubs need not be provided if an 6732 implementation does not support the Timers option. 6733 The APPLICATION USAGE section is added. 6734 The following changes were made to align with the IEEE P1003.1a draft standard: 6735 * Clarification is added of the effect of resetting the clock resolution. 6736 CPU-time clocks and the clock_getcpuclockid( ) function are added for alignment with 6737 IEEE Std 1003.1d-1999. 6738 The following changes are added for alignment with IEEE Std 1003.1j-2000: 6739 * The DESCRIPTION is updated as follows: 6740 - The value returned by clock_gettime( ) for CLOCK_MONOTONIC is specified. 6741 - clock_settime( ) failing for CLOCK_MONOTONIC is specified. 6742 - The effects of clock_settime( ) on the clock_nanosleep( ) function with respect to 6743 CLOCK_REALTIME is specified. 6744 * An [EINVAL] error is added to the ERRORS section, indicating that clock_settime( ) fails for 6745 CLOCK_MONOTONIC. 6746 * The APPLICATION USAGE section notes that the CLOCK_MONOTONIC clock need not 6747 and shall not be set by clock_settime( ) since the absolute value of the CLOCK_MONOTONIC 6748 clock is meaningless. 6749 * The clock_nanosleep( ), mq_timedreceive( ), mq_timedsend( ), pthread_mutex_timedlock( ), 6750 sem_timedwait( ), timer_create( ), and timer_settime( ) functions are added to the SEE ALSO 6751 section. System Interfaces, Issue 6 655 clock_nanosleep( ) System Interfaces 6752 NAME 6753 clock_nanosleep - high resolution sleep with specifiable clock (ADVANCED REALTIME) 6754 SYNOPSIS 6755 CS #include 6756 int clock_nanosleep(clockid_t clock_id, int flags, 6757 const struct timespec *rqtp, struct timespec *rmtp); 6758 6759 DESCRIPTION 6760 If the flag TIMER_ABSTIME is not set in the flags argument, the clock_nanosleep( ) function shall 6761 cause the current thread to be suspended from execution until either the time interval specified 6762 by the rqtp argument has elapsed, or a signal is delivered to the calling thread and its action is to 6763 invoke a signal-catching function, or the process is terminated. The clock used to measure the 6764 time shall be the clock specified by clock_id. 6765 If the flag TIMER_ABSTIME is set in the flags argument, the clock_nanosleep( ) function shall 6766 cause the current thread to be suspended from execution until either the time value of the clock 6767 specified by clock_id reaches the absolute time specified by the rqtp argument, or a signal is 6768 delivered to the calling thread and its action is to invoke a signal-catching function, or the 6769 process is terminated. If, at the time of the call, the time value specified by rqtp is less than or 6770 equal to the time value of the specified clock, then clock_nanosleep( ) shall return immediately 6771 and the calling process shall not be suspended. 6772 The suspension time caused by this function may be longer than requested because the 6773 argument value is rounded up to an integer multiple of the sleep resolution, or because of the 6774 scheduling of other activity by the system. But, except for the case of being interrupted by a 6775 signal, the suspension time for the relative clock_nanosleep( ) function (that is, with the 6776 TIMER_ABSTIME flag not set) shall not be less than the time interval specified by rqtp, as 6777 measured by the corresponding clock. The suspension for the absolute clock_nanosleep( ) function 6778 (that is, with the TIMER_ABSTIME flag set) shall be in effect at least until the value of the 6779 corresponding clock reaches the absolute time specified by rqtp, except for the case of being 6780 interrupted by a signal. 6781 The use of the clock_nanosleep( ) function shall have no effect on the action or blockage of any 6782 signal. 6783 The clock_nanosleep( ) function shall fail if the clock_id argument refers to the CPU-time clock of 6784 the calling thread. It is unspecified if clock_id values of other CPU-time clocks are allowed. 6785 RETURN VALUE 6786 If the clock_nanosleep( ) function returns because the requested time has elapsed, its return value 6787 shall be zero. 6788 If the clock_nanosleep( ) function returns because it has been interrupted by a signal, it shall return 6789 the corresponding error value. For the relative clock_nanosleep( ) function, if the rmtp argument is 6790 non-NULL, the timespec structure referenced by it shall be updated to contain the amount of 6791 time remaining in the interval (the requested time minus the time actually slept). If the rmtp 6792 argument is NULL, the remaining time is not returned. The absolute clock_nanosleep( ) function 6793 has no effect on the structure referenced by rmtp. 6794 If clock_nanosleep( ) fails, it shall return the corresponding error value. 656 Technical Standard (2001) (Draft April 16, 2001) System Interfaces clock_nanosleep( ) 6795 ERRORS 6796 The clock_nanosleep( ) function shall fail if: 6797 [EINTR] The clock_nanosleep( ) function was interrupted by a signal. 6798 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than 6799 or equal to 1 000 million; or the TIMER_ABSTIME flag was specified in flags 6800 and the rqtp argument is outside the range for the clock specified by clock_id; 6801 or the clock_id argument does not specify a known clock, or specifies the 6802 CPU-time clock of the calling thread. 6803 [ENOTSUP] The clock_id argument specifies a clock for which clock_nanosleep( ) is not 6804 supported, such as a CPU-time clock. 6805 EXAMPLES 6806 None. 6807 APPLICATION USAGE 6808 Calling clock_nanosleep( ) with the value TIMER_ABSTIME not set in the flags argument and with 6809 a clock_id of CLOCK_REALTIME is equivalent to calling nanosleep( ) with the same rqtp and rmtp 6810 arguments. 6811 RATIONALE 6812 The nanosleep( ) function specifies that the system-wide clock CLOCK_REALTIME is used to 6813 measure the elapsed time for this time service. However, with the introduction of the monotonic 6814 clock CLOCK_MONOTONIC a new relative sleep function is needed to allow an application to 6815 take advantage of the special characteristics of this clock. 6816 There are many applications in which a process needs to be suspended and then activated 6817 multiple times in a periodic way; for example, to poll the status of a non-interrupting device or 6818 to refresh a display device. For these cases, it is known that precise periodic activation cannot be 6819 achieved with a relative sleep( ) or nanosleep( ) function call. Suppose, for example, a periodic 6820 process that is activated at time T0, executes for a while, and then wants to suspend itself until 6821 time T0+T, the period being T. If this process wants to use the nanosleep( ) function, it must first 6822 call clock_gettime( ) to get the current time, then calculate the difference between the current time 6823 and T0+T and, finally, call nanosleep( ) using the computed interval. However, the process could 6824 be preempted by a different process between the two function calls, and in this case the interval 6825 computed would be wrong; the process would wake up later than desired. This problem would 6826 not occur with the absolute clock_nanosleep( ) function, since only one function call would be 6827 necessary to suspend the process until the desired time. In other cases, however, a relative sleep 6828 is needed, and that is why both functionalities are required. 6829 Although it is possible to implement periodic processes using the timers interface, this 6830 implementation would require the use of signals, and the reservation of some signal numbers. In 6831 this regard, the reasons for including an absolute version of the clock_nanosleep( ) function in 6832 IEEE Std 1003.1-200x are the same as for the inclusion of the relative nanosleep( ). 6833 It is also possible to implement precise periodic processes using pthread_cond_timedwait( ), in 6834 which an absolute timeout is specified that takes effect if the condition variable involved is 6835 never signaled. However, the use of this interface is unnatural, and involves performing other 6836 operations on mutexes and condition variables that imply an unnecessary overhead. 6837 Furthermore, pthread_cond_timedwait( ) is not available in implementations that do not support 6838 threads. 6839 Although the interface of the relative and absolute versions of the new high resolution sleep 6840 service is the same clock_nanosleep( ) function, the rmtp argument is only used in the relative 6841 sleep. This argument is needed in the relative clock_nanosleep( ) function to reissue the function System Interfaces, Issue 6 657 clock_nanosleep( ) System Interfaces 6842 call if it is interrupted by a signal, but it is not needed in the absolute clock_nanosleep( ) function 6843 call; if the call is interrupted by a signal, the absolute clock_nanosleep( ) function can be invoked 6844 again with the same rqtp argument used in the interrupted call. 6845 FUTURE DIRECTIONS 6846 None. 6847 SEE ALSO 6848 clock_getres( ), nanosleep( ), pthread_cond_timedwait( ), sleep( ), the Base Definitions volume of 6849 IEEE Std 1003.1-200x, 6850 CHANGE HISTORY 6851 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 658 Technical Standard (2001) (Draft April 16, 2001) System Interfaces clock_settime( ) 6852 NAME 6853 clock_settime - clock and timer functions (REALTIME) 6854 SYNOPSIS 6855 TMR #include 6856 int clock_settime(clockid_t clock_id, const struct timespec *tp); 6857 6858 DESCRIPTION 6859 Refer to clock_getres( ). System Interfaces, Issue 6 659 clog( ) System Interfaces 6860 NAME 6861 clog, clogf, clogl - complex natural logarithm functions 6862 SYNOPSIS 6863 #include 6864 double complex clog(double complex z); 6865 float complex clogf(float complex z); 6866 long double complex clogl(long double complex z); 6867 DESCRIPTION 6868 CX The functionality described on this reference page is aligned with the ISO C standard. Any 6869 conflict between the requirements described here and the ISO C standard is unintentional. This 6870 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 6871 These functions shall compute the complex natural (base e) logarithm of z, with a branch cut 6872 along the negative real axis. 6873 RETURN VALUE 6874 These functions shall return the complex natural logarithm value, in the range of a strip 6875 mathematically unbounded along the real axis and in the interval [-i , +i ] along the imaginary 6876 axis. 6877 ERRORS 6878 No errors are defined. 6879 EXAMPLES 6880 None. 6881 APPLICATION USAGE 6882 None. 6883 RATIONALE 6884 None. 6885 FUTURE DIRECTIONS 6886 None. 6887 SEE ALSO 6888 cexp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 6889 CHANGE HISTORY 6890 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 660 Technical Standard (2001) (Draft April 16, 2001) System Interfaces close( ) 6891 NAME 6892 close - close a file descriptor 6893 SYNOPSIS 6894 #include 6895 int close(int fildes); 6896 DESCRIPTION 6897 The close( ) function shall deallocate the file descriptor indicated by fildes. To deallocate means 6898 to make the file descriptor available for return by subsequent calls to open( ) or other functions 6899 that allocate file descriptors. All outstanding record locks owned by the process on the file 6900 associated with the file descriptor shall be removed (that is, unlocked). 6901 If close( ) is interrupted by a signal that is to be caught, it shall return -1 with errno set to [EINTR] 6902 and the state of fildes is unspecified. If an I/O error occurred while reading from or writing to the 6903 file system during close( ), it may return -1 with errno set to [EIO]; if this error is returned, the 6904 state of fildes is unspecified. 6905 When all file descriptors associated with a pipe or FIFO special file are closed, any data 6906 remaining in the pipe or FIFO shall be discarded. 6907 When all file descriptors associated with an open file description have been closed the open file 6908 description shall be freed. 6909 If the link count of the file is 0, when all file descriptors associated with the file are closed, the 6910 space occupied by the file shall be freed and the file shall no longer be accessible. 6911 XSR If a STREAMS-based fildes is closed and the calling process was previously registered to receive 6912 a SIGPOLL signal for events associated with that STREAM, the calling process shall be 6913 unregistered for events associated with the STREAM. The last close( ) for a STREAM shall cause | 6914 the STREAM associated with fildes to be dismantled. If O_NONBLOCK is not set and there have | 6915 been no signals posted for the STREAM, and if there is data on the module's write queue, close( ) | 6916 shall wait for an unspecified time (for each module and driver) for any output to drain before | 6917 dismantling the STREAM. The time delay can be changed via an I_SETCLTIME ioctl( ) request. If | 6918 the O_NONBLOCK flag is set, or if there are any pending signals, close( ) shall not wait for | 6919 output to drain, and shall dismantle the STREAM immediately. | 6920 If the implementation supports STREAMS-based pipes, and fildes is associated with one end of a 6921 pipe, the last close( ) shall cause a hangup to occur on the other end of the pipe. In addition, if the | 6922 other end of the pipe has been named by fattach( ), then the last close( ) shall force the named end | 6923 to be detached by fdetach( ). If the named end has no open file descriptors associated with it and | 6924 gets detached, the STREAM associated with that end shall also be dismantled. | 6925 XSI If fildes refers to the master side of a pseudo-terminal, and this is the last close, a SIGHUP signal | 6926 shall be sent to the process group, if any, for which the slave side of the pseudo-terminal is the | 6927 controlling terminal. It is unspecified whether closing the master side of the pseudo-terminal 6928 flushes all queued input and output. 6929 XSR If fildes refers to the slave side of a STREAMS-based pseudo-terminal, a zero-length message 6930 may be sent to the master. 6931 AIO When there is an outstanding cancelable asynchronous I/O operation against fildes when close( ) 6932 is called, that I/O operation may be canceled. An I/O operation that is not canceled completes 6933 as if the close( ) operation had not yet occurred. All operations that are not canceled shall 6934 complete as if the close( ) blocked until the operations completed. The close( ) operation itself 6935 need not block awaiting such I/O completion. Whether any I/O operation is canceled, and 6936 which I/O operation may be canceled upon close( ), is implementation-defined. System Interfaces, Issue 6 661 close( ) System Interfaces 6937 MF|SHM If a shared memory object or a memory mapped file remains referenced at the last close (that is, 6938 a process has it mapped), then the entire contents of the memory object shall persist until the 6939 memory object becomes unreferenced. If this is the last close of a shared memory object or a 6940 memory mapped file and the close results in the memory object becoming unreferenced, and the 6941 memory object has been unlinked, then the memory object shall be removed. 6942 If fildes refers to a socket, close( ) shall cause the socket to be destroyed. If the socket is in 6943 connection-mode, and the SO_LINGER option is set for the socket with non-zero linger time, 6944 and the socket has untransmitted data, then close( ) shall block for up to the current linger 6945 interval until all data is transmitted. 6946 RETURN VALUE 6947 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 6948 indicate the error. 6949 ERRORS 6950 The close( ) function shall fail if: 6951 [EBADF] The fildes argument is not a valid file descriptor. 6952 [EINTR] The close( ) function was interrupted by a signal. 6953 The close( ) function may fail if: 6954 [EIO] An I/O error occurred while reading from or writing to the file system. 6955 EXAMPLES 6956 Reassigning a File Descriptor 6957 The following example closes the file descriptor associated with standard output for the current 6958 process, re-assigns standard output to a new file descriptor, and closes the original file 6959 descriptor to clean up. This example assumes that the file descriptor 0 (which is the descriptor 6960 for standard input) is not closed. 6961 #include 6962 ... 6963 int pfd; 6964 ... 6965 close(1); 6966 dup(pfd); 6967 close(pfd); 6968 ... 6969 Incidentally, this is exactly what could be achieved using: 6970 dup2(pfd, 1); 6971 close(pfd); 6972 Closing a File Descriptor 6973 In the following example, close( ) is used to close a file descriptor after an unsuccessful attempt is 6974 made to associate that file descriptor with a stream. 6975 #include 6976 #include 6977 #include 662 Technical Standard (2001) (Draft April 16, 2001) System Interfaces close( ) 6978 #define LOCKFILE "/etc/ptmp" 6979 ... 6980 int pfd; 6981 FILE *fpfd; 6982 ... 6983 if ((fpfd = fdopen (pfd, "w")) == NULL) { 6984 close(pfd); 6985 unlink(LOCKFILE); 6986 exit(1); 6987 } 6988 ... 6989 APPLICATION USAGE 6990 An application that had used the stdio routine fopen( ) to open a file should use the 6991 corresponding fclose( ) routine rather than close( ). Once a file is closed, the file descriptor no 6992 longer exists, since the integer corresponding to it no longer refers to a file. 6993 RATIONALE 6994 The use of interruptible device close routines should be discouraged to avoid problems with the 6995 implicit closes of file descriptors by exec and exit( ). This volume of IEEE Std 1003.1-200x only 6996 intends to permit such behavior by specifying the [EINTR] error condition. 6997 FUTURE DIRECTIONS 6998 None. 6999 SEE ALSO 7000 fattach( ), fclose( ), fdetach( ), fopen( ), ioctl( ), open( ), the Base Definitions volume of 7001 IEEE Std 1003.1-200x, , Section 2.6 (on page 488) 7002 CHANGE HISTORY 7003 First released in Issue 1. Derived from Issue 1 of the SVID. 7004 Issue 5 7005 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 7006 Issue 6 7007 The DESCRIPTION related to a STREAMS-based file or pseudo-terminal is marked as part of the 7008 XSI STREAMS Option Group. 7009 The following new requirements on POSIX implementations derive from alignment with the 7010 Single UNIX Specification: 7011 * The [EIO] error condition is added as an optional error. 7012 * The DESCRIPTION is updated to describe the state of the fildes file descriptor as unspecified 7013 if an I/O error occurs and an [EIO] error condition is returned. 7014 Text referring to sockets is added to the DESCRIPTION. 7015 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 7016 shared memory objects and memory mapped files (and not typed memory objects) are the types 7017 of memory objects to which the paragraph on last closes applies. System Interfaces, Issue 6 663 closedir( ) System Interfaces 7018 NAME 7019 closedir - close a directory stream 7020 SYNOPSIS 7021 #include 7022 int closedir(DIR *dirp); 7023 DESCRIPTION 7024 The closedir( ) function shall close the directory stream referred to by the argument dirp. Upon 7025 return, the value of dirp may no longer point to an accessible object of the type DIR. If a file 7026 descriptor is used to implement type DIR, that file descriptor shall be closed. 7027 RETURN VALUE 7028 Upon successful completion, closedir( ) shall return 0; otherwise, -1 shall be returned and errno 7029 set to indicate the error. 7030 ERRORS 7031 The closedir( ) function may fail if: 7032 [EBADF] The dirp argument does not refer to an open directory stream. 7033 [EINTR] The closedir( ) function was interrupted by a signal. 7034 EXAMPLES 7035 Closing a Directory Stream 7036 The following program fragment demonstrates how the closedir( ) function is used. 7037 ... 7038 DIR *dir; 7039 struct dirent *dp; 7040 ... 7041 if ((dir = opendir (".")) == NULL) { 7042 ... 7043 } 7044 while ((dp = readdir (dir)) != NULL) { 7045 ... 7046 } 7047 closedir(dir); 7048 ... 7049 APPLICATION USAGE 7050 None. 7051 RATIONALE 7052 None. 7053 FUTURE DIRECTIONS 7054 None. 7055 SEE ALSO 7056 opendir( ), the Base Definitions volume of IEEE Std 1003.1-200x, 664 Technical Standard (2001) (Draft April 16, 2001) System Interfaces closedir( ) 7057 CHANGE HISTORY 7058 First released in Issue 2. 7059 Issue 6 7060 In the SYNOPSIS, the optional include of the header is removed. 7061 The following new requirements on POSIX implementations derive from alignment with the 7062 Single UNIX Specification: 7063 * The requirement to include has been removed. Although was 7064 required for conforming implementations of previous POSIX specifications, it was not 7065 required for UNIX applications. 7066 * The [EINTR] error condition is added as an optional error condition. System Interfaces, Issue 6 665 closelog( ) System Interfaces 7067 NAME 7068 closelog, openlog, setlogmask, syslog - control system log 7069 SYNOPSIS 7070 XSI #include 7071 void closelog(void); 7072 void openlog(const char *ident, int logopt, int facility); 7073 int setlogmask(int maskpri); 7074 void syslog(int priority, const char *message, ... /* arguments */); 7075 7076 DESCRIPTION 7077 The syslog( ) function shall send a message to an implementation-defined logging facility, which 7078 may log it in an implementation-defined system log, write it to the system console, forward it to 7079 a list of users, or forward it to the logging facility on another host over the network. The logged 7080 message shall include a message header and a message body. The message header contains at 7081 least a timestamp and a tag string. 7082 The message body is generated from the message and following arguments in the same manner 7083 as if these were arguments to printf( ), except that the additional conversion specification %m 7084 shall be recognized; it shall convert no arguments, shall cause the output of the error message 7085 string associated with the value of errno on entry to syslog( ), and may be mixed with argument 7086 specifications of the "%n$" form. If a complete conversion specification with the m conversion 7087 specifier character is not just %m, the behavior is undefined. A trailing may be added 7088 if needed. 7089 Values of the priority argument are formed by OR'ing together a severity level value and an 7090 optional facility value. If no facility value is specified, the current default facility value is used. 7091 Possible values of severity level include: 7092 LOG_EMERG A panic condition. 7093 LOG_ALERT A condition that should be corrected immediately, such as a corrupted system 7094 database. 7095 LOG_CRIT Critical conditions, such as hard device errors. 7096 LOG_ERR Errors. 7097 LOG_WARNING 7098 Warning messages. 7099 LOG_NOTICE Conditions that are not error conditions, but that may require special 7100 handling. 7101 LOG_INFO Informational messages. 7102 LOG_DEBUG Messages that contain information normally of use only when debugging a 7103 program. 7104 The facility indicates the application or system component generating the message. Possible 7105 facility values include: 7106 LOG_USER Messages generated by arbitrary processes. This is the default facility 7107 identifier if none is specified. 7108 LOG_LOCAL0 Reserved for local use. 666 Technical Standard (2001) (Draft April 16, 2001) System Interfaces closelog( ) 7109 LOG_LOCAL1 Reserved for local use. 7110 LOG_LOCAL2 Reserved for local use. 7111 LOG_LOCAL3 Reserved for local use. 7112 LOG_LOCAL4 Reserved for local use. 7113 LOG_LOCAL5 Reserved for local use. 7114 LOG_LOCAL6 Reserved for local use. 7115 LOG_LOCAL7 Reserved for local use. 7116 The openlog( ) function shall set process attributes that affect subsequent calls to syslog( ). The 7117 ident argument is a string that is prepended to every message. The logopt argument indicates 7118 logging options. Values for logopt are constructed by a bitwise-inclusive OR of zero or more of 7119 the following: 7120 LOG_PID Log the process ID with each message. This is useful for identifying specific 7121 processes. 7122 LOG_CONS Write messages to the system console if they cannot be sent to the logging 7123 facility. The syslog( ) function ensures that the process does not acquire the 7124 console as a controlling terminal in the process of writing the message. 7125 LOG_NDELAY Open the connection to the logging facility immediately. Normally the open is 7126 delayed until the first message is logged. This is useful for programs that need 7127 to manage the order in which file descriptors are allocated. 7128 LOG_ODELAY Delay open until syslog( ) is called. 7129 LOG_NOWAIT Do not wait for child processes that may have been created during the course 7130 of logging the message. This option should be used by processes that enable 7131 notification of child termination using SIGCHLD, since syslog( ) may 7132 otherwise block waiting for a child whose exit status has already been 7133 collected. 7134 The facility argument encodes a default facility to be assigned to all messages that do not have 7135 an explicit facility already encoded. The initial default facility is LOG_USER. 7136 The openlog( ) and syslog( ) functions may allocate a file descriptor. It is not necessary to call 7137 openlog( ) prior to calling syslog( ). 7138 The closelog( ) function shall close any open file descriptors allocated by previous calls to 7139 openlog( ) or syslog( ). 7140 The setlogmask( ) function shall set the log priority mask for the current process to maskpri and 7141 return the previous mask. If the maskpri argument is 0, the current log mask is not modified. 7142 Calls by the current process to syslog( ) with a priority not set in maskpri shall be rejected. The 7143 default log mask allows all priorities to be logged. A call to openlog( ) is not required prior to 7144 calling setlogmask( ). 7145 Symbolic constants for use as values of the logopt, facility , priority, and maskpri arguments are 7146 defined in the header. 7147 RETURN VALUE 7148 The setlogmask( ) function shall return the previous log priority mask. The closelog( ), openlog( ), 7149 and syslog( ) functions shall not return a value. System Interfaces, Issue 6 667 closelog( ) System Interfaces 7150 ERRORS 7151 No errors are defined. 7152 EXAMPLES 7153 Using openlog( ) 7154 The following example causes subsequent calls to syslog( ) to log the process ID with each 7155 message, and to write messages to the system console if they cannot be sent to the logging 7156 facility. 7157 #include 7158 char *ident = "Process demo"; 7159 int logopt = LOG_PID | LOG_CONS; 7160 int facility = LOG_USER; 7161 ... 7162 openlog(ident, logopt, facility); 7163 Using setlogmask( ) 7164 The following example causes subsequent calls to syslog( ) to accept error messages or messages 7165 generated by arbitrary processes, and to reject all other messages. 7166 #include 7167 int result; 7168 int mask = LOG_MASK (LOG_ERR | LOG_USER); 7169 ... 7170 result = setlogmask(mask); 7171 Using syslog 7172 The following example sends the message "This is a message" to the default logging 7173 facility, marking the message as an error message generated by random processes. 7174 #include 7175 char *message = "This is a message"; 7176 int priority = LOG_ERR | LOG_USER; 7177 ... 7178 syslog(priority, message); 7179 APPLICATION USAGE 7180 None. 7181 RATIONALE 7182 None. 7183 FUTURE DIRECTIONS 7184 None. 7185 SEE ALSO 7186 printf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 668 Technical Standard (2001) (Draft April 16, 2001) System Interfaces closelog( ) 7187 CHANGE HISTORY 7188 First released in Issue 4, Version 2. 7189 Issue 5 7190 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 669 confstr( ) System Interfaces 7191 NAME 7192 confstr - get configurable variables 7193 SYNOPSIS 7194 #include 7195 size_t confstr(int name, char *buf, size_t len); 7196 DESCRIPTION 7197 The confstr( ) function shall return configuration-defined string values. Its use and purpose are | 7198 similar to sysconf( ), but it is used where string values rather than numeric values are returned. | 7199 The name argument represents the system variable to be queried. The implementation shall 7200 support the following name values, defined in . It may support others: 7201 _CS_PATH 7202 _CS_POSIX_V6_ILP32_OFF32_CFLAGS 7203 _CS_POSIX_V6_ILP32_OFF32_LDFLAGS 7204 _CS_POSIX_V6_ILP32_OFF32_LIBS 7205 _CS_POSIX_V6_ILP32_OFF32_LINTFLAGS 7206 _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS 7207 _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS 7208 _CS_POSIX_V6_ILP32_OFFBIG_LIBS 7209 _CS_POSIX_V6_ILP32_OFFBIG_LINTFLAGS 7210 _CS_POSIX_V6_LP64_OFF64_CFLAGS 7211 _CS_POSIX_V6_LP64_OFF64_LDFLAGS 7212 _CS_POSIX_V6_LP64_OFF64_LIBS 7213 _CS_POSIX_V6_LP64_OFF64_LINTFLAGS 7214 _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS 7215 _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS 7216 _CS_POSIX_V6_LPBIG_OFFBIG_LIBS 7217 _CS_POSIX_V6_LPBIG_OFFBIG_LINTFLAGS 7218 XSI _CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY) 7219 _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY) 7220 _CS_XBS5_ILP32_OFF32_LIBS (LEGACY) 7221 _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY) 7222 _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY) 7223 _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY) 7224 _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY) 7225 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY) 7226 _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY) 7227 _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY) 7228 _CS_XBS5_LP64_OFF64_LIBS (LEGACY) 7229 _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY) 7230 _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY) 7231 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY) 7232 _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY) 7233 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY) 7234 7235 If len is not 0, and if name has a configuration-defined value, confstr( ) shall copy that value into 7236 the len-byte buffer pointed to by buf. If the string to be returned is longer than len bytes, 7237 including the terminating null, then confstr( ) shall truncate the string to len-1 bytes and null- 7238 terminate the result. The application can detect that the string was truncated by comparing the 7239 value returned by confstr( ) with len. 670 Technical Standard (2001) (Draft April 16, 2001) System Interfaces confstr( ) 7240 If len is 0 and buf is a null pointer, then confstr( ) shall still return the integer value as defined 7241 below, but shall not return a string. If len is 0 but buf is not a null pointer, the result is 7242 unspecified. 7243 If the implementation supports the Shell option, the string stored in buf after a call to: 7244 confstr(_CS_PATH, buf, sizeof(buf)) 7245 can be used as a value of the PATH environment variable that accesses all of the standard 7246 utilities of IEEE Std 1003.1-200x, if the return value is less than or equal to sizeof(buf). 7247 RETURN VALUE 7248 If name has a configuration-defined value, confstr( ) shall return the size of buffer that would be 7249 needed to hold the entire configuration-defined value including the terminating null. If this 7250 return value is greater than len, the string returned in buf is truncated. 7251 If name is invalid, confstr( ) shall return 0 and set errno to indicate the error. 7252 If name does not have a configuration-defined value, confstr( ) shall return 0 and leave errno 7253 unchanged. 7254 ERRORS 7255 The confstr( ) function shall fail if: 7256 [EINVAL] The value of the name argument is invalid. 7257 EXAMPLES 7258 None. 7259 APPLICATION USAGE 7260 An application can distinguish between an invalid name parameter value and one that 7261 corresponds to a configurable variable that has no configuration-defined value by checking if 7262 errno is modified. This mirrors the behavior of sysconf( ). 7263 The original need for this function was to provide a way of finding the configuration-defined 7264 default value for the environment variable PATH. Since PATH can be modified by the user to 7265 include directories that could contain utilities replacing the standard utilities in the Shell and 7266 Utilities volume of IEEE Std 1003.1-200x, applications need a way to determine the system- 7267 supplied PATH environment variable value that contains the correct search path for the standard 7268 utilities. 7269 An application could use: 7270 confstr(name, (char *)NULL, (size_t)0) 7271 to find out how big a buffer is needed for the string value; use malloc( ) to allocate a buffer to 7272 hold the string; and call confstr( ) again to get the string. Alternately, it could allocate a fixed, 7273 static buffer that is big enough to hold most answers (perhaps 512 or 1 024 bytes), but then use 7274 malloc( ) to allocate a larger buffer if it finds that this is too small. 7275 RATIONALE 7276 Application developers can normally determine any configuration variable by means of reading 7277 from the stream opened by a call to: 7278 popen("command -p getconf variable", "r"); 7279 The confstr( ) function with a name argument of _CS_PATH returns a string that can be used as a 7280 PATH environment variable setting that will reference the standard shell and utilities as 7281 described in the Shell and Utilities volume of IEEE Std 1003.1-200x. System Interfaces, Issue 6 671 confstr( ) System Interfaces 7282 The confstr( ) function copies the returned string into a buffer supplied by the application instead 7283 of returning a pointer to a string. This allows a cleaner function in some implementations (such 7284 as those with lightweight threads) and resolves questions about when the application must copy 7285 the string returned. 7286 FUTURE DIRECTIONS 7287 None. 7288 SEE ALSO 7289 pathconf( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell 7290 and Utilities volume of IEEE Std 1003.1-200x, c99 7291 CHANGE HISTORY 7292 First released in Issue 4. Derived from the ISO POSIX-2 standard. 7293 Issue 5 7294 A table indicating the permissible values of name are added to the DESCRIPTION. All those 7295 marked EX are new in this issue. 7296 Issue 6 7297 The Open Group Corrigendum U033/7 is applied. The return value for the case returning the 7298 size of the buffer now explicitly states that this includes the terminating null. 7299 The following new requirements on POSIX implementations derive from alignment with the 7300 Single UNIX Specification: 7301 * The DESCRIPTION is updated with new arguments which can be used to determine 7302 configuration strings for C compiler flags, linker/loader flags, and libraries for each different 7303 supported programming environment. This is a change to support data size neutrality. 7304 The following changes were made to align with the IEEE P1003.1a draft standard: 7305 * The DESCRIPTION is updated to include text describing how _CS_PATH can be used to 7306 obtain a PATH to access the standard utilities. 7307 The macros associated with the c89 programming models are marked LEGACY and new 7308 equivalent macros associated with c99 are introduced. 672 Technical Standard (2001) (Draft April 16, 2001) System Interfaces conj( ) 7309 NAME 7310 conj, conjf, conjl - complex conjugate functions 7311 SYNOPSIS 7312 #include 7313 double complex conj(double complex z); 7314 float complex conjf(float complex z); 7315 long double complex conjl(long double complex z); 7316 DESCRIPTION 7317 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7318 conflict between the requirements described here and the ISO C standard is unintentional. This 7319 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7320 These functions shall compute the complex conjugate of z, by reversing the sign of its imaginary 7321 part. 7322 RETURN VALUE 7323 These functions return the complex conjugate value. 7324 ERRORS 7325 No errors are defined. 7326 EXAMPLES 7327 None. 7328 APPLICATION USAGE 7329 None. 7330 RATIONALE 7331 None. 7332 FUTURE DIRECTIONS 7333 None. 7334 SEE ALSO 7335 carg( ), cimag( ), cproj( ), creal( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7336 7337 CHANGE HISTORY 7338 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 673 connect( ) System Interfaces 7339 NAME 7340 connect - connect a socket 7341 SYNOPSIS 7342 #include 7343 int connect(int socket, const struct sockaddr *address, 7344 socklen_t address_len); 7345 DESCRIPTION 7346 The connect( ) function shall attempt to make a connection on a socket. The function takes the | 7347 following arguments: 7348 socket Specifies the file descriptor associated with the socket. 7349 address Points to a sockaddr structure containing the peer address. The length and 7350 format of the address depend on the address family of the socket. 7351 address_len Specifies the length of the sockaddr structure pointed to by the address 7352 argument. 7353 If the socket has not already been bound to a local address, connect( ) shall bind it to an address 7354 which, unless the socket's address family is AF_UNIX, is an unused local address. 7355 If the initiating socket is not connection-mode, then connect( ) shall set the socket's peer address, 7356 and no connection is made. For SOCK_DGRAM sockets, the peer address identifies where all 7357 datagrams are sent on subsequent send( ) functions, and limits the remote sender for subsequent 7358 recv( ) functions. If address is a null address for the protocol, the socket's peer address shall be 7359 reset. 7360 If the initiating socket is connection-mode, then connect( ) shall attempt to establish a connection | 7361 to the address specified by the address argument. If the connection cannot be established | 7362 immediately and O_NONBLOCK is not set for the file descriptor for the socket, connect( ) shall | 7363 block for up to an unspecified timeout interval until the connection is established. If the timeout 7364 interval expires before the connection is established, connect( ) shall fail and the connection 7365 attempt shall be aborted. If connect( ) is interrupted by a signal that is caught while blocked 7366 waiting to establish a connection, connect( ) shall fail and set errno to [EINTR], but the connection 7367 request shall not be aborted, and the connection shall be established asynchronously. 7368 If the connection cannot be established immediately and O_NONBLOCK is set for the file 7369 descriptor for the socket, connect( ) shall fail and set errno to [EINPROGRESS], but the connection 7370 request shall not be aborted, and the connection shall be established asynchronously. 7371 Subsequent calls to connect( ) for the same socket, before the connection is established, shall fail 7372 and set errno to [EALREADY]. 7373 When the connection has been established asynchronously, select( ) and poll( ) shall indicate that 7374 the file descriptor for the socket is ready for writing. 7375 The socket in use may require the process to have appropriate privileges to use the connect( ) 7376 function. 7377 RETURN VALUE 7378 Upon successful completion, connect( ) shall return 0; otherwise, -1 shall be returned and errno 7379 set to indicate the error. 7380 ERRORS 7381 The connect( ) function shall fail if: 7382 [EADDRNOTAVAIL] 7383 The specified address is not available from the local machine. 674 Technical Standard (2001) (Draft April 16, 2001) System Interfaces connect( ) 7384 [EAFNOSUPPORT] 7385 The specified address is not a valid address for the address family of the 7386 specified socket. 7387 [EALREADY] A connection request is already in progress for the specified socket. 7388 [EBADF] The socket argument is not a valid file descriptor. 7389 [ECONNREFUSED] 7390 The target address was not listening for connections or refused the connection 7391 request. 7392 [EINPROGRESS] O_NONBLOCK is set for the file descriptor for the socket and the connection 7393 cannot be immediately established; the connection shall be established 7394 asynchronously. 7395 [EINTR] The attempt to establish a connection was interrupted by delivery of a signal 7396 that was caught; the connection shall be established asynchronously. 7397 [EISCONN] The specified socket is connection-mode and is already connected. 7398 [ENETUNREACH] 7399 No route to the network is present. 7400 [ENOTSOCK] The socket argument does not refer to a socket. 7401 [EPROTOTYPE] The specified address has a different type than the socket bound to the 7402 specified peer address. 7403 [ETIMEDOUT] The attempt to connect timed out before a connection was made. 7404 If the address family of the socket is AF_UNIX, then connect( ) shall fail if: 7405 [EIO] An I/O error occurred while reading from or writing to the file system. 7406 [ELOOP] A loop exists in symbolic links encountered during resolution of the pathname | 7407 in address. | 7408 [ENAMETOOLONG] 7409 A component of a pathname exceeded {NAME_MAX} characters, or an entire | 7410 pathname exceeded {PATH_MAX} characters. | 7411 [ENOENT] A component of the pathname does not name an existing file or the pathname | 7412 is an empty string. | 7413 [ENOTDIR] A component of the path prefix of the pathname in address is not a directory. | 7414 The connect( ) function may fail if: 7415 [EACCES] Search permission is denied for a component of the path prefix; or write 7416 access to the named socket is denied. 7417 [EADDRINUSE] Attempt to establish a connection that uses addresses that are already in use. 7418 [ECONNRESET] Remote host reset the connection request. 7419 [EHOSTUNREACH] 7420 The destination host cannot be reached (probably because the host is down or 7421 a remote router cannot reach it). 7422 [EINVAL] The address_len argument is not a valid length for the address family; or 7423 invalid address family in the sockaddr structure. System Interfaces, Issue 6 675 connect( ) System Interfaces 7424 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 7425 resolution of the pathname in address. | 7426 [ENAMETOOLONG] 7427 Pathname resolution of a symbolic link produced an intermediate result | 7428 whose length exceeds {PATH_MAX}. 7429 [ENETDOWN] The local network interface used to reach the destination is down. 7430 [ENOBUFS] No buffer space is available. 7431 [EOPNOTSUPP] The socket is listening and cannot be connected. 7432 EXAMPLES 7433 None. 7434 APPLICATION USAGE 7435 If connect( ) fails, the state of the socket is unspecified. Conforming applications should close the | 7436 file descriptor and create a new socket before attempting to reconnect. 7437 RATIONALE 7438 None. 7439 FUTURE DIRECTIONS 7440 None. 7441 SEE ALSO 7442 accept( ), bind( ), close( ), getsockname( ), poll( ), select( ), send( ), shutdown( ), socket( ), the Base 7443 Definitions volume of IEEE Std 1003.1-200x, 7444 CHANGE HISTORY 7445 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 7446 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 7447 [ELOOP] error condition is added. 676 Technical Standard (2001) (Draft April 16, 2001) System Interfaces copysign( ) 7448 NAME 7449 copysign, copysignf, copysignl - number manipulation function 7450 SYNOPSIS 7451 #include 7452 double copysign(double x, double y); 7453 float copysignf(float x, float y); 7454 long double copysignl(long double x, long double y); 7455 DESCRIPTION 7456 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7457 conflict between the requirements described here and the ISO C standard is unintentional. This 7458 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7459 These functions shall produce a value with the magnitude of x and the sign of y. On 7460 implementations that represent a signed zero but do not treat negative zero consistently in 7461 arithmetic operations, these functions regard the sign of zero as positive. 7462 RETURN VALUE 7463 Upon successful completion, these functions shall return a value with the magnitude of x and 7464 the sign of y. 7465 ERRORS 7466 No errors are defined. 7467 EXAMPLES 7468 None. 7469 APPLICATION USAGE 7470 None. 7471 RATIONALE 7472 None. 7473 FUTURE DIRECTIONS 7474 None. 7475 SEE ALSO 7476 signbit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7477 CHANGE HISTORY 7478 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 677 cos( ) System Interfaces 7479 NAME 7480 cos, cosf, cosl - cosine function 7481 SYNOPSIS 7482 #include 7483 double cos(double x); 7484 float cosf(float x); 7485 long double cosl(long double x); 7486 DESCRIPTION 7487 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7488 conflict between the requirements described here and the ISO C standard is unintentional. This 7489 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7490 These functions shall compute the cosine of their argument x, measured in radians. 7491 An application wishing to check for error situations should set errno to zero and call 7492 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 7493 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 7494 zero, an error has occurred. 7495 RETURN VALUE 7496 Upon successful completion, these functions shall return the cosine of x. 7497 MX If x is NaN, a NaN shall be returned. 7498 If x is ±0, the value 1.0 shall be returned. 7499 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 7500 defined value shall be returned. 7501 ERRORS 7502 These functions shall fail if: 7503 MX Domain Error The x argument is ±Inf. 7504 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 7505 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 7506 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 7507 shall be raised. | 7508 EXAMPLES 7509 Taking the Cosine of a 45-Degree Angle 7510 #include 7511 ... 7512 double radians = 45 * M_PI / 180; 7513 double result; 7514 ... 7515 result = cos(radians); 7516 APPLICATION USAGE 7517 These functions may lose accuracy when their argument is near an odd multiple of /2 or is far 7518 from 0. 7519 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 7520 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 678 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cos( ) 7521 RATIONALE 7522 None. 7523 FUTURE DIRECTIONS 7524 None. 7525 SEE ALSO 7526 acos( ), feclearexcept( ), fetestexcept( ), isnan( ), sin( ), tan( ), the Base Definitions volume of | 7527 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 7528 7529 CHANGE HISTORY 7530 First released in Issue 1. Derived from Issue 1 of the SVID. 7531 Issue 5 7532 The DESCRIPTION is updated to indicate how an application should check for an error. This 7533 text was previously published in the APPLICATION USAGE section. 7534 Issue 6 7535 The cosf( ) and cosl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 7536 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 7537 revised to align with the ISO/IEC 9899: 1999 standard. 7538 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 7539 marked. System Interfaces, Issue 6 679 cosf( ) System Interfaces 7540 NAME 7541 cosf - cosine function 7542 SYNOPSIS 7543 #include 7544 float cosf(float x); 7545 DESCRIPTION 7546 Refer to cos( ). 680 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cosh( ) 7547 NAME 7548 cosh, coshf, coshl - hyperbolic cosine functions 7549 SYNOPSIS 7550 #include 7551 double cosh(double x); 7552 float coshf(float x); 7553 long double coshl(long double x); 7554 DESCRIPTION 7555 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7556 conflict between the requirements described here and the ISO C standard is unintentional. This 7557 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7558 These functions shall compute the hyperbolic cosine of their argument x. 7559 An application wishing to check for error situations should set errno to zero and call 7560 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 7561 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 7562 zero, an error has occurred. 7563 RETURN VALUE 7564 Upon successful completion, these functions shall return the hyperbolic cosine of x. 7565 If the correct value would cause overflow, a range error shall occur and cosh( ), coshf( ), and 7566 coshl( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 7567 respectively. 7568 MX If x is NaN, a NaN shall be returned. 7569 If x is ±0, the value 1.0 shall be returned. 7570 If x is ±Inf, +Inf shall be returned. 7571 ERRORS 7572 These functions shall fail if: 7573 Range Error The result would cause an overflow. 7574 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 7575 then errno shall be set to [ERANGE]. If the integer expression | 7576 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 7577 floating-point exception shall be raised. | 7578 EXAMPLES 7579 None. 7580 APPLICATION USAGE 7581 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 7582 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 7583 For IEEE Std 754-1985 double, 710.5 < |x| implies that cosh(x) has overflowed. 7584 RATIONALE 7585 None. 7586 FUTURE DIRECTIONS 7587 None. System Interfaces, Issue 6 681 cosh( ) System Interfaces 7588 SEE ALSO 7589 acosh( ), feclearexcept( ), fetestexcept( ), isnan( ), sinh( ), tanh( ), the Base Definitions volume of | 7590 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 7591 7592 CHANGE HISTORY 7593 First released in Issue 1. Derived from Issue 1 of the SVID. 7594 Issue 5 7595 The DESCRIPTION is updated to indicate how an application should check for an error. This 7596 text was previously published in the APPLICATION USAGE section. 7597 Issue 6 7598 The coshf( ) and coshl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 7599 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 7600 revised to align with the ISO/IEC 9899: 1999 standard. 7601 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 7602 marked. 682 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cosl( ) 7603 NAME 7604 cosl - cosine function 7605 SYNOPSIS 7606 #include 7607 long double cosl(long double x); 7608 DESCRIPTION 7609 Refer to cos( ). System Interfaces, Issue 6 683 cpow( ) System Interfaces 7610 NAME 7611 cpow, cpowf, cpowl - complex power functions 7612 SYNOPSIS 7613 #include 7614 double complex cpow(double complex x, double complex y); 7615 float complex cpowf(float complex x, float complex y); 7616 long double complex cpowl(long double complex x, 7617 long double complex y); 7618 DESCRIPTION 7619 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7620 conflict between the requirements described here and the ISO C standard is unintentional. This 7621 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7622 These functions shall compute the complex power function xy, with a branch cut for the first 7623 parameter along the negative real axis. 7624 RETURN VALUE 7625 These functions shall return the complex power function value. 7626 ERRORS 7627 No errors are defined. 7628 EXAMPLES 7629 None. 7630 APPLICATION USAGE 7631 None. 7632 RATIONALE 7633 None. 7634 FUTURE DIRECTIONS 7635 None. 7636 SEE ALSO 7637 cabs( ), csqrt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7638 CHANGE HISTORY 7639 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 684 Technical Standard (2001) (Draft April 16, 2001) System Interfaces cproj( ) 7640 NAME 7641 cproj, cprojf, cprojl - complex projection functions 7642 SYNOPSIS 7643 #include 7644 double complex cproj(double complex z); 7645 float complex cprojf(float complex z); 7646 long double complex cprojl(long double complex z); 7647 DESCRIPTION 7648 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7649 conflict between the requirements described here and the ISO C standard is unintentional. This 7650 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7651 These functions shall compute a projection of z onto the Riemann sphere: z projects to z, except 7652 that all complex infinities (even those with one infinite part and one NaN part) project to 7653 positive infinity on the real axis. If z has an infinite part, then cproj(z) shall be equivalent to: | 7654 INFINITY + I * copysign(0.0, cimag(z)) 7655 RETURN VALUE 7656 These functions shall return the value of the projection onto the Riemann sphere. 7657 ERRORS 7658 No errors are defined. 7659 EXAMPLES 7660 None. 7661 APPLICATION USAGE 7662 None. 7663 RATIONALE 7664 Two topologies are commonly used in complex mathematics: the complex plane with its 7665 continuum of infinities, and the Riemann sphere with its single infinity. The complex plane is 7666 better suited for transcendental functions, the Riemann sphere for algebraic functions. The 7667 complex types with their multiplicity of infinities provide a useful (though imperfect) model for 7668 the complex plane. The cproj( ) function helps model the Riemann sphere by mapping all 7669 infinities to one, and should be used just before any operation, especially comparisons, that 7670 might give spurious results for any of the other infinities. Note that a complex value with one 7671 infinite part and one NaN part is regarded as an infinity, not a NaN, because if one part is 7672 infinite, the complex value is infinite independent of the value of the other part. For the same 7673 reason, cabs( ) returns an infinity if its argument has an infinite part and a NaN part. 7674 FUTURE DIRECTIONS 7675 None. 7676 SEE ALSO 7677 carg( ), cimag( ), conj( ), creal( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7678 7679 CHANGE HISTORY 7680 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 685 creal( ) System Interfaces 7681 NAME 7682 creal, crealf, creall - complex real functions 7683 SYNOPSIS 7684 #include 7685 double creal(double complex z); 7686 float crealf(float complex z); 7687 long double creall(long double complex z); 7688 DESCRIPTION 7689 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7690 conflict between the requirements described here and the ISO C standard is unintentional. This 7691 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7692 These functions shall compute the real part of z. 7693 RETURN VALUE 7694 These functions shall return the real part value. 7695 ERRORS 7696 No errors are defined. 7697 EXAMPLES 7698 None. 7699 APPLICATION USAGE 7700 For a variable z of complex type: 7701 z == creal(z) + cimag(z)*I 7702 RATIONALE 7703 None. 7704 FUTURE DIRECTIONS 7705 None. 7706 SEE ALSO 7707 carg( ), cimag( ), conj( ), cproj( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7708 7709 CHANGE HISTORY 7710 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 686 Technical Standard (2001) (Draft April 16, 2001) System Interfaces creat( ) 7711 NAME 7712 creat - create a new file or rewrite an existing one 7713 SYNOPSIS 7714 OH #include 7715 #include 7716 int creat(const char *path, mode_t mode); 7717 DESCRIPTION 7718 The function call: 7719 creat(path, mode) 7720 shall be equivalent to: | 7721 open(path, O_WRONLY|O_CREAT|O_TRUNC, mode) 7722 RETURN VALUE 7723 Refer to open( ). 7724 ERRORS 7725 Refer to open( ). 7726 EXAMPLES 7727 Creating a File 7728 The following example creates the file /tmp/file with read and write permissions for the file 7729 owner and read permission for group and others. The resulting file descriptor is assigned to the 7730 fd variable. 7731 #include 7732 ... 7733 int fd; 7734 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; 7735 char *filename = "/tmp/file"; 7736 ... 7737 fd = creat(filename, mode); 7738 ... 7739 APPLICATION USAGE 7740 None. 7741 RATIONALE 7742 The creat( ) function is redundant. Its services are also provided by the open( ) function. It has 7743 been included primarily for historical purposes since many existing applications depend on it. It 7744 is best considered a part of the C binding rather than a function that should be provided in other 7745 languages. 7746 FUTURE DIRECTIONS 7747 None. 7748 SEE ALSO 7749 open( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 7750 System Interfaces, Issue 6 687 creat( ) System Interfaces 7751 CHANGE HISTORY 7752 First released in Issue 1. Derived from Issue 1 of the SVID. 7753 Issue 6 7754 In the SYNOPSIS, the optional include of the header is removed. 7755 The following new requirements on POSIX implementations derive from alignment with the 7756 Single UNIX Specification: 7757 * The requirement to include has been removed. Although was 7758 required for conforming implementations of previous POSIX specifications, it was not 7759 required for UNIX applications. 688 Technical Standard (2001) (Draft April 16, 2001) System Interfaces crypt( ) 7760 NAME 7761 crypt - string encoding function (CRYPT) 7762 SYNOPSIS 7763 XSI #include 7764 char *crypt(const char *key, const char *salt); 7765 7766 DESCRIPTION 7767 The crypt( ) function is a string encoding function. The algorithm is implementation-defined. 7768 The key argument points to a string to be encoded. The salt argument is a string chosen from the 7769 set: 7770 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 7771 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 7772 0 1 2 3 4 5 6 7 8 9 . / 7773 The first two characters of this string may be used to perturb the encoding algorithm. 7774 The return value of crypt( ) points to static data that is overwritten by each call. 7775 The crypt( ) function need not be reentrant. A function that is not required to be reentrant is not 7776 required to be thread-safe. 7777 RETURN VALUE 7778 Upon successful completion, crypt( ) shall return a pointer to the encoded string. The first two 7779 characters of the returned value shall be those of the salt argument. Otherwise, it shall return a | 7780 null pointer and set errno to indicate the error. 7781 ERRORS 7782 The crypt( ) function shall fail if: 7783 [ENOSYS] The functionality is not supported on this implementation. 7784 EXAMPLES 7785 Encoding Passwords 7786 The following example finds a user database entry matching a particular user name and changes 7787 the current password to a new password. The crypt( ) function generates an encoded version of | 7788 each password. The first call to crypt( ) produces an encoded version of the old password; that | 7789 encoded password is then compared to the password stored in the user database. The second 7790 call to crypt( ) encodes the new password before it is stored. 7791 The putpwent( ) function, used in the following example, is not part of IEEE Std 1003.1-200x. 7792 #include 7793 #include 7794 #include 7795 #include 7796 ... 7797 int valid_change; 7798 int pfd; /* Integer for file descriptor returned by open(). */ 7799 FILE *fpfd; /* File pointer for use in putpwent(). */ 7800 struct passwd *p; 7801 char user[100]; 7802 char oldpasswd[100]; 7803 char newpasswd[100]; System Interfaces, Issue 6 689 crypt( ) System Interfaces 7804 char savepasswd[100]; 7805 ... 7806 valid_change = 0; 7807 while ((p = getpwent()) != NULL) { 7808 /* Change entry if found. */ 7809 if (strcmp(p->pw_name, user) == 0) { 7810 if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { 7811 strcpy(savepasswd, crypt(newpasswd, user)); 7812 p->pw_passwd = savepasswd; 7813 valid_change = 1; 7814 } 7815 else { 7816 fprintf(stderr, "Old password is not valid\n"); 7817 } 7818 } 7819 /* Put passwd entry into ptmp. */ 7820 putpwent(p, fpfd); 7821 } 7822 APPLICATION USAGE 7823 The values returned by this function need not be portable among XSI-conformant systems. 7824 RATIONALE 7825 None. 7826 FUTURE DIRECTIONS 7827 None. 7828 SEE ALSO 7829 encrypt( ), setkey( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7830 CHANGE HISTORY 7831 First released in Issue 1. Derived from Issue 1 of the SVID. 7832 Issue 5 7833 Normative text previously in the APPLICATION USAGE section is moved to the 7834 DESCRIPTION. 690 Technical Standard (2001) (Draft April 16, 2001) System Interfaces csin( ) 7835 NAME 7836 csin, csinf, csinl - complex sine functions 7837 SYNOPSIS 7838 #include 7839 double complex csin(double complex z); 7840 float complex csinf(float complex z); 7841 long double complex csinl(long double complex z); 7842 DESCRIPTION 7843 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7844 conflict between the requirements described here and the ISO C standard is unintentional. This 7845 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7846 These functions shall compute the complex sine of z. 7847 RETURN VALUE 7848 These functions shall return the complex sine value. 7849 ERRORS 7850 No errors are defined. 7851 EXAMPLES 7852 None. 7853 APPLICATION USAGE 7854 None. 7855 RATIONALE 7856 None. 7857 FUTURE DIRECTIONS 7858 None. 7859 SEE ALSO 7860 casin( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7861 CHANGE HISTORY 7862 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 691 csinf( ) System Interfaces 7863 NAME 7864 csinf - complex sine functions 7865 SYNOPSIS 7866 #include 7867 float complex csinf(float complex z); 7868 DESCRIPTION 7869 Refer to csin( ). 692 Technical Standard (2001) (Draft April 16, 2001) System Interfaces csinh( ) 7870 NAME 7871 csinh, csinhf, csinhl - complex hyperbolic sine functions 7872 SYNOPSIS 7873 #include 7874 double complex csinh(double complex z); 7875 float complex csinhf(float complex z); 7876 long double complex csinhl(long double complex z); 7877 DESCRIPTION 7878 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7879 conflict between the requirements described here and the ISO C standard is unintentional. This 7880 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7881 These functions shall compute the complex hyperbolic sine of z. 7882 RETURN VALUE 7883 These functions shall return the complex hyperbolic sine value. 7884 ERRORS 7885 No errors are defined. 7886 EXAMPLES 7887 None. 7888 APPLICATION USAGE 7889 None. 7890 RATIONALE 7891 None. 7892 FUTURE DIRECTIONS 7893 None. 7894 SEE ALSO 7895 casinh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7896 CHANGE HISTORY 7897 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 693 csinl( ) System Interfaces 7898 NAME 7899 csinl - complex sine functions 7900 SYNOPSIS 7901 #include 7902 long double complex csinl(long double complex z); 7903 DESCRIPTION 7904 Refer to csin( ). 694 Technical Standard (2001) (Draft April 16, 2001) System Interfaces csqrt( ) 7905 NAME 7906 csqrt, csqrtf, csqrtl - complex square root functions 7907 SYNOPSIS 7908 #include 7909 double complex csqrt(double complex z); 7910 float complex csqrtf(float complex z); 7911 long double complex csqrtl(long double complex z); 7912 DESCRIPTION 7913 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7914 conflict between the requirements described here and the ISO C standard is unintentional. This 7915 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7916 These functions shall compute the complex square root of z, with a branch cut along the 7917 negative real axis. 7918 RETURN VALUE 7919 These functions shall return the complex square root value, in the range of the right half-plane 7920 (including the imaginary axis). 7921 ERRORS 7922 No errors are defined. 7923 EXAMPLES 7924 None. 7925 APPLICATION USAGE 7926 None. 7927 RATIONALE 7928 None. 7929 FUTURE DIRECTIONS 7930 None. 7931 SEE ALSO 7932 cabs( ), cpow( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7933 CHANGE HISTORY 7934 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 695 ctan( ) System Interfaces 7935 NAME 7936 ctan, ctanf, ctanl - complex tangent functions 7937 SYNOPSIS 7938 #include 7939 double complex ctan(double complex z); 7940 float complex ctanf(float complex z); 7941 long double complex ctanl(long double complex z); 7942 DESCRIPTION 7943 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7944 conflict between the requirements described here and the ISO C standard is unintentional. This 7945 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7946 These functions shall compute the complex tangent of z. 7947 RETURN VALUE 7948 These functions shall return the complex tangent value. 7949 ERRORS 7950 No errors are defined. 7951 EXAMPLES 7952 None. 7953 APPLICATION USAGE 7954 None. 7955 RATIONALE 7956 None. 7957 FUTURE DIRECTIONS 7958 None. 7959 SEE ALSO 7960 catan( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7961 CHANGE HISTORY 7962 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 696 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ctanf( ) 7963 NAME 7964 ctanf - complex tangent functions 7965 SYNOPSIS 7966 #include 7967 float complex ctanf(float complex z); 7968 DESCRIPTION 7969 Refer to ctan( ). System Interfaces, Issue 6 697 ctanh( ) System Interfaces 7970 NAME 7971 ctanh, ctanhf, ctanhl - complex hyperbolic tangent functions 7972 SYNOPSIS 7973 #include 7974 double complex ctanh(double complex z); 7975 float complex ctanhf(float complex z); 7976 long double complex ctanhl(long double complex z); 7977 DESCRIPTION 7978 CX The functionality described on this reference page is aligned with the ISO C standard. Any 7979 conflict between the requirements described here and the ISO C standard is unintentional. This 7980 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 7981 These functions shall compute the complex hyperbolic tangent of z. 7982 RETURN VALUE 7983 These functions shall return the complex hyperbolic tangent value. 7984 ERRORS 7985 No errors are defined. 7986 EXAMPLES 7987 None. 7988 APPLICATION USAGE 7989 None. 7990 RATIONALE 7991 None. 7992 FUTURE DIRECTIONS 7993 None. 7994 SEE ALSO 7995 catanh( ), the Base Definitions volume of IEEE Std 1003.1-200x, 7996 CHANGE HISTORY 7997 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 698 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ctanl( ) 7998 NAME 7999 ctanl - complex tangent functions 8000 SYNOPSIS 8001 #include 8002 long double complex ctanl(long double complex z); 8003 DESCRIPTION 8004 Refer to ctan( ). System Interfaces, Issue 6 699 ctermid( ) System Interfaces 8005 NAME 8006 ctermid - generate a pathname for controlling terminal | 8007 SYNOPSIS 8008 CX #include | 8009 char *ctermid(char *s); 8010 | 8011 DESCRIPTION 8012 The ctermid( ) function shall generate a string that, when used as a pathname, refers to the | 8013 current controlling terminal for the current process. If ctermid( ) returns a pathname, access to the | 8014 file is not guaranteed. | 8015 If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS 8016 functions, it shall ensure that the ctermid( ) function is called with a non-NULL parameter. 8017 RETURN VALUE 8018 If s is a null pointer, the string shall be generated in an area that may be static (and therefore may | 8019 be overwritten by each call), the address of which shall be returned. Otherwise, s is assumed to 8020 point to a character array of at least L_ctermid bytes; the string is placed in this array and the 8021 value of s shall be returned. The symbolic constant L_ctermid is defined in , and shall | 8022 have a value greater than 0. 8023 The ctermid( ) function shall return an empty string if the pathname that would refer to the | 8024 controlling terminal cannot be determined, or if the function is unsuccessful. 8025 ERRORS 8026 No errors are defined. 8027 EXAMPLES 8028 Determining the Controlling Terminal for the Current Process 8029 The following example returns a pointer to a string that identifies the controlling terminal for the | 8030 current process. The pathname for the terminal is stored in the array pointed to by the ptr | 8031 argument, which has a size of L_ctermid bytes, as indicated by the term argument. 8032 #include 8033 ... 8034 char term[L_ctermid]; 8035 char *ptr; 8036 ptr = ctermid(term); 8037 APPLICATION USAGE 8038 The difference between ctermid( ) and ttyname( ) is that ttyname( ) must be handed a file 8039 descriptor and return a path of the terminal associated with that file descriptor, while ctermid( ) 8040 returns a string (such as "/dev/tty") that refers to the current controlling terminal if used as a | 8041 pathname. | 8042 RATIONALE 8043 L_ctermid must be defined appropriately for a given implementation and must be greater than 8044 zero so that array declarations using it are accepted by the compiler. The value includes the 8045 terminating null byte. 8046 Conforming applications that use threads cannot call ctermid( ) with NULL as the parameter if | 8047 either _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If s is not 8048 NULL, the ctermid( ) function generates a string that, when used as a pathname, refers to the | 700 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ctermid( ) 8049 current controlling terminal for the current process. If s is NULL, the return value of ctermid( ) is 8050 undefined. 8051 There is no additional burden on the programmer-changing to use a hypothetical thread-safe 8052 version of ctermid( ) along with allocating a buffer is more of a burden than merely allocating a 8053 buffer. Application code should not assume that the returned string is short, as some 8054 implementations have more than two pathname components before reaching a logical device | 8055 name. | 8056 FUTURE DIRECTIONS 8057 None. 8058 SEE ALSO 8059 ttyname( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8060 CHANGE HISTORY 8061 First released in Issue 1. Derived from Issue 1 of the SVID. 8062 Issue 5 8063 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 8064 Issue 6 8065 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 701 ctime( ) System Interfaces 8066 NAME 8067 ctime, ctime_r - convert a time value to date and time string 8068 SYNOPSIS 8069 #include 8070 char *ctime(const time_t *clock); 8071 TSF char *ctime_r(const time_t *clock, char *buf); 8072 8073 DESCRIPTION 8074 CX For ctime( ): The functionality described on this reference page is aligned with the ISO C | 8075 standard. Any conflict between the requirements described here and the ISO C standard is 8076 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 8077 The ctime( ) function shall convert the time pointed to by clock, representing time in seconds 8078 since the Epoch, to local time in the form of a string. It shall be equivalent to: | 8079 asctime(localtime(clock)) 8080 CX The asctime( ), ctime( ), gmtime( ), and localtime( ) functions shall return values in one of two static | 8081 objects: a broken-down time structure and an array of char. Execution of any of the functions | 8082 may overwrite the information returned in either of these objects by any of the other functions. 8083 The ctime( ) function need not be reentrant. A function that is not required to be reentrant is not 8084 required to be thread-safe. 8085 TSF The ctime_r( ) function shall convert the calendar time pointed to by clock to local time in exactly 8086 the same form as ctime( ) and puts the string into the array pointed to by buf (which shall be at | 8087 least 26 bytes in size) and return buf. | 8088 Unlike ctime( ), the thread-safe version ctime_r( ) is not required to set tzname. 8089 RETURN VALUE 8090 The ctime( ) function shall return the pointer returned by asctime( ) with that broken-down time 8091 as an argument. 8092 TSF Upon successful completion, ctime_r( ) shall return a pointer to the string pointed to by buf. 8093 When an error is encountered, a null pointer shall be returned. 8094 ERRORS 8095 No errors are defined. 8096 EXAMPLES 8097 None. 8098 APPLICATION USAGE 8099 Values for the broken-down time structure can be obtained by calling gmtime( ) or localtime( ). 8100 The ctime( ) function is included for compatibility with older implementations, and does not 8101 support localized date and time formats. Applications should use the strftime( ) function to 8102 achieve maximum portability. 8103 The ctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead of 8104 possibly using a static data area that may be overwritten by each call. 8105 RATIONALE 8106 None. 702 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ctime( ) 8107 FUTURE DIRECTIONS 8108 None. 8109 SEE ALSO 8110 asctime( ), clock( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), 8111 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 5 8115 Normative text previously in the APPLICATION USAGE section is moved to the 8116 DESCRIPTION. 8117 The ctime_r( ) function is included for alignment with the POSIX Threads Extension. 8118 A note indicating that the ctime( ) function need not be reentrant is added to the DESCRIPTION. 8119 Issue 6 8120 Extensions beyond the ISO C standard are now marked. 8121 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 8122 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 8123 its avoidance of possibly using a static data area. System Interfaces, Issue 6 703 daylight System Interfaces 8124 NAME 8125 daylight - daylight savings time flag 8126 SYNOPSIS 8127 XSI #include 8128 extern int daylight; 8129 8130 DESCRIPTION 8131 Refer to tzset( ). 704 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dbm_clearerr( ) 8132 NAME 8133 dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, 8134 dbm_open, dbm_store - database functions 8135 SYNOPSIS 8136 XSI #include 8137 int dbm_clearerr(DBM *db); 8138 void dbm_close(DBM *db); 8139 int dbm_delete(DBM *db, datum key); 8140 int dbm_error(DBM *db); 8141 datum dbm_fetch(DBM *db, datum key); 8142 datum dbm_firstkey(DBM *db); 8143 datum dbm_nextkey(DBM *db); 8144 DBM *dbm_open(const char *file, int open_flags, mode_t file_mode); 8145 int dbm_store(DBM *db, datum key, datum content, int store_mode); 8146 8147 DESCRIPTION 8148 These functions create, access, and modify a database. 8149 A datum consists of at least two members, dptr and dsize. The dptr member points to an object 8150 that is dsize bytes in length. Arbitrary binary data, as well as character strings, may be stored in 8151 the object pointed to by dptr. 8152 The database is stored in two files. One file is a directory containing a bit map of keys and has 8153 .dir as its suffix. The second file contains all data and has .pag as its suffix. 8154 The dbm_open( ) function shall open a database. The file argument to the function is the | 8155 pathname of the database. The function opens two files named file.dir and file.pag. The | 8156 open_flags argument has the same meaning as the flags argument of open( ) except that a database 8157 opened for write-only access opens the files for read and write access and the behavior of the 8158 O_APPEND flag is unspecified. The file_mode argument has the same meaning as the third 8159 argument of open( ). 8160 The dbm_close( ) function shall close a database. The application shall ensure that argument db is 8161 a pointer to a dbm structure that has been returned from a call to dbm_open( ). 8162 These database functions shall support an internal block size large enough to support | 8163 key/content pairs of at least 1 023 bytes. | 8164 The dbm_fetch( ) function shall read a record from a database. The argument db is a pointer to a | 8165 database structure that has been returned from a call to dbm_open( ). The argument key is a 8166 datum that has been initialized by the application to the value of the key that matches the key of 8167 the record the program is fetching. 8168 The dbm_store( ) function shall write a record to a database. The argument db is a pointer to a 8169 database structure that has been returned from a call to dbm_open( ). The argument key is a 8170 datum that has been initialized by the application to the value of the key that identifies (for | 8171 subsequent reading, writing, or deleting) the record the application is writing. The argument | 8172 content is a datum that has been initialized by the application to the value of the record the | 8173 program is writing. The argument store_mode controls whether dbm_store( ) replaces any pre- | 8174 existing record that has the same key that is specified by the key argument. The application shall 8175 set store_mode to either DBM_INSERT or DBM_REPLACE. If the database contains a record that 8176 matches the key argument and store_mode is DBM_REPLACE, the existing record shall be | 8177 replaced with the new record. If the database contains a record that matches the key argument | 8178 and store_mode is DBM_INSERT, the existing record shall be left unchanged and the new record | System Interfaces, Issue 6 705 dbm_clearerr( ) System Interfaces 8179 ignored. If the database does not contain a record that matches the key argument and store_mode | 8180 is either DBM_INSERT or DBM_REPLACE, the new record shall be inserted in the database. | 8181 If the sum of a key/content pair exceeds the internal block size, the result is unspecified. | 8182 Moreover, the application shall ensure that all key/content pairs that hash together fit on a | 8183 single block. The dbm_store( ) function shall return an error in the event that a disk block fills | 8184 with inseparable data. 8185 The dbm_delete( ) function shall delete a record and its key from the database. The argument db is 8186 a pointer to a database structure that has been returned from a call to dbm_open( ). The argument 8187 key is a datum that has been initialized by the application to the value of the key that identifies 8188 the record the program is deleting. 8189 The dbm_firstkey( ) function shall return the first key in the database. The argument db is a 8190 pointer to a database structure that has been returned from a call to dbm_open( ). 8191 The dbm_nextkey( ) function shall return the next key in the database. The argument db is a 8192 pointer to a database structure that has been returned from a call to dbm_open( ). The application 8193 shall ensure that the dbm_firstkey( ) function is called before calling dbm_nextkey( ). Subsequent 8194 calls to dbm_nextkey( ) return the next key until all of the keys in the database have been 8195 returned. 8196 The dbm_error( ) function shall return the error condition of the database. The argument db is a 8197 pointer to a database structure that has been returned from a call to dbm_open( ). 8198 The dbm_clearerr( ) function shall clear the error condition of the database. The argument db is a 8199 pointer to a database structure that has been returned from a call to dbm_open( ). 8200 The dptr pointers returned by these functions may point into static storage that may be changed | 8201 by subsequent calls. 8202 These functions need not be reentrant. A function that is not required to be reentrant is not 8203 required to be thread-safe. 8204 RETURN VALUE 8205 The dbm_store( ) and dbm_delete( ) functions shall return 0 when they succeed and a negative 8206 value when they fail. 8207 The dbm_store( ) function shall return 1 if it is called with a flags value of DBM_INSERT and the 8208 function finds an existing record with the same key. 8209 The dbm_error( ) function shall return 0 if the error condition is not set and return a non-zero 8210 value if the error condition is set. 8211 The return value of dbm_clearerr( ) is unspecified. 8212 The dbm_firstkey( ) and dbm_nextkey( ) functions shall return a key datum. When the end of the 8213 database is reached, the dptr member of the key is a null pointer. If an error is detected, the dptr 8214 member of the key shall be a null pointer and the error condition of the database shall be set. 8215 The dbm_fetch( ) function shall return a content datum. If no record in the database matches the 8216 key or if an error condition has been detected in the database, the dptr member of the content 8217 shall be a null pointer. 8218 The dbm_open( ) function shall return a pointer to a database structure. If an error is detected 8219 during the operation, dbm_open( ) shall return a (DBM *)0. 706 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dbm_clearerr( ) 8220 ERRORS 8221 No errors are defined. 8222 EXAMPLES 8223 None. 8224 APPLICATION USAGE 8225 The following code can be used to traverse the database: 8226 for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) 8227 The dbm_ functions provided in this library should not be confused in any way with those of a 8228 general-purpose database management system. These functions do not provide for multiple 8229 search keys per entry, they do not protect against multi-user access (in other words they do not 8230 lock records or files), and they do not provide the many other useful database functions that are 8231 found in more robust database management systems. Creating and updating databases by use of 8232 these functions is relatively slow because of data copies that occur upon hash collisions. These 8233 functions are useful for applications requiring fast lookup of relatively static information that is 8234 to be indexed by a single key. 8235 The dbm_delete( ) function need not physically reclaim file space, although it does make it 8236 available for reuse by the database. 8237 After calling dbm_store( ) or dbm_delete( ) during a pass through the keys by dbm_firstkey( ) and 8238 dbm_nextkey( ), the application should reset the database by calling dbm_firstkey( ) before again 8239 calling dbm_nextkey( ). The contents of these files are unspecified and may not be portable. 8240 RATIONALE 8241 None. 8242 FUTURE DIRECTIONS 8243 None. 8244 SEE ALSO 8245 open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8246 CHANGE HISTORY 8247 First released in Issue 4, Version 2. 8248 Issue 5 8249 Moved from X/OPEN UNIX extension to BASE. 8250 Normative text previously in the APPLICATION USAGE section is moved to the 8251 DESCRIPTION. 8252 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8253 Issue 6 8254 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 707 difftime( ) System Interfaces 8255 NAME 8256 difftime - compute the difference between two calendar time values 8257 SYNOPSIS 8258 #include 8259 double difftime(time_t time1, time_t time0); 8260 DESCRIPTION 8261 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8262 conflict between the requirements described here and the ISO C standard is unintentional. This 8263 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 8264 The difftime( ) function shall compute the difference between two calendar times (as returned by 8265 time( )): time1- time0. 8266 RETURN VALUE 8267 The difftime( ) function shall return the difference expressed in seconds as a type double. 8268 ERRORS 8269 No errors are defined. 8270 EXAMPLES 8271 None. 8272 APPLICATION USAGE 8273 None. 8274 RATIONALE 8275 None. 8276 FUTURE DIRECTIONS 8277 None. 8278 SEE ALSO 8279 asctime( ), clock( ), ctime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), 8280 the Base Definitions volume of IEEE Std 1003.1-200x, 8281 CHANGE HISTORY 8282 First released in Issue 4. Derived from the ISO C standard. 708 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dirname( ) 8283 NAME 8284 dirname - report the parent directory name of a file pathname | 8285 SYNOPSIS 8286 XSI #include 8287 char *dirname(char *path); 8288 8289 DESCRIPTION 8290 The dirname( ) function shall take a pointer to a character string that contains a pathname, and | 8291 return a pointer to a string that is a pathname of the parent directory of that file. Trailing '/' | 8292 characters in the path are not counted as part of the path. 8293 If path does not contain a '/', then dirname( ) shall return a pointer to the string ".". If path is a 8294 null pointer or points to an empty string, dirname( ) shall return a pointer to the string ".". 8295 The dirname( ) function need not be reentrant. A function that is not required to be reentrant is 8296 not required to be thread-safe. 8297 RETURN VALUE 8298 The dirname( ) function shall return a pointer to a string that is the parent directory of path. If 8299 path is a null pointer or points to an empty string, a pointer to a string "." is returned. 8300 The dirname( ) function may modify the string pointed to by path, and may return a pointer to 8301 static storage that may then be overwritten by subsequent calls to dirname( ). 8302 ERRORS 8303 No errors are defined. 8304 EXAMPLES 8305 The following code fragment reads a pathname, changes the current working directory to the | 8306 parent directory, and opens the file. 8307 char path[MAXPATHLEN], *pathcopy; 8308 int fd; 8309 fgets(path, MAXPATHLEN, stdin); 8310 pathcopy = strdup(path); 8311 chdir(dirname(pathcopy)); 8312 fd = open(basename(path), O_RDONLY); 8313 Sample Input and Output Strings for dirname( ) 8314 In the following table, the input string is the value pointed to by path, and the output string is 8315 the return value of the dirname( ) function. ______________________________ 8316 _ Input String Output String _____________________________ 8317 "/usr/lib" "/usr" 8318 "/usr/" "/" 8319 "usr" "." 8320 "/" "/" 8321 "." "." 8322 _ ".." "." _____________________________ System Interfaces, Issue 6 709 dirname( ) System Interfaces 8323 Changing the Current Directory to the Parent Directory 8324 The following program fragment reads a pathname, changes the current working directory to | 8325 the parent directory, and opens the file. 8326 #include 8327 #include 8328 #include 8329 #include 8330 #include 8331 #include 8332 ... 8333 char path[PATH_MAX], *pathcopy; 8334 int fd; 8335 ... 8336 fgets(path, PATH_MAX, stdin); 8337 pathcopy = strdup(path); 8338 chdir(dirname(pathcopy)); 8339 fd = open(basename(path), O_RDONLY); 8340 APPLICATION USAGE 8341 The dirname( ) and basename( ) functions together yield a complete pathname. The expression | 8342 dirname(path) obtains the pathname of the directory where basename(path) is found. | 8343 Since the meaning of the leading "//" is implementation-defined, dirname("//foo) may return 8344 either "//" or '/' (but nothing else). 8345 RATIONALE 8346 None. 8347 FUTURE DIRECTIONS 8348 None. 8349 SEE ALSO 8350 basename( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8351 CHANGE HISTORY 8352 First released in Issue 4, Version 2. 8353 Issue 5 8354 Moved from X/OPEN UNIX extension to BASE. 8355 Normative text previously in the APPLICATION USAGE section is moved to the 8356 DESCRIPTION. 8357 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 710 Technical Standard (2001) (Draft April 16, 2001) System Interfaces div( ) 8358 NAME 8359 div - compute the quotient and remainder of an integer division 8360 SYNOPSIS 8361 #include 8362 div_t div(int numer, int denom); 8363 DESCRIPTION 8364 CX The functionality described on this reference page is aligned with the ISO C standard. Any 8365 conflict between the requirements described here and the ISO C standard is unintentional. This 8366 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 8367 The div( ) function shall compute the quotient and remainder of the division of the numerator 8368 numer by the denominator denom. If the division is inexact, the resulting quotient is the integer 8369 of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be 8370 represented, the behavior is undefined; otherwise, quot*denom+rem shall equal numer. 8371 RETURN VALUE 8372 The div( ) function shall return a structure of type div_t, comprising both the quotient and the 8373 remainder. The structure includes the following members, in any order: 8374 int quot; /* quotient */ 8375 int rem; /* remainder */ 8376 ERRORS 8377 No errors are defined. 8378 EXAMPLES 8379 None. 8380 APPLICATION USAGE 8381 None. 8382 RATIONALE 8383 None. 8384 FUTURE DIRECTIONS 8385 None. 8386 SEE ALSO 8387 ldiv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8388 CHANGE HISTORY 8389 First released in Issue 4. Derived from the ISO C standard. System Interfaces, Issue 6 711 dlclose( ) System Interfaces 8390 NAME 8391 dlclose - close a dlopen( ) object 8392 SYNOPSIS 8393 XSI #include 8394 int dlclose(void *handle); 8395 8396 DESCRIPTION 8397 The dlclose( ) function shall inform the system that the object referenced by a handle returned | 8398 from a previous dlopen( ) invocation is no longer needed by the application. 8399 The use of dlclose( ) reflects a statement of intent on the part of the process, but does not create 8400 any requirement upon the implementation, such as removal of the code or symbols referenced 8401 by handle. Once an object has been closed using dlclose( ) an application should assume that its 8402 symbols are no longer available to dlsym( ). All objects loaded automatically as a result of 8403 invoking dlopen( ) on the referenced object shall also be closed if this is the last reference to it. | 8404 Although a dlclose( ) operation is not required to remove structures from an address space, 8405 neither is an implementation prohibited from doing so. The only restriction on such a removal is 8406 that no object shall be removed to which references have been relocated, until or unless all such 8407 references are removed. For instance, an object that had been loaded with a dlopen( ) operation 8408 specifying the RTLD_GLOBAL flag might provide a target for dynamic relocations performed in 8409 the processing of other objects-in such environments, an application may assume that no 8410 relocation, once made, shall be undone or remade unless the object requiring the relocation has 8411 itself been removed. 8412 RETURN VALUE 8413 If the referenced object was successfully closed, dlclose( ) shall return 0. If the object could not be 8414 closed, or if handle does not refer to an open object, dlclose( ) shall return a non-zero value. More 8415 detailed diagnostic information shall be available through dlerror( ). 8416 ERRORS 8417 No errors are defined. 8418 EXAMPLES 8419 The following example illustrates use of dlopen( ) and dlclose( ): 8420 ... 8421 /* Open a dynamic library and then close it ... */ 8422 #include 8423 void *mylib; 8424 int eret; 8425 mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY); | 8426 ... | 8427 eret = dlclose(mylib); 8428 ... 8429 APPLICATION USAGE 8430 A conforming application should employ a handle returned from a dlopen( ) invocation only | 8431 within a given scope bracketed by the dlopen( ) and dlclose( ) operations. Implementations are 8432 free to use reference counting or other techniques such that multiple calls to dlopen( ) referencing 8433 the same object may return the same object for handle. Implementations are also free to reuse a 8434 handle. For these reasons, the value of a handle must be treated as an opaque object by the 8435 application, used only in calls to dlsym( ) and dlclose( ). 712 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dlclose( ) 8436 RATIONALE 8437 None. 8438 FUTURE DIRECTIONS 8439 None. 8440 SEE ALSO 8441 dlerror( ), dlopen( ), dlsym( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8442 CHANGE HISTORY 8443 First released in Issue 5. 8444 Issue 6 8445 The DESCRIPTION is updated to say that the referenced object is closed ``if this is the last 8446 reference to it''. System Interfaces, Issue 6 713 dlerror( ) System Interfaces 8447 NAME 8448 dlerror - get diagnostic information 8449 SYNOPSIS 8450 XSI #include 8451 char *dlerror(void); 8452 8453 DESCRIPTION 8454 The dlerror( ) function shall return a null-terminated character string (with no trailing ) 8455 that describes the last error that occurred during dynamic linking processing. If no dynamic 8456 linking errors have occurred since the last invocation of dlerror( ), dlerror( ) shall return NULL. 8457 Thus, invoking dlerror( ) a second time, immediately following a prior invocation, shall result in 8458 NULL being returned. 8459 The dlerror( ) function need not be reentrant. A function that is not required to be reentrant is not 8460 required to be thread-safe. 8461 RETURN VALUE 8462 If successful, dlerror( ) shall return a null-terminated character string; otherwise, NULL shall be 8463 returned. 8464 ERRORS 8465 No errors are defined. 8466 EXAMPLES 8467 The following example prints out the last dynamic linking error: 8468 ... 8469 #include 8470 char *errstr; 8471 errstr = dlerror(); 8472 if (errstr != NULL) 8473 printf ("A dynamic linking error occurred: (%s)\n", errstr); 8474 ... 8475 APPLICATION USAGE 8476 The messages returned by dlerror( ) may reside in a static buffer that is overwritten on each call 8477 to dlerror( ). Application code should not write to this buffer. Programs wishing to preserve an 8478 error message should make their own copies of that message. Depending on the application 8479 environment with respect to asynchronous execution events, such as signals or other 8480 asynchronous computation sharing the address space, conforming applications should use a | 8481 critical section to retrieve the error pointer and buffer. | 8482 RATIONALE 8483 None. 8484 FUTURE DIRECTIONS 8485 None. 8486 SEE ALSO 8487 dlclose( ), dlopen( ), dlsym( ), the Base Definitions volume of IEEE Std 1003.1-200x, 714 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dlerror( ) 8488 CHANGE HISTORY 8489 First released in Issue 5. 8490 Issue 6 8491 In the DESCRIPTION the note about reentrancy and thread-safety is added. System Interfaces, Issue 6 715 dlopen( ) System Interfaces 8492 NAME 8493 dlopen - gain access to an executable object file 8494 SYNOPSIS 8495 XSI #include 8496 void *dlopen(const char *file, int mode); 8497 8498 DESCRIPTION 8499 The dlopen( ) function shall make an executable object file specified by file available to the calling 8500 program. The class of files eligible for this operation and the manner of their construction are | 8501 implementation-defined, though typically such files are executable objects such as shared | 8502 libraries, relocatable files, or programs. Note that some implementations permit the construction | 8503 of dependencies between such objects that are embedded within files. In such cases, a dlopen( ) | 8504 operation shall load such dependencies in addition to the object referenced by file. 8505 Implementations may also impose specific constraints on the construction of programs that can 8506 employ dlopen( ) and its related services. 8507 A successful dlopen( ) shall return a handle which the caller may use on subsequent calls to 8508 dlsym( ) and dlclose( ). The value of this handle should not be interpreted in any way by the caller. 8509 The file argument is used to construct a pathname to the object file. If file contains a slash | 8510 character, the file argument is used as the pathname for the file. Otherwise, file is used in an | 8511 implementation-defined manner to yield a pathname. | 8512 If the value of file is 0, dlopen( ) shall provide a handle on a global symbol object. This object shall | 8513 provide access to the symbols from an ordered set of objects consisting of the original program | 8514 image file, together with any objects loaded at program start-up as specified by that process | 8515 image file (for example, shared libraries), and the set of objects loaded using a dlopen( ) operation | 8516 together with the RTLD_GLOBAL flag. As the latter set of objects can change during execution, 8517 the set identified by handle can also change dynamically. 8518 Only a single copy of an object file is brought into the address space, even if dlopen( ) is invoked 8519 multiple times in reference to the file, and even if different pathnames are used to reference the | 8520 file. | 8521 The mode parameter describes how dlopen( ) shall operate upon file with respect to the processing 8522 of relocations and the scope of visibility of the symbols provided within file. When an object is 8523 brought into the address space of a process, it may contain references to symbols whose 8524 addresses are not known until the object is loaded. These references shall be relocated before the 8525 symbols can be accessed. The mode parameter governs when these relocations take place and 8526 may have the following values: 8527 RTLD_LAZY Relocations shall be performed at an implementation-defined time, 8528 ranging from the time of the dlopen( ) call until the first reference to a 8529 given symbol occurs. Specifying RTLD_LAZY should improve 8530 performance on implementations supporting dynamic symbol binding as 8531 a process may not reference all of the functions in any given object. And, 8532 for systems supporting dynamic symbol resolution for normal process 8533 execution, this behavior mimics the normal handling of process 8534 execution. 8535 RTLD_NOW All necessary relocations shall be performed when the object is first 8536 loaded. This may waste some processing if relocations are performed for 8537 functions that are never referenced. This behavior may be useful for 8538 applications that need to know as soon as an object is loaded that all 716 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dlopen( ) 8539 symbols referenced during execution are available. 8540 Any object loaded by dlopen( ) that requires relocations against global symbols can reference the 8541 symbols in the original process image file, any objects loaded at program start-up, from the 8542 object itself as well as any other object included in the same dlopen( ) invocation, and any objects 8543 that were loaded in any dlopen( ) invocation and which specified the RTLD_GLOBAL flag. To 8544 determine the scope of visibility for the symbols loaded with a dlopen( ) invocation, the mode 8545 parameter should be a bitwise-inclusive OR with one of the following values: 8546 RTLD_GLOBAL The object's symbols shall be made available for the relocation processing 8547 of any other object. In addition, symbol lookup using dlopen(0, mode) and 8548 an associated dlsym( ) allows objects loaded with this mode to be searched. 8549 RTLD_LOCAL The object's symbols shall not be made available for the relocation 8550 processing of any other object. 8551 If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implementation-defined 8552 default behavior shall be applied. 8553 If a file is specified in multiple dlopen( ) invocations, mode is interpreted at each invocation. Note, 8554 however, that once RTLD_NOW has been specified all relocations shall have been completed 8555 rendering further RTLD_NOW operations redundant and any further RTLD_LAZY operations 8556 irrelevant. Similarly, note that once RTLD_GLOBAL has been specified the object shall maintain 8557 the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, 8558 as long as the object remains in the address space (see dlclose( )). 8559 Symbols introduced into a program through calls to dlopen( ) may be used in relocation 8560 activities. Symbols so introduced may duplicate symbols already defined by the program or 8561 previous dlopen( ) operations. To resolve the ambiguities such a situation might present, the 8562 resolution of a symbol reference to symbol definition is based on a symbol resolution order. Two 8563 such resolution orders are defined: load or dependency ordering. Load order establishes an 8564 ordering among symbol definitions, such that the definition first loaded (including definitions 8565 from the image file and any dependent objects loaded with it) has priority over objects added 8566 later (via dlopen( )). Load ordering is used in relocation processing. Dependency ordering uses a 8567 breadth-first order starting with a given object, then all of its dependencies, then any dependents 8568 of those, iterating until all dependencies are satisfied. With the exception of the global symbol 8569 object obtained via a dlopen( ) operation on a file of 0, dependency ordering is used by the 8570 dlsym( ) function. Load ordering is used in dlsym( ) operations upon the global symbol object. 8571 When an object is first made accessible via dlopen( ) it and its dependent objects are added in 8572 dependency order. Once all the objects are added, relocations are performed using load order. 8573 Note that if an object or its dependencies had been previously loaded, the load and dependency 8574 orders may yield different resolutions. 8575 The symbols introduced by dlopen( ) operations, and available through dlsym( ) are at a 8576 minimum those which are exported as symbols of global scope by the object. Typically such 8577 symbols shall be those that were specified in (for example) C source code as having extern 8578 linkage. The precise manner in which an implementation constructs the set of exported symbols 8579 for a dlopen( ) object is specified by that implementation. 8580 RETURN VALUE 8581 If file cannot be found, cannot be opened for reading, is not of an appropriate object format for 8582 processing by dlopen( ), or if an error occurs during the process of loading file or relocating its 8583 symbolic references, dlopen( ) shall return NULL. More detailed diagnostic information shall be 8584 available through dlerror( ). System Interfaces, Issue 6 717 dlopen( ) System Interfaces 8585 ERRORS 8586 No errors are defined. 8587 EXAMPLES 8588 None. 8589 APPLICATION USAGE 8590 None. 8591 RATIONALE 8592 None. 8593 FUTURE DIRECTIONS 8594 None. 8595 SEE ALSO 8596 dlclose( ), dlerror( ), dlsym( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8597 CHANGE HISTORY 8598 First released in Issue 5. 718 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dlsym( ) 8599 NAME 8600 dlsym - obtain the address of a symbol from a dlopen( ) object 8601 SYNOPSIS 8602 XSI #include 8603 void *dlsym(void *restrict handle, const char *restrict name); 8604 8605 DESCRIPTION 8606 The dlsym( ) function shall obtain the address of a symbol defined within an object made | 8607 accessible through a dlopen( ) call. The handle argument is the value returned from a call to | 8608 dlopen( ) (and which has not since been released via a call to dlclose( )), and name is the symbol's 8609 name as a character string. 8610 The dlsym( ) function shall search for the named symbol in all objects loaded automatically as a 8611 result of loading the object referenced by handle (see dlopen( )). Load ordering is used in dlsym( ) 8612 operations upon the global symbol object. The symbol resolution algorithm used shall be 8613 dependency order as described in dlopen( ). 8614 The RTLD_NEXT flag is reserved for future use. 8615 RETURN VALUE 8616 If handle does not refer to a valid object opened by dlopen( ), or if the named symbol cannot be 8617 found within any of the objects associated with handle, dlsym( ) shall return NULL. More 8618 detailed diagnostic information shall be available through dlerror( ). 8619 ERRORS 8620 No errors are defined. 8621 EXAMPLES 8622 The following example shows how dlopen( ) and dlsym( ) can be used to access either function or 8623 data objects. For simplicity, error checking has been omitted. 8624 void *handle; 8625 int *iptr, (*fptr)(int); 8626 /* open the needed object */ 8627 handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY); | 8628 /* find the address of function and data objects */ | 8629 fptr = (int (*)(int))dlsym(handle, "my_function"); 8630 iptr = (int *)dlsym(handle, "my_object"); 8631 /* invoke function, passing value of integer as a parameter */ 8632 (*fptr)(*iptr); 8633 APPLICATION USAGE 8634 Special purpose values for handle are reserved for future use. These values and their meanings 8635 are: 8636 RTLD_DEFAULT The symbol lookup happens in the normal global scope; that is, a search for a | 8637 symbol using this handle would find the same definition as a direct use of this | 8638 symbol in the program code. | 8639 RTLD_NEXT Specifies the next object after this one that defines name. This one refers to the 8640 object containing the invocation of dlsym( ). The next object is the one found 8641 upon the application of a load order symbol resolution algorithm (see 8642 dlopen( )). The next object is either one of global scope (because it was 8643 introduced as part of the original process image or because it was added with System Interfaces, Issue 6 719 dlsym( ) System Interfaces 8644 a dlopen( ) operation including the RTLD_GLOBAL flag), or is an object that 8645 was included in the same dlopen( ) operation that loaded this one. 8646 The RTLD_NEXT flag is useful to navigate an intentionally created hierarchy 8647 of multiply-defined symbols created through interposition. For example, if a 8648 program wished to create an implementation of malloc( ) that embedded some 8649 statistics gathering about memory allocations, such an implementation could 8650 use the real malloc( ) definition to perform the memory allocation-and itself 8651 only embed the necessary logic to implement the statistics gathering function. 8652 RATIONALE 8653 None. 8654 FUTURE DIRECTIONS 8655 None. 8656 SEE ALSO 8657 dlclose( ), dlerror( ), dlopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8658 CHANGE HISTORY 8659 First released in Issue 5. 8660 Issue 6 8661 The restrict keyword is added to the dlsym( ) prototype for alignment with the 8662 ISO/IEC 9899: 1999 standard. 720 Technical Standard (2001) (Draft April 16, 2001) System Interfaces drand48( ) 8663 NAME 8664 drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48, srand48 - generate 8665 uniformly distributed pseudo-random numbers 8666 SYNOPSIS 8667 XSI #include 8668 double drand48(void); 8669 double erand48(unsigned short xsubi[3]); 8670 long jrand48(unsigned short xsubi[3]); 8671 void lcong48(unsigned short param[7]); 8672 long lrand48(void); 8673 long mrand48(void); 8674 long nrand48(unsigned short xsubi[3]); 8675 unsigned short *seed48(unsigned short seed16v[3]); 8676 void srand48(long seedval); 8677 8678 DESCRIPTION 8679 This family of functions shall generate pseudo-random numbers using a linear congruential | 8680 algorithm and 48-bit integer arithmetic. 8681 The drand48( ) and erand48( ) functions shall return non-negative, double-precision, floating- 8682 point values, uniformly distributed over the interval [0.0,1.0). 8683 The lrand48( ) and nrand48( ) functions shall return non-negative, long integers, uniformly 8684 distributed over the interval [0,231). 8685 The mrand48( ) and jrand48( ) functions shall return signed long integers uniformly distributed 8686 over the interval [-231,231). 8687 The srand48( ), seed48( ), and lcong48( ) are initialization entry points, one of which should be 8688 invoked before either drand48( ), lrand48( ), or mrand48( ) is called. (Although it is not 8689 recommended practice, constant default initializer values shall be supplied automatically if 8690 drand48( ), lrand48( ), or mrand48( ) is called without a prior call to an initialization entry point.) 8691 The erand48( ), nrand48( ), and jrand48( ) functions do not require an initialization entry point to 8692 be called first. 8693 All the routines work by generating a sequence of 48-bit integer values, Xi, according to the 8694 linear congruential formula: 8695 Xn+1 = (aXn + c)mod m n 0 8696 The parameter m = 248; hence 48-bit integer arithmetic is performed. Unless lcong48( ) is invoked, 8697 the multiplier value a and the addend value c are given by: 8698 a = 5DEECE66D 16 = 273673163155 8 8699 c = B 16 = 13 8 8700 The value returned by any of the drand48( ), erand48( ), jrand48( ), lrand48( ), mrand48( ), or 8701 nrand48( ) functions is computed by first generating the next 48-bit Xi in the sequence. Then the 8702 appropriate number of bits, according to the type of data item to be returned, are copied from 8703 the high-order (leftmost) bits of Xi and transformed into the returned value. 8704 The drand48( ), lrand48( ), and mrand48( ) functions store the last 48-bit Xi generated in an 8705 internal buffer; that is why the application shall ensure that these are initialized prior to being 8706 invoked. The erand48( ), nrand48( ), and jrand48( ) functions require the calling program to 8707 provide storage for the successive Xi values in the array specified as an argument when the System Interfaces, Issue 6 721 drand48( ) System Interfaces 8708 functions are invoked. That is why these routines do not have to be initialized; the calling 8709 program merely has to place the desired initial value of Xi into the array and pass it as an 8710 argument. By using different arguments, erand48( ), nrand48( ), and jrand48( ) allow separate 8711 modules of a large program to generate several independent streams of pseudo-random numbers; 8712 that is, the sequence of numbers in each stream shall not depend upon how many times the 8713 routines are called to generate numbers for the other streams. 8714 The initializer function srand48( ) sets the high-order 32 bits of Xi to the low-order 32 bits 8715 contained in its argument. The low-order 16 bits of Xi are set to the arbitrary value 330E16. 8716 The initializer function seed48( ) sets the value of Xi to the 48-bit value specified in the argument 8717 array. The low-order 16 bits of Xi are set to the low-order 16 bits of seed16v[0]. The mid-order 16 8718 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 8719 low-order 16 bits of seed16v[2]. In addition, the previous value of Xi is copied into a 48-bit 8720 internal buffer, used only by seed48( ), and a pointer to this buffer is the value returned by 8721 seed48( ). This returned pointer, which can just be ignored if not needed, is useful if a program is 8722 to be restarted from a given point at some future time-use the pointer to get at and store the 8723 last Xi value, and then use this value to reinitialize via seed48( ) when the program is restarted. | 8724 The initializer function lcong48( ) allows the user to specify the initial Xi, the multiplier value a, 8725 and the addend value c. Argument array elements param[0-2] specify Xi, param[3-5] specify the 8726 multiplier a, and param[6] specifies the 16-bit addend c. After lcong48( ) is called, a subsequent 8727 call to either srand48( ) or seed48( ) shall restore the standard multiplier and addend values, a and 8728 c, specified above. 8729 The drand48( ), lrand48( ), and mrand48( ) functions need not be reentrant. A function that is not 8730 required to be reentrant is not required to be thread-safe. 8731 RETURN VALUE 8732 As described in the DESCRIPTION above. 8733 ERRORS 8734 No errors are defined. 8735 EXAMPLES 8736 None. 8737 APPLICATION USAGE 8738 None. 8739 RATIONALE 8740 None. 8741 FUTURE DIRECTIONS 8742 None. 8743 SEE ALSO 8744 rand( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8745 CHANGE HISTORY 8746 First released in Issue 1. Derived from Issue 1 of the SVID. 8747 Issue 5 8748 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8749 Issue 6 8750 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 722 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dup( ) 8751 NAME 8752 dup, dup2 - duplicate an open file descriptor 8753 SYNOPSIS 8754 #include 8755 int dup(int fildes); 8756 int dup2(int fildes, int fildes2); 8757 DESCRIPTION 8758 The dup( ) and dup2( ) functions provide an alternative interface to the service provided by 8759 fcntl( ) using the F_DUPFD command. The call: 8760 fid = dup(fildes); 8761 shall be equivalent to: | 8762 fid = fcntl(fildes, F_DUPFD, 0); 8763 The call: 8764 fid = dup2(fildes, fildes2); 8765 shall be equivalent to: | 8766 close(fildes2); 8767 fid = fcntl(fildes, F_DUPFD, fildes2); 8768 except for the following: 8769 * If fildes2 is less than 0 or greater than or equal to {OPEN_MAX}, dup2( ) shall return -1 with 8770 errno set to [EBADF]. 8771 * If fildes is a valid file descriptor and is equal to fildes2, dup2( ) shall return fildes2 without 8772 closing it. 8773 * If fildes is not a valid file descriptor, dup2( ) shall return -1 and shall not close fildes2. 8774 * The value returned shall be equal to the value of fildes2 upon successful completion, or -1 8775 upon failure. 8776 RETURN VALUE 8777 Upon successful completion a non-negative integer, namely the file descriptor, shall be returned; 8778 otherwise, -1 shall be returned and errno set to indicate the error. 8779 ERRORS 8780 The dup( ) function shall fail if: 8781 [EBADF] The fildes argument is not a valid open file descriptor. 8782 [EMFILE] The number of file descriptors in use by this process would exceed 8783 {OPEN_MAX}. 8784 The dup2( ) function shall fail if: 8785 [EBADF] The fildes argument is not a valid open file descriptor or the argument fildes2 is 8786 negative or greater than or equal to {OPEN_MAX}. 8787 [EINTR] The dup2( ) function was interrupted by a signal. System Interfaces, Issue 6 723 dup( ) System Interfaces 8788 EXAMPLES 8789 Redirecting Standard Output to a File 8790 The following example closes standard output for the current processes, re-assigns standard 8791 output to go to the file referenced by pfd, and closes the original file descriptor to clean up. 8792 #include 8793 ... 8794 int pfd; 8795 ... 8796 close(1); 8797 dup(pfd); 8798 close(pfd); 8799 ... 8800 Redirecting Error Messages 8801 The following example redirects messages from stderr to stdout. 8802 #include 8803 ... 8804 dup2(1, 2); 8805 ... 8806 APPLICATION USAGE 8807 None. 8808 RATIONALE 8809 The dup( ) and dup2( ) functions are redundant. Their services are also provided by the fcntl( ) 8810 function. They have been included in this volume of IEEE Std 1003.1-200x primarily for historical 8811 reasons, since many existing applications use them. 8812 While the brief code segment shown is very similar in behavior to dup2( ), a conforming 8813 implementation based on other functions defined in this volume of IEEE Std 1003.1-200x is 8814 significantly more complex. Least obvious is the possible effect of a signal-catching function that 8815 could be invoked between steps and allocate or deallocate file descriptors. This could be avoided 8816 by blocking signals. 8817 The dup2( ) function is not marked obsolescent because it presents a type-safe version of 8818 functionality provided in a type-unsafe version by fcntl( ). It is used in the POSIX Ada binding. 8819 The dup2( ) function is not intended for use in critical regions as a synchronization mechanism. 8820 In the description of [EBADF], the case of fildes being out of range is covered by the given case of 8821 fildes not being valid. The descriptions for fildes and fildes2 are different because the only kind of 8822 invalidity that is relevant for fildes2 is whether it is out of range; that is, it does not matter 8823 whether fildes2 refers to an open file when the dup2( ) call is made. 8824 FUTURE DIRECTIONS 8825 None. 8826 SEE ALSO 8827 close( ), fcntl( ), open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 724 Technical Standard (2001) (Draft April 16, 2001) System Interfaces dup( ) 8828 CHANGE HISTORY 8829 First released in Issue 1. Derived from Issue 1 of the SVID. 8830 Issue 6 8831 The RATIONALE section is added. System Interfaces, Issue 6 725 ecvt( ) System Interfaces 8832 NAME 8833 ecvt, fcvt, gcvt - convert a floating-point number to a string (LEGACY) 8834 SYNOPSIS 8835 XSI #include 8836 char *ecvt(double value, int ndigit, int *restrict decpt, 8837 int *restrict sign); 8838 char *fcvt(double value, int ndigit, int *restrict decpt, 8839 int *restrict sign); 8840 char *gcvt(double value, int ndigit, char *buf); 8841 8842 DESCRIPTION 8843 The ecvt( ), fcvt( ), and gcvt( ) functions shall convert floating-point numbers to null-terminated 8844 strings. 8845 The ecvt( ) function shall convert value to a null-terminated string of ndigit digits (where ndigit is 8846 reduced to an unspecified limit determined by the precision of a double) and return a pointer to | 8847 the string. The high-order digit shall be non-zero, unless the value is 0. The low-order digit shall | 8848 be rounded in an implementation-defined manner. The position of the radix character relative to | 8849 the beginning of the string shall be stored in the integer pointed to by decpt (negative means to | 8850 the left of the returned digits). If value is zero, it is unspecified whether the integer pointed to by 8851 decpt would be 0 or 1. The radix character shall not be included in the returned string. If the sign | 8852 of the result is negative, the integer pointed to by sign shall be non-zero; otherwise, it shall be 0. | 8853 If the converted value is out of range or is not representable, the contents of the returned string 8854 are unspecified. 8855 The fcvt( ) function shall be equivalent to ecvt( ), except that ndigit specifies the number of digits | 8856 desired after the radix character. The total number of digits in the result string is restricted to an 8857 unspecified limit as determined by the precision of a double. 8858 The gcvt( ) function shall convert value to a null-terminated string (similar to that of the %g 8859 conversion specification format of printf( )) in the array pointed to by buf and shall return buf. It | 8860 shall produce ndigit significant digits (limited to an unspecified value determined by the | 8861 precision of a double) in the %f conversion specification format of printf( ) if possible, or the %e 8862 conversion specification format of printf( ) (scientific notation) otherwise. A minus sign shall be | 8863 included in the returned string if value is less than 0. A radix character shall be included in the | 8864 returned string if value is not a whole number. Trailing zeros shall be suppressed where value is | 8865 not a whole number. The radix character is determined by the current locale. If setlocale( ) has not 8866 been called successfully, the default locale, POSIX, is used. The default locale specifies a period 8867 ('.') as the radix character. The LC_NUMERIC category determines the value of the radix 8868 character within the current locale. 8869 These functions need not be reentrant. A function that is not required to be reentrant is not 8870 required to be thread-safe. 8871 RETURN VALUE 8872 The ecvt( ) and fcvt( ) functions shall return a pointer to a null-terminated string of digits. 8873 The gcvt( ) function shall return buf. 8874 The return values from ecvt( ) and fcvt( ) may point to static data which may be overwritten by 8875 subsequent calls to these functions. 726 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ecvt( ) 8876 ERRORS 8877 No errors are defined. 8878 EXAMPLES 8879 None. 8880 APPLICATION USAGE 8881 sprintf( ) is preferred over this function. 8882 RATIONALE 8883 None. 8884 FUTURE DIRECTIONS 8885 These functions may be withdrawn in a future version. 8886 SEE ALSO 8887 printf( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8888 CHANGE HISTORY 8889 First released in Issue 4, Version 2. 8890 Issue 5 8891 Moved from X/OPEN UNIX extension to BASE. 8892 Normative text previously in the APPLICATION USAGE section is moved to the 8893 DESCRIPTION. 8894 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 8895 Issue 6 8896 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 8897 This function is marked LEGACY. 8898 The restrict keyword is added to the ecvt( ) and fcvt( ) prototypes for alignment with the 8899 ISO/IEC 9899: 1999 standard. 8900 The DESCRIPTION is updated to explicitly use ``conversion specification'' to describe %g, %f, 8901 and %e. System Interfaces, Issue 6 727 encrypt( ) System Interfaces 8902 NAME 8903 encrypt - encoding function (CRYPT) 8904 SYNOPSIS 8905 XSI #include 8906 void encrypt(char block[64], int edflag); 8907 8908 DESCRIPTION 8909 The encrypt( ) function shall provide access to an implementation-defined encoding algorithm. | 8910 The key generated by setkey( ) is used to encrypt the string block with encrypt( ). | 8911 The block argument to encrypt( ) shall be an array of length 64 bytes containing only the bytes | 8912 with values of 0 and 1. The array is modified in place to a similar array using the key set by | 8913 setkey( ). If edflag is 0, the argument is encoded. If edflag is 1, the argument may be decoded (see 8914 the APPLICATION USAGE section); if the argument is not decoded, errno shall be set to 8915 [ENOSYS]. 8916 The encrypt( ) function shall not change the setting of errno if successful. An application wishing 8917 to check for error situations should set errno to 0 before calling encrypt( ). If errno is non-zero on 8918 return, an error has occurred. 8919 The encrypt( ) function need not be reentrant. A function that is not required to be reentrant is 8920 not required to be thread-safe. 8921 RETURN VALUE 8922 The encrypt( ) function shall not return a value. 8923 ERRORS 8924 The encrypt( ) function shall fail if: 8925 [ENOSYS] The functionality is not supported on this implementation. 8926 EXAMPLES 8927 None. 8928 APPLICATION USAGE 8929 Historical implementations of the encrypt( ) function used a rather primitive encoding algorithm. | 8930 In some environments, decoding might not be implemented. This is related to some Government | 8931 restrictions on encryption and decryption routines. Historical practice has been to ship a | 8932 different version of the encryption library without the decryption feature in the routines | 8933 supplied. Thus the exported version of encrypt( ) does encoding but not decoding. 8934 RATIONALE 8935 None. 8936 FUTURE DIRECTIONS 8937 None. 8938 SEE ALSO 8939 crypt( ), setkey( ), the Base Definitions volume of IEEE Std 1003.1-200x, 8940 CHANGE HISTORY 8941 First released in Issue 1. Derived from Issue 1 of the SVID. 728 Technical Standard (2001) (Draft April 16, 2001) System Interfaces encrypt( ) 8942 Issue 5 8943 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 8944 Issue 6 8945 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. System Interfaces, Issue 6 729 endgrent( ) System Interfaces 8946 NAME 8947 endgrent, getgrent, setgrent - group database entry functions 8948 SYNOPSIS 8949 XSI #include 8950 void endgrent(void); 8951 struct group *getgrent(void); 8952 void setgrent(void); 8953 8954 DESCRIPTION 8955 The getgrent( ) function shall return a pointer to a structure containing the broken-out fields of an 8956 entry in the group database. When first called, getgrent( ) shall return a pointer to a group 8957 structure containing the first entry in the group database. Thereafter, it shall return a pointer to a 8958 group structure containing the next group structure in the group database, so successive calls 8959 may be used to search the entire database. 8960 An implementation that provides extended security controls may impose further 8961 implementation-defined restrictions on accessing the group database. In particular, the system 8962 may deny the existence of some or all of the group database entries associated with groups other 8963 than those groups associated with the caller and may omit users other than the caller from the 8964 list of members of groups in database entries that are returned. 8965 The setgrent( ) function shall rewind the group database to allow repeated searches. | 8966 The endgrent( ) function may be called to close the group database when processing is complete. 8967 These functions need not be reentrant. A function that is not required to be reentrant is not 8968 required to be thread-safe. 8969 RETURN VALUE 8970 When first called, getgrent( ) shall return a pointer to the first group structure in the group 8971 database. Upon subsequent calls it shall return the next group structure in the group database. 8972 The getgrent( ) function shall return a null pointer on end-of-file or an error and errno may be set 8973 to indicate the error. 8974 The return value may point to a static area which is overwritten by a subsequent call to 8975 getgrgid( ), getgrnam( ), or getgrent( ). 8976 ERRORS 8977 The getgrent( ) function may fail if: 8978 [EINTR] A signal was caught during the operation. 8979 [EIO] An I/O error has occurred. 8980 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 8981 [ENFILE] The maximum allowable number of files is currently open in the system. 730 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endgrent( ) 8982 EXAMPLES 8983 None. 8984 APPLICATION USAGE 8985 These functions are provided due to their historical usage. Applications should avoid 8986 dependencies on fields in the group database, whether the database is a single file, or where in 8987 the file system name space the database resides. Applications should use getgrnam( ) and 8988 getgrgid( ) whenever possible because it avoids these dependencies. 8989 RATIONALE 8990 None. 8991 FUTURE DIRECTIONS 8992 None. 8993 SEE ALSO 8994 getgrgid( ), getgrnam( ), getlogin( ), getpwent( ), the Base Definitions volume of 8995 IEEE Std 1003.1-200x, 8996 CHANGE HISTORY 8997 First released in Issue 4, Version 2. 8998 Issue 5 8999 Moved from X/OPEN UNIX extension to BASE. 9000 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 9001 VALUE section. 9002 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9003 Issue 6 9004 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. System Interfaces, Issue 6 731 endhostent( ) System Interfaces 9005 NAME 9006 endhostent, gethostent, sethostent - network host database functions 9007 SYNOPSIS 9008 #include 9009 void endhostent(void); 9010 struct hostent *gethostent(void); 9011 void sethostent(int stayopen); 9012 DESCRIPTION 9013 These functions shall retrieve information about hosts. This information is considered to be | 9014 stored in a database that can be accessed sequentially or randomly. The implementation of this | 9015 database is unspecified. | 9016 Note: In many cases it is implemented by the Domain Name System, as documented in RFC 1034, 9017 RFC 1035, and RFC 1886. 9018 The sethostent( ) function shall open a connection to the database and set the next entry for 9019 retrieval to the first entry in the database. If the stayopen argument is non-zero, the connection 9020 shall not be closed by a call to gethostent( ), gethostbyname( ), or gethostbyaddr( ), and the 9021 implementation may maintain an open file descriptor. 9022 The gethostent( ) function shall read the next entry in the database, opening and closing a 9023 connection to the database as necessary. 9024 Entries shall be returned in hostent structures. Refer to gethostbyaddr( ) for a definition of the | 9025 hostent structure. 9026 The endhostent( ) function shall close the connection to the database, releasing any open file 9027 descriptor. 9028 These functions need not be reentrant. A function that is not required to be reentrant is not 9029 required to be thread-safe. 9030 RETURN VALUE 9031 Upon successful completion, the gethostent( ) function shall return a pointer to a hostent 9032 structure if the requested entry was found, and a null pointer if the end of the database was 9033 reached or the requested entry was not found. 9034 ERRORS 9035 No errors are defined for endhostent( ), gethostent( ), and sethostent( ). 9036 EXAMPLES 9037 None. 9038 APPLICATION USAGE 9039 The gethostent( ) function may return pointers to static data, which may be overwritten by 9040 subsequent calls to any of these functions. 9041 RATIONALE 9042 None. 9043 FUTURE DIRECTIONS 9044 None. 9045 SEE ALSO 9046 endservent( ), gethostbyaddr( ), gethostbyname( ), the Base Definitions volume of 9047 IEEE Std 1003.1-200x, 732 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endhostent( ) 9048 CHANGE HISTORY 9049 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 733 endnetent( ) System Interfaces 9050 NAME 9051 endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent - network database functions 9052 SYNOPSIS 9053 #include 9054 void endnetent(void); 9055 struct netent *getnetbyaddr(uint32_t net, int type); 9056 struct netent *getnetbyname(const char *name); 9057 struct netent *getnetent(void); 9058 void setnetent(int stayopen); 9059 DESCRIPTION 9060 These functions shall retrieve information about networks. This information is considered to be | 9061 stored in a database that can be accessed sequentially or randomly. The implementation of this | 9062 database is unspecified. | 9063 The setnetent( ) function shall open and rewind the database. If the stayopen argument is non- 9064 zero, the connection to the net database shall not be closed after each call to getnetent( ) (either 9065 directly, or indirectly through one of the other getnet*( ) functions), and the implementation may 9066 maintain an open file descriptor to the database. 9067 The getnetent( ) function shall read the next entry of the database, opening and closing a 9068 connection to the database as necessary. 9069 The getnetbyaddr( ) function shall search the database from the beginning, and find the first entry 9070 for which the address family specified by type matches the n_addrtype member and the network 9071 number net matches the n_net member, opening and closing a connection to the database as 9072 necessary. The net argument shall be the network number in host byte order. 9073 The getnetbyname( ) function shall search the database from the beginning and find the first entry 9074 for which the network name specified by name matches the n_name member, opening and 9075 closing a connection to the database as necessary. 9076 The getnetbyaddr( ), getnetbyname( ), and getnetent( ), functions shall each return a pointer to a 9077 netent structure, the members of which shall contain the fields of an entry in the network 9078 database. 9079 The endnetent( ) function shall close the database, releasing any open file descriptor. 9080 These functions need not be reentrant. A function that is not required to be reentrant is not 9081 required to be thread-safe. 9082 RETURN VALUE 9083 Upon successful completion, getnetbyaddr( ), getnetbyname( ), and getnetent( ), shall return a 9084 pointer to a netent structure if the requested entry was found, and a null pointer if the end of the 9085 database was reached or the requested entry was not found. Otherwise, a null pointer shall be 9086 returned. 9087 ERRORS 9088 No errors are defined. 734 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endnetent( ) 9089 EXAMPLES 9090 None. 9091 APPLICATION USAGE 9092 The getnetbyaddr( ), getnetbyname( ), and getnetent( ), functions may return pointers to static data, 9093 which may be overwritten by subsequent calls to any of these functions. 9094 RATIONALE 9095 None. 9096 FUTURE DIRECTIONS 9097 None. 9098 SEE ALSO 9099 The Base Definitions volume of IEEE Std 1003.1-200x, 9100 CHANGE HISTORY 9101 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 735 endprotoent( ) System Interfaces 9102 NAME 9103 endprotoent, getprotobyname, getprotobynumber, getprotoent, setprotoent - network protocol 9104 database functions 9105 SYNOPSIS 9106 #include 9107 void endprotoent(void); 9108 struct protoent *getprotobyname(const char *name); 9109 struct protoent *getprotobynumber(int proto); 9110 struct protoent *getprotoent(void); 9111 void setprotoent(int stayopen); 9112 DESCRIPTION 9113 These functions shall retrieve information about protocols. This information is considered to be | 9114 stored in a database that can be accessed sequentially or randomly. The implementation of this | 9115 database is unspecified. | 9116 The setprotoent( ) function shall open a connection to the database, and set the next entry to the 9117 first entry. If the stayopen argument is non-zero, the connection to the network protocol database 9118 shall not be closed after each call to getprotoent( ) (either directly, or indirectly through one of the 9119 other getproto*( ) functions), and the implementation may maintain an open file descriptor for 9120 the database. 9121 The getprotobyname( ) function shall search the database from the beginning and find the first 9122 entry for which the protocol name specified by name matches the p_name member, opening and 9123 closing a connection to the database as necessary. 9124 The getprotobynumber( ) function shall search the database from the beginning and find the first 9125 entry for which the protocol number specified by proto matches the p_proto member, opening 9126 and closing a connection to the database as necessary. 9127 The getprotoent( ) function shall read the next entry of the database, opening and closing a 9128 connection to the database as necessary. 9129 The getprotobyname( ), getprotobynumber( ), and getprotoent( ), functions shall each return a pointer 9130 to a protoent structure, the members of which shall contain the fields of an entry in the network 9131 protocol database. 9132 The endprotoent( ) function shall close the connection to the database, releasing any open file 9133 descriptor. 9134 These functions need not be reentrant. A function that is not required to be reentrant is not 9135 required to be thread-safe. 9136 RETURN VALUE 9137 Upon successful completion, getprotobyname( ), getprotobynumber( ), and getprotoent( ) return a 9138 pointer to a protoent structure if the requested entry was found, and a null pointer if the end of 9139 the database was reached or the requested entry was not found. Otherwise, a null pointer is 9140 returned. 9141 ERRORS 9142 No errors are defined. 736 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endprotoent( ) 9143 EXAMPLES 9144 None. 9145 APPLICATION USAGE 9146 The getprotobyname( ), getprotobynumber( ), and getprotoent( ) functions may return pointers to 9147 static data, which may be overwritten by subsequent calls to any of these functions. 9148 RATIONALE 9149 None. 9150 FUTURE DIRECTIONS 9151 None. 9152 SEE ALSO 9153 The Base Definitions volume of IEEE Std 1003.1-200x, 9154 CHANGE HISTORY 9155 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 737 endpwent( ) System Interfaces 9156 NAME 9157 endpwent, getpwent, setpwent - user database functions 9158 SYNOPSIS 9159 XSI #include 9160 void endpwent(void); 9161 struct passwd *getpwent(void); 9162 void setpwent(void); 9163 9164 DESCRIPTION 9165 These functions shall retrieve information about users. | 9166 The getpwent( ) function shall return a pointer to a structure containing the broken-out fields of | 9167 an entry in the user database. Each entry in the user database contains a passwd structure. When 9168 first called, getpwent( ) shall return a pointer to a passwd structure containing the first entry in 9169 the user database. Thereafter, it shall return a pointer to a passwd structure containing the next 9170 entry in the user database. Successive calls can be used to search the entire user database. 9171 If an end-of-file or an error is encountered on reading, getpwent( ) shall return a null pointer. 9172 An implementation that provides extended security controls may impose further 9173 implementation-defined restrictions on accessing the user database. In particular, the system 9174 may deny the existence of some or all of the user database entries associated with users other 9175 than the caller. 9176 The setpwent( ) function effectively rewinds the user database to allow repeated searches. 9177 The endpwent( ) function may be called to close the user database when processing is complete. 9178 These functions need not be reentrant. A function that is not required to be reentrant is not 9179 required to be thread-safe. 9180 RETURN VALUE 9181 The getpwent( ) function shall return a null pointer on end-of-file or error. 9182 ERRORS 9183 The getpwent( ), setpwent( ), and endpwent( ) functions may fail if: 9184 [EIO] An I/O error has occurred. 9185 In addition, getpwent( ) and setpwent( ) may fail if: 9186 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 9187 [ENFILE] The maximum allowable number of files is currently open in the system. 9188 The return value may point to a static area which is overwritten by a subsequent call to 9189 getpwuid( ), getpwnam( ), or getpwent( ). | 738 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endpwent( ) 9190 EXAMPLES | 9191 Searching the User Database 9192 The following example uses the getpwent( ) function to get successive entries in the user 9193 database, returning a pointer to a passwd structure that contains information about each user. 9194 The call to endpwent( ) closes the user database and cleans up. 9195 #include 9196 ... 9197 struct passwd *p; 9198 ... 9199 while ((p = getpwent ()) != NULL) { 9200 ... 9201 } 9202 endpwent(); 9203 ... 9204 APPLICATION USAGE 9205 These functions are provided due to their historical usage. Applications should avoid 9206 dependencies on fields in the password database, whether the database is a single file, or where 9207 in the file system name space the database resides. Applications should use getpwuid( ) 9208 whenever possible because it avoids these dependencies. 9209 RATIONALE 9210 None. 9211 FUTURE DIRECTIONS 9212 None. 9213 SEE ALSO 9214 endgrent( ), getlogin( ), getpwnam( ), getpwuid( ), the Base Definitions volume of 9215 IEEE Std 1003.1-200x, 9216 CHANGE HISTORY 9217 First released in Issue 4, Version 2. 9218 Issue 5 9219 Moved from X/OPEN UNIX extension to BASE. 9220 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 9221 VALUE section. 9222 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9223 Issue 6 9224 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. System Interfaces, Issue 6 739 endservent( ) System Interfaces 9225 NAME 9226 endservent, getservbyname, getservbyport, getservent, setservent - network services database 9227 functions 9228 SYNOPSIS 9229 #include 9230 void endservent(void); 9231 struct servent *getservbyname(const char *name, const char *proto); 9232 struct servent *getservbyport(int port, const char *proto); 9233 struct servent *getservent(void); 9234 void setservent(int stayopen); 9235 DESCRIPTION 9236 These functions shall retrieve information about network services. This information is | 9237 considered to be stored in a database that can be accessed sequentially or randomly. The | 9238 implementation of this database is unspecified. | 9239 The setservent( ) function shall open a connection to the database, and set the next entry to the 9240 first entry. If the stayopen argument is non-zero, the net database shall not be closed after each 9241 call to the getservent( ) function (either directly, or indirectly through one of the other getserv*( ) 9242 functions), and the implementation may maintain an open file descriptor for the database. 9243 The getservent( ) function shall read the next entry of the database, opening and closing a 9244 connection to the database as necessary. 9245 The getservbyname( ) function shall search the database from the beginning and find the first 9246 entry for which the service name specified by name matches the s_name member and the protocol 9247 name specified by proto matches the s_proto member, opening and closing a connection to the 9248 database as necessary. If proto is a null pointer, any value of the s_proto member shall be 9249 matched. 9250 The getservbyport( ) function shall search the database from the beginning and find the first entry 9251 for which the port specified by port matches the s_port member and the protocol name specified 9252 by proto matches the s_proto member, opening and closing a connection to the database as 9253 necessary. If proto is a null pointer, any value of the s_proto member shall be matched. The port 9254 argument shall be in network byte order. 9255 The getservbyname( ), getservbyport( ), and getservent( ) functions shall each return a pointer to a 9256 servent structure, the members of which shall contain the fields of an entry in the network 9257 services database. 9258 The endservent( ) function shall close the database, releasing any open file descriptor. 9259 These functions need not be reentrant. A function that is not required to be reentrant is not 9260 required to be thread-safe. 9261 RETURN VALUE 9262 Upon successful completion, getservbyname( ), getservbyport( ), and getservent( ) return a pointer to 9263 a servent structure if the requested entry was found, and a null pointer if the end of the database 9264 was reached or the requested entry was not found. Otherwise, a null pointer is returned. 9265 ERRORS 9266 No errors are defined. 740 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endservent( ) 9267 EXAMPLES 9268 None. 9269 APPLICATION USAGE 9270 The port argument of getservbyport( ) need not be compatible with the port values of all address 9271 families. 9272 The getservbyname( ), getservbyport( ), and getservent( ) functions may return pointers to static 9273 data, which may be overwritten by subsequent calls to any of these functions. 9274 RATIONALE 9275 None. 9276 FUTURE DIRECTIONS 9277 None. 9278 SEE ALSO 9279 endhostent( ), endprotoent( ), htonl( ), inet_addr( ), the Base Definitions volume of 9280 IEEE Std 1003.1-200x, 9281 CHANGE HISTORY 9282 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 741 endutxent( ) System Interfaces 9283 NAME 9284 endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - user accounting database 9285 functions 9286 SYNOPSIS 9287 XSI #include 9288 void endutxent(void); 9289 struct utmpx *getutxent(void); 9290 struct utmpx *getutxid(const struct utmpx *id); 9291 struct utmpx *getutxline(const struct utmpx *line); 9292 struct utmpx *pututxline(const struct utmpx *utmpx); 9293 void setutxent(void); 9294 9295 DESCRIPTION 9296 These functions shall provide access to the user accounting database. | 9297 The getutxent( ) function shall read the next entry from the user accounting database. If the | 9298 database is not already open, it shall open it. If it reaches the end of the database, it shall fail. | 9299 The getutxid( ) function shall search forward from the current point in the database. If the | 9300 ut_type value of the utmpx structure pointed to by id is BOOT_TIME, OLD_TIME, or | 9301 NEW_TIME, then it shall stop when it finds an entry with a matching ut_type value. If the | 9302 ut_type value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, | 9303 then it shall stop when it finds an entry whose type is one of these four and whose ut_id member | 9304 matches the ut_id member of the utmpx structure pointed to by id. If the end of the database is 9305 reached without a match, getutxid( ) shall fail. | 9306 The getutxline( ) function shall search forward from the current point in the database until it | 9307 finds an entry of the type LOGIN_PROCESS or USER_PROCESS which also has a ut_line value | 9308 matching that in the utmpx structure pointed to by line. If the end of the database is reached 9309 without a match, getutxline( ) shall fail. | 9310 The getutxid( ) or getutxline( ) function may cache data. For this reason, to use getutxline( ) to | 9311 search for multiple occurrences, the application shall zero out the static data after each success, | 9312 or getutxline( ) may return a pointer to the same utmpx structure. | 9313 There is one exception to the rule about clearing the structure before further reads are done. The | 9314 implicit read done by pututxline( ) (if it finds that it is not already at the correct place in the user 9315 accounting database) shall not modify the static structure returned by getutxent( ), getutxid( ), or 9316 getutxline( ), if the application has modified this structure and passed the pointer back to | 9317 pututxline( ). 9318 For all entries that match a request, the ut_type member indicates the type of the entry. Other 9319 members of the entry shall contain meaningful data based on the value of the ut_type member as 9320 follows: 742 Technical Standard (2001) (Draft April 16, 2001) System Interfaces endutxent( ) 9321 _________________________________________________________________________ 9322 _ ut_type Member Other Members with Meaningful Data ________________________________________________________________________ 9323 EMPTY No others 9324 BOOT_TIME ut_tv 9325 OLD_TIME ut_tv 9326 NEW_TIME ut_tv 9327 USER_PROCESS ut_id, ut_user (login name of the user), ut_line, ut_pid, ut_tv 9328 INIT_PROCESS ut_id, ut_pid, ut_tv 9329 LOGIN_PROCESS ut_id, ut_user (implementation-defined name of the login 9330 process), ut_pid, ut_tv 9331 _ DEAD_PROCESS ut_id, ut_pid, ut_tv ________________________________________________________________________ 9332 An implementation that provides extended security controls may impose implementation- | 9333 defined restrictions on accessing the user accounting database. In particular, the system may | 9334 deny the existence of some or all of the user accounting database entries associated with users | 9335 other than the caller. | 9336 If the process has appropriate privileges, the pututxline( ) function shall write out the structure | 9337 into the user accounting database. It shall use getutxid( ) to search for a record that satisfies the | 9338 request. If this search succeeds, then the entry shall be replaced. Otherwise, a new entry shall be | 9339 made at the end of the user accounting database. | 9340 The endutxent( ) function shall close the user accounting database. | 9341 The setutxent( ) function shall reset the input to the beginning of the database. This should be | 9342 done before each search for a new entry if it is desired that the entire database be examined. 9343 These functions need not be reentrant. A function that is not required to be reentrant is not 9344 required to be thread-safe. 9345 RETURN VALUE 9346 Upon successful completion, getutxent( ), getutxid( ), and getutxline( ) shall return a pointer to a 9347 utmpx structure containing a copy of the requested entry in the user accounting database. 9348 Otherwise, a null pointer shall be returned. 9349 The return value may point to a static area which is overwritten by a subsequent call to 9350 getutxid( ) or getutxline( ). 9351 Upon successful completion, pututxline( ) shall return a pointer to a utmpx structure containing a 9352 copy of the entry added to the user accounting database. Otherwise, a null pointer shall be 9353 returned. 9354 The endutxent( ) and setutxent( ) functions shall not return a value. 9355 ERRORS 9356 No errors are defined for the endutxent( ), getutxent( ), getutxid( ), getutxline( ), and setutxent( ) 9357 functions. 9358 The pututxline( ) function may fail if: 9359 [EPERM] The process does not have appropriate privileges. System Interfaces, Issue 6 743 endutxent( ) System Interfaces 9360 EXAMPLES 9361 None. 9362 APPLICATION USAGE 9363 The sizes of the arrays in the structure can be found using the sizeof operator. 9364 RATIONALE 9365 None. 9366 FUTURE DIRECTIONS 9367 None. 9368 SEE ALSO 9369 The Base Definitions volume of IEEE Std 1003.1-200x, 9370 CHANGE HISTORY 9371 First released in Issue 4, Version 2. 9372 Issue 5 9373 Moved from X/OPEN UNIX extension to BASE. 9374 Normative text previously in the APPLICATION USAGE section is moved to the 9375 DESCRIPTION. 9376 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 9377 Issue 6 9378 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 744 Technical Standard (2001) (Draft April 16, 2001) System Interfaces environ 9379 NAME 9380 environ - array of character pointers to the environment strings 9381 SYNOPSIS 9382 extern char **environ; 9383 DESCRIPTION 9384 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables 9385 and exec. System Interfaces, Issue 6 745 erand48( ) System Interfaces 9386 NAME 9387 erand48 - generate uniformly distributed pseudo-random numbers 9388 SYNOPSIS 9389 XSI #include 9390 double erand48(unsigned short xsubi[3]); 9391 9392 DESCRIPTION 9393 Refer to drand48( ). 746 Technical Standard (2001) (Draft April 16, 2001) System Interfaces erf( ) 9394 NAME 9395 erf, erff, erfl - error functions 9396 SYNOPSIS 9397 #include 9398 double erf(double x); 9399 float erff(float x); 9400 long double erfl(long double x); 9401 DESCRIPTION 9402 CX The functionality described on this reference page is aligned with the ISO C standard. Any 9403 conflict between the requirements described here and the ISO C standard is unintentional. This 9404 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 9405 These functions shall compute the error function of their argument x, defined as: | x _2 ___ e-t2dt || 9406 0 9407 An application wishing to check for error situations should set errno to zero and call | 9408 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 9409 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 9410 zero, an error has occurred. 9411 RETURN VALUE 9412 Upon successful completion, these functions shall return the value of the error function. 9413 MX If x is NaN, a NaN shall be returned. 9414 If x is ±0, ±0 shall be returned. 9415 If x is ±Inf, ±1 shall be returned. 9416 If x is subnormal, a range error may occur, and 2 * x/sqrt( ) should be returned. 9417 ERRORS 9418 These functions may fail if: 9419 MX Range Error The result underflows. 9420 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 9421 then errno shall be set to [ERANGE]. If the integer expression | 9422 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 9423 floating-point exception shall be raised. | 9424 EXAMPLES 9425 None. 9426 APPLICATION USAGE 9427 Underflow occurs when |x| < DBL_MIN * (sqrt( )/2). 9428 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 9429 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 9430 RATIONALE 9431 None. System Interfaces, Issue 6 747 erf( ) System Interfaces 9432 FUTURE DIRECTIONS 9433 None. 9434 SEE ALSO 9435 erfc( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 9436 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 9437 CHANGE HISTORY 9438 First released in Issue 1. Derived from Issue 1 of the SVID. 9439 Issue 5 9440 The DESCRIPTION is updated to indicate how an application should check for an error. This 9441 text was previously published in the APPLICATION USAGE section. 9442 Issue 6 9443 The erf( ) function is no longer marked as an extension. 9444 The erfc( ) function is now split out onto its own reference page. 9445 The erff( ) and erfl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 9446 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 9447 revised to align with the ISO/IEC 9899: 1999 standard. 9448 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 9449 marked. 748 Technical Standard (2001) (Draft April 16, 2001) System Interfaces erfc( ) 9450 NAME 9451 erfc, erfcf, erfcl - complementary error functions 9452 SYNOPSIS 9453 #include 9454 double erfc(double x); 9455 float erfcf(float x); 9456 long double erfcl(long double x); 9457 DESCRIPTION 9458 CX The functionality described on this reference page is aligned with the ISO C standard. Any 9459 conflict between the requirements described here and the ISO C standard is unintentional. This 9460 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 9461 These functions shall compute the complementary error function 1.0 - erf(x). 9462 An application wishing to check for error situations should set errno to zero and call 9463 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 9464 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 9465 zero, an error has occurred. 9466 RETURN VALUE 9467 Upon successful completion, these functions shall return the value of the complementary error 9468 function. 9469 If the correct value would cause underflow and is not representable, a range error may occur 9470 MX and either 0.0 (if representable), oran implementation-defined value shall be returned. 9471 MX If x is NaN, a NaN shall be returned. 9472 If x is ±0, +1 shall be returned. 9473 If x is -Inf, +2 shall be returned. 9474 If x is +Inf, +0 shall be returned. 9475 If the correct value would cause underflow and is representable, a range error may occur and the 9476 correct value shall be returned. 9477 ERRORS 9478 These functions may fail if: 9479 Range Error The result underflows. 9480 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 9481 then errno shall be set to [ERANGE]. If the integer expression | 9482 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 9483 floating-point exception shall be raised. | 9484 EXAMPLES 9485 None. 9486 APPLICATION USAGE 9487 The erfc( ) function is provided because of the extreme loss of relative accuracy if erf(x) is called 9488 for large x and the result subtracted from 1.0. 9489 Note for IEEE Std 754-1985 double, 26.55 < x implies erfc(x) has underflowed. 9490 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 9491 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. System Interfaces, Issue 6 749 erfc( ) System Interfaces 9492 RATIONALE 9493 None. 9494 FUTURE DIRECTIONS 9495 None. 9496 SEE ALSO 9497 erf( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 9498 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 9499 CHANGE HISTORY 9500 First released in Issue 1. Derived from Issue 1 of the SVID. 9501 Issue 5 9502 The DESCRIPTION is updated to indicate how an application should check for an error. This 9503 text was previously published in the APPLICATION USAGE section. 9504 Issue 6 9505 The erfc( ) function is no longer marked as an extension. 9506 These functions are split out from the erf( ) reference page. 9507 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 9508 revised to align with the ISO/IEC 9899: 1999 standard. 9509 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 9510 marked. 750 Technical Standard (2001) (Draft April 16, 2001) System Interfaces erff( ) 9511 NAME 9512 erff, erfl - error functions 9513 SYNOPSIS 9514 #include 9515 float erff(float x); 9516 long double erfl(long double x); 9517 DESCRIPTION 9518 Refer to erf( ). System Interfaces, Issue 6 751 errno System Interfaces 9519 NAME 9520 errno - error return value 9521 SYNOPSIS 9522 #include 9523 DESCRIPTION 9524 The lvalue errno is used by many functions to return error values. | 9525 Many functions provide an error number in errno. It has type int and is defined in . | 9526 The value of errno shall be defined only after a call to a function for which it is explicitly stated to 9527 be set and until it is changed by the next function call or if the application assigns it a value. The | 9528 value of errno should only be examined when it is indicated to be valid by a function's return | 9529 value. Applications shall obtain the definition of errno by the inclusion of . No | 9530 function in this volume of IEEE Std 1003.1-200x shall set errno to 0. 9531 It is unspecified whether errno is a macro or an identifier declared with external linkage. If a 9532 macro definition is suppressed in order to access an actual object, or a program defines an 9533 identifier with the name errno, the behavior is undefined. 9534 The symbolic values stored in errno are documented in the ERRORS sections on all relevant 9535 pages. 9536 RETURN VALUE 9537 None. 9538 ERRORS 9539 None. 9540 EXAMPLES 9541 None. 9542 APPLICATION USAGE 9543 Previously both POSIX and X/Open documents were more restrictive than the ISO C standard 9544 in that they required errno to be defined as an external variable, whereas the ISO C standard 9545 required only that errno be defined as a modifiable lvalue with type int. | 9546 A program that uses errno for error checking should set it to 0 before a function call, then inspect 9547 it before a subsequent function call. 9548 RATIONALE 9549 None. 9550 FUTURE DIRECTIONS 9551 None. 9552 SEE ALSO 9553 Section 2.3, the Base Definitions volume of IEEE Std 1003.1-200x, 9554 CHANGE HISTORY 9555 First released in Issue 1. Derived from Issue 1 of the SVID. 9556 Issue 5 9557 The following sentence is deleted from the DESCRIPTION: ``The value of errno is 0 at program 9558 start-up, but is never set to 0 by any XSI function''. The DESCRIPTION also no longer states that 9559 conforming implementations may support the declaration: 9560 extern int errno; 752 Technical Standard (2001) (Draft April 16, 2001) System Interfaces errno 9561 Issue 6 9562 Obsolescent text regarding defining errno as: 9563 extern int errno 9564 is removed. 9565 Text regarding no function setting errno to zero to indicate an error is changed to no function 9566 shall set errno to zero. This is for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 753 exec System Interfaces 9567 NAME 9568 environ, execl, execv, execle, execve, execlp, execvp - execute a file 9569 SYNOPSIS 9570 #include 9571 extern char **environ; 9572 int execl(const char *path, const char *arg0, ... /*, (char *)0 */); 9573 int execv(const char *path, char *const argv[]); 9574 int execle(const char *path, const char *arg0, ... /*, 9575 (char *)0, char *const envp[]*/); 9576 int execve(const char *path, char *const argv[], char *const envp[]); 9577 int execlp(const char *file, const char *arg0, ... /*, (char *)0 */); 9578 int execvp(const char *file, char *const argv[]); 9579 DESCRIPTION 9580 The exec family of functions shall replace the current process image with a new process image. | 9581 The new image shall be constructed from a regular, executable file called the new process image | 9582 file. There shall be no return from a successful exec, because the calling process image is overlaid 9583 by the new process image. 9584 When a C-language program is executed as a result of this call, it shall be entered as a C- 9585 language function call as follows: 9586 int main (int argc, char *argv[]); 9587 where argc is the argument count and argv is an array of character pointers to the arguments 9588 themselves. In addition, the following variable: 9589 extern char **environ; 9590 is initialized as a pointer to an array of character pointers to the environment strings. The argv 9591 and environ arrays are each terminated by a null pointer. The null pointer terminating the argv 9592 array is not counted in argc. 9593 THR Conforming multi-threaded applications shall not use the environ variable to access or modify 9594 any environment variable while any other thread is concurrently modifying any environment 9595 variable. A call to any function dependent on any environment variable shall be considered a use 9596 of the environ variable to access that environment variable. 9597 The arguments specified by a program with one of the exec functions shall be passed on to the 9598 new process image in the corresponding main( ) arguments. 9599 The argument path points to a pathname that identifies the new process image file. | 9600 The argument file is used to construct a pathname that identifies the new process image file. If | 9601 the file argument contains a slash character, the file argument shall be used as the pathname for | 9602 this file. Otherwise, the path prefix for this file is obtained by a search of the directories passed | 9603 as the environment variable PATH (see the Base Definitions volume of IEEE Std 1003.1-200x, 9604 Chapter 8, Environment Variables). If this environment variable is not present, the results of the 9605 search are implementation-defined. 9606 If the process image file is not a valid executable object, and the system does not recognize it as 9607 something that cannot be executed (and thus returns [EINVAL]), execlp( ) and execvp( ) shall use 9608 the contents of that file as standard input to a command interpreter conforming to system( ). In 9609 this case, the command interpreter becomes the new process image. 9610 The arguments represented by arg0,. . . are pointers to null-terminated character strings. These 9611 strings shall constitute the argument list available to the new process image. The list is | 754 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exec 9612 terminated by a null pointer. The argument arg0 should point to a filename that is associated | 9613 with the process being started by one of the exec functions. 9614 The argument argv is an array of character pointers to null-terminated strings. The application 9615 shall ensure that the last member of this array is a null pointer. These strings shall constitute the | 9616 argument list available to the new process image. The value in argv[0] should point to a filename | 9617 that is associated with the process being started by one of the exec functions. 9618 The argument envp is an array of character pointers to null-terminated strings. These strings | 9619 shall constitute the environment for the new process image. The envp array is terminated by a | 9620 null pointer. 9621 For those forms not containing an envp pointer (execl( ), execv( ), execlp( ), and execvp( )), the | 9622 environment for the new process image shall be taken from the external variable environ in the | 9623 calling process. 9624 The number of bytes available for the new process' combined argument and environment lists is 9625 {ARG_MAX}. It is implementation-defined whether null terminators, pointers, and/or any 9626 alignment bytes are included in this total. 9627 File descriptors open in the calling process image shall remain open in the new process image, | 9628 except for those whose close-on-exec flag FD_CLOEXEC is set. For those file descriptors that | 9629 remain open, all attributes of the open file description remain unchanged. For any file descriptor 9630 that is closed for this reason, file locks are removed as a result of the close as described in close( ). 9631 Locks that are not removed by closing of file descriptors remain unchanged. 9632 Directory streams open in the calling process image shall be closed in the new process image. 9633 The state of the floating-point environment in the new process image shall be set to the default. | 9634 XSI The state of conversion descriptors and message catalog descriptors in the new process image is | 9635 undefined. For the new process image, the equivalent of: | 9636 setlocale(LC_ALL, "C") 9637 shall be executed at start-up. | 9638 Signals set to the default action (SIG_DFL) in the calling process image shall be set to the default 9639 action in the new process image. Except for SIGCHLD, signals set to be ignored (SIG_IGN) by | 9640 the calling process image shall be set to be ignored by the new process image. Signals set to be | 9641 caught by the calling process image shall be set to the default action in the new process image 9642 (see ). If the SIGCHLD signal is set to be ignored by the calling process image, it is | 9643 unspecified whether the SIGCHLD signal is set to be ignored or to the default action in the new | 9644 XSI process image. After a successful call to any of the exec functions, alternate signal stacks are not | 9645 preserved and the SA_ONSTACK flag shall be cleared for all signals. 9646 After a successful call to any of the exec functions, any functions previously registered by atexit( ) 9647 are no longer registered. 9648 XSI If the ST_NOSUID bit is set for the file system containing the new process image file, then the 9649 effective user ID, effective group ID, saved set-user-ID, and saved set-group-ID are unchanged 9650 in the new process image. Otherwise,if the set-user-ID mode bit of the new process image file is 9651 set, the effective user ID of the new process image shall be set to the user ID of the new process | 9652 image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the | 9653 effective group ID of the new process image shall be set to the group ID of the new process | 9654 image file. The real user ID, real group ID, and supplementary group IDs of the new process | 9655 image shall remain the same as those of the calling process image. The effective user ID and | 9656 effective group ID of the new process image shall be saved (as the saved set-user-ID and the | 9657 saved set-group-ID) for use by setuid( ). | System Interfaces, Issue 6 755 exec System Interfaces 9658 XSI Any shared memory segments attached to the calling process image shall not be attached to the 9659 new process image. 9660 SEM Any named semaphores open in the calling process shall be closed as if by appropriate calls to 9661 sem_close( ). 9662 TYM Any blocks of typed memory that were mapped in the calling process are unmapped, as if 9663 munmap( ) was implicitly called to unmap them. 9664 ML Memory locks established by the calling process via calls to mlockall( ) or mlock( ) shall be 9665 removed. If locked pages in the address space of the calling process are also mapped into the 9666 address spaces of other processes and are locked by those processes, the locks established by the 9667 other processes shall be unaffected by the call by this process to the exec function. If the exec 9668 function fails, the effect on memory locks is unspecified. 9669 MF|SHM Memory mappings created in the process are unmapped before the address space is rebuilt for 9670 the new process image. 9671 PS For the SCHED_FIFO and SCHED_RR scheduling policies, the policy and priority settings shall 9672 not be changed by a call to an exec function. For other scheduling policies, the policy and priority 9673 settings on exec are implementation-defined. 9674 TMR Per-process timers created by the calling process shall be deleted before replacing the current 9675 process image with the new process image. 9676 MSG All open message queue descriptors in the calling process shall be closed, as described in 9677 mq_close( ). 9678 AIO Any outstanding asynchronous I/O operations may be canceled. Those asynchronous I/O 9679 operations that are not canceled shall complete as if the exec function had not yet occurred, but 9680 any associated signal notifications shall be suppressed. It is unspecified whether the exec 9681 function itself blocks awaiting such I/O completion. In no event, however, shall the new process 9682 image created by the exec function be affected by the presence of outstanding asynchronous I/O 9683 operations at the time the exec function is called. Whether any I/O is canceled, and which I/O 9684 may be canceled upon exec, is implementation-defined. 9685 CPT The new process image shall inherit the CPU-time clock of the calling process image. This 9686 inheritance means that the process CPU-time clock of the process being execed shall not be 9687 reinitialized or altered as a result of the exec function other than to reflect the time spent by the 9688 process executing the exec function itself. 9689 TCT The initial value of the CPU-time clock of the initial thread of the new process image shall be set 9690 to zero. 9691 TRC If the calling process is being traced, the new process image shall continue to be traced into the | 9692 same trace stream as the original process image, but the new process image shall not inherit the | 9693 mapping of trace event names to trace event type identifiers that was defined by calls to the | 9694 posix_trace_eventid_open( ) or the posix_trace_trid_eventid_open( ) functions in the calling process 9695 image. 9696 If the calling process is a trace controller process, any trace streams that were created by the 9697 calling process shall be shut down as described in the posix_trace_shutdown( ) function. 9698 The new process shall inherit at least the following attributes from the calling process image: | 9699 XSI * Nice value (see nice( )) 9700 XSI * semadj values (see semop( )) 756 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exec 9701 * Process ID 9702 * Parent process ID 9703 * Process group ID 9704 * Session membership 9705 * Real user ID 9706 * Real group ID 9707 * Supplementary group IDs 9708 * Time left until an alarm clock signal (see alarm( )) 9709 * Current working directory 9710 * Root directory 9711 * File mode creation mask (see umask( )) 9712 XSI * File size limit (see ulimit( )) 9713 * Process signal mask (see sigprocmask( )) 9714 * Pending signal (see sigpending( )) 9715 * tms_utime, tms_stime, tms_cutime, and tms_cstime (see times( )) 9716 XSI * Resource limits 9717 XSI * Controlling terminal 9718 XSI * Interval timers 9719 All other process attributes defined in this volume of IEEE Std 1003.1-200x shall be the same in 9720 the new and old process images. The inheritance of process attributes not defined by this 9721 volume of IEEE Std 1003.1-200x is implementation-defined. 9722 A call to any exec function from a process with more than one thread shall result in all threads 9723 being terminated and the new executable image being loaded and executed. No destructor 9724 functions shall be called. 9725 Upon successful completion, the exec functions shall mark for update the st_atime field of the file. 9726 If an exec function failed but was able to locate the process image file, whether the st_atime field is 9727 marked for update is unspecified. Should the exec function succeed, the process image file shall 9728 be considered to have been opened with open( ). The corresponding close( ) shall be considered 9729 to occur at a time after this open, but before process termination or successful completion of a 9730 subsequent call to one of the exec functions, posix_spawn( ), or posix_spawnp( ). The argv[ ] and | 9731 envp[ ] arrays of pointers and the strings to which those arrays point shall not be modified by a 9732 call to one of the exec functions, except as a consequence of replacing the process image. 9733 XSI The saved resource limits in the new process image are set to be a copy of the process' 9734 corresponding hard and soft limits. 9735 RETURN VALUE 9736 If one of the exec functions returns to the calling process image, an error has occurred; the return 9737 value shall be -1, and errno shall be set to indicate the error. System Interfaces, Issue 6 757 exec System Interfaces 9738 ERRORS 9739 The exec functions shall fail if: 9740 [E2BIG] The number of bytes used by the new process image's argument list and 9741 environment list is greater than the system-imposed limit of {ARG_MAX} 9742 bytes. 9743 [EACCES] Search permission is denied for a directory listed in the new process image 9744 file's path prefix, or the new process image file denies execution permission, 9745 or the new process image file is not a regular file and the implementation does 9746 not support execution of files of its type. 9747 [EINVAL] The new process image file has the appropriate permission and has a 9748 recognized executable binary format, but the system does not support 9749 execution of a file with this format. 9750 [ELOOP] A loop exists in symbolic links encountered during resolution of the path or file 9751 argument. 9752 [ENAMETOOLONG] 9753 The length of the path or file arguments exceeds {PATH_MAX} or a pathname | 9754 component is longer than {NAME_MAX}. | 9755 [ENOENT] A component of path or file does not name an existing file or path or file is an 9756 empty string. 9757 [ENOTDIR] A component of the new process image file's path prefix is not a directory. 9758 The exec functions, except for execlp( ) and execvp( ), shall fail if: 9759 [ENOEXEC] The new process image file has the appropriate access permission but has an 9760 unrecognized format. 9761 The exec functions may fail if: 9762 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 9763 resolution of the path or file argument. 9764 [ENAMETOOLONG] 9765 As a result of encountering a symbolic link in resolution of the path argument, | 9766 the length of the substituted pathname string exceeded {PATH_MAX}. | 9767 [ENOMEM] The new process image requires more memory than is allowed by the 9768 hardware or system-imposed memory management constraints. 9769 [ETXTBSY] The new process image file is a pure procedure (shared text) file that is 9770 currently open for writing by some process. 9771 EXAMPLES 9772 Using execl( ) 9773 The following example executes the ls command, specifying the pathname of the executable | 9774 (/bin/ls) and using arguments supplied directly to the command to produce single-column 9775 output. 9776 #include 9777 int ret; 9778 ... 9779 ret = execl ("/bin/ls", "ls", "-1", (char *)0); 758 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exec 9780 Using execle( ) 9781 The following example is similar to Using execl( ) (on page 758). In addition, it specifies the 9782 environment for the new process image using the env argument. 9783 #include 9784 int ret; 9785 char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; 9786 ... 9787 ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); 9788 Using execlp( ) 9789 The following example searches for the location of the ls command among the directories 9790 specified by the PATH environment variable. 9791 #include 9792 int ret; 9793 ... 9794 ret = execlp ("ls", "ls", "-l", (char *)0); 9795 Using execv( ) 9796 The following example passes arguments to the ls command in the cmd array. 9797 #include 9798 int ret; 9799 char *cmd[] = { "ls", "-l", (char *)0 }; 9800 ... 9801 ret = execv ("/bin/ls", cmd); 9802 Using execve( ) 9803 The following example passes arguments to the ls command in the cmd array, and specifies the 9804 environment for the new process image using the env argument. 9805 #include 9806 int ret; 9807 char *cmd[] = { "ls", "-l", (char *)0 }; 9808 char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; 9809 ... 9810 ret = execve ("/bin/ls", cmd, env); 9811 Using execvp( ) 9812 The following example searches for the location of the ls command among the directories 9813 specified by the PATH environment variable, and passes arguments to the ls command in the 9814 cmd array. 9815 #include 9816 int ret; 9817 char *cmd[] = { "ls", "-l", (char *)0 }; 9818 ... System Interfaces, Issue 6 759 exec System Interfaces 9819 ret = execvp ("ls", cmd); 9820 APPLICATION USAGE 9821 As the state of conversion descriptors and message catalog descriptors in the new process image | 9822 is undefined, conforming applications should not rely on their use and should close them prior | 9823 to calling one of the exec functions. 9824 Applications that require other than the default POSIX locale should call setlocale( ) with the 9825 appropriate parameters to establish the locale of the new process. 9826 The environ array should not be accessed directly by the application. 9827 RATIONALE 9828 Early proposals required that the value of argc passed to main( ) be ``one or greater''. This was 9829 driven by the same requirement in drafts of the ISO C standard. In fact, historical 9830 implementations have passed a value of zero when no arguments are supplied to the caller of 9831 the exec functions. This requirement was removed from the ISO C standard and subsequently 9832 removed from this volume of IEEE Std 1003.1-200x as well. The wording, in particular the use of 9833 the word should, requires a Strictly Conforming POSIX Application to pass at least one argument 9834 to the exec function, thus guaranteeing that argc be one or greater when invoked by such an 9835 application. In fact, this is good practice, since many existing applications reference argv[0] 9836 without first checking the value of argc. 9837 The requirement on a Strictly Conforming POSIX Application also states that the value passed 9838 as the first argument be a filename associated with the process being started. Although some 9839 existing applications pass a pathname rather than a filename in some circumstances, a filename | 9840 is more generally useful, since the common usage of argv[0] is in printing diagnostics. In some 9841 cases the filename passed is not the actual filename of the file; for example, many 9842 implementations of the login utility use a convention of prefixing a hyphen ('-') to the actual 9843 filename, which indicates to the command interpreter being invoked that it is a ``login shell''. 9844 Some implementations can exec shell scripts. | 9845 One common historical implementation is that the execl( ), execv( ), execle( ), and execve( ) 9846 functions return an [ENOEXEC] error for any file not recognizable as executable, including a 9847 shell script. When the execlp( ) and execvp( ) functions encounter such a file, they assume the file 9848 to be a shell script and invoke a known command interpreter to interpret such files. These 9849 implementations of execvp( ) and execlp( ) only give the [ENOEXEC] error in the rare case of a 9850 problem with the command interpreter's executable file. Because of these implementations, the 9851 [ENOEXEC] error is not mentioned for execlp( ) or execvp( ), although implementations can still 9852 give it. 9853 Another way that some historical implementations handle shell scripts is by recognizing the first 9854 two bytes of the file as the character string "#!" and using the remainder of the first line of the 9855 file as the name of the command interpreter to execute. 9856 Some implementations provide a third argument to main( ) called envp. This is defined as a 9857 pointer to the environment. The ISO C standard specifies invoking main( ) with two arguments, 9858 so implementations must support applications written this way. Since this volume of 9859 IEEE Std 1003.1-200x defines the global variable environ, which is also provided by historical 9860 implementations and can be used anywhere that envp could be used, there is no functional need 9861 for the envp argument. Applications should use the getenv( ) function rather than accessing the 9862 environment directly via either envp or environ. Implementations are required to support the 9863 two-argument calling sequence, but this does not prohibit an implementation from supporting 9864 envp as an optional third argument. 760 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exec 9865 This volume of IEEE Std 1003.1-200x specifies that signals set to SIG_IGN remain set to 9866 SIG_IGN, and that the process signal mask be unchanged across an exec. This is consistent with 9867 historical implementations, and it permits some useful functionality, such as the nohup 9868 command. However, it should be noted that many existing applications wrongly assume that 9869 they start with certain signals set to the default action and/or unblocked. In particular, 9870 applications written with a simpler signal model that does not include blocking of signals, such 9871 as the one in the ISO C standard, may not behave properly if invoked with some signals blocked. 9872 Therefore, it is best not to block or ignore signals across execs without explicit reason to do so, 9873 and especially not to block signals across execs of arbitrary (not closely co-operating) programs. 9874 The exec functions always save the value of the effective user ID and effective group ID of the 9875 process at the completion of the exec, whether or not the set-user-ID or the set-group-ID bit of 9876 the process image file is set. 9877 The statement about argv[ ] and envp[ ] being constants is included to make explicit to future 9878 writers of language bindings that these objects are completely constant. Due to a limitation of 9879 the ISO C standard, it is not possible to state that idea in standard C. Specifying two levels of 9880 const-qualification for the argv[ ] and envp[ ] parameters for the exec functions may seem to be the 9881 natural choice, given that these functions do not modify either the array of pointers or the 9882 characters to which the function points, but this would disallow existing correct code. Instead, 9883 only the array of pointers is noted as constant. The table of assignment compatibility for dst=src, 9884 derived from the ISO C standard summarizes the compatibility: _______________________________________________________________________________ | 9885 _ dst: char *[ ] const char *[ ] char *const[ ] const char *const[ ] ______________________________________________________________________________ || 9886 src: | 9887 char *[ ] VALID - VALID - | 9888 const char *[ ] - VALID - VALID | 9889 char * const [ ] - - VALID - | 9890 _ const char *const[ ] - - - VALID ______________________________________________________________________________ |||||||| 9891 Since all existing code has a source type matching the first row, the column that gives the most 9892 valid combinations is the third column. The only other possibility is the fourth column, but 9893 using it would require a cast on the argv or envp arguments. It is unfortunate that the fourth 9894 column cannot be used, because the declaration a non-expert would naturally use would be that 9895 in the second row. 9896 The ISO C standard and this volume of IEEE Std 1003.1-200x do not conflict on the use of 9897 environ, but some historical implementations of environ may cause a conflict. As long as environ 9898 is treated in the same way as an entry point (for example, fork( )), it conforms to both standards. 9899 A library can contain fork( ), but if there is a user-provided fork( ), that fork( ) is given precedence 9900 and no problem ensues. The situation is similar for environ: the definition in this volume of 9901 IEEE Std 1003.1-200x is to be used if there is no user-provided environ to take precedence. At 9902 least three implementations are known to exist that solve this problem. 9903 [E2BIG] The limit {ARG_MAX} applies not just to the size of the argument list, but to 9904 the sum of that and the size of the environment list. 9905 [EFAULT] Some historical systems return [EFAULT] rather than [ENOEXEC] when the 9906 new process image file is corrupted. They are non-conforming. 9907 [EINVAL] This error condition was added to IEEE Std 1003.1-200x to allow an 9908 implementation to detect executable files generated for different architectures, 9909 and indicate this situation to the application. Historical implementations of 9910 shells, execvp( ), and execlp( ) that encounter an [ENOEXEC] error will execute 9911 a shell on the assumption that the file is a shell script. This will not produce 9912 the desired effect when the file is a valid executable for a different System Interfaces, Issue 6 761 exec System Interfaces 9913 architecture. An implementation may now choose to avoid this problem by 9914 returning [EINVAL] when a valid executable for a different architecture is 9915 encountered. Some historical implementations return [EINVAL] to indicate 9916 that the path argument contains a character with the high order bit set. The 9917 standard developers chose to deviate from historical practice for the following 9918 reasons: 9919 1. The new utilization of [EINVAL] will provide some measure of utility to 9920 the user community. 9921 2. Historical use of [EINVAL] is not acceptable in an internationalized 9922 operating environment. 9923 [ENAMETOOLONG] 9924 Since the file pathname may be constructed by taking elements in the PATH | 9925 variable and putting them together with the filename, the 9926 [ENAMETOOLONG] error condition could also be reached this way. 9927 [ETXTBSY] System V returns this error when the executable file is currently open for 9928 writing by some process. This volume of IEEE Std 1003.1-200x neither requires 9929 nor prohibits this behavior. 9930 Other systems (such as System V) may return [EINTR] from exec. This is not addressed by this 9931 volume of IEEE Std 1003.1-200x, but implementations may have a window between the call to 9932 exec and the time that a signal could cause one of the exec calls to return with [EINTR]. | 9933 An explicit statement regarding the floating-point environment (as defined in the | 9934 header) was added to make it clear that the floating-point environment is set to its default when | 9935 a call to one of the exec functions succeeds. The requirements for inheritance or setting to the | 9936 default for other process and thread start-up functions is covered by more generic statements in | 9937 their descriptions and can be summarized as follows: | ________________________________ || 9938 posix_spawn( ) Set to default. || 9939 fork( ) Inherit. || 9940 _ pthread_create( ) Inherit. _______________________________ |||||||||| 9941 FUTURE DIRECTIONS | 9942 None. 9943 SEE ALSO 9944 alarm( ), atexit( ), chmod( ), close( ), exit( ), fcntl( ), fork( ), fstatvfs( ), getenv( ), getitimer( ), getrlimit( ), 9945 mmap( ), nice( ), posix_spawn( ), posix_trace_eventid_open( ), posix_trace_shutdown( ), | 9946 posix_trace_trid_eventid_open( ), putenv( ), semop( ), setlocale( ), shmat( ), sigaction( ), sigaltstack( ), 9947 sigpending( ), sigprocmask( ), system( ), times( ), ulimit( ), umask( ), the Base Definitions volume of 9948 IEEE Std 1003.1-200x, , the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 9949 11, General Terminal Interface 9950 CHANGE HISTORY 9951 First released in Issue 1. Derived from Issue 1 of the SVID. 9952 Issue 5 9953 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 9954 Threads Extension. 9955 Large File Summit extensions are added. 762 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exec 9956 Issue 6 9957 The following new requirements on POSIX implementations derive from alignment with the | 9958 Single UNIX Specification: 9959 * In the DESCRIPTION, behavior is defined for when the process image file is not a valid 9960 executable. 9961 * In this issue, _POSIX_SAVED_IDS is mandated, thus the effective user ID and effective group 9962 ID of the new process image shall be saved (as the saved set-user-ID and the saved set- 9963 group-ID) for use by the setuid( ) function. 9964 * The [ELOOP] mandatory error condition is added. 9965 * A second [ENAMETOOLONG] is added as an optional error condition. 9966 * The [ETXTBSY] optional error condition is added. 9967 The following changes were made to align with the IEEE P1003.1a draft standard: 9968 * The [EINVAL] mandatory error condition is added. 9969 * The [ELOOP] optional error condition is added. 9970 The description of CPU-time clock semantics is added for alignment with IEEE Std 1003.1d-1999. 9971 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding semantics for 9972 typed memory. 9973 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 9974 The description of tracing semantics is added for alignment with IEEE Std 1003.1q-2000. | 9975 IEEE PASC Interpretation 1003.1 #132 is applied. | 9976 The DESCRIPTION is updated to make it explicit that the floating-point environment in the new | 9977 process image is set to the default. | System Interfaces, Issue 6 763 exit( ) System Interfaces 9978 NAME 9979 exit, _Exit, _exit - terminate a process 9980 SYNOPSIS 9981 #include 9982 void exit(int status); 9983 void _Exit(int status); 9984 #include 9985 void _exit(int status); 9986 DESCRIPTION 9987 CX The functionality described on this reference page for the exit( ) and _Exit( ) functions is aligned 9988 with the ISO C standard. Any conflict between the requirements described here and the ISO C 9989 standard are unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 9990 CX The value of status may be 0, EXIT_SUCCESS, EXIT_FAILURE, or any other value, though only | 9991 the least significant 8 bits (that is, status & 0377) shall be available to a waiting parent process. | 9992 The exit( ) function shall first call all functions registered by atexit( ), in the reverse order of their 9993 registration, except that a function is called after any previously registered functions that had 9994 already been called at the time it was registered. Each function is called as many times as it was 9995 registered. If, during the call to any such function, a call to the longjmp( ) function is made that 9996 would terminate the call to the registered function, the behavior is undefined. 9997 If a function registered by a call to atexit( ) fails to return, the remaining registered functions shall 9998 not be called and the rest of the exit( ) processing shall not be completed. If exit( ) is called more 9999 than once, the behavior is undefined. 10000 The exit( ) function shall then flush all open streams with unwritten buffered data, close all open | 10001 streams, and remove all files created by tmpfile( ). Finally, control shall be terminated with the | 10002 consequences described below. | 10003 CX The _Exit( ) and _exit( ) functions shall be functionally equivalent. | 10004 CX The _Exit( ) and _exit( ) functions shall not call functions registered with atexit( ) nor any | 10005 registered signal handlers. Whether open streams are flushed or closed, or temporary files are | 10006 removed is implementation-defined. Finally, the calling process is terminated with the | 10007 consequences described below. | 10008 CX These functions shall terminate the calling process with the following consequences: | 10009 Note: These consequences are all extensions to the ISO C standard and are not further CX shaded. | 10010 However, XSI extensions are shaded. | 10011 XSI * All of the file descriptors, directory streams, conversion descriptors, and message catalog | 10012 descriptors open in the calling process shall be closed. | 10013 XSI * If the parent process of the calling process is executing a wait( ) or waitpid ( ), and has neither | 10014 set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, it shall be notified of the calling | 10015 process' termination and the low-order eight bits (that is, bits 0377) of status are made | 10016 available to it. If the parent is not waiting, the child's status shall be made available to it 10017 when the parent subsequently executes wait( ) or waitpid( ). | 10018 XSI The semantics of the waitid( ) function shall be equivalent to wait( ). | 10019 XSI * If the parent process of the calling process is not executing a wait( ) or waitpid ( ), and has | 10020 neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, the calling process shall | 10021 be transformed into a zombie process. A zombie process is an inactive process and it shall be | 764 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exit( ) 10022 deleted at some later time when its parent process executes wait( ) or waitpid( ). | 10023 XSI The semantics of the waitid( ) function shall be equivalent to wait( ). | 10024 * Termination of a process does not directly terminate its children. The sending of a SIGHUP 10025 signal as described below indirectly terminates children in some circumstances. 10026 * Either: | 10027 If the implementation supports the SIGCHLD signal, a SIGCHLD shall be sent to the parent | 10028 process. | 10029 Or: | 10030 XSI If the parent process has set its SA_NOCLDWAIT flag, or set SIGCHLD to SIG_IGN, the | 10031 status shall be discarded, and the lifetime of the calling process shall end immediately. If 10032 SA_NOCLDWAIT is set, it is implementation-defined whether a SIGCHLD signal is sent to | 10033 the parent process. | 10034 * The parent process ID of all of the calling process' existing child processes and zombie 10035 processes shall be set to the process ID of an implementation-defined system process. That is, | 10036 these processes shall be inherited by a special system process. | 10037 XSI * Each attached shared-memory segment is detached and the value of shm_nattch (see 10038 shmget( )) in the data structure associated with its shared memory ID shall be decremented by | 10039 1. | 10040 XSI * For each semaphore for which the calling process has set a semadj value (see semop( )), that | 10041 value shall be added to the semval of the specified semaphore. | 10042 * If the process is a controlling process, the SIGHUP signal shall be sent to each process in the 10043 foreground process group of the controlling terminal belonging to the calling process. 10044 * If the process is a controlling process, the controlling terminal associated with the session | 10045 shall be disassociated from the session, allowing it to be acquired by a new controlling | 10046 process. | 10047 * If the exit of the process causes a process group to become orphaned, and if any member of 10048 the newly-orphaned process group is stopped, then a SIGHUP signal followed by a 10049 SIGCONT signal shall be sent to each process in the newly-orphaned process group. 10050 SEM * All open named semaphores in the calling process shall be closed as if by appropriate calls to 10051 sem_close( ). 10052 ML * Any memory locks established by the process via calls to mlockall ( ) or mlock( ) shall be 10053 removed. If locked pages in the address space of the calling process are also mapped into the 10054 address spaces of other processes and are locked by those processes, the locks established by 10055 the other processes shall be unaffected by the call by this process to _Exit( ) or _exit( ). 10056 MF|SHM * Memory mappings created in the process shall be unmapped before the process is destroyed. | 10057 10058 TYM * Any blocks of typed memory that were mapped in the calling process shall be unmapped, as | 10059 if munmap( ) was implicitly called to unmap them. | 10060 MSG * All open message queue descriptors in the calling process shall be closed as if by appropriate 10061 calls to mq_close( ). 10062 AIO * Any outstanding cancelable asynchronous I/O operations may be canceled. Those 10063 asynchronous I/O operations that are not canceled shall complete as if the _Exit( ) or _exit( ) 10064 operation had not yet occurred, but any associated signal notifications shall be suppressed. System Interfaces, Issue 6 765 exit( ) System Interfaces 10065 The _Exit( ) or _exit( ) operation may block awaiting such I/O completion. Whether any I/O 10066 is canceled, and which I/O may be canceled upon _Exit( ) or _exit( ), is implementation- 10067 defined. 10068 * Threads terminated by a call to _Exit( ) or _exit( ) shall not invoke their cancelation cleanup 10069 handlers or per-thread data destructors. 10070 TRC * If the calling process is a trace controller process, any trace streams that were created by the 10071 calling process shall be shut down as described by the posix_trace_shutdown( ) function, and 10072 any process' mapping of trace event names to trace event type identifiers built for these trace 10073 streams may be deallocated. 10074 RETURN VALUE 10075 These functions do not return. 10076 ERRORS 10077 No errors are defined. 10078 EXAMPLES 10079 None. 10080 APPLICATION USAGE 10081 Normally applications should use exit( ) rather than _Exit( ) or _exit( ). 10082 RATIONALE 10083 Process Termination 10084 Early proposals drew a distinction between normal and abnormal process termination. 10085 Abnormal termination was caused only by certain signals and resulted in implementation- 10086 defined ``actions'', as discussed below. Subsequent proposals distinguished three types of 10087 termination: normal termination (as in the current specification), simple abnormal termination, and 10088 abnormal termination with actions. Again the distinction between the two types of abnormal 10089 termination was that they were caused by different signals and that implementation-defined 10090 actions would result in the latter case. Given that these actions were completely 10091 implementation-defined, the early proposals were only saying when the actions could occur and 10092 how their occurrence could be detected, but not what they were. This was of little or no use to | 10093 conforming applications, and thus the distinction is not made in this volume of | 10094 IEEE Std 1003.1-200x. 10095 The implementation-defined actions usually include, in most historical implementations, the 10096 creation of a file named core in the current working directory of the process. This file contains an 10097 image of the memory of the process, together with descriptive information about the process, 10098 perhaps sufficient to reconstruct the state of the process at the receipt of the signal. 10099 There is a potential security problem in creating a core file if the process was set-user-ID and the 10100 current user is not the owner of the program, if the process was set-group-ID and none of the 10101 user's groups match the group of the program, or if the user does not have permission to write in 10102 the current directory. In this situation, an implementation either should not create a core file or 10103 should make it unreadable by the user. 10104 Despite the silence of this volume of IEEE Std 1003.1-200x on this feature, applications are 10105 advised not to create files named core because of potential conflicts in many implementations. 10106 Some historical implementations use a different name than core for the file, such as by 10107 appending the process ID to the filename. 766 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exit( ) 10108 Terminating a Process 10109 It is important that the consequences of process termination as described occur regardless of 10110 whether the process called _exit( ) (perhaps indirectly through exit( )) or instead was terminated 10111 due to a signal or for some other reason. Note that in the specific case of exit( ) this means that 10112 the status argument to exit( ) is treated in the same way as the status argument to _exit( ). | 10113 A language other than C may have other termination primitives than the C-language exit( ) 10114 function, and programs written in such a language should use its native termination primitives, 10115 but those should have as part of their function the behavior of _exit( ) as described. 10116 Implementations in languages other than C are outside the scope of the present version of this 10117 volume of IEEE Std 1003.1-200x, however. 10118 As required by the ISO C standard, using return from main( ) has the same behavior (other than 10119 with respect to language scope issues) as calling exit( ) with the returned value. Reaching the end 10120 of the main( ) function has the same behavior as calling exit(0). 10121 A value of zero (or EXIT_SUCCESS, which is required to be zero) for the argument status 10122 conventionally indicates successful termination. This corresponds to the specification for exit( ) 10123 in the ISO C standard. The convention is followed by utilities such as make and various shells, 10124 which interpret a zero status from a child process as success. For this reason, applications should 10125 not call exit(0) or _exit(0) when they terminate unsuccessfully; for example, in signal-catching 10126 functions. 10127 Historically, the implementation-defined process that inherits children whose parents have 10128 terminated without waiting on them is called init and has a process ID of 1. 10129 The sending of a SIGHUP to the foreground process group when a controlling process 10130 terminates corresponds to somewhat different historical implementations. In System V, the 10131 kernel sends a SIGHUP on termination of (essentially) a controlling process. In 4.2 BSD, the 10132 kernel does not send SIGHUP in a case like this, but the termination of a controlling process is 10133 usually noticed by a system daemon, which arranges to send a SIGHUP to the foreground 10134 process group with the vhangup( ) function. However, in 4.2 BSD, due to the behavior of the 10135 shells that support job control, the controlling process is usually a shell with no other processes 10136 in its process group. Thus, a change to make _exit( ) behave this way in such systems should not 10137 cause problems with existing applications. 10138 The termination of a process may cause a process group to become orphaned in either of two 10139 ways. The connection of a process group to its parent(s) outside of the group depends on both 10140 the parents and their children. Thus, a process group may be orphaned by the termination of the 10141 last connecting parent process outside of the group or by the termination of the last direct 10142 descendant of the parent process(es). In either case, if the termination of a process causes a 10143 process group to become orphaned, processes within the group are disconnected from their job 10144 control shell, which no longer has any information on the existence of the process group. 10145 Stopped processes within the group would languish forever. In order to avoid this problem, 10146 newly orphaned process groups that contain stopped processes are sent a SIGHUP signal and a 10147 SIGCONT signal to indicate that they have been disconnected from their session. The SIGHUP 10148 signal causes the process group members to terminate unless they are catching or ignoring 10149 SIGHUP. Under most circumstances, all of the members of the process group are stopped if any 10150 of them are stopped. 10151 The action of sending a SIGHUP and a SIGCONT signal to members of a newly orphaned 10152 process group is similar to the action of 4.2 BSD, which sends SIGHUP and SIGCONT to each 10153 stopped child of an exiting process. If such children exit in response to the SIGHUP, any 10154 additional descendants receive similar treatment at that time. In this volume of 10155 IEEE Std 1003.1-200x, the signals are sent to the entire process group at the same time. Also, in System Interfaces, Issue 6 767 exit( ) System Interfaces 10156 this volume of IEEE Std 1003.1-200x, but not in 4.2 BSD, stopped processes may be orphaned, 10157 but may be members of a process group that is not orphaned; therefore, the action taken at 10158 _exit( ) must consider processes other than child processes. 10159 It is possible for a process group to be orphaned by a call to setpgid( ) or setsid( ), as well as by 10160 process termination. This volume of IEEE Std 1003.1-200x does not require sending SIGHUP and 10161 SIGCONT in those cases, because, unlike process termination, those cases are not caused 10162 accidentally by applications that are unaware of job control. An implementation can choose to 10163 send SIGHUP and SIGCONT in those cases as an extension; such an extension must be 10164 documented as required in . 10165 The ISO/IEC 9899: 1999 standard adds the _Exit( ) function that results in immediate program 10166 termination without triggering signals or atexit( )-registered functions. In IEEE Std 1003.1-200x, 10167 this is equivalent to the _exit( ) function. 10168 FUTURE DIRECTIONS 10169 None. 10170 SEE ALSO 10171 atexit( ), close( ), fclose( ), longjmp( ), posix_trace_shutdown( ), posix_trace_trid_eventid_open( ), 10172 semop( ), shmget( ), sigaction( ), wait( ), waitid( ), waitpid( ), the Base Definitions volume of 10173 IEEE Std 1003.1-200x, , 10174 CHANGE HISTORY 10175 First released in Issue 1. Derived from Issue 1 of the SVID. 10176 Issue 5 10177 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 10178 Threads Extension. 10179 Interactions with the SA_NOCLDWAIT flag and SIGCHLD signal are further clarified. 10180 The values of status from exit( ) are better described. 10181 Issue 6 10182 Extensions beyond the ISO C standard are now marked. 10183 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding semantics for 10184 typed memory. 10185 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 10186 * The _Exit( ) function is included. 10187 * The DESCRIPTION is updated. 10188 The description of tracing semantics is added for alignment with IEEE Std 1003.1q-2000. 10189 References to the wait3( ) function are removed. 768 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exp( ) 10190 NAME 10191 exp, expf, expl - exponential function 10192 SYNOPSIS 10193 #include 10194 double exp(double x); 10195 float expf(float x); 10196 long double expl(long double x); 10197 DESCRIPTION 10198 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10199 conflict between the requirements described here and the ISO C standard is unintentional. This 10200 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 10201 These functions shall compute the base-e exponential of x. 10202 An application wishing to check for error situations should set errno to zero and call 10203 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 10204 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 10205 zero, an error has occurred. 10206 RETURN VALUE 10207 Upon successful completion, these functions shall return the exponential value of x. 10208 If the correct value would cause overflow, a range error shall occur and exp( ), expf( ), and expl( ) 10209 shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 10210 If the correct value would cause underflow, and is not representable, a range error may occur, 10211 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 10212 MX If x is NaN, a NaN shall be returned. 10213 If x is ±0, 1 shall be returned. 10214 If x is -Inf, +0 shall be returned. 10215 If x is +Inf, x shall be returned. 10216 If the correct value would cause underflow, and is representable, a range error may occur and 10217 the correct value shall be returned. 10218 ERRORS 10219 These functions shall fail if: 10220 Range Error The result overflows. 10221 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10222 then errno shall be set to [ERANGE]. If the integer expression | 10223 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 10224 floating-point exception shall be raised. | 10225 These functions may fail if: 10226 Range Error The result underflows. 10227 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10228 then errno shall be set to [ERANGE]. If the integer expression | 10229 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 10230 floating-point exception shall be raised. | System Interfaces, Issue 6 769 exp( ) System Interfaces 10231 EXAMPLES 10232 None. 10233 APPLICATION USAGE 10234 Note that for IEEE Std 754-1985 double, 709.8 < x implies exp(x) has overflowed. The value x < 10235 -708.4 implies exp(x) has underflowed. 10236 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 10237 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 10238 RATIONALE 10239 None. 10240 FUTURE DIRECTIONS 10241 None. 10242 SEE ALSO 10243 feclearexcept( ), fetestexcept( ), isnan( ), log( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 10244 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 10245 CHANGE HISTORY 10246 First released in Issue 1. Derived from Issue 1 of the SVID. 10247 Issue 5 10248 The DESCRIPTION is updated to indicate how an application should check for an error. This 10249 text was previously published in the APPLICATION USAGE section. 10250 Issue 6 10251 The expf( ) and expl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 10252 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 10253 revised to align with the ISO/IEC 9899: 1999 standard. 10254 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 10255 marked. 770 Technical Standard (2001) (Draft April 16, 2001) System Interfaces exp2( ) 10256 NAME 10257 exp2, exp2f, exp2l - exponential base 2 functions 10258 SYNOPSIS 10259 #include 10260 double exp2(double x); 10261 float exp2f(float x); 10262 long double exp2l(long double x); 10263 DESCRIPTION 10264 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10265 conflict between the requirements described here and the ISO C standard is unintentional. This 10266 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 10267 These functions shall compute the base-2 exponential of x. 10268 An application wishing to check for error situations should set errno to zero and call 10269 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 10270 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 10271 zero, an error has occurred. 10272 RETURN VALUE 10273 Upon successful completion, these functions shall return 2x. 10274 If the correct value would cause overflow, a range error shall occur and exp2( ), exp2f( ), and 10275 exp2l( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 10276 respectively. 10277 If the correct value would cause underflow, and is not representable, a range error may occur, 10278 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 10279 MX If x is NaN, a NaN shall be returned. 10280 If x is ±0, 1 shall be returned. 10281 If x is -Inf, +0 shall be returned. 10282 If x is +Inf, x shall be returned. 10283 If the correct value would cause underflow, and is representable, a range error may occur and 10284 the correct value shall be returned. 10285 ERRORS 10286 These functions shall fail if: 10287 Range Error The result overflows. 10288 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10289 then errno shall be set to [ERANGE]. If the integer expression | 10290 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 10291 floating-point exception shall be raised. | 10292 These functions may fail if: 10293 Range Error The result underflows. 10294 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10295 then errno shall be set to [ERANGE]. If the integer expression | 10296 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 10297 floating-point exception shall be raised. | System Interfaces, Issue 6 771 exp2( ) System Interfaces 10298 EXAMPLES 10299 None. 10300 APPLICATION USAGE 10301 For IEEE Std 754-1985 double, 1024 <= x implies exp2(x) has overflowed. The value x < -1022 10302 implies exp(x) has underflowed. 10303 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 10304 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 10305 RATIONALE 10306 None. 10307 FUTURE DIRECTIONS 10308 None. 10309 SEE ALSO 10310 exp( ), feclearexcept( ), fetestexcept( ), isnan( ), log( ), the Base Definitions volume of | 10311 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 10312 10313 CHANGE HISTORY 10314 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 772 Technical Standard (2001) (Draft April 16, 2001) System Interfaces expm1( ) 10315 NAME 10316 expm1, expm1f, expm1l - compute exponential functions 10317 SYNOPSIS 10318 #include 10319 double expm1(double x); 10320 float expm1f(float x); 10321 long double expm1l(long double x); 10322 DESCRIPTION 10323 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10324 conflict between the requirements described here and the ISO C standard is unintentional. This 10325 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 10326 These functions shall compute ex-1.0. 10327 An application wishing to check for error situations should set errno to zero and call 10328 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 10329 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 10330 zero, an error has occurred. 10331 RETURN VALUE 10332 Upon successful completion, these functions return ex-1.0. 10333 If the correct value would cause overflow, a range error shall occur and expm1( ), expm1f( ), and 10334 expm1l( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 10335 respectively. 10336 MX If x is NaN, a NaN shall be returned. 10337 If x is ±0, ±0 shall be returned. 10338 If x is -Inf, -1 shall be returned. 10339 If x is +Inf, x shall be returned. 10340 If x is subnormal, a range error may occur and x should be returned. 10341 ERRORS 10342 These functions shall fail if: 10343 Range Error The result overflows. 10344 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10345 then errno shall be set to [ERANGE]. If the integer expression | 10346 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 10347 floating-point exception shall be raised. | 10348 These functions may fail if: 10349 MX Range Error The value of x is subnormal. 10350 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 10351 then errno shall be set to [ERANGE]. If the integer expression | 10352 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 10353 floating-point exception shall be raised. | System Interfaces, Issue 6 773 expm1( ) System Interfaces 10354 EXAMPLES 10355 None. 10356 APPLICATION USAGE 10357 The value of expm1(x) may be more accurate than exp(x)-1.0 for small values of x. 10358 The expm1( ) and log1p( ) functions are useful for financial calculations of ((1+x)n-1)/x, namely: 10359 expm1(n * log1p(x))/x 10360 when x is very small (for example, when calculating small daily interest rates). These functions 10361 also simplify writing accurate inverse hyperbolic functions. 10362 For IEEE Std 754-1985 double, 709.8 < x implies expm1(x) has overflowed. 10363 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 10364 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 10365 RATIONALE 10366 None. 10367 FUTURE DIRECTIONS 10368 None. 10369 SEE ALSO 10370 exp( ), feclearexcept( ), fetestexcept( ), ilogb( ), log1p( ), the Base Definitions volume of | 10371 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 10372 10373 CHANGE HISTORY 10374 First released in Issue 4, Version 2. 10375 Issue 5 10376 Moved from X/OPEN UNIX extension to BASE. 10377 Issue 6 10378 The expm1f( ) and expm1l( ) functions are added for alignment with the ISO/IEC 9899: 1999 10379 standard. 10380 The expm1( ) function is no longer marked as an extension. | 10381 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are | 10382 revised to align with the ISO/IEC 9899: 1999 standard. 10383 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 10384 marked. 774 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fabs( ) 10385 NAME 10386 fabs, fabsf, fabsl - absolute value function 10387 SYNOPSIS 10388 #include 10389 double fabs(double x); 10390 float fabsf(float x); 10391 long double fabsl(long double x); 10392 DESCRIPTION 10393 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10394 conflict between the requirements described here and the ISO C standard is unintentional. This 10395 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 10396 These functions shall compute the absolute value of their argument x,|x|. 10397 RETURN VALUE 10398 Upon successful completion, these functions shall return the absolute value of x. 10399 MX If x is NaN, a NaN shall be returned. 10400 If x is ±0, +0 shall be returned. 10401 If x is ±Inf, +Inf shall be returned. 10402 ERRORS 10403 No errors are defined. 10404 EXAMPLES 10405 None. 10406 APPLICATION USAGE 10407 None. 10408 RATIONALE 10409 None. 10410 FUTURE DIRECTIONS 10411 None. 10412 SEE ALSO 10413 isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, 10414 CHANGE HISTORY 10415 First released in Issue 1. Derived from Issue 1 of the SVID. 10416 Issue 5 10417 The DESCRIPTION is updated to indicate how an application should check for an error. This 10418 text was previously published in the APPLICATION USAGE section. 10419 Issue 6 10420 The fabsf( ) and fabsl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 10421 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 10422 revised to align with the ISO/IEC 9899: 1999 standard. 10423 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 10424 marked. System Interfaces, Issue 6 775 fattach( ) System Interfaces 10425 NAME 10426 fattach - attach a STREAMS-based file descriptor to a file in the file system name space 10427 (STREAMS) 10428 SYNOPSIS 10429 XSR #include 10430 int fattach(int fildes, const char *path); 10431 10432 DESCRIPTION 10433 The fattach( ) function shall attach a STREAMS-based file descriptor to a file, effectively | 10434 associating a pathname with fildes. The application shall ensure that the fildes argument is a | 10435 valid open file descriptor associated with a STREAMS file. The path argument points to a | 10436 pathname of an existing file. The application shall have the appropriate privileges, or is the | 10437 owner of the file named by path and has write permission. A successful call to fattach( ) shall | 10438 cause all pathnames that name the file named by path to name the STREAMS file associated with | 10439 fildes, until the STREAMS file is detached from the file. A STREAMS file can be attached to more | 10440 than one file and can have several pathnames associated with it. | 10441 The attributes of the named STREAMS file shall be initialized as follows: the permissions, user 10442 ID, group ID, and times are set to those of the file named by path, the number of links is set to 1, 10443 and the size and device identifier are set to those of the STREAMS file associated with fildes. If 10444 any attributes of the named STREAMS file are subsequently changed (for example, by chmod( )), 10445 neither the attributes of the underlying file nor the attributes of the STREAMS file to which fildes 10446 refers shall be affected. 10447 File descriptors referring to the underlying file, opened prior to an fattach( ) call, shall continue to 10448 refer to the underlying file. 10449 RETURN VALUE 10450 Upon successful completion, fattach( ) shall return 0. Otherwise, -1 shall be returned and errno 10451 set to indicate the error. 10452 ERRORS 10453 The fattach( ) function shall fail if: 10454 [EACCES] Search permission is denied for a component of the path prefix, or the process 10455 is the owner of path but does not have write permissions on the file named by 10456 path. 10457 [EBADF] The fildes argument is not a valid open file descriptor. 10458 [EBUSY] The file named by path is currently a mount point or has a STREAMS file 10459 attached to it. 10460 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 10461 argument. 10462 [ENAMETOOLONG] 10463 The size of path exceeds {PATH_MAX} or a component of path is longer than 10464 {NAME_MAX}. 10465 [ENOENT] A component of path does not name an existing file or path is an empty string. 10466 [ENOTDIR] A component of the path prefix is not a directory. 10467 [EPERM] The effective user ID of the process is not the owner of the file named by path 10468 and the process does not have appropriate privilege. 776 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fattach( ) 10469 The fattach( ) function may fail if: 10470 [EINVAL] The fildes argument does not refer to a STREAMS file. 10471 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 10472 resolution of the path argument. 10473 [ENAMETOOLONG] 10474 Pathname resolution of a symbolic link produced an intermediate result | 10475 whose length exceeds {PATH_MAX}. 10476 [EXDEV] A link to a file on another file system was attempted. 10477 EXAMPLES 10478 Attaching a File Descriptor to a File 10479 In the following example, fd refers to an open STREAMS file. The call to fattach( ) associates this 10480 STREAM with the file /tmp/named-STREAM, such that any future calls to open /tmp/named- 10481 STREAM, prior to breaking the attachment via a call to fdetach( ), will instead create a new file 10482 handle referring to the STREAMS file associated with fd. 10483 #include 10484 ... 10485 int fd; 10486 char *filename = "/tmp/named-STREAM"; 10487 int ret; 10488 ret = fattach(fd, filename); 10489 APPLICATION USAGE 10490 The fattach( ) function behaves similarly to the traditional mount( ) function in the way a file is 10491 temporarily replaced by the root directory of the mounted file system. In the case of fattach( ), the 10492 replaced file need not be a directory and the replacing file is a STREAMS file. 10493 RATIONALE 10494 The file attributes of a file which has been the subject of an fattach( ) call are specifically set | 10495 because of an artefact of the original implementation. The internal mechanism was the same as | 10496 for the mount( ) function. Since mount( ) is typically only applied to directories, the effects when | 10497 applied to a regular file are a little surprising, especially as regards the link count which rigidly | 10498 remains one, even if there were several links originally and despite the fact that all original links | 10499 refer to the STREAM as long as the fattach( ) remains in effect. | 10500 FUTURE DIRECTIONS 10501 None. 10502 SEE ALSO 10503 fdetach( ), isastream( ), the Base Definitions volume of IEEE Std 1003.1-200x, 10504 CHANGE HISTORY 10505 First released in Issue 4, Version 2. 10506 Issue 5 10507 Moved from X/OPEN UNIX extension to BASE. 10508 The [EXDEV] error is added to the list of optional errors in the ERRORS section. System Interfaces, Issue 6 777 fattach( ) System Interfaces 10509 Issue 6 10510 This function is marked as part of the XSI STREAMS Option Group. 10511 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 10512 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 10513 [ELOOP] error condition is added. 778 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fchdir( ) 10514 NAME 10515 fchdir - change working directory 10516 SYNOPSIS 10517 XSI #include 10518 int fchdir(int fildes); 10519 10520 DESCRIPTION 10521 The fchdir( ) function shall be equivalent to chdir( ) except that the directory that is to be the new | 10522 current working directory is specified by the file descriptor fildes. 10523 A conforming application can obtain a file descriptor for a file of type directory using open( ), 10524 provided that the file status flags and access modes do not contain O_WRONLY or O_RDWR. 10525 RETURN VALUE 10526 Upon successful completion, fchdir( ) shall return 0. Otherwise, it shall return -1 and set errno to 10527 indicate the error. On failure the current working directory shall remain unchanged. 10528 ERRORS 10529 The fchdir( ) function shall fail if: 10530 [EACCES] Search permission is denied for the directory referenced by fildes. 10531 [EBADF] The fildes argument is not an open file descriptor. 10532 [ENOTDIR] The open file descriptor fildes does not refer to a directory. 10533 The fchdir( ) may fail if: 10534 [EINTR] A signal was caught during the execution of fchdir( ). 10535 [EIO] An I/O error occurred while reading from or writing to the file system. 10536 EXAMPLES 10537 None. 10538 APPLICATION USAGE 10539 None. 10540 RATIONALE 10541 None. 10542 FUTURE DIRECTIONS 10543 None. 10544 SEE ALSO 10545 chdir( ), the Base Definitions volume of IEEE Std 1003.1-200x, 10546 CHANGE HISTORY 10547 First released in Issue 4, Version 2. 10548 Issue 5 10549 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 779 fchmod( ) System Interfaces 10550 NAME 10551 fchmod - change mode of a file 10552 SYNOPSIS 10553 #include 10554 int fchmod(int fildes, mode_t mode); 10555 DESCRIPTION 10556 The fchmod( ) function shall be equivalent to chmod( ) except that the file whose permissions are | 10557 changed is specified by the file descriptor fildes. 10558 SHM If fildes references a shared memory object, the fchmod( ) function need only affect the S_IRUSR, 10559 S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits. 10560 TYM If fildes references a typed memory object, the behavior of fchmod( ) is unspecified. | 10561 If fildes refers to a socket, the behavior of fchmod( ) is unspecified. | 10562 XSR If fildes refers to a STREAM (which is fattach( )-ed into the file system name space) the call | 10563 returns successfully, doing nothing. | 10564 RETURN VALUE 10565 Upon successful completion, fchmod( ) shall return 0. Otherwise, it shall return -1 and set errno to 10566 indicate the error. 10567 ERRORS 10568 The fchmod( ) function shall fail if: 10569 [EBADF] The fildes argument is not an open file descriptor. 10570 [EPERM] The effective user ID does not match the owner of the file and the process 10571 does not have appropriate privilege. 10572 [EROFS] The file referred to by fildes resides on a read-only file system. 10573 The fchmod( ) function may fail if: 10574 XSI [EINTR] The fchmod( ) function was interrupted by a signal. 10575 XSI [EINVAL] The value of the mode argument is invalid. 10576 [EINVAL] The fildes argument refers to a pipe and the implementation disallows 10577 execution of fchmod( ) on a pipe. 10578 EXAMPLES 10579 Changing the Current Permissions for a File 10580 The following example shows how to change the permissions for a file named /home/cnd/mod1 10581 so that the owner and group have read/write/execute permissions, but the world only has 10582 read/write permissions. 10583 #include 10584 #include 10585 mode_t mode; 10586 int fildes; 10587 ... 10588 fildes = open("/home/cnd/mod1", O_RDWR); 10589 fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); 780 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fchmod( ) 10590 APPLICATION USAGE 10591 None. 10592 RATIONALE 10593 None. 10594 FUTURE DIRECTIONS 10595 None. 10596 SEE ALSO 10597 chmod( ), chown( ), creat( ), fcntl( ), fstatvfs( ), mknod( ), open( ), read( ), stat( ), write( ), the Base 10598 Definitions volume of IEEE Std 1003.1-200x, 10599 CHANGE HISTORY 10600 First released in Issue 4, Version 2. 10601 Issue 5 10602 Moved from X/OPEN UNIX extension to BASE and aligned with fchmod( ) in the POSIX 10603 Realtime Extension. Specifically, the second paragraph of the DESCRIPTION is added and a 10604 second instance of [EINVAL] is defined in the list of optional errors. 10605 Issue 6 10606 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by stating that fchmod( ) 10607 behavior is unspecified for typed memory objects. System Interfaces, Issue 6 781 fchown( ) System Interfaces 10608 NAME 10609 fchown - change owner and group of a file 10610 SYNOPSIS 10611 #include 10612 int fchown(int fildes, uid_t owner, gid_t group); 10613 DESCRIPTION 10614 The fchown( ) function shall be equivalent to chown( ) except that the file whose owner and group | 10615 are changed is specified by the file descriptor fildes. 10616 RETURN VALUE 10617 Upon successful completion, fchown( ) shall return 0. Otherwise, it shall return -1 and set errno to 10618 indicate the error. 10619 ERRORS 10620 The fchown( ) function shall fail if: 10621 [EBADF] The fildes argument is not an open file descriptor. 10622 [EPERM] The effective user ID does not match the owner of the file or the process does 10623 not have appropriate privilege and _POSIX_CHOWN_RESTRICTED indicates 10624 that such privilege is required. 10625 [EROFS] The file referred to by fildes resides on a read-only file system. 10626 The fchown( ) function may fail if: 10627 [EINVAL] The owner or group ID is not a value supported by the implementation. The 10628 XSR fildes argument refers to a pipe or socket or an fattach( )-ed STREAM and the | 10629 implementation disallows execution of fchown( ) on a pipe. | 10630 [EIO] A physical I/O error has occurred. 10631 [EINTR] The fchown( ) function was interrupted by a signal which was caught. 10632 EXAMPLES 10633 Changing the Current Owner of a File 10634 The following example shows how to change the owner of a file named /home/cnd/mod1 to 10635 ``jones'' and the group to ``cnd''. 10636 The numeric value for the user ID is obtained by extracting the user ID from the user database 10637 entry associated with ``jones''. Similarly, the numeric value for the group ID is obtained by 10638 extracting the group ID from the group database entry associated with ``cnd''. This example 10639 assumes the calling program has appropriate privileges. 10640 #include 10641 #include 10642 #include 10643 #include 10644 #include 10645 struct passwd *pwd; 10646 struct group *grp; 10647 int fildes; 10648 ... 10649 fildes = open("/home/cnd/mod1", O_RDWR); 10650 pwd = getpwnam("jones"); 782 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fchown( ) 10651 grp = getgrnam("cnd"); 10652 fchown(fildes, pwd->pw_uid, grp->gr_gid); 10653 APPLICATION USAGE 10654 None. 10655 RATIONALE 10656 None. 10657 FUTURE DIRECTIONS 10658 None. 10659 SEE ALSO 10660 chown( ), the Base Definitions volume of IEEE Std 1003.1-200x, 10661 CHANGE HISTORY 10662 First released in Issue 4, Version 2. 10663 Issue 5 10664 Moved from X/OPEN UNIX extension to BASE. | 10665 Issue 6 10666 The following changes were made to align with the IEEE P1003.1a draft standard: 10667 * Clarification is added that a call to fchown( ) may not be allowed on a pipe. | 10668 The fchown( ) function is now defined as mandatory. | System Interfaces, Issue 6 783 fclose( ) System Interfaces 10669 NAME 10670 fclose - close a stream 10671 SYNOPSIS 10672 #include 10673 int fclose(FILE *stream); 10674 DESCRIPTION 10675 CX The functionality described on this reference page is aligned with the ISO C standard. Any 10676 conflict between the requirements described here and the ISO C standard is unintentional. This 10677 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 10678 The fclose( ) function shall cause the stream pointed to by stream to be flushed and the associated 10679 file to be closed. Any unwritten buffered data for the stream shall be written to the file; any 10680 unread buffered data shall be discarded. Whether or not the call succeeds, the stream shall be 10681 disassociated from the file and any buffer set by the setbuf( ) or setvbuf( ) function shall be 10682 disassociated from the stream. If the associated buffer was automatically allocated, it shall be 10683 deallocated. | 10684 CX The fclose( ) function shall mark for update the st_ctime and st_mtime fields of the underlying file, | 10685 if the stream was writable, and if buffered data remains that has not yet been written to the file. 10686 The fclose( ) function shall perform the equivalent of a close( ) on the file descriptor that is 10687 associated with the stream pointed to by stream. 10688 After the call to fclose( ), any use of stream results in undefined behavior. 10689 RETURN VALUE 10690 CX Upon successful completion, fclose( ) shall return 0; otherwise, it shall return EOF and set errno to 10691 indicate the error. 10692 ERRORS 10693 The fclose( ) function shall fail if: 10694 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 10695 process would be delayed in the write operation. 10696 CX [EBADF] The file descriptor underlying stream is not valid. 10697 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 10698 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 10699 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 10700 offset maximum associated with the corresponding stream. 10701 CX [EINTR] The fclose( ) function was interrupted by a signal. 10702 CX [EIO] The process is a member of a background process group attempting to write 10703 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 10704 blocking SIGTTOU, and the process group of the process is orphaned. This 10705 error may also be returned under implementation-defined conditions. 10706 CX [ENOSPC] There was no free space remaining on the device containing the file. 10707 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 10708 any process. A SIGPIPE signal shall also be sent to the thread. 10709 The fclose( ) function may fail if: 10710 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 10711 capabilities of the device. 784 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fclose( ) 10712 EXAMPLES 10713 None. 10714 APPLICATION USAGE 10715 None. 10716 RATIONALE 10717 None. 10718 FUTURE DIRECTIONS 10719 None. 10720 SEE ALSO 10721 close( ), fopen( ), getrlimit( ), ulimit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 10722 10723 CHANGE HISTORY 10724 First released in Issue 1. Derived from Issue 1 of the SVID. 10725 Issue 5 10726 Large File Summit extensions are added. 10727 Issue 6 10728 Extensions beyond the ISO C standard are now marked. 10729 The following new requirements on POSIX implementations derive from alignment with the 10730 Single UNIX Specification: 10731 * The [EFBIG] error is added as part of the large file support extensions. 10732 * The [ENXIO] optional error condition is added. 10733 The DESCRIPTION is updated to note that the stream and any buffer are disassociated whether 10734 or not the call succeeds. This is for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 785 fcntl( ) System Interfaces 10735 NAME 10736 fcntl - file control 10737 SYNOPSIS 10738 OH #include 10739 #include 10740 int fcntl(int fildes, int cmd, ...); 10741 DESCRIPTION 10742 The fcntl( ) function shall perform the operations described below on open files. The fildes | 10743 argument is a file descriptor. 10744 The available values for cmd are defined in and are as follows: | 10745 F_DUPFD Return a new file descriptor which shall be the lowest numbered available | 10746 (that is, not already open) file descriptor greater than or equal to the third | 10747 argument, arg, taken as an integer of type int. The new file descriptor shall | 10748 refer to the same open file description as the original file descriptor, and shall | 10749 share any locks. The FD_CLOEXEC flag associated with the new file | 10750 descriptor shall be cleared to keep the file open across calls to one of the exec | 10751 functions. 10752 F_GETFD Get the file descriptor flags defined in that are associated with the 10753 file descriptor fildes. File descriptor flags are associated with a single file 10754 descriptor and do not affect other file descriptors that refer to the same file. 10755 F_SETFD Set the file descriptor flags defined in , that are associated with fildes, 10756 to the third argument, arg, taken as type int. If the FD_CLOEXEC flag in the 10757 third argument is 0, the file shall remain open across the exec functions; 10758 otherwise, the file shall be closed upon successful execution of one of the exec 10759 functions. 10760 F_GETFL Get the file status flags and file access modes, defined in , for the file 10761 description associated with fildes. The file access modes can be extracted from 10762 the return value using the mask O_ACCMODE, which is defined in . | 10763 File status flags and file access modes are associated with the file description 10764 and do not affect other file descriptors that refer to the same file with different 10765 open file descriptions. 10766 F_SETFL Set the file status flags, defined in , for the file description associated 10767 with fildes from the corresponding bits in the third argument, arg, taken as 10768 type int. Bits corresponding to the file access mode and the file creation flags, | 10769 as defined in , that are set in arg shall be ignored. If any bits in arg | 10770 other than those mentioned here are changed by the application, the result is 10771 unspecified. 10772 F_GETOWN If fildes refers to a socket, get the process or process group ID specified to 10773 receive SIGURG signals when out-of-band data is available. Positive values 10774 indicate a process ID; negative values, other than -1, indicate a process group 10775 ID. If fildes does not refer to a socket, the results are unspecified. 10776 F_SETOWN If fildes refers to a socket, set the process or process group ID specified to 10777 receive SIGURG signals when out-of-band data is available, using the value of 10778 the third argument, arg, taken as type int. Positive values indicate a process 10779 ID; negative values, other than -1, indicate a process group ID. If fildes does 10780 not refer to a socket, the results are unspecified. 786 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fcntl( ) 10781 The following values for cmd are available for advisory record locking. Record locking shall be | 10782 supported for regular files, and may be supported for other files. | 10783 F_GETLK Get the first lock which blocks the lock description pointed to by the third 10784 argument, arg, taken as a pointer to type struct flock, defined in . | 10785 The information retrieved shall overwrite the information passed to fcntl( ) in | 10786 the structure flock. If no lock is found that would prevent this lock from 10787 being created, then the structure shall be left unchanged except for the lock 10788 type which shall be set to F_UNLCK. 10789 F_SETLK Set or clear a file segment lock according to the lock description pointed to by 10790 the third argument, arg, taken as a pointer to type struct flock, defined in 10791 . F_SETLK can establish shared (or read) locks (F_RDLCK) or | 10792 exclusive (or write) locks (F_WRLCK), as well as to remove either type of lock 10793 (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in . 10794 If a shared or exclusive lock cannot be set, fcntl( ) shall return immediately 10795 with a return value of -1. 10796 F_SETLKW This command shall be equivalent to F_SETLK except that if a shared or | 10797 exclusive lock is blocked by other locks, the thread shall wait until the request 10798 can be satisfied. If a signal that is to be caught is received while fcntl( ) is 10799 waiting for a region, fcntl( ) shall be interrupted. Upon return from the signal 10800 handler, fcntl( ) shall return -1 with errno set to [EINTR], and the lock 10801 operation shall not be done. 10802 Additional implementation-defined values for cmd may be defined in . Their names 10803 shall start with F_. 10804 When a shared lock is set on a segment of a file, other processes shall be able to set shared locks 10805 on that segment or a portion of it. A shared lock prevents any other process from setting an 10806 exclusive lock on any portion of the protected area. A request for a shared lock shall fail if the 10807 file descriptor was not opened with read access. 10808 An exclusive lock shall prevent any other process from setting a shared lock or an exclusive lock 10809 on any portion of the protected area. A request for an exclusive lock shall fail if the file 10810 descriptor was not opened with write access. 10811 The structure flock describes the type (l_type), starting offset (l_whence), relative offset (l_start), 10812 size (l_len), and process ID (l_pid) of the segment of the file to be affected. 10813 The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate that the relative 10814 offset l_start bytes shall be measured from the start of the file, current position, or end of the file, 10815 respectively. The value of l_len is the number of consecutive bytes to be locked. The value of 10816 l_len may be negative (where the definition of off_t permits negative values of l_len). The l_pid 10817 field is only used with F_GETLK to return the process ID of the process holding a blocking lock. 10818 After a successful F_GETLK request, when a blocking lock is found, the values returned in the 10819 flock structure shall be as follows: 10820 l_type Type of blocking lock found. 10821 l_whence SEEK_SET. 10822 l_start Start of the blocking lock. 10823 l_len Length of the blocking lock. 10824 l_pid Process ID of the process that holds the blocking lock. System Interfaces, Issue 6 787 fcntl( ) System Interfaces 10825 If the command is F_SETLKW and the process must wait for another process to release a lock, 10826 then the range of bytes to be locked shall be determined before the fcntl( ) function blocks. If the 10827 file size or file descriptor seek offset change while fcntl( ) is blocked, this shall not affect the 10828 range of bytes locked. 10829 If l_len is positive, the area affected shall start at l_start and end at l_start+l_len-1. If l_len is | 10830 negative, the area affected shall start at l_start+l_len and end at l_start-1. Locks may start and | 10831 extend beyond the current end of a file, but shall not extend before the beginning of the file. A | 10832 lock shall be set to extend to the largest possible value of the file offset for that file by setting | 10833 l_len to 0. If such a lock also has l_start set to 0 and l_whence is set to SEEK_SET, the whole file 10834 shall be locked. 10835 There shall be at most one type of lock set for each byte in the file. Before a successful return 10836 from an F_SETLK or an F_SETLKW request when the calling process has previously existing 10837 locks on bytes in the region specified by the request, the previous lock type for each byte in the 10838 specified region shall be replaced by the new lock type. As specified above under the 10839 descriptions of shared locks and exclusive locks, an F_SETLK or an F_SETLKW request 10840 (respectively) shall fail or block when another process has existing locks on bytes in the specified 10841 region and the type of any of those locks conflicts with the type specified in the request. 10842 All locks associated with a file for a given process shall be removed when a file descriptor for 10843 that file is closed by that process or the process holding that file descriptor terminates. Locks are 10844 not inherited by a child process. 10845 A potential for deadlock occurs if a process controlling a locked region is put to sleep by 10846 attempting to lock another process' locked region. If the system detects that sleeping until a 10847 locked region is unlocked would cause a deadlock, fcntl( ) shall fail with an [EDEADLK] error. 10848 An unlock (F_UNLCK) request in which l_len is non-zero and the offset of the last byte of the | 10849 requested segment is the maximum value for an object of type off_t, when the process has an | 10850 existing lock in which l_len is 0 and which includes the last byte of the requested segment, shall | 10851 be treated as a request to unlock from the start of the requested segment with an l_len equal to 0. | 10852 Otherwise, an unlock (F_UNLCK) request shall attempt to unlock only the requested segment. | 10853 SHM When the file descriptor fildes refers to a shared memory object, the behavior of fcntl( ) shall be | 10854 the same as for a regular file except the effect of the following values for the argument cmd shall 10855 be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW. 10856 TYM If fildes refers to a typed memory object, the result of the fcntl( ) function is unspecified. | 10857 RETURN VALUE 10858 Upon successful completion, the value returned shall depend on cmd as follows: 10859 F_DUPFD A new file descriptor. 10860 F_GETFD Value of flags defined in . The return value shall not be negative. 10861 F_SETFD Value other than -1. 10862 F_GETFL Value of file status flags and access modes. The return value is not negative. 10863 F_SETFL Value other than -1. 10864 F_GETLK Value other than -1. 10865 F_SETLK Value other than -1. 10866 F_SETLKW Value other than -1. 10867 F_GETOWN Value of the socket owner process or process group; this will not be -1. 788 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fcntl( ) 10868 F_SETOWN Value other than -1. 10869 Otherwise, -1 shall be returned and errno set to indicate the error. 10870 ERRORS 10871 The fcntl( ) function shall fail if: 10872 [EACCES] or [EAGAIN] 10873 The cmd argument is F_SETLK; the type of lock (l_type) is a shared (F_RDLCK) 10874 or exclusive (F_WRLCK) lock and the segment of a file to be locked is already 10875 exclusive-locked by another process, or the type is an exclusive lock and some 10876 portion of the segment of a file to be locked is already shared-locked or 10877 exclusive-locked by another process. 10878 [EBADF] The fildes argument is not a valid open file descriptor, or the argument cmd is 10879 F_SETLK or F_SETLKW, the type of lock, l_type, is a shared lock (F_RDLCK), 10880 and fildes is not a valid file descriptor open for reading, or the type of lock 10881 l_type, is an exclusive lock (F_WRLCK), and fildes is not a valid file descriptor 10882 open for writing. 10883 [EINTR] The cmd argument is F_SETLKW and the function was interrupted by a signal. 10884 [EINVAL] The cmd argument is invalid, or the cmd argument is F_DUPFD and arg is 10885 negative or greater than or equal to {OPEN_MAX}, or the cmd argument is 10886 F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by arg is not valid, 10887 or fildes refers to a file that does not support locking. 10888 [EMFILE] The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors are 10889 currently open in the calling process, or no file descriptors greater than or 10890 equal to arg are available. 10891 [ENOLCK] The argument cmd is F_SETLK or F_SETLKW and satisfying the lock or unlock 10892 request would result in the number of locked regions in the system exceeding 10893 a system-imposed limit. 10894 [EOVERFLOW] One of the values to be returned cannot be represented correctly. 10895 [EOVERFLOW] The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, 10896 if l_len is non-zero, the largest offset of any byte in the requested segment 10897 cannot be represented correctly in an object of type off_t. 10898 The fcntl( ) function may fail if: 10899 [EDEADLK] The cmd argument is F_SETLKW, the lock is blocked by some lock from 10900 another process and putting the calling process to sleep, waiting for that lock 10901 to become free would cause a deadlock. 10902 EXAMPLES 10903 None. 10904 APPLICATION USAGE 10905 None. 10906 RATIONALE 10907 The ellipsis in the SYNOPSIS is the syntax specified by the ISO C standard for a variable number 10908 of arguments. It is used because System V uses pointers for the implementation of file locking 10909 functions. 10910 The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag values to allow 10911 for future growth. Applications using these functions should do a read-modify-write operation System Interfaces, Issue 6 789 fcntl( ) System Interfaces 10912 on them, rather than assuming that only the values defined by this volume of 10913 IEEE Std 1003.1-200x are valid. It is a common error to forget this, particularly in the case of 10914 F_SETFD. 10915 This volume of IEEE Std 1003.1-200x permits concurrent read and write access to file data using 10916 the fcntl( ) function; this is a change from the 1984 /usr/group standard and early proposals. 10917 Without concurrency controls, this feature may not be fully utilized without occasional loss of 10918 data. 10919 Data losses occur in several ways. One case occurs when several processes try to update the 10920 same record, without sequencing controls; several updates may occur in parallel and the last 10921 writer ``wins''. Another case is a bit-tree or other internal list-based database that is undergoing 10922 reorganization. Without exclusive use to the tree segment by the updating process, other reading 10923 processes chance getting lost in the database when the index blocks are split, condensed, 10924 inserted, or deleted. While fcntl( ) is useful for many applications, it is not intended to be overly 10925 general and does not handle the bit-tree example well. 10926 This facility is only required for regular files because it is not appropriate for many devices such 10927 as terminals and network connections. 10928 Since fcntl( ) works with ``any file descriptor associated with that file, however it is obtained'', 10929 the file descriptor may have been inherited through a fork( ) or exec operation and thus may 10930 affect a file that another process also has open. 10931 The use of the open file description to identify what to lock requires extra calls and presents 10932 problems if several processes are sharing an open file description, but there are too many 10933 implementations of the existing mechanism for this volume of IEEE Std 1003.1-200x to use 10934 different specifications. 10935 Another consequence of this model is that closing any file descriptor for a given file (whether or 10936 not it is the same open file description that created the lock) causes the locks on that file to be 10937 relinquished for that process. Equivalently, any close for any file/process pair relinquishes the 10938 locks owned on that file for that process. But note that while an open file description may be 10939 shared through fork( ), locks are not inherited through fork( ). Yet locks may be inherited through 10940 one of the exec functions. 10941 The identification of a machine in a network environment is outside of the scope of this volume 10942 of IEEE Std 1003.1-200x. Thus, an l_sysid member, such as found in System V, is not included in 10943 the locking structure. 10944 Changing of lock types can result in a previously locked region being split into smaller regions. | 10945 Mandatory locking was a major feature of the 1984 /usr/group standard. 10946 For advisory file record locking to be effective, all processes that have access to a file must 10947 cooperate and use the advisory mechanism before doing I/O on the file. Enforcement-mode 10948 record locking is important when it cannot be assumed that all processes are cooperating. For 10949 example, if one user uses an editor to update a file at the same time that a second user executes 10950 another process that updates the same file and if only one of the two processes is using advisory 10951 locking, the processes are not cooperating. Enforcement-mode record locking would protect 10952 against accidental collisions. 10953 Secondly, advisory record locking requires a process using locking to bracket each I/O operation 10954 with lock (or test) and unlock operations. With enforcement-mode file and record locking, a 10955 process can lock the file once and unlock when all I/O operations have been completed. 10956 Enforcement-mode record locking provides a base that can be enhanced; for example, with 10957 sharable locks. That is, the mechanism could be enhanced to allow a process to lock a file so 10958 other processes could read it, but none of them could write it. 790 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fcntl( ) 10959 Mandatory locks were omitted for several reasons: 10960 1. Mandatory lock setting was done by multiplexing the set-group-ID bit in most 10961 implementations; this was confusing, at best. 10962 2. The relationship to file truncation as supported in 4.2 BSD was not well specified. 10963 3. Any publicly readable file could be locked by anyone. Many historical implementations 10964 keep the password database in a publicly readable file. A malicious user could thus 10965 prohibit logins. Another possibility would be to hold open a long-distance telephone line. 10966 4. Some demand-paged historical implementations offer memory mapped files, and 10967 enforcement cannot be done on that type of file. 10968 Since sleeping on a region is interrupted with any signal, alarm( ) may be used to provide a 10969 timeout facility in applications requiring it. This is useful in deadlock detection. Since | 10970 implementation of full deadlock detection is not always feasible, the [EDEADLK] error was | 10971 made optional. 10972 FUTURE DIRECTIONS 10973 None. 10974 SEE ALSO 10975 close( ), exec, open( ), sigaction( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 10976 , 10977 CHANGE HISTORY 10978 First released in Issue 1. Derived from Issue 1 of the SVID. 10979 Issue 5 10980 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 10981 Threads Extension. 10982 Large File Summit extensions are added. 10983 Issue 6 10984 In the SYNOPSIS, the optional include of the header is removed. 10985 The following new requirements on POSIX implementations derive from alignment with the 10986 Single UNIX Specification: 10987 * The requirement to include has been removed. Although was 10988 required for conforming implementations of previous POSIX specifications, it was not 10989 required for UNIX applications. 10990 * In the DESCRIPTION, sentences describing behavior when l_len is negative are now 10991 mandated, and the description of unlock (F_UNLOCK) when l_len is non-negative is 10992 mandated. 10993 * In the ERRORS section, the [EINVAL] error condition has the case mandated when the cmd is 10994 invalid, and two [EOVERFLOW] error conditions are added. 10995 The F_GETOWN and F_SETOWN values are added for sockets. 10996 The following changes were made to align with the IEEE P1003.1a draft standard: 10997 * Clarification is added that the extent of the bytes locked is determined prior to the blocking 10998 action. 10999 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 11000 fcntl( ) results are unspecified for typed memory objects. System Interfaces, Issue 6 791 fcntl( ) System Interfaces 11001 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 792 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fcvt( ) 11002 NAME 11003 fcvt - convert a floating-point number to a string (LEGACY) 11004 SYNOPSIS 11005 XSI #include 11006 char *fcvt(double value, int ndigit, int *restrict decpt, 11007 int *restrict sign); 11008 11009 DESCRIPTION 11010 Refer to ecvt( ). System Interfaces, Issue 6 793 fdatasync( ) System Interfaces 11011 NAME 11012 fdatasync - synchronize the data of a file (REALTIME) 11013 SYNOPSIS 11014 SIO #include 11015 int fdatasync(int fildes); 11016 11017 DESCRIPTION 11018 The fdatasync( ) function shall force all currently queued I/O operations associated with the file 11019 indicated by file descriptor fildes to the synchronized I/O completion state. 11020 The functionality shall be equivalent to fsync( ) with the symbol _POSIX_SYNCHRONIZED_IO | 11021 defined, with the exception that all I/O operations shall be completed as defined for | 11022 synchronized I/O data integrity completion. 11023 RETURN VALUE 11024 If successful, the fdatasync( ) function shall return the value 0; otherwise, the function shall return 11025 the value -1 and set errno to indicate the error. If the fdatasync( ) function fails, outstanding I/O 11026 operations are not guaranteed to have been completed. 11027 ERRORS 11028 The fdatasync( ) function shall fail if: 11029 [EBADF] The fildes argument is not a valid file descriptor open for writing. 11030 [EINVAL] This implementation does not support synchronized I/O for this file. 11031 In the event that any of the queued I/O operations fail, fdatasync( ) shall return the error 11032 conditions defined for read( ) and write( ). 11033 EXAMPLES 11034 None. 11035 APPLICATION USAGE 11036 None. 11037 RATIONALE 11038 None. 11039 FUTURE DIRECTIONS 11040 None. 11041 SEE ALSO 11042 aio_fsync( ), fcntl( ), fsync( ), open( ), read( ), write( ), the Base Definitions volume of 11043 IEEE Std 1003.1-200x, 11044 CHANGE HISTORY 11045 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 11046 Issue 6 11047 The [ENOSYS] error condition has been removed as stubs need not be provided if an 11048 implementation does not support the Synchronized Input and Output option. 11049 The fdatasync( ) function is marked as part of the Synchronized Input and Output option. 794 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fdetach( ) 11050 NAME 11051 fdetach - detach a name from a STREAMS-based file descriptor (STREAMS) 11052 SYNOPSIS 11053 XSR #include 11054 int fdetach(const char *path); 11055 11056 DESCRIPTION 11057 The fdetach( ) function shall detach a STREAMS-based file from the file to which it was attached | 11058 by a previous call to fattach( ). The path argument points to the pathname of the attached | 11059 STREAMS file. The process shall have appropriate privileges or be the owner of the file. A | 11060 successful call to fdetach( ) shall cause all pathnames that named the attached STREAMS file to | 11061 again name the file to which the STREAMS file was attached. All subsequent operations on path | 11062 shall operate on the underlying file and not on the STREAMS file. 11063 All open file descriptions established while the STREAMS file was attached to the file referenced 11064 by path shall still refer to the STREAMS file after the fdetach( ) has taken effect. 11065 If there are no open file descriptors or other references to the STREAMS file, then a successful 11066 call to fdetach( ) shall have be equivalent to performing the last close( ) on the attached file. | 11067 RETURN VALUE 11068 Upon successful completion, fdetach( ) shall return 0; otherwise, it shall return -1 and set errno to 11069 indicate the error. 11070 ERRORS 11071 The fdetach( ) function shall fail if: 11072 [EACCES] Search permission is denied on a component of the path prefix. 11073 [EINVAL] The path argument names a file that is not currently attached. 11074 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 11075 argument. 11076 [ENAMETOOLONG] 11077 The size of a pathname exceeds {PATH_MAX} or a pathname component is | 11078 longer than {NAME_MAX}. | 11079 [ENOENT] A component of path does not name an existing file or path is an empty string. 11080 [ENOTDIR] A component of the path prefix is not a directory. 11081 [EPERM] The effective user ID is not the owner of path and the process does not have 11082 appropriate privileges. 11083 The fdetach( ) function may fail if: 11084 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 11085 resolution of the path argument. 11086 [ENAMETOOLONG] 11087 Pathname resolution of a symbolic link produced an intermediate result | 11088 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 795 fdetach( ) System Interfaces 11089 EXAMPLES 11090 Detaching a File 11091 The following example detaches the STREAMS-based file /tmp/named-STREAM from the file to 11092 which it was attached by a previous, successful call to fattach( ). Subsequent calls to open this 11093 file refer to the underlying file, not to the STREAMS file. 11094 #include 11095 ... 11096 char *filename = "/tmp/named-STREAM"; 11097 int ret; 11098 ret = fdetach(filename); 11099 APPLICATION USAGE 11100 None. 11101 RATIONALE 11102 None. 11103 FUTURE DIRECTIONS 11104 None. 11105 SEE ALSO 11106 fattach( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11107 CHANGE HISTORY 11108 First released in Issue 4, Version 2. 11109 Issue 5 11110 Moved from X/OPEN UNIX extension to BASE. 11111 Issue 6 11112 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 11113 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 11114 [ELOOP] error condition is added. 796 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fdim( ) 11115 NAME 11116 fdim, fdimf, fdiml - compute positive difference between two floating-point numbers 11117 SYNOPSIS 11118 #include 11119 double fdim(double x, double y); 11120 float fdimf(float x, float y); 11121 long double fdiml(long double x, long double y); 11122 DESCRIPTION 11123 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11124 conflict between the requirements described here and the ISO C standard is unintentional. This 11125 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11126 These functions shall determine the positive difference between their arguments. If x is greater 11127 than y, x-y is returned. If x is less than or equal to y, +0 is returned. 11128 An application wishing to check for error situations should set errno to zero and call 11129 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 11130 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 11131 zero, an error has occurred. 11132 RETURN VALUE 11133 Upon successful completion, these functions shall return the positive difference value. 11134 If x-y is positive and overflows, a range error shall occur and fdim( ), fdimf( ), and fdiml( ) shall 11135 return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 11136 XSI If x-y is positive and underflows, a range error may occur, and either (x-y) (if representable), or 11137 0.0 (if supported),or an implementation-defined value shall be returned. 11138 MX If x or y is NaN, a NaN shall be returned. 11139 ERRORS 11140 The fdim( ) function shall fail if: 11141 Range Error The result overflows. 11142 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 11143 then errno shall be set to [ERANGE]. If the integer expression | 11144 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 11145 floating-point exception shall be raised. | 11146 The fdim( ) function may fail if: 11147 Range Error The result underflows. 11148 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 11149 then errno shall be set to [ERANGE]. If the integer expression | 11150 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 11151 floating-point exception shall be raised. | System Interfaces, Issue 6 797 fdim( ) System Interfaces 11152 EXAMPLES 11153 None. 11154 APPLICATION USAGE 11155 On implementations supporting IEEE Std 754-1985, x-y cannot underflow, and hence the 0.0 11156 return value is shaded as an extension for implementations supporting the XSI extension rather 11157 than an MX extension. 11158 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 11159 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 11160 RATIONALE 11161 None. 11162 FUTURE DIRECTIONS 11163 None. 11164 SEE ALSO 11165 feclearexcept( ), fetestexcept( ), fmax( ), fmin( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 11166 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 11167 CHANGE HISTORY 11168 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 798 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fdopen( ) 11169 NAME 11170 fdopen - associate a stream with a file descriptor 11171 SYNOPSIS 11172 CX #include | 11173 FILE *fdopen(int fildes, const char *mode); 11174 | 11175 DESCRIPTION 11176 The fdopen( ) function shall associate a stream with a file descriptor. 11177 The mode argument is a character string having one of the following values: 11178 r or rb Open a file for reading. 11179 w or wb Open a file for writing. 11180 a or ab Open a file for writing at end of file. 11181 r+ or rb+ or r+b Open a file for update (reading and writing). 11182 w+ or wb+ or w+b Open a file for update (reading and writing). 11183 a+ or ab+ or a+b Open a file for update (reading and writing) at end of file. 11184 The meaning of these flags is exactly as specified in fopen( ), except that modes beginning with w | 11185 shall not cause truncation of the file. | 11186 Additional values for the mode argument may be supported by an implementation. 11187 The application shall ensure that the mode of the stream as expressed by the mode argument is 11188 allowed by the file access mode of the open file description to which fildes refers. The file 11189 position indicator associated with the new stream is set to the position indicated by the file 11190 offset associated with the file descriptor. 11191 The error and end-of-file indicators for the stream shall be cleared. The fdopen( ) function may 11192 cause the st_atime field of the underlying file to be marked for update. 11193 SHM If fildes refers to a shared memory object, the result of the fdopen( ) function is unspecified. 11194 TYM If fildes refers to a typed memory object, the result of the fdopen( ) function is unspecified. 11195 The fdopen( ) function shall preserve the offset maximum previously set for the open file 11196 description corresponding to fildes. 11197 RETURN VALUE 11198 Upon successful completion, fdopen( ) shall return a pointer to a stream; otherwise, a null pointer 11199 shall be returned and errno set to indicate the error. 11200 ERRORS 11201 The fdopen( ) function may fail if: 11202 [EBADF] The fildes argument is not a valid file descriptor. 11203 [EINVAL] The mode argument is not a valid mode. 11204 [EMFILE] {FOPEN_MAX} streams are currently open in the calling process. 11205 [EMFILE] {STREAM_MAX} streams are currently open in the calling process. 11206 [ENOMEM] Insufficient space to allocate a buffer. System Interfaces, Issue 6 799 fdopen( ) System Interfaces 11207 EXAMPLES 11208 None. 11209 APPLICATION USAGE 11210 File descriptors are obtained from calls like open( ), dup( ), creat( ), or pipe( ), which open files but 11211 do not return streams. 11212 RATIONALE 11213 The file descriptor may have been obtained from open( ), creat( ), pipe( ), dup( ), or fcntl( ); 11214 inherited through fork( ) or exec; or perhaps obtained by implementation-defined means, such as 11215 the 4.3 BSD socket( ) call. 11216 The meanings of the mode arguments of fdopen( ) and fopen( ) differ. With fdopen( ), open for write 11217 (w or w+) does not truncate, and append (a or a+) cannot create for writing. The mode argument 11218 formats that include a b are allowed for consistency with the ISO C standard function fopen( ). 11219 The b has no effect on the resulting stream. Although not explicitly required by this volume of 11220 IEEE Std 1003.1-200x, a good implementation of append (a) mode would cause the O_APPEND 11221 flag to be set. 11222 FUTURE DIRECTIONS 11223 None. 11224 SEE ALSO 11225 fclose( ), fopen( ), open( ), the Base Definitions volume of IEEE Std 1003.1-200x, , Section 11226 2.5.1 (on page 485) 11227 CHANGE HISTORY 11228 First released in Issue 1. Derived from Issue 1 of the SVID. 11229 Issue 5 11230 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 11231 Large File Summit extensions are added. 11232 Issue 6 11233 The following new requirements on POSIX implementations derive from alignment with the 11234 Single UNIX Specification: 11235 * In the DESCRIPTION, the use and setting of the mode argument are changed to include 11236 binary streams. 11237 * In the DESCRIPTION, text is added for large file support to indicate setting of the offset 11238 maximum in the open file description. 11239 * All errors identified in the ERRORS section are added. 11240 * In the DESCRIPTION, text is added that the fdopen( ) function may cause st_atime to be 11241 updated. 11242 The following changes were made to align with the IEEE P1003.1a draft standard: 11243 * Clarification is added that it is the responsibility of the application to ensure that the mode is 11244 compatible with the open file descriptor. 11245 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 11246 fdopen( ) results are unspecified for typed memory objects. 800 Technical Standard (2001) (Draft April 16, 2001) System Interfaces feclearexcept( ) 11247 NAME 11248 feclearexcept - clear floating-point exception 11249 SYNOPSIS 11250 #include 11251 int feclearexcept(int excepts); 11252 DESCRIPTION 11253 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11254 conflict between the requirements described here and the ISO C standard is unintentional. This 11255 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11256 The feclearexcept( ) function shall attempt to clear the supported floating-point exceptions | 11257 represented by excepts. | 11258 RETURN VALUE 11259 If the argument is zero or if all the specified exceptions were successfully cleared, feclearexcept( ) | 11260 shall return zero. Otherwise, it shall return a non-zero value. | 11261 ERRORS 11262 No errors are defined. 11263 EXAMPLES 11264 None. 11265 APPLICATION USAGE 11266 None. 11267 RATIONALE 11268 None. 11269 FUTURE DIRECTIONS 11270 None. 11271 SEE ALSO 11272 fegetexceptflag( ), feraiseexcept( ), fesetexceptflag( ), fetestexcept( ), the Base Definitions volume of 11273 IEEE Std 1003.1-200x, 11274 CHANGE HISTORY 11275 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11276 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 801 fegetenv( ) System Interfaces 11277 NAME 11278 fegetenv, fesetenv - get and set current floating-point environment 11279 SYNOPSIS 11280 #include 11281 int fegetenv(fenv_t *envp); 11282 int 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 attempt to store the current floating-point environment in the object | 11288 pointed to by envp. | 11289 The fesetenv( ) function shall attempt to establish the floating-point environment represented by | 11290 the object pointed to by envp. The argument envp shall point to an object set by a call to | 11291 fegetenv( ) or feholdexcept( ), or equal a floating-point environment macro. The fesetenv( ) function 11292 does not raise floating-point exceptions, but only installs the state of the floating-point status 11293 flags represented through its argument. 11294 RETURN VALUE 11295 If the representation was successfully stored, fegetenv( ) shall return zero. Otherwise, it shall | 11296 return a non-zero value. If the environment was successfully established, fesetenv( ) shall return | 11297 zero. Otherwise, it shall return a non-zero value. | 11298 ERRORS 11299 No errors are defined. 11300 EXAMPLES 11301 None. 11302 APPLICATION USAGE 11303 None. 11304 RATIONALE 11305 None. 11306 FUTURE DIRECTIONS 11307 None. 11308 SEE ALSO 11309 feholdexcept( ), feupdateenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11310 CHANGE HISTORY 11311 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11312 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 802 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fegetexceptflag( ) 11313 NAME 11314 fegetexceptflag, fesetexceptflag - get and set floating-point status flags 11315 SYNOPSIS 11316 #include 11317 int fegetexceptflag(fexcept_t *flagp, int excepts); 11318 int fesetexceptflag(const fexcept_t *flagp, int excepts); 11319 DESCRIPTION 11320 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11321 conflict between the requirements described here and the ISO C standard is unintentional. This 11322 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11323 The fegetexceptflag( ) function shall attempt to store an implementation-defined representation of | 11324 the states of the floating-point status flags indicated by the argument excepts in the object | 11325 pointed to by the argument flagp. 11326 The fesetexceptflag( ) function shall attempt to set the floating-point status flags indicated by the | 11327 argument excepts to the states stored in the object pointed to by flagp. The value pointed to by | 11328 flagp shall have been set by a previous call to fegetexceptflag( ) whose second argument 11329 represented at least those floating-point exceptions represented by the argument excepts. This 11330 function does not raise floating-point exceptions, but only sets the state of the flags. 11331 RETURN VALUE 11332 If the representation was successfully stored, fegetexceptflag( ) shall return zero. Otherwise, it | 11333 shall return a non-zero value. If the excepts argument is zero or if all the specified execptions | 11334 were successfully set, fesetexceptflag( ) shall return zero. Otherwise, it shall return a non-zero | 11335 value. | 11336 ERRORS 11337 No errors are defined. 11338 EXAMPLES 11339 None. 11340 APPLICATION USAGE 11341 None. 11342 RATIONALE 11343 None. 11344 FUTURE DIRECTIONS 11345 None. 11346 SEE ALSO 11347 feclearexcept( ), feraiseexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11348 11349 CHANGE HISTORY 11350 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11351 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 803 fegetround( ) System Interfaces 11352 NAME 11353 fegetround, fesetround - get and set current rounding direction 11354 SYNOPSIS 11355 #include 11356 int fegetround(void); 11357 int fesetround(int round); 11358 DESCRIPTION 11359 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11360 conflict between the requirements described here and the ISO C standard is unintentional. This 11361 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11362 The fegetround( ) function shall get the current rounding direction. 11363 The fesetround( ) function shall establish the rounding direction represented by its argument 11364 round. If the argument is not equal to the value of a rounding direction macro, the rounding 11365 direction is not changed. 11366 RETURN VALUE 11367 The fegetround( ) function shall return the value of the rounding direction macro representing the 11368 current rounding direction or a negative value if there is no such rounding direction macro or 11369 the current rounding direction is not determinable. 11370 The fesetround( ) function shall return a zero value if and only if the requested rounding direction | 11371 was established. | 11372 ERRORS 11373 No errors are defined. 11374 EXAMPLES 11375 The following example saves, sets, and restores the rounding direction, reporting an error and 11376 aborting if setting the rounding direction fails: 11377 #include 11378 #include 11379 void f(int round_dir) 11380 { 11381 #pragma STDC FENV_ACCESS ON 11382 int save_round; 11383 int setround_ok; 11384 save_round = fegetround(); 11385 setround_ok = fesetround(round_dir); 11386 assert(setround_ok == 0); 11387 /* ... */ 11388 fesetround(save_round); 11389 /* ... */ 11390 } 11391 APPLICATION USAGE 11392 None. 11393 RATIONALE 11394 None. 804 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fegetround( ) 11395 FUTURE DIRECTIONS 11396 None. 11397 SEE ALSO 11398 The Base Definitions volume of IEEE Std 1003.1-200x, 11399 CHANGE HISTORY 11400 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11401 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 805 feholdexcept( ) System Interfaces 11402 NAME 11403 feholdexcept - save current floating-point environment 11404 SYNOPSIS 11405 #include 11406 int feholdexcept(fenv_t *envp); 11407 DESCRIPTION 11408 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11409 conflict between the requirements described here and the ISO C standard is unintentional. This 11410 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11411 The feholdexcept( ) function shall save the current floating-point environment in the object 11412 pointed to by envp, clear the floating-point status flags, and then install a non-stop (continue on 11413 floating-point exceptions) mode, if available, for all floating-point exceptions. 11414 RETURN VALUE 11415 The feholdexcept( ) function shall return zero if and only if non-stop floating-point exception 11416 handling was successfully installed. 11417 ERRORS 11418 No errors are defined. 11419 EXAMPLES 11420 None. 11421 APPLICATION USAGE 11422 None. 11423 RATIONALE 11424 The feholdexcept( ) function should be effective on typical IEC 60559: 1989 standard 11425 implementations which have the default non-stop mode and at least one other mode for trap 11426 handling or aborting. If the implementation provides only the non-stop mode, then installing the 11427 non-stop mode is trivial. 11428 FUTURE DIRECTIONS 11429 None. 11430 SEE ALSO 11431 fegetenv( ), fesetenv( ), feupdateenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11432 11433 CHANGE HISTORY 11434 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 806 Technical Standard (2001) (Draft April 16, 2001) System Interfaces feof( ) 11435 NAME 11436 feof - test end-of-file indicator on a stream 11437 SYNOPSIS 11438 #include 11439 int feof(FILE *stream); 11440 DESCRIPTION 11441 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11442 conflict between the requirements described here and the ISO C standard is unintentional. This 11443 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11444 The feof( ) function shall test the end-of-file indicator for the stream pointed to by stream. 11445 RETURN VALUE 11446 The feof( ) function shall return non-zero if and only if the end-of-file indicator is set for stream. 11447 ERRORS 11448 No errors are defined. 11449 EXAMPLES 11450 None. 11451 APPLICATION USAGE 11452 None. 11453 RATIONALE 11454 None. 11455 FUTURE DIRECTIONS 11456 None. 11457 SEE ALSO 11458 clearerr( ), ferror( ), fopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11459 CHANGE HISTORY 11460 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 807 feraiseexcept( ) System Interfaces 11461 NAME 11462 feraiseexcept - raise floating-point exception 11463 SYNOPSIS 11464 #include 11465 int feraiseexcept(int excepts); 11466 DESCRIPTION 11467 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11468 conflict between the requirements described here and the ISO C standard is unintentional. This 11469 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11470 The feraiseexcept( ) function shall attempt to raise the supported floating-point exceptions | 11471 represented by the argument excepts. The order in which these floating-point exceptions are 11472 raised is unspecified. Whether the feraiseexcept( ) function additionally raises the inexact 11473 floating-point exception whenever it raises the overflow or underflow floating-point exception is 11474 implementation-defined. 11475 RETURN VALUE 11476 If the argument is zero or if all the specified exceptions were successfully raised, feraiseexcept( ) | 11477 shall return zero. Otherwise, it shall return a non-zero value. | 11478 ERRORS 11479 No errors are defined. 11480 EXAMPLES 11481 None. 11482 APPLICATION USAGE 11483 The effect is intended to be similar to that of floating-point exceptions raised by arithmetic 11484 operations. Hence, enabled traps for floating-point exceptions raised by this function are taken. 11485 RATIONALE 11486 Raising overflow or underflow is allowed to also raise inexact because on some architectures the 11487 only practical way to raise an exception is to execute an instruction that has the exception as a 11488 side effect. The function is not restricted to accept only valid coincident expressions for atomic 11489 operations, so the function can be used to raise exceptions accrued over several operations. 11490 FUTURE DIRECTIONS 11491 None. 11492 SEE ALSO 11493 feclearexcept( ), fegetexceptflag( ), fesetexceptflag( ), fetestexcept( ), the Base Definitions volume of 11494 IEEE Std 1003.1-200x, 11495 CHANGE HISTORY 11496 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11497 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 808 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ferror( ) 11498 NAME 11499 ferror - test error indicator on a stream 11500 SYNOPSIS 11501 #include 11502 int ferror(FILE *stream); 11503 DESCRIPTION 11504 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11505 conflict between the requirements described here and the ISO C standard is unintentional. This 11506 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11507 The ferror( ) function shall test the error indicator for the stream pointed to by stream. 11508 RETURN VALUE 11509 The ferror( ) function shall return non-zero if and only if the error indicator is set for stream. 11510 ERRORS 11511 No errors are defined. 11512 EXAMPLES 11513 None. 11514 APPLICATION USAGE 11515 None. 11516 RATIONALE 11517 None. 11518 FUTURE DIRECTIONS 11519 None. 11520 SEE ALSO 11521 clearerr( ), feof( ), fopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11522 CHANGE HISTORY 11523 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 809 fesetenv( ) System Interfaces 11524 NAME 11525 fesetenv - set current floating-point environment 11526 SYNOPSIS 11527 #include 11528 int fesetenv(const fenv_t *envp); 11529 DESCRIPTION 11530 Refer to fegetenv( ). 810 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fesetexceptflag( ) 11531 NAME 11532 fesetexceptflag - set floating-point status flags 11533 SYNOPSIS 11534 #include 11535 int fesetexceptflag(const fexcept_t *flagp, int excepts); 11536 DESCRIPTION 11537 Refer to fegetexceptflag( ). System Interfaces, Issue 6 811 fesetround( ) System Interfaces 11538 NAME 11539 fesetround - set current rounding direction 11540 SYNOPSIS 11541 #include 11542 int fesetround(int round); 11543 DESCRIPTION 11544 Refer to fegetround( ). 812 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fetestexcept( ) 11545 NAME 11546 fetestexcept - test floating-point exception flags 11547 SYNOPSIS 11548 #include 11549 int fetestexcept(int excepts); 11550 DESCRIPTION 11551 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11552 conflict between the requirements described here and the ISO C standard is unintentional. This 11553 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11554 The fetestexcept( ) function shall determine which of a specified subset of the floating-point 11555 exception flags are currently set. The excepts argument specifies the floating-point status flags to 11556 be queried. 11557 RETURN VALUE 11558 The fetestexcept( ) function shall return the value of the bitwise-inclusive OR of the floating-point 11559 exception macros corresponding to the currently set floating-point exceptions included in 11560 excepts. 11561 ERRORS 11562 No errors are defined. 11563 EXAMPLES 11564 The following example calls function f( ) if an invalid exception is set, and then function g( ) if an 11565 overflow exception is set: 11566 #include 11567 /* ... */ 11568 { 11569 #pragma STDC FENV_ACCESS ON 11570 int set_excepts; 11571 feclearexcept(FE_INVALID | FE_OVERFLOW); 11572 // maybe raise exceptions 11573 set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW); 11574 if (set_excepts & FE_INVALID) f(); 11575 if (set_excepts & FE_OVERFLOW) g(); 11576 /* ... */ 11577 } 11578 APPLICATION USAGE 11579 None. 11580 RATIONALE 11581 None. 11582 FUTURE DIRECTIONS 11583 None. 11584 SEE ALSO 11585 feclearexcept( ), fegetexceptflag( ), feraiseexcept( ), the Base Definitions volume of 11586 IEEE Std 1003.1-200x, System Interfaces, Issue 6 813 fetestexcept( ) System Interfaces 11587 CHANGE HISTORY 11588 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 814 Technical Standard (2001) (Draft April 16, 2001) System Interfaces feupdateenv( ) 11589 NAME 11590 feupdateenv - update floating-point environment 11591 SYNOPSIS 11592 #include 11593 int feupdateenv(const fenv_t *envp); 11594 DESCRIPTION 11595 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11596 conflict between the requirements described here and the ISO C standard is unintentional. This 11597 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11598 The feupdateenv( ) function shall attempt to save the currently raised floating-point exceptions in | 11599 its automatic storage, attempt to install the floating-point environment represented by the object | 11600 pointed to by envp, and then attempt to raise the saved floating-point exceptions. The argument | 11601 envp shall point to an object set by a call to feholdexcept( ) or fegetenv( ), or equal a floating-point 11602 environment macro. 11603 RETURN VALUE 11604 The feupdateenv( ) function shall return a zero value if and only if all the required actions were | 11605 successfully carried out. | 11606 ERRORS 11607 No errors are defined. 11608 EXAMPLES 11609 The following example shows sample code to hide spurious underflow floating-point 11610 exceptions: 11611 #include 11612 double f(double x) 11613 { 11614 #pragma STDC FENV_ACCESS ON 11615 double result; 11616 fenv_t save_env; 11617 feholdexcept(&save_env); 11618 // compute result 11619 if (/* test spurious underflow */) 11620 feclearexcept(FE_UNDERFLOW); 11621 feupdateenv(&save_env); 11622 return result; 11623 } 11624 APPLICATION USAGE 11625 None. 11626 RATIONALE 11627 None. 11628 FUTURE DIRECTIONS 11629 None. 11630 SEE ALSO 11631 fegetenv( ), feholdexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 815 feupdateenv( ) System Interfaces 11632 CHANGE HISTORY 11633 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. | 11634 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 816 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fflush( ) 11635 NAME 11636 fflush - flush a stream 11637 SYNOPSIS 11638 #include 11639 int fflush(FILE *stream); 11640 DESCRIPTION 11641 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11642 conflict between the requirements described here and the ISO C standard is unintentional. This 11643 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11644 If stream points to an output stream or an update stream in which the most recent operation was 11645 CX not input, fflush( ) shall cause any unwritten data for that stream to be written to the file, and the | 11646 st_ctime and st_mtime fields of the underlying file shall be marked for update. | 11647 If stream is a null pointer, fflush( ) shall perform this flushing action on all streams for which the 11648 behavior is defined above. 11649 RETURN VALUE 11650 Upon successful completion, fflush( ) shall return 0; otherwise, it shall set the error indicator for 11651 CX the stream, return EOF, and set errno to indicate the error. 11652 ERRORS 11653 The fflush( ) function shall fail if: 11654 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 11655 process would be delayed in the write operation. 11656 CX [EBADF] The file descriptor underlying stream is not valid. 11657 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 11658 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 11659 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 11660 offset maximum associated with the corresponding stream. 11661 CX [EINTR] The fflush( ) function was interrupted by a signal. 11662 CX [EIO] The process is a member of a background process group attempting to write 11663 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 11664 blocking SIGTTOU, and the process group of the process is orphaned. This 11665 error may also be returned under implementation-defined conditions. 11666 CX [ENOSPC] There was no free space remaining on the device containing the file. 11667 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 11668 any process. A SIGPIPE signal shall also be sent to the thread. 11669 The fflush( ) function may fail if: 11670 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 11671 capabilities of the device. System Interfaces, Issue 6 817 fflush( ) System Interfaces 11672 EXAMPLES 11673 Sending Prompts to Standard Output 11674 The following example uses printf( ) calls to print a series of prompts for information the user 11675 must enter from standard input. The fflush( ) calls force the output to standard output. The 11676 fflush( ) function is used because standard output is usually buffered and the prompt may not 11677 immediately be printed on the output or terminal. The gets( ) calls read strings from standard 11678 input and place the results in variables, for use later in the program 11679 #include 11680 ... 11681 char user[100]; 11682 char oldpasswd[100]; 11683 char newpasswd[100]; 11684 ... 11685 printf("User name: "); 11686 fflush(stdout); 11687 gets(user); 11688 printf("Old password: "); 11689 fflush(stdout); 11690 gets(oldpasswd); 11691 printf("New password: "); 11692 fflush(stdout); 11693 gets(newpasswd); 11694 ... 11695 APPLICATION USAGE 11696 None. 11697 RATIONALE 11698 Data buffered by the system may make determining the validity of the position of the current 11699 file descriptor impractical. Thus, enforcing the repositioning of the file descriptor after fflush( ) 11700 on streams open for read( ) is not mandated by IEEE Std 1003.1-200x. 11701 FUTURE DIRECTIONS 11702 None. 11703 SEE ALSO 11704 getrlimit( ), ulimit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11705 CHANGE HISTORY 11706 First released in Issue 1. Derived from Issue 1 of the SVID. 11707 Issue 5 11708 Large File Summit extensions are added. 11709 Issue 6 11710 Extensions beyond the ISO C standard are now marked. 11711 The following new requirements on POSIX implementations derive from alignment with the 11712 Single UNIX Specification: 11713 * The [EFBIG] error is added as part of the large file support extensions. 11714 * The [ENXIO] optional error condition is added. 818 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fflush( ) 11715 The RETURN VALUE section is updated to note that the error indicator shall be set for the 11716 stream. This is for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 819 ffs( ) System Interfaces 11717 NAME 11718 ffs - find first set bit 11719 SYNOPSIS 11720 XSI #include 11721 int ffs(int i); 11722 11723 DESCRIPTION 11724 The ffs( ) function shall find the first bit set (beginning with the least significant bit) in i, and 11725 return the index of that bit. Bits are numbered starting at one (the least significant bit). 11726 RETURN VALUE 11727 The ffs( ) function shall return the index of the first bit set. If i is 0, then ffs( ) shall return 0. 11728 ERRORS 11729 No errors are defined. 11730 EXAMPLES 11731 None. 11732 APPLICATION USAGE 11733 None. 11734 RATIONALE 11735 None. 11736 FUTURE DIRECTIONS 11737 None. 11738 SEE ALSO 11739 The Base Definitions volume of IEEE Std 1003.1-200x, 11740 CHANGE HISTORY 11741 First released in Issue 4, Version 2. 11742 Issue 5 11743 Moved from X/OPEN UNIX extension to BASE. 820 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fgetc( ) 11744 NAME 11745 fgetc - get a byte from a stream 11746 SYNOPSIS 11747 #include 11748 int fgetc(FILE *stream); 11749 DESCRIPTION 11750 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11751 conflict between the requirements described here and the ISO C standard is unintentional. This 11752 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11753 If the end-of-file indicator for the input stream pointed to by stream is not set and a next byte is 11754 present, the fgetc( ) function shall obtain the next byte as an unsigned char converted to an int, | 11755 from the input stream pointed to by stream, and advance the associated file position indicator for | 11756 the stream (if defined). Since fgetc( ) operates on bytes, reading a character consisting of multiple | 11757 bytes (or ``a multi-byte character'') may require multiple calls to fgetc( ). 11758 CX The fgetc( ) function may mark the st_atime field of the file associated with stream for update. The 11759 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11760 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11761 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11762 RETURN VALUE 11763 Upon successful completion, fgetc( ) shall return the next byte from the input stream pointed to 11764 by stream. If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the 11765 end-of-file indicator for the stream shall be set and fgetc( ) shall return EOF. If a read error occurs, 11766 CX the error indicator for the stream shall be set, fgetc( ) shall return EOF, and shall set errno to 11767 indicate the error. 11768 ERRORS 11769 The fgetc( ) function shall fail if data needs to be read and: 11770 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 11771 process would be delayed in the fgetc( ) operation. 11772 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 11773 reading. 11774 CX [EINTR] The read operation was terminated due to the receipt of a signal, and no data 11775 was transferred. 11776 CX [EIO] A physical I/O error has occurred, or the process is in a background process 11777 group attempting to read from its controlling terminal, and either the process 11778 is ignoring or blocking the SIGTTIN signal or the process group is orphaned. 11779 This error may also be generated for implementation-defined reasons. 11780 CX [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the 11781 offset maximum associated with the corresponding stream. 11782 The fgetc( ) function may fail if: 11783 CX [ENOMEM] Insufficient storage space is available. 11784 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 11785 capabilities of the device. System Interfaces, Issue 6 821 fgetc( ) System Interfaces 11786 EXAMPLES 11787 None. 11788 APPLICATION USAGE 11789 If the integer value returned by fgetc( ) is stored into a variable of type char and then compared 11790 against the integer constant EOF, the comparison may never succeed, because sign-extension of 11791 a variable of type char on widening to integer is implementation-defined. 11792 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 11793 end-of-file condition. 11794 RATIONALE 11795 None. 11796 FUTURE DIRECTIONS 11797 None. 11798 SEE ALSO 11799 feof( ), ferror( ), fopen( ), getchar( ), getc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11800 11801 CHANGE HISTORY 11802 First released in Issue 1. Derived from Issue 1 of the SVID. 11803 Issue 5 11804 Large File Summit extensions are added. 11805 Issue 6 11806 Extensions beyond the ISO C standard are now marked. 11807 The following new requirements on POSIX implementations derive from alignment with the 11808 Single UNIX Specification: 11809 * The [EIO] and [EOVERFLOW] mandatory error conditions are added. 11810 * The [ENOMEM] and [ENXIO] optional error conditions are added. 11811 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 11812 * The DESCRIPTION is updated to clarify the behavior when the end-of-file indicator for the 11813 input stream is not set. 11814 * The RETURN VALUE section is updated to note that the error indicator shall be set for the 11815 stream. 822 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fgetpos( ) 11816 NAME 11817 fgetpos - get current file position information 11818 SYNOPSIS 11819 #include 11820 int fgetpos(FILE *restrict stream, fpos_t *restrict pos); 11821 DESCRIPTION 11822 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11823 conflict between the requirements described here and the ISO C standard is unintentional. This 11824 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11825 The fgetpos( ) function shall store the current values of the parse state (if any) and file position 11826 indicator for the stream pointed to by stream in the object pointed to by pos. The value stored 11827 contains unspecified information usable by fsetpos( ) for repositioning the stream to its position 11828 at the time of the call to fgetpos( ). 11829 RETURN VALUE 11830 Upon successful completion, fgetpos( ) shall return 0; otherwise, it shall return a non-zero value 11831 and set errno to indicate the error. 11832 ERRORS 11833 The fgetpos( ) function shall fail if: 11834 CX [EOVERFLOW] The current value of the file position cannot be represented correctly in an 11835 object of type fpos_t. 11836 The fgetpos( ) function may fail if: 11837 CX [EBADF] The file descriptor underlying stream is not valid. 11838 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe, FIFO, or socket. 11839 11840 EXAMPLES 11841 None. 11842 APPLICATION USAGE 11843 None. 11844 RATIONALE 11845 None. 11846 FUTURE DIRECTIONS 11847 None. 11848 SEE ALSO 11849 fopen( ), ftell( ), rewind( ), ungetc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11850 CHANGE HISTORY 11851 First released in Issue 4. Derived from the ISO C standard. 11852 Issue 5 11853 Large File Summit extensions are added. 11854 Issue 6 11855 Extensions beyond the ISO C standard are now marked. 11856 The following new requirements on POSIX implementations derive from alignment with the 11857 Single UNIX Specification: System Interfaces, Issue 6 823 fgetpos( ) System Interfaces 11858 * The [EIO] mandatory error condition is added. 11859 * The [EBADF] and [ESPIPE] optional error conditions are added. 11860 An additional [ESPIPE] error condition is added for sockets. 11861 The prototype for fgetpos( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. 824 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fgets( ) 11862 NAME 11863 fgets - get a string from a stream 11864 SYNOPSIS 11865 #include 11866 char *fgets(char *restrict s, int n, FILE *restrict stream); 11867 DESCRIPTION 11868 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11869 conflict between the requirements described here and the ISO C standard is unintentional. This 11870 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11871 The fgets( ) function shall read bytes from stream into the array pointed to by s, until n-1 bytes 11872 are read, or a is read and transferred to s, or an end-of-file condition is encountered. 11873 The string is then terminated with a null byte. 11874 CX The fgets( ) function may mark the st_atime field of the file associated with stream for update. The 11875 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11876 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11877 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11878 RETURN VALUE 11879 Upon successful completion, fgets( ) shall return s. If the stream is at end-of-file, the end-of-file 11880 indicator for the stream shall be set and fgets( ) shall return a null pointer. If a read error occurs, 11881 CX the error indicator for the stream shall be set, fgets( ) shall return a null pointer, and shall set 11882 errno to indicate the error. 11883 ERRORS 11884 Refer to fgetc( ). 11885 EXAMPLES 11886 Reading Input 11887 The following example uses fgets( ) to read each line of input. {LINE_MAX}, which defines the 11888 maximum size of the input line, is defined in the header. 11889 #include 11890 ... 11891 char line[LINE_MAX]; 11892 ... 11893 while (fgets(line, LINE_MAX, fp) != NULL) { 11894 ... 11895 } 11896 ... 11897 APPLICATION USAGE 11898 None. 11899 RATIONALE 11900 None. 11901 FUTURE DIRECTIONS 11902 None. System Interfaces, Issue 6 825 fgets( ) System Interfaces 11903 SEE ALSO 11904 fopen( ), fread( ), gets( ), the Base Definitions volume of IEEE Std 1003.1-200x, 11905 CHANGE HISTORY 11906 First released in Issue 1. Derived from Issue 1 of the SVID. 11907 Issue 6 11908 Extensions beyond the ISO C standard are now marked. 11909 The prototype for fgets( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. 826 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fgetwc( ) 11910 NAME 11911 fgetwc - get a wide-character code from a stream 11912 SYNOPSIS 11913 #include 11914 #include 11915 wint_t fgetwc(FILE *stream); 11916 DESCRIPTION 11917 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11918 conflict between the requirements described here and the ISO C standard is unintentional. This 11919 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11920 The fgetwc( ) function shall obtain the next character (if present) from the input stream pointed to 11921 by stream, convert that to the corresponding wide-character code, and advance the associated 11922 file position indicator for the stream (if defined). 11923 If an error occurs, the resulting value of the file position indicator for the stream is unspecified. | 11924 CX The fgetwc( ) function may mark the st_atime field of the file associated with stream for update. 11925 The st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11926 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11927 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11928 RETURN VALUE 11929 Upon successful completion, the fgetwc( ) function shall return the wide-character code of the 11930 character read from the input stream pointed to by stream converted to a type wint_t. If the 11931 stream is at end-of-file, the end-of-file indicator for the stream shall be set and fgetwc( ) shall 11932 return WEOF. If a read error occurs, the error indicator for the stream shall be set, fgetwc( ) shall 11933 CX return WEOF, and shall set errno to indicate the error. If an encoding error occurs, the error | 11934 indicator for the stream shall be set, fgetwc( ) shall return WEOF, and shall set errno to indicate | 11935 the error. | 11936 ERRORS 11937 The fgetwc( ) function shall fail if data needs to be read and: 11938 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 11939 process would be delayed in the fgetwc( ) operation. 11940 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 11941 reading. | 11942 [EILSEQ] The data obtained from the input stream does not form a valid character. | 11943 CX [EINTR] The read operation was terminated due to the receipt of a signal, and no data 11944 was transferred. 11945 CX [EIO] A physical I/O error has occurred, or the process is in a background process 11946 group attempting to read from its controlling terminal, and either the process 11947 is ignoring or blocking the SIGTTIN signal or the process group is orphaned. 11948 This error may also be generated for implementation-defined reasons. 11949 CX [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the 11950 offset maximum associated with the corresponding stream. 11951 The fgetwc( ) function may fail if: 11952 CX [ENOMEM] Insufficient storage space is available. System Interfaces, Issue 6 827 fgetwc( ) System Interfaces 11953 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 11954 capabilities of the device. | 11955 EXAMPLES 11956 None. 11957 APPLICATION USAGE 11958 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 11959 end-of-file condition. 11960 RATIONALE 11961 None. 11962 FUTURE DIRECTIONS 11963 None. 11964 SEE ALSO 11965 feof( ), ferror( ), fopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 11966 11967 CHANGE HISTORY 11968 First released in Issue 4. Derived from the MSE working draft. 11969 Issue 5 11970 The Optional Header (OH) marking is removed from . 11971 Large File Summit extensions are added. 11972 Issue 6 11973 Extensions beyond the ISO C standard are now marked. 11974 The following new requirements on POSIX implementations derive from alignment with the 11975 Single UNIX Specification: 11976 * The [EIO] and [EOVERFLOW] mandatory error conditions are added. 11977 * The [ENOMEM] and [ENXIO] optional error conditions are added. | 828 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fgetws( ) 11978 NAME 11979 fgetws - get a wide-character string from a stream 11980 SYNOPSIS 11981 #include 11982 #include 11983 wchar_t *fgetws(wchar_t *restrict ws, int n, 11984 FILE *restrict stream); 11985 DESCRIPTION 11986 CX The functionality described on this reference page is aligned with the ISO C standard. Any 11987 conflict between the requirements described here and the ISO C standard is unintentional. This 11988 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 11989 The fgetws( ) function shall read characters from the stream, convert these to the corresponding 11990 wide-character codes, place them in the wchar_t array pointed to by ws, until n-1 characters are 11991 read, or a is read, converted, and transferred to ws, or an end-of-file condition is 11992 encountered. The wide-character string, ws, shall then be terminated with a null wide-character | 11993 code. | 11994 If an error occurs, the resulting value of the file position indicator for the stream is unspecified. | 11995 CX The fgetws( ) function may mark the st_atime field of the file associated with stream for update. 11996 The st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 11997 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 11998 data not supplied by a prior call to ungetc( ) or ungetwc( ). 11999 RETURN VALUE 12000 Upon successful completion, fgetws( ) shall return ws. If the stream is at end-of-file, the end-of- 12001 file indicator for the stream shall be set and fgetws( ) shall return a null pointer. If a read error 12002 CX occurs, the error indicator for the stream shall be set, fgetws( ) shall return a null pointer, and 12003 shall set errno to indicate the error. 12004 ERRORS 12005 Refer to fgetwc( ). 12006 EXAMPLES 12007 None. 12008 APPLICATION USAGE 12009 None. 12010 RATIONALE 12011 None. 12012 FUTURE DIRECTIONS 12013 None. 12014 SEE ALSO 12015 fopen( ), fread( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 12016 CHANGE HISTORY 12017 First released in Issue 4. Derived from the MSE working draft. 12018 Issue 5 12019 The Optional Header (OH) marking is removed from . System Interfaces, Issue 6 829 fgetws( ) System Interfaces 12020 Issue 6 12021 Extensions beyond the ISO C standard are now marked. 12022 The prototype for fgetws( ) is changed for alignment with the ISO/IEC 9899: 1999 standard. 830 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fileno( ) 12023 NAME 12024 fileno - map a stream pointer to a file descriptor 12025 SYNOPSIS 12026 CX #include | 12027 int fileno(FILE *stream); 12028 | 12029 DESCRIPTION 12030 The fileno( ) function shall return the integer file descriptor associated with the stream pointed to 12031 by stream. 12032 RETURN VALUE 12033 Upon successful completion, fileno( ) shall return the integer value of the file descriptor 12034 associated with stream. Otherwise, the value -1 shall be returned and errno set to indicate the 12035 error. 12036 ERRORS 12037 The fileno( ) function may fail if: 12038 [EBADF] The stream argument is not a valid stream. 12039 EXAMPLES 12040 None. 12041 APPLICATION USAGE 12042 None. 12043 RATIONALE 12044 Without some specification of which file descriptors are associated with these streams, it is 12045 impossible for an application to set up the streams for another application it starts with fork( ) 12046 and exec. In particular, it would not be possible to write a portable version of the sh command 12047 interpreter (although there may be other constraints that would prevent that portability). 12048 FUTURE DIRECTIONS 12049 None. 12050 SEE ALSO 12051 fdopen( ), fopen( ), stdin, the Base Definitions volume of IEEE Std 1003.1-200x, , Section 12052 2.5.1 (on page 485) 12053 CHANGE HISTORY 12054 First released in Issue 1. Derived from Issue 1 of the SVID. 12055 Issue 6 12056 The following new requirements on POSIX implementations derive from alignment with the 12057 Single UNIX Specification: 12058 * The [EBADF] optional error condition is added. System Interfaces, Issue 6 831 flockfile( ) System Interfaces 12059 NAME 12060 flockfile, ftrylockfile, funlockfile - stdio locking functions 12061 SYNOPSIS 12062 TSF #include 12063 void flockfile(FILE *file); 12064 int ftrylockfile(FILE *file); 12065 void funlockfile(FILE *file); 12066 12067 DESCRIPTION 12068 These functions shall provide for explicit application-level locking of stdio (FILE *) objects. | 12069 These functions can be used by a thread to delineate a sequence of I/O statements that are 12070 executed as a unit. 12071 The flockfile ( ) function shall acquire for a thread ownership of a (FILE *) object. | 12072 The ftrylockfile ( ) function shall acquire for a thread ownership of a (FILE *) object if the object is | 12073 available; ftrylockfile ( ) is a non-blocking version of flockfile ( ). 12074 The funlockfile ( ) function shall relinquish the ownership granted to the thread. The behavior is | 12075 undefined if a thread other than the current owner calls the funlockfile ( ) function. 12076 The functions shall behave as if there is a lock count associated with each (FILE *) object. This | 12077 count is implicitly initialized to zero when the (FILE *) object is created. The (FILE *) object is 12078 unlocked when the count is zero. When the count is positive, a single thread owns the (FILE *) 12079 object. When the flockfile ( ) function is called, if the count is zero or if the count is positive and 12080 the caller owns the (FILE *) object, the count shall be incremented. Otherwise, the calling thread | 12081 shall be suspended, waiting for the count to return to zero. Each call to funlockfile ( ) shall | 12082 decrement the count. This allows matching calls to flockfile ( ) (or successful calls to ftrylockfile ( )) | 12083 and funlockfile ( ) to be nested. 12084 All functions that reference (FILE *) objects shall behave as if they use flockfile ( ) and funlockfile ( ) 12085 internally to obtain ownership of these (FILE *) objects. 12086 RETURN VALUE 12087 None for flockfile ( ) and funlockfile ( ). The ftrylockfile ( ) function shall return zero for success and 12088 non-zero to indicate that the lock cannot be acquired. 12089 ERRORS 12090 No errors are defined. 12091 EXAMPLES 12092 None. 12093 APPLICATION USAGE 12094 Applications using these functions may be subject to priority inversion, as discussed in the Base 12095 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 12096 RATIONALE 12097 The flockfile ( ) and funlockfile ( ) functions provide an orthogonal mutual exclusion lock for each 12098 FILE. The ftrylockfile ( ) function provides a non-blocking attempt to acquire a file lock, 12099 analogous to pthread_mutex_trylock( ). 12100 These locks behave as if they are the same as those used internally by stdio for thread-safety. 12101 This both provides thread-safety of these functions without requiring a second level of internal 12102 locking and allows functions in stdio to be implemented in terms of other stdio functions. 832 Technical Standard (2001) (Draft April 16, 2001) System Interfaces flockfile( ) 12103 Application writers and implementors should be aware that there are potential deadlock 12104 problems on FILE objects. For example, the line-buffered flushing semantics of stdio (requested 12105 via {_IOLBF}) require that certain input operations sometimes cause the buffered contents of 12106 implementation-defined line-buffered output streams to be flushed. If two threads each hold the 12107 lock on the other's FILE, deadlock ensues. This type of deadlock can be avoided by acquiring 12108 FILE locks in a consistent order. In particular, the line-buffered output stream deadlock can 12109 typically be avoided by acquiring locks on input streams before locks on output streams if a 12110 thread would be acquiring both. 12111 In summary, threads sharing stdio streams with other threads can use flockfile ( ) and funlockfile ( ) 12112 to cause sequences of I/O performed by a single thread to be kept bundled. The only case where 12113 the use of flockfile ( ) and funlockfile ( ) is required is to provide a scope protecting uses of the 12114 *_unlocked( ) functions/macros. This moves the cost/performance tradeoff to the optimal point. 12115 FUTURE DIRECTIONS 12116 None. 12117 SEE ALSO 12118 getc_unlocked( ), putc_unlocked( ), the Base Definitions volume of IEEE Std 1003.1-200x, 12119 CHANGE HISTORY 12120 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 12121 Issue 6 12122 These functions are marked as part of the Thread-Safe Functions option. System Interfaces, Issue 6 833 floor( ) System Interfaces 12123 NAME 12124 floor, floorf, floorl - floor function 12125 SYNOPSIS 12126 #include 12127 double floor(double x); 12128 float floorf(float x); 12129 long double floorl(long double x); 12130 DESCRIPTION 12131 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12132 conflict between the requirements described here and the ISO C standard is unintentional. This 12133 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 12134 These functions shall compute the largest integral value not greater than x. 12135 An application wishing to check for error situations should set errno to zero and call 12136 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 12137 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 12138 zero, an error has occurred. 12139 RETURN VALUE 12140 Upon successful completion, these functions shall return the largest integral value not greater 12141 than x, expressed as a double, float, or long double, as appropriate for the return type of the 12142 function. 12143 MX If x is NaN, a NaN shall be returned. 12144 If x is ±0 or ±Inf, x shall be returned. 12145 XSI If the correct value would cause overflow, a range error shall occur and floor( ), floorf( ), and 12146 floorl( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 12147 respectively. 12148 ERRORS 12149 These functions shall fail if: 12150 XSI Range Error The result would cause an overflow. 12151 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12152 then errno shall be set to [ERANGE]. If the integer expression | 12153 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 12154 floating-point exception shall be raised. | 12155 EXAMPLES 12156 None. 12157 APPLICATION USAGE 12158 The integral value returned by these functions might not be expressible as an int or long. The 12159 return value should be tested before assigning it to an integer type to avoid the undefined results 12160 of an integer overflow. 12161 The floor( ) function can only overflow when the floating-point representation has 12162 DBL_MANT_DIG > DBL_MAX_EXP. 12163 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 12164 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 834 Technical Standard (2001) (Draft April 16, 2001) System Interfaces floor( ) 12165 RATIONALE 12166 None. 12167 FUTURE DIRECTIONS 12168 None. 12169 SEE ALSO 12170 ceil( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 12171 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 12172 CHANGE HISTORY 12173 First released in Issue 1. Derived from Issue 1 of the SVID. 12174 Issue 5 12175 The DESCRIPTION is updated to indicate how an application should check for an error. This 12176 text was previously published in the APPLICATION USAGE section. 12177 Issue 6 12178 The floorf( ) and floorl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 12179 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 12180 revised to align with the ISO/IEC 9899: 1999 standard. 12181 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 12182 marked. System Interfaces, Issue 6 835 fma( ) System Interfaces 12183 NAME 12184 fma, fmaf, fmal - floating-point multiply-add 12185 SYNOPSIS 12186 #include 12187 double fma(double x, double y, double z); 12188 float fmaf(float x, float y, float z); 12189 long double fmal(long double x, long double y, long double z); 12190 DESCRIPTION 12191 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12192 conflict between the requirements described here and the ISO C standard is unintentional. This 12193 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 12194 These functions shall compute (x * y) + z, rounded as one ternary operation: they shall compute 12195 the value (as if) to infinite precision and round once to the result format, according to the 12196 rounding mode characterized by the value of FLT_ROUNDS. 12197 An application wishing to check for error situations should set errno to zero and call 12198 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 12199 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 12200 zero, an error has occurred. 12201 RETURN VALUE 12202 Upon successful completion, these functions shall return (x * y) + z, rounded as one ternary 12203 operation. 12204 MX If x or y are NaN, a NaN shall be returned. 12205 If x multiplied by y is an exact infinity and z is also an infinity but with the opposite sign, a 12206 domain error shall occur, and either a NaN (if supported), or an implementation-defined value 12207 shall be returned. 12208 If one of x and y is infinite, the other is zero, and z is not a NaN, a domain error shall occur, and 12209 either a NaN (if supported), or an implementation-defined value shall be returned. 12210 If one of x and y is infinite, the other is zero, and z is a NaN, a NaN shall be returned and a 12211 domain error may occur. 12212 If x*y is not 0*Inf nor Inf*0 and z is a NaN, a NaN shall be returned. 12213 ERRORS 12214 These functions shall fail if: 12215 MX Domain Error The value of x*y+z is invalid, or the value x*y is invalid and z is not a NaN. 12216 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12217 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 12218 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 12219 shall be raised. | 12220 MX Range Error The result overflows. 12221 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12222 then errno shall be set to [ERANGE]. If the integer expression | 12223 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 12224 floating-point exception shall be raised. | 12225 These functions may fail if: 836 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fma( ) 12226 MX Domain Error The value x*y is invalid and z is a NaN. 12227 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12228 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 12229 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 12230 shall be raised. | 12231 MX Range Error The result underflows. 12232 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12233 then errno shall be set to [ERANGE]. If the integer expression | 12234 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 12235 floating-point exception shall be raised. | 12236 EXAMPLES 12237 None. 12238 APPLICATION USAGE 12239 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 12240 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 12241 RATIONALE 12242 In many cases, clever use of floating (fused) multiply-add leads to much improved code; but its 12243 unexpected use by the compiler can undermine carefully written code. The FP_CONTRACT 12244 macro can be used to disallow use of floating multiply-add; and the fma( ) function guarantees 12245 its use where desired. Many current machines provide hardware floating multiply-add 12246 instructions; software implementation can be used for others. 12247 FUTURE DIRECTIONS 12248 None. 12249 SEE ALSO 12250 feclearexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section 4.18, | 12251 Treatment of Error Conditions for Mathematical Functions, | 12252 CHANGE HISTORY 12253 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 837 fmax( ) System Interfaces 12254 NAME 12255 fmax, fmaxf, fmaxl - determine maximum numeric value of two floating-point numbers 12256 SYNOPSIS 12257 #include 12258 double fmax(double x, double y); 12259 float fmaxf(float x, float y); 12260 long double fmaxl(long double x, long double y); 12261 DESCRIPTION 12262 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12263 conflict between the requirements described here and the ISO C standard is unintentional. This 12264 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 12265 These functions shall determine the maximum numeric value of their arguments. NaN 12266 arguments shall be treated as missing data: if one argument is a NaN and the other numeric, 12267 then these functions shall choose the numeric value. 12268 RETURN VALUE 12269 Upon successful completion, these functions shall return the maximum numeric value of their 12270 arguments. 12271 If just one argument is a NaN, the other argument shall be returned. 12272 MX If x and y are NaN, a NaN shall be returned. 12273 ERRORS 12274 No errors are defined. 12275 EXAMPLES 12276 None. 12277 APPLICATION USAGE 12278 None. 12279 RATIONALE 12280 None. 12281 FUTURE DIRECTIONS 12282 None. 12283 SEE ALSO 12284 fdim( ), fmin( ), the Base Definitions volume of IEEE Std 1003.1-200x, 12285 CHANGE HISTORY 12286 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 838 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fmin( ) 12287 NAME 12288 fmin, fminf, fminl - determine minimum numeric value of two floating-point numbers 12289 SYNOPSIS 12290 #include 12291 double fmin(double x, double y); 12292 float fminf(float x, float y); 12293 long double fminl(long double x, long double y); 12294 DESCRIPTION 12295 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12296 conflict between the requirements described here and the ISO C standard is unintentional. This 12297 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 12298 These functions shall determine the minimum numeric value of their arguments. NaN 12299 arguments shall be treated as missing data: if one argument is a NaN and the other numeric, 12300 then these functions shall choose the numeric value. 12301 RETURN VALUE 12302 Upon successful completion, these functions shall return the minimum numeric value of their 12303 arguments. 12304 If just one argument is a NaN, the other argument shall be returned. 12305 MX If x and y are NaN, a NaN shall be returned. 12306 ERRORS 12307 No errors are defined. 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 839 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 zero and call 12333 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 12334 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 12335 zero, an error has occurred. 12336 RETURN VALUE 12337 These functions shall return the value x-i*y, for some integer i such that, if y is non-zero, the 12338 result has the same sign as x and magnitude less than the magnitude of y. 12339 If the correct value would cause underflow, and is not representable, a range error may occur, 12340 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 12341 MX If x or y is NaN, a NaN shall be returned. 12342 If y is zero, a domain error shall occur, and either a NaN (if supported), or an implementation- 12343 defined value shall be returned. 12344 If x is infinite, a domain error shall occur, and either a NaN (if supported), or an 12345 implementation-defined value shall be returned. 12346 If x is ±0 and y is not zero, ±0 shall be returned. 12347 If x is not infinite and y is ±Inf, x shall be returned. 12348 If the correct value would cause underflow, and is representable, a range error may occur and 12349 the correct value shall be returned. 12350 ERRORS 12351 These functions shall fail if: 12352 MX Domain Error The x argument is infinite or y is zero. 12353 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12354 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 12355 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 12356 shall be raised. | 12357 These functions may fail if: 12358 Range Error The result underflows. 12359 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 12360 then errno shall be set to [ERANGE]. If the integer expression | 12361 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 12362 floating-point exception shall be raised. | 840 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fmod( ) 12363 EXAMPLES 12364 None. 12365 APPLICATION USAGE 12366 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 12367 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 12368 RATIONALE 12369 None. 12370 FUTURE DIRECTIONS 12371 None. 12372 SEE ALSO 12373 feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 12374 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 12375 CHANGE HISTORY 12376 First released in Issue 1. Derived from Issue 1 of the SVID. 12377 Issue 5 12378 The DESCRIPTION is updated to indicate how an application should check for an error. This 12379 text was previously published in the APPLICATION USAGE section. 12380 Issue 6 12381 The behavior for when the y argument is zero is now defined. 12382 The fmodf( ) and fmodl( ) functions are added for alignment with the ISO/IEC 9899: 1999 12383 standard. 12384 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 12385 revised to align with the ISO/IEC 9899: 1999 standard. 12386 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 12387 marked. System Interfaces, Issue 6 841 fmtmsg( ) System Interfaces 12388 NAME 12389 fmtmsg - display a message in the specified format on standard error and/or a system console 12390 SYNOPSIS 12391 XSI #include 12392 int fmtmsg(long classification, const char *label, int severity, 12393 const char *text, const char *action, const char *tag); 12394 12395 DESCRIPTION 12396 The fmtmsg( ) function shall display messages in a specified format instead of the traditional | 12397 printf( ) function. 12398 Based on a message's classification component, fmtmsg( ) shall write a formatted message either | 12399 to standard error, to the console, or to both. | 12400 A formatted message consists of up to five components as defined below. The component 12401 classification is not part of a message displayed to the user, but defines the source of the message 12402 and directs the display of the formatted message. 12403 classification Contains the sum of identifying values constructed from the constants defined | 12404 below. Any one identifier from a subclass may be used in combination with a | 12405 single identifier from a different subclass. Two or more identifiers from the | 12406 same subclass should not be used together, with the exception of identifiers | 12407 from the display subclass. (Both display subclass identifiers may be used so 12408 that messages can be displayed to both standard error and the system 12409 console). 12410 Major Classifications 12411 Identifies the source of the condition. Identifiers are: MM_HARD 12412 (hardware), MM_SOFT (software), and MM_FIRM (firmware). 12413 Message Source Subclassifications 12414 Identifies the type of software in which the problem is detected. 12415 Identifiers are: MM_APPL (application), MM_UTIL (utility), and 12416 MM_OPSYS (operating system). 12417 Display Subclassifications 12418 Indicates where the message is to be displayed. Identifiers are: 12419 MM_PRINT to display the message on the standard error stream, 12420 MM_CONSOLE to display the message on the system console. One or 12421 both identifiers may be used. 12422 Status Subclassifications 12423 Indicates whether the application can recover from the condition. 12424 Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV (non- 12425 recoverable). 12426 An additional identifier, MM_NULLMC, indicates that no classification 12427 component is supplied for the message. 12428 label Identifies the source of the message. The format is two fields separated by a 12429 colon. The first field is up to 10 bytes, the second is up to 14 bytes. 12430 severity Indicates the seriousness of the condition. Identifiers for the levels of severity 12431 are: 842 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fmtmsg( ) 12432 MM_HALT Indicates that the application has encountered a severe fault 12433 and is halting. Produces the string "HALT". 12434 MM_ERROR Indicates that the application has detected a fault. Produces 12435 the string "ERROR". 12436 MM_WARNING Indicates a condition that is out of the ordinary, that might 12437 be a problem, and should be watched. Produces the string 12438 "WARNING". 12439 MM_INFO Provides information about a condition that is not in error. 12440 Produces the string "INFO". 12441 MM_NOSEV Indicates that no severity level is supplied for the message. 12442 text Describes the error condition that produced the message. The character string 12443 is not limited to a specific size. If the character string is empty, then the text 12444 produced is unspecified. 12445 action Describes the first step to be taken in the error-recovery process. The fmtmsg( ) 12446 function precedes the action string with the prefix: "TO FIX:". The action 12447 string is not limited to a specific size. 12448 tag An identifier that references on-line documentation for the message. 12449 Suggested usage is that tag includes the label and a unique identifying number. 12450 A sample tag is "XSI:cat:146". 12451 The MSGVERB environment variable (for message verbosity) shall determine for fmtmsg( ) | 12452 which message components it is to select when writing messages to standard error. The value of 12453 MSGVERB shall be a colon-separated list of optional keywords. Valid keywords are: label, severity, | 12454 text, action, and tag. If MSGVERB contains a keyword for a component and the component's | 12455 value is not the component's null value, fmtmsg( ) shall include that component in the message | 12456 when writing the message to standard error. If MSGVERB does not include a keyword for a | 12457 message component, that component is shall not be included in the display of the message. The | 12458 keywords may appear in any order. If MSGVERB is not defined, if its value is the null string, if | 12459 its value is not of the correct format, or if it contains keywords other than the valid ones listed 12460 above, fmtmsg( ) shall select all components. | 12461 MSGVERB shall determine which components are selected for display to standard error. All | 12462 message components shall be included in console messages. | 12463 RETURN VALUE 12464 The fmtmsg( ) function shall return one of the following values: 12465 MM_OK The function succeeded. 12466 MM_NOTOK The function failed completely. 12467 MM_NOMSG The function was unable to generate a message on standard error, but 12468 otherwise succeeded. 12469 MM_NOCON The function was unable to generate a console message, but otherwise 12470 succeeded. 12471 ERRORS 12472 None. System Interfaces, Issue 6 843 fmtmsg( ) System Interfaces 12473 EXAMPLES 12474 1. The following example of fmtmsg( ): 12475 fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", 12476 "refer to cat in user's reference manual", "XSI:cat:001") 12477 produces a complete message in the specified message format: 12478 XSI:cat: ERROR: illegal option 12479 TO FIX: refer to cat in user's reference manual XSI:cat:001 12480 2. When the environment variable MSGVERB is set as follows: 12481 MSGVERB=severity:text:action 12482 and Example 1 is used, fmtmsg( ) produces: 12483 ERROR: illegal option 12484 TO FIX: refer to cat in user's reference manual 12485 APPLICATION USAGE 12486 One or more message components may be systematically omitted from messages generated by 12487 an application by using the null value of the argument for that component. 12488 RATIONALE 12489 None. 12490 FUTURE DIRECTIONS 12491 None. 12492 SEE ALSO 12493 printf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 12494 CHANGE HISTORY 12495 First released in Issue 4, Version 2. 12496 Issue 5 12497 Moved from X/OPEN UNIX extension to BASE. 844 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fnmatch( ) 12498 NAME 12499 fnmatch - match a filename or a pathname | 12500 SYNOPSIS 12501 #include 12502 int fnmatch(const char *pattern, const char *string, int flags); 12503 DESCRIPTION 12504 The fnmatch( ) function shall match patterns as described in the Shell and Utilities volume of 12505 IEEE Std 1003.1-200x, Section 2.13.1, Patterns Matching a Single Character, and Section 2.13.2, 12506 Patterns Matching Multiple Characters. It checks the string specified by the string argument to 12507 see if it matches the pattern specified by the pattern argument. 12508 The flags argument shall modify the interpretation of pattern and string. It is the bitwise-inclusive | 12509 OR of zero or more of the flags defined in . If the FNM_PATHNAME flag is set in 12510 flags, then a slash character ('/') in string shall be explicitly matched by a slash in pattern; it shall 12511 not be matched by either the asterisk or question-mark special characters, nor by a bracket 12512 expression. If the FNM_PATHNAME flag is not set, the slash character shall be treated as an | 12513 ordinary character. | 12514 If FNM_NOESCAPE is not set in flags, a backslash character ('\') in pattern followed by any 12515 other character shall match that second character in string. In particular, "\\" shall match a 12516 backslash in string. If FNM_NOESCAPE is set, a backslash character shall be treated as an 12517 ordinary character. 12518 If FNM_PERIOD is set in flags, then a leading period ('.') in string shall match a period in 12519 pattern; as described by rule 2 in the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 12520 2.13.3, Patterns Used for Filename Expansion where the location of ``leading'' is indicated by the 12521 value of FNM_PATHNAME: 12522 * If FNM_PATHNAME is set, a period is ``leading'' if it is the first character in string or if it 12523 immediately follows a slash. 12524 * If FNM_PATHNAME is not set, a period is ``leading'' only if it is the first character of string. 12525 If FNM_PERIOD is not set, then no special restrictions are placed on matching a period. 12526 RETURN VALUE 12527 If string matches the pattern specified by pattern, then fnmatch( ) shall return 0. If there is no 12528 match, fnmatch( ) shall return FNM_NOMATCH, which is defined in . If an error | 12529 occurs, fnmatch( ) shall return another non-zero value. 12530 ERRORS 12531 No errors are defined. 12532 EXAMPLES 12533 None. 12534 APPLICATION USAGE 12535 The fnmatch( ) function has two major uses. It could be used by an application or utility that 12536 needs to read a directory and apply a pattern against each entry. The find utility is an example of 12537 this. It can also be used by the pax utility to process its pattern operands, or by applications that 12538 need to match strings in a similar manner. 12539 The name fnmatch( ) is intended to imply filename match, rather than pathname match. The default | 12540 action of this function is to match filenames, rather than pathnames, since it gives no special | 12541 significance to the slash character. With the FNM_PATHNAME flag, fnmatch( ) does match | 12542 pathnames, but without tilde expansion, parameter expansion, or special treatment for a period | System Interfaces, Issue 6 845 fnmatch( ) System Interfaces 12543 at the beginning of a filename. 12544 RATIONALE 12545 This function replaced the REG_FILENAME flag of regcomp( ) in early proposals of this volume 12546 of IEEE Std 1003.1-200x. It provides virtually the same functionality as the regcomp( ) and 12547 regexec( ) functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag 12548 was proposed for regcomp( ), and would have had the opposite effect from FNM_PATHNAME), 12549 but with a simpler function and less system overhead. 12550 FUTURE DIRECTIONS 12551 None. 12552 SEE ALSO 12553 glob( ), wordexp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell 12554 and Utilities volume of IEEE Std 1003.1-200x 12555 CHANGE HISTORY 12556 First released in Issue 4. Derived from the ISO POSIX-2 standard. 12557 Issue 5 12558 Moved from POSIX2 C-language Binding to BASE. 846 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fopen( ) 12559 NAME 12560 fopen - open a stream 12561 SYNOPSIS 12562 #include 12563 FILE *fopen(const char *restrict filename, const char *restrict mode); 12564 DESCRIPTION 12565 CX The functionality described on this reference page is aligned with the ISO C standard. Any 12566 conflict between the requirements described here and the ISO C standard is unintentional. This 12567 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 12568 The fopen( ) function shall open the file whose pathname is the string pointed to by filename, and | 12569 associates a stream with it. 12570 The mode argument points to a string. If the string is one of the following, the file shall be opened | 12571 in the indicated mode. Otherwise, the behavior is undefined. | 12572 r or rb Open file for reading. 12573 w or wb Truncate to zero length or create file for writing. 12574 a or ab Append; open or create file for writing at end-of-file. 12575 r+ or rb+ or r+b Open file for update (reading and writing). 12576 w+ or wb+ or w+b Truncate to zero length or create file for update. 12577 a+ or ab+ or a+b Append; open or create file for update, writing at end-of-file. 12578 CX The character 'b' shall have no effect, but is allowed for ISO C standard conformance. Opening | 12579 a file with read mode (r as the first character in the mode argument) shall fail if the file does not 12580 exist or cannot be read. 12581 Opening a file with append mode (a as the first character in the mode argument) shall cause all 12582 subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening 12583 calls to fseek( ). 12584 When a file is opened with update mode ('+' as the second or third character in the mode 12585 argument), both input and output may be performed on the associated stream. However, the 12586 application shall ensure that output is not directly followed by input without an intervening call 12587 to fflush( ) or to a file positioning function (fseek( ), fsetpos( ), or rewind( )), and input is not directly 12588 followed by output without an intervening call to a file positioning function, unless the input 12589 operation encounters end-of-file. 12590 When opened, a stream is fully buffered if and only if it can be determined not to refer to an 12591 interactive device. The error and end-of-file indicators for the stream shall be cleared. 12592 CX If mode is w, wb, a, ab, w+, wb+, w+b, a+, ab+, or a+b, and the file did not previously exist, upon 12593 successful completion, fopen( ) function shall mark for update the st_atime, st_ctime, and st_mtime 12594 fields of the file and the st_ctime and st_mtime fields of the parent directory. 12595 If mode is w, wb, w+, wb+, or w+b, and the file did previously exist, upon successful completion, 12596 fopen( ) shall mark for update the st_ctime and st_mtime fields of the file. The fopen( ) function 12597 shall allocate a file descriptor as open( ) does. 12598 XSI After a successful call to the fopen( ) function, the orientation of the stream shall be cleared, the 12599 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 12600 initial conversion state. System Interfaces, Issue 6 847 fopen( ) System Interfaces 12601 CX The largest value that can be represented correctly in an object of type off_t shall be established 12602 as the offset maximum in the open file description. 12603 RETURN VALUE 12604 Upon successful completion, fopen( ) shall return a pointer to the object controlling the stream. 12605 CX Otherwise, a null pointer shall be returned, and errno shall be set to indicate the error. 12606 ERRORS 12607 The fopen( ) function shall fail if: 12608 CX [EACCES] Search permission is denied on a component of the path prefix, or the file 12609 exists and the permissions specified by mode are denied, or the file does not 12610 exist and write permission is denied for the parent directory of the file to be 12611 created. 12612 CX [EINTR] A signal was caught during fopen( ). 12613 CX [EISDIR] The named file is a directory and mode requires write access. 12614 CX [ELOOP] A loop exists in symbolic links encountered during resolution of the path 12615 argument. 12616 CX [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 12617 CX [ENAMETOOLONG] 12618 The length of the filename argument exceeds {PATH_MAX} or a pathname | 12619 component is longer than {NAME_MAX}. | 12620 CX [ENFILE] The maximum allowable number of files is currently open in the system. 12621 CX [ENOENT] A component of filename does not name an existing file or filename is an empty 12622 string. 12623 CX [ENOSPC] The directory or file system that would contain the new file cannot be 12624 expanded, the file does not exist, and it was to be created. 12625 CX [ENOTDIR] A component of the path prefix is not a directory. 12626 CX [ENXIO] The named file is a character special or block special file, and the device 12627 associated with this special file does not exist. 12628 CX [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented 12629 correctly in an object of type off_t. 12630 CX [EROFS] The named file resides on a read-only file system and mode requires write 12631 access. 12632 The fopen( ) function may fail if: 12633 CX [EINVAL] The value of the mode argument is not valid. 12634 CX [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 12635 resolution of the path argument. 12636 CX [EMFILE] {FOPEN_MAX} streams are currently open in the calling process. 12637 CX [EMFILE] {STREAM_MAX} streams are currently open in the calling process. 12638 CX [ENAMETOOLONG] 12639 Pathname resolution of a symbolic link produced an intermediate result | 12640 whose length exceeds {PATH_MAX}. 848 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fopen( ) 12641 CX [ENOMEM] Insufficient storage space is available. 12642 CX [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode 12643 requires write access. 12644 EXAMPLES 12645 Opening a File 12646 The following example tries to open the file named file for reading. The fopen( ) function returns 12647 a file pointer that is used in subsequent fgets( ) and fclose( ) calls. If the program cannot open the 12648 file, it just ignores it. 12649 #include 12650 ... 12651 FILE *fp; 12652 ... 12653 void rgrep(const char *file) 12654 { 12655 ... 12656 if ((fp = fopen(file, "r")) == NULL) 12657 return; 12658 ... 12659 } 12660 APPLICATION USAGE 12661 None. 12662 RATIONALE 12663 None. 12664 FUTURE DIRECTIONS 12665 None. 12666 SEE ALSO 12667 fclose( ), fdopen( ), freopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, 12668 CHANGE HISTORY 12669 First released in Issue 1. Derived from Issue 1 of the SVID. 12670 Issue 5 12671 Large File Summit extensions are added. 12672 Issue 6 12673 Extensions beyond the ISO C standard are now marked. 12674 The following new requirements on POSIX implementations derive from alignment with the | 12675 Single UNIX Specification: 12676 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 12677 description. This change is to support large files. 12678 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 12679 large files. 12680 * The [ELOOP] mandatory error condition is added. 12681 * The [EINVAL], [EMFILE], [ENAMETOOLONG], [ENOMEM], and [ETXTBSY] optional error 12682 conditions are added. System Interfaces, Issue 6 849 fopen( ) System Interfaces 12683 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 12684 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 12685 * The prototype for fopen( ) is updated. 12686 * The DESCRIPTION is updated to note that if the argument mode points to a string other than 12687 those listed, then the behavior is undefined. 12688 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 12689 [ELOOP] error condition is added. 850 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fork( ) 12690 NAME 12691 fork - create a new process 12692 SYNOPSIS 12693 #include 12694 pid_t fork(void); 12695 DESCRIPTION 12696 The fork( ) function shall create a new process. The new process (child process) shall be an exact 12697 copy of the calling process (parent process) except as detailed below: 12698 * The child process shall have a unique process ID. | 12699 * The child process ID also shall not match any active process group ID. | 12700 * The child process shall have a different parent process ID, which shall be the process ID of | 12701 the calling process. | 12702 * The child process shall have its own copy of the parent's file descriptors. Each of the child's | 12703 file descriptors shall refer to the same open file description with the corresponding file | 12704 descriptor of the parent. | 12705 * The child process shall have its own copy of the parent's open directory streams. Each open | 12706 directory stream in the child process may share directory stream positioning with the 12707 corresponding directory stream of the parent. 12708 XSI * The child process shall have its own copy of the parent's message catalog descriptors. | 12709 * The child process' values of tms_utime, tms_stime, tms_cutime, and tms_cstime shall be set to 0. | 12710 * The time left until an alarm clock signal shall be reset to zero, and the alarm, if any, shall be | 12711 canceled; see alarm( ). | 12712 XSI * All semadj values shall be cleared. | 12713 * File locks set by the parent process shall not be inherited by the child process. | 12714 * The set of signals pending for the child process shall be initialized to the empty set. | 12715 XSI * Interval timers shall be reset in the child process. | 12716 SEM * Any semaphores that are open in the parent process shall also be open in the child process. 12717 ML * The child process shall not inherit any address space memory locks established by the parent 12718 process via calls to mlockall( ) or mlock( ). 12719 MF|SHM * Memory mappings created in the parent shall be retained in the child process. | 12720 MAP_PRIVATE mappings inherited from the parent shall also be MAP_PRIVATE mappings 12721 in the child, and any modifications to the data in these mappings made by the parent prior to 12722 calling fork( ) shall be visible to the child. Any modifications to the data in MAP_PRIVATE 12723 mappings made by the parent after fork( ) returns shall be visible only to the parent. 12724 Modifications to the data in MAP_PRIVATE mappings made by the child shall be visible only 12725 to the child. 12726 PS * For the SCHED_FIFO and SCHED_RR scheduling policies, the child process shall inherit the 12727 policy and priority settings of the parent process during a fork( ) function. For other 12728 scheduling policies, the policy and priority settings on fork( ) are implementation-defined. 12729 TMR * Per-process timers created by the parent shall not be inherited by the child process. | 12730 MSG * The child process shall have its own copy of the message queue descriptors of the parent. | 12731 Each of the message descriptors of the child shall refer to the same open message queue | System Interfaces, Issue 6 851 fork( ) System Interfaces 12732 description as the corresponding message descriptor of the parent. | 12733 AIO * No asynchronous input or asynchronous output operations shall be inherited by the child | 12734 process. | 12735 * A process shall be created with a single thread. If a multi-threaded process calls fork( ), the | 12736 new process shall contain a replica of the calling thread and its entire address space, possibly 12737 including the states of mutexes and other resources. Consequently, to avoid errors, the child 12738 process may only execute async-signal-safe operations until such time as one of the exec 12739 THR functions is called. Fork handlers may be established by means of the pthread_atfork( ) 12740 function in order to maintain application invariants across fork( ) calls. 12741 TRC TRI * If the Trace option and the Trace Inherit option are both supported: 12742 If the calling process was being traced in a trace stream that had its inheritance policy set to 12743 POSIX_TRACE_INHERITED, the child process shall be traced into that trace stream, and the 12744 child process shall inherit the parent's mapping of trace event names to trace event type 12745 identifiers. If the trace stream in which the calling process was being traced had its 12746 inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD, the child process shall not be 12747 traced into that trace stream. The inheritance policy is set by a call to the 12748 posix_trace_attr_setinherited( ) function. 12749 TRC * If the Trace option is supported, but the Trace Inherit option is not supported: 12750 The child process shall not be traced into any of the trace streams of its parent process. 12751 TRC * If the Trace option is supported, the child process of a trace controller process shall not 12752 control the trace streams controlled by its parent process. | 12753 CPT * The initial value of the CPU-time clock of the child process shall be set to zero. | 12754 TCT * The initial value of the CPU-time clock of the single thread of the child process shall be set to | 12755 zero. | 12756 All other process characteristics defined by IEEE Std 1003.1-200x shall be the same in the parent | 12757 and child processes. The inheritance of process characteristics not defined by 12758 IEEE Std 1003.1-200x is unspecified by IEEE Std 1003.1-200x. 12759 After fork( ), both the parent and the child processes shall be capable of executing independently 12760 before either one terminates. 12761 RETURN VALUE 12762 Upon successful completion, fork( ) shall return 0 to the child process and shall return the 12763 process ID of the child process to the parent process. Both processes shall continue to execute 12764 from the fork( ) function. Otherwise, -1 shall be returned to the parent process, no child process 12765 shall be created, and errno shall be set to indicate the error. 12766 ERRORS 12767 The fork( ) function shall fail if: 12768 [EAGAIN] The system lacked the necessary resources to create another process, or the 12769 system-imposed limit on the total number of processes under execution 12770 system-wide or by a single user {CHILD_MAX} would be exceeded. 12771 The fork( ) function may fail if: 12772 [ENOMEM] Insufficient storage space is available. 852 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fork( ) 12773 EXAMPLES 12774 None. 12775 APPLICATION USAGE 12776 None. 12777 RATIONALE 12778 Many historical implementations have timing windows where a signal sent to a process group 12779 (for example, an interactive SIGINT) just prior to or during execution of fork( ) is delivered to the 12780 parent following the fork( ) but not to the child because the fork( ) code clears the child's set of 12781 pending signals. This volume of IEEE Std 1003.1-200x does not require, or even permit, this 12782 behavior. However, it is pragmatic to expect that problems of this nature may continue to exist 12783 in implementations that appear to conform to this volume of IEEE Std 1003.1-200x and pass 12784 available verification suites. This behavior is only a consequence of the implementation failing to 12785 make the interval between signal generation and delivery totally invisible. From the 12786 application's perspective, a fork( ) call should appear atomic. A signal that is generated prior to 12787 the fork( ) should be delivered prior to the fork( ). A signal sent to the process group after the 12788 fork( ) should be delivered to both parent and child. The implementation may actually initialize 12789 internal data structures corresponding to the child's set of pending signals to include signals 12790 sent to the process group during the fork( ). Since the fork( ) call can be considered as atomic 12791 from the application's perspective, the set would be initialized as empty and such signals would 12792 have arrived after the fork( ); see also . 12793 One approach that has been suggested to address the problem of signal inheritance across fork( ) 12794 is to add an [EINTR] error, which would be returned when a signal is detected during the call. 12795 While this is preferable to losing signals, it was not considered an optimal solution. Although it 12796 is not recommended for this purpose, such an error would be an allowable extension for an 12797 implementation. 12798 The [ENOMEM] error value is reserved for those implementations that detect and distinguish 12799 such a condition. This condition occurs when an implementation detects that there is not enough 12800 memory to create the process. This is intended to be returned when [EAGAIN] is inappropriate 12801 because there can never be enough memory (either primary or secondary storage) to perform the | 12802 operation. Since fork( ) duplicates an existing process, this must be a condition where there is | 12803 sufficient memory for one such process, but not for two. Many historical implementations 12804 actually return [ENOMEM] due to temporary lack of memory, a case that is not generally 12805 distinct from [EAGAIN] from the perspective of a conforming application. | 12806 Part of the reason for including the optional error [ENOMEM] is because the SVID specifies it 12807 and it should be reserved for the error condition specified there. The condition is not applicable 12808 on many implementations. 12809 IEEE Std 1003.1-1988 neglected to require concurrent execution of the parent and child of fork( ). 12810 A system that single-threads processes was clearly not intended and is considered an 12811 unacceptable ``toy implementation'' of this volume of IEEE Std 1003.1-200x. The only objection 12812 anticipated to the phrase ``executing independently'' is testability, but this assertion should be 12813 testable. Such tests require that both the parent and child can block on a detectable action of the 12814 other, such as a write to a pipe or a signal. An interactive exchange of such actions should be 12815 possible for the system to conform to the intent of this volume of IEEE Std 1003.1-200x. 12816 The [EAGAIN] error exists to warn applications that such a condition might occur. Whether it 12817 occurs or not is not in any practical sense under the control of the application because the 12818 condition is usually a consequence of the user's use of the system, not of the application's code. 12819 Thus, no application can or should rely upon its occurrence under any circumstances, nor 12820 should the exact semantics of what concept of ``user'' is used be of concern to the application 12821 writer. Validation writers should be cognizant of this limitation. System Interfaces, Issue 6 853 fork( ) System Interfaces 12822 There are two reasons why POSIX programmers call fork( ). One reason is to create a new thread 12823 of control within the same program (which was originally only possible in POSIX by creating a 12824 new process); the other is to create a new process running a different program. In the latter case, 12825 the call to fork( ) is soon followed by a call to one of the exec functions. 12826 The general problem with making fork( ) work in a multi-threaded world is what to do with all 12827 of the threads. There are two alternatives. One is to copy all of the threads into the new process. 12828 This causes the programmer or implementation to deal with threads that are suspended on 12829 system calls or that might be about to execute system calls that should not be executed in the 12830 new process. The other alternative is to copy only the thread that calls fork( ). This creates the 12831 difficulty that the state of process-local resources is usually held in process memory. If a thread 12832 that is not calling fork( ) holds a resource, that resource is never released in the child process 12833 because the thread whose job it is to release the resource does not exist in the child process. 12834 When a programmer is writing a multi-threaded program, the first described use of fork( ), 12835 creating new threads in the same program, is provided by the pthread_create( ) function. The 12836 fork( ) function is thus used only to run new programs, and the effects of calling functions that 12837 require certain resources between the call to fork( ) and the call to an exec function are undefined. 12838 The addition of the forkall ( ) function to the standard was considered and rejected. The forkall ( ) 12839 function lets all the threads in the parent be duplicated in the child. This essentially duplicates 12840 the state of the parent in the child. This allows threads in the child to continue processing and 12841 allows locks and the state to be preserved without explicit pthread_atfork( ) code. The calling 12842 process has to ensure that the threads processing state that is shared between the parent and 12843 child (that is, file descriptors or MAP_SHARED memory) behaves properly after forkall ( ). For 12844 example, if a thread is reading a file descriptor in the parent when forkall ( ) is called, then two 12845 threads (one in the parent and one in the child) are reading the file descriptor after the forkall ( ). 12846 If this is not desired behavior, the parent process has to synchronize with such threads before 12847 calling forkall ( ). 12848 When forkall ( ) is called, threads, other than the calling thread, that are in POSIX System 12849 Interfaces functions that can return with an [EINTR] error may have those functions return 12850 [EINTR] if the implementation cannot ensure that the function behaves correctly in the parent 12851 and child. In particular, pthread_cond_wait( ) and pthread_cond_timedwait( ) need to return in order 12852 to ensure that the condition has not changed. These functions can be awakened by a spurious 12853 condition wakeup rather than returning [EINTR]. 12854 FUTURE DIRECTIONS 12855 None. 12856 SEE ALSO 12857 alarm( ), exec, fcntl( ), posix_trace_attr_getinherited( ), posix_trace_trid_eventid_open( ), semop( ), 12858 signal( ), times( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 12859 CHANGE HISTORY 12860 First released in Issue 1. Derived from Issue 1 of the SVID. 12861 Issue 5 12862 The DESCRIPTION is changed for alignment with the POSIX Realtime Extension and the POSIX 12863 Threads Extension. 12864 Issue 6 12865 The following new requirements on POSIX implementations derive from alignment with the 12866 Single UNIX Specification: 12867 * The requirement to include has been removed. Although was 12868 required for conforming implementations of previous POSIX specifications, it was not 854 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fork( ) 12869 required for UNIX applications. 12870 The following changes were made to align with the IEEE P1003.1a draft standard: 12871 * The effect of fork( ) on a pending alarm call in the child process is clarified. 12872 The description of CPU-time clock semantics is added for alignment with IEEE Std 1003.1d-1999. 12873 The description of tracing semantics is added for alignment with IEEE Std 1003.1q-2000. System Interfaces, Issue 6 855 fpathconf( ) System Interfaces 12874 NAME 12875 fpathconf, pathconf - get configurable pathname variables | 12876 SYNOPSIS 12877 #include 12878 long fpathconf(int fildes, int name); 12879 long pathconf(const char *path, int name); 12880 DESCRIPTION 12881 The fpathconf( ) and pathconf( ) functions shall determine the current value of a configurable limit | 12882 or option (variable) that is associated with a file or directory. | 12883 For pathconf( ), the path argument points to the pathname of a file or directory. | 12884 For fpathconf( ), the fildes argument is an open file descriptor. 12885 The name argument represents the variable to be queried relative to that file or directory. 12886 Implementations shall support all of the variables listed in the following table and may support 12887 others. The variables in the following table come from or and the 12888 symbolic constants, defined in , are the corresponding values used for name. Support | 12889 for some pathname configuration variables is dependent on implementation options (see | 12890 shading and margin codes in the table below). Where an implementation option is not 12891 supported, the variable need not be supported. 12892 _____________________________________________________________________________ 12893 _ Variable Value of name Requirements ____________________________________________________________________________ || 12894 {FILESIZEBITS} _PC_FILESIZEBITS 3, 4 12895 {LINK_MAX} _PC_LINK_MAX 1 12896 {MAX_CANON} _PC_MAX_CANON 2 12897 {MAX_INPUT} _PC_MAX_INPUT 2 12898 {NAME_MAX} _PC_NAME_MAX 3,4 12899 {PATH_MAX} _PC_PATH_MAX 4, 5 12900 {PIPE_BUF} _PC_PIPE_BUF 6 12901 ADV {POSIX_ALLOC_SIZE_MIN} _PC_ALLOC_SIZE_MIN 12902 ADV {POSIX_REC_INCR_XFER_SIZE} _PC_REC_INCR_XFER_SIZE 12903 ADV {POSIX_REC_MAX_XFER_SIZE} _PC_REC_MAX_XFER_SIZE 12904 ADV {POSIX_REC_MIN_XFER_SIZE} _PC_REC_MIN_XFER_SIZE 12905 ADV {POSIX_REC_XFER_ALIGN} _PC_REC_XFER_ALIGN 12906 {SYMLINK_MAX} _PC_SYMLINK_MAX 4, 9 | 12907 _POSIX_CHOWN_RESTRICTED _PC_CHOWN_RESTRICTED 7 | 12908 _POSIX_NO_TRUNC _PC_NO_TRUNC 3, 4 12909 _POSIX_VDISABLE _PC_VDISABLE 2 12910 _POSIX_ASYNC_IO _PC_ASYNC_IO 8 12911 _POSIX_PRIO_IO _PC_PRIO_IO 8 12912 _ _POSIX_SYNC_IO _PC_SYNC_IO 8 ____________________________________________________________________________ 856 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fpathconf( ) 12913 Requirements | 12914 1. If path or fildes refers to a directory, the value returned shall apply to the directory itself. | 12915 2. If path or fildes does not refer to a terminal file, it is unspecified whether an implementation 12916 supports an association of the variable name with the specified file. 12917 3. If path or fildes refers to a directory, the value returned shall apply to filenames within the | 12918 directory. | 12919 4. If path or fildes does not refer to a directory, it is unspecified whether an implementation 12920 supports an association of the variable name with the specified file. 12921 5. If path or fildes refers to a directory, the value returned shall be the maximum length of a | 12922 relative pathname when the specified directory is the working directory. | 12923 6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the value returned shall apply to | 12924 the referenced object. If path or fildes refers to a directory, the value returned shall apply to | 12925 any FIFO that exists or can be created within the directory. If path or fildes refers to any | 12926 other type of file, it is unspecified whether an implementation supports an association of 12927 the variable name with the specified file. 12928 7. If path or fildes refers to a directory, the value returned shall apply to any files, other than | 12929 directories, that exist or can be created within the directory. | 12930 8. If path or fildes refers to a directory, it is unspecified whether an implementation supports 12931 an association of the variable name with the specified file. 12932 9. If path or fildes refers to a directory, the value returned shall be the maximum length of the | 12933 string that a symbolic link in that directory can contain. | 12934 RETURN VALUE | 12935 If name is an invalid value, both pathconf( ) and fpathconf( ) shall return -1 and set errno to 12936 indicate the error. 12937 If the variable corresponding to name has no limit for the path or file descriptor, both pathconf( ) 12938 and fpathconf( ) shall return -1 without changing errno. If the implementation needs to use path 12939 to determine the value of name and the implementation does not support the association of name 12940 with the file specified by path, or if the process did not have appropriate privileges to query the 12941 file specified by path, or path does not exist, pathconf( ) shall return -1 and set errno to indicate the 12942 error. 12943 If the implementation needs to use fildes to determine the value of name and the implementation 12944 does not support the association of name with the file specified by fildes, or if fildes is an invalid 12945 file descriptor, fpathconf( ) shall return -1 and set errno to indicate the error. 12946 Otherwise, pathconf( ) or fpathconf( ) shall return the current variable value for the file or 12947 directory without changing errno. The value returned shall not be more restrictive than the 12948 corresponding value available to the application when it was compiled with the 12949 implementation's or . 12950 ERRORS 12951 The pathconf( ) function shall fail if: 12952 [EINVAL] The value of name is not valid. 12953 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 12954 argument. 12955 The pathconf( ) function may fail if: System Interfaces, Issue 6 857 fpathconf( ) System Interfaces 12956 [EACCES] Search permission is denied for a component of the path prefix. 12957 [EINVAL] The implementation does not support an association of the variable name with 12958 the specified file. 12959 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 12960 resolution of the path argument. 12961 [ENAMETOOLONG] 12962 The length of the path argument exceeds {PATH_MAX} or a pathname | 12963 component is longer than {NAME_MAX}. | 12964 [ENAMETOOLONG] 12965 As a result of encountering a symbolic link in resolution of the path argument, | 12966 the length of the substituted pathname string exceeded {PATH_MAX}. | 12967 [ENOENT] A component of path does not name an existing file or path is an empty string. 12968 [ENOTDIR] A component of the path prefix is not a directory. 12969 The fpathconf( ) function shall fail if: 12970 [EINVAL] The value of name is not valid. 12971 The fpathconf( ) function may fail if: 12972 [EBADF] The fildes argument is not a valid file descriptor. 12973 [EINVAL] The implementation does not support an association of the variable name with 12974 the specified file. 12975 EXAMPLES 12976 None. 12977 APPLICATION USAGE 12978 None. 12979 RATIONALE 12980 The pathconf( ) function was proposed immediately after the sysconf( ) function when it was 12981 realized that some configurable values may differ across file system, directory, or device 12982 boundaries. 12983 For example, {NAME_MAX} frequently changes between System V and BSD-based file systems; 12984 System V uses a maximum of 14, BSD 255. On an implementation that provides both types of file 12985 systems, an application would be forced to limit all pathname components to 14 bytes, as this | 12986 would be the value specified in on such a system. 12987 Therefore, various useful values can be queried on any pathname or file descriptor, assuming 12988 that the appropriate permissions are in place. 12989 The value returned for the variable {PATH_MAX} indicates the longest relative pathname that | 12990 could be given if the specified directory is the process' current working directory. A process may | 12991 not always be able to generate a name that long and use it if a subdirectory in the pathname | 12992 crosses into a more restrictive file system. | 12993 The value returned for the variable _POSIX_CHOWN_RESTRICTED also applies to directories 12994 that do not have file systems mounted on them. The value may change when crossing a mount 12995 point, so applications that need to know should check for each directory. (An even easier check 12996 is to try the chown( ) function and look for an error in case it happens.) 12997 Unlike the values returned by sysconf( ), the pathname-oriented variables are potentially more | 12998 volatile and are not guaranteed to remain constant throughout the process' lifetime. For | 858 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fpathconf( ) 12999 example, in between two calls to pathconf( ), the file system in question may have been 13000 unmounted and remounted with different characteristics. 13001 Also note that most of the errors are optional. If one of the variables always has the same value 13002 on an implementation, the implementation need not look at path or fildes to return that value and 13003 is, therefore, not required to detect any of the errors except the meaning of [EINVAL] that 13004 indicates that the value of name is not valid for that variable. 13005 If the value of any of the limits are unspecified (logically infinite), they will not be defined in | 13006 and the pathconf( ) and fpathconf( ) functions return -1 without changing errno. This 13007 can be distinguished from the case of giving an unrecognized name argument because errno is set 13008 to [EINVAL] in this case. 13009 Since -1 is a valid return value for the pathconf( ) and fpathconf( ) functions, applications should 13010 set errno to zero before calling them and check errno only if the return value is -1. 13011 For the case of {SYMLINK_MAX}, since both pathconf( ) and open( ) follow symbolic links, there 13012 is no way that path or fildes could refer to a symbolic link. 13013 FUTURE DIRECTIONS 13014 None. 13015 SEE ALSO 13016 confstr( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 13017 the Shell and Utilities volume of IEEE Std 1003.1-200x 13018 CHANGE HISTORY 13019 First released in Issue 3. 13020 Entry included for alignment with the POSIX.1-1988 standard. 13021 Issue 5 13022 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 13023 Large File Summit extensions are added. 13024 Issue 6 13025 The following new requirements on POSIX implementations derive from alignment with the | 13026 Single UNIX Specification: 13027 * The DESCRIPTION is updated to include {FILESIZEBITS}. 13028 * The [ELOOP] mandatory error condition is added. 13029 * A second [ENAMETOOLONG] is added as an optional error condition. 13030 The following changes were made to align with the IEEE P1003.1a draft standard: 13031 * The _PC_SYMLINK_MAX entry is added to the table in the DESCRIPTION. 13032 The pathconf( ) variables {POSIX_ALLOC_SIZE_MIN}, {POSIX_REC_INCR_XFER_SIZE}, 13033 {POSIX_REC_MAX_XFER_SIZE}, {POSIX_REC_MIN_XFER_SIZE}, 13034 {POSIX_REC_XFER_ALIGN} and their associated names are added for alignment with 13035 IEEE Std 1003.1d-1999. System Interfaces, Issue 6 859 fpclassify( ) System Interfaces 13036 NAME 13037 fpclassify - classify real floating type 13038 SYNOPSIS 13039 #include 13040 int fpclassify(real-floating x); 13041 DESCRIPTION 13042 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13043 conflict between the requirements described here and the ISO C standard is unintentional. This 13044 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13045 The fpclassify( ) macro shall classify its argument value as NaN, infinite, normal, subnormal, 13046 zero, or into another implementation-defined category. First, an argument represented in a 13047 format wider than its semantic type is converted to its semantic type. Then classification is based 13048 on the type of the argument. 13049 RETURN VALUE 13050 The fpclassify( ) macro shall return the value of the number classification macro appropriate to 13051 the value of its argument. 13052 ERRORS 13053 No errors are defined. 13054 EXAMPLES 13055 None. 13056 APPLICATION USAGE 13057 None. 13058 RATIONALE 13059 None. 13060 FUTURE DIRECTIONS 13061 None. 13062 SEE ALSO 13063 isfinite( ), isinf( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of 13064 IEEE Std 1003.1-200x, 13065 CHANGE HISTORY 13066 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 860 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13067 NAME 13068 fprintf, printf, snprintf, sprintf - print formatted output 13069 SYNOPSIS 13070 #include 13071 int fprintf(FILE *restrict stream, const char *restrict format, ...); 13072 int printf(const char *restrict format, ...); 13073 int snprintf(char *restrict s, size_t n, 13074 const char *restrict format, ...); 13075 int sprintf(char *restrict s, const char *restrict format, ...); 13076 DESCRIPTION 13077 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13078 conflict between the requirements described here and the ISO C standard is unintentional. This 13079 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13080 The fprintf( ) function shall place output on the named output stream. The printf( ) function shall | 13081 place output on the standard output stream stdout. The sprintf( ) function shall place output | 13082 followed by the null byte, '\0', in consecutive bytes starting at *s; it is the user's responsibility | 13083 to ensure that enough space is available. 13084 The snprintf( ) function shall be equivalent to sprintf( ), with the addition of the n argument | 13085 which states the size of the buffer referred to by s. If n is zero, nothing shall be written and s may | 13086 be a null pointer. Otherwise, output bytes beyond the n-1st shall be discarded instead of being | 13087 written to the array, and a null byte is written at the end of the bytes actually written into the | 13088 array. | 13089 If copying takes place between objects that overlap as a result of a call to sprintf( ) or snprintf( ), 13090 the results are undefined. 13091 Each of these functions converts, formats, and prints its arguments under control of the format. 13092 The format is a character string, beginning and ending in its initial shift state, if any. The format is 13093 composed of zero or more directives: ordinary characters, which are simply copied to the output 13094 stream, and conversion specifications, each of which shall result in the fetching of zero or more 13095 arguments. The results are undefined if there are insufficient arguments for the format. If the 13096 format is exhausted while arguments remain, the excess arguments shall be evaluated but are | 13097 otherwise ignored. | 13098 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 13099 to the next unused argument. In this case, the conversion specifier character % (see below) is 13100 replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], 13101 giving the position of the argument in the argument list. This feature provides for the definition 13102 of format strings that select arguments in an order appropriate to specific languages (see the 13103 EXAMPLES section). 13104 The format can contain either numbered argument conversion specifications (that is, "%n$" and 13105 "*m$"), or unnumbered argument conversion specifications (that is, % and *), but not both. The | 13106 only exception to this is that %% can be mixed with the "%n$" form. The results of mixing | 13107 numbered and unnumbered argument specifications in a format string are undefined. When 13108 numbered argument specifications are used, specifying the Nth argument requires that all the 13109 leading arguments, from the first to the (N-1)th, are specified in the format string. 13110 In format strings containing the "%n$" form of conversion specification, numbered arguments 13111 in the argument list can be referenced from the format string as many times as required. 13112 In format strings containing the % form of conversion specification, each argument in the 13113 argument list is used exactly once. System Interfaces, Issue 6 861 fprintf( ) System Interfaces 13114 CX All forms of the fprintf( ) functions allow for the insertion of a language-dependent radix 13115 character in the output string. The radix character is defined in the program's locale (category 13116 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 13117 radix character shall default to a period ('.'). 13118 XSI Each conversion specification is introduced by the '%' character or by the character sequence 13119 "%n$",after which the following appear in sequence: 13120 * Zero or more flags (in any order), which modify the meaning of the conversion specification. 13121 * An optional minimum field width. If the converted value has fewer bytes than the field 13122 width, it shall be padded with spaces by default on the left; it shall be padded on the right if | 13123 the left-adjustment flag ('-'), described below, is given to the field width. The field width | 13124 takes the form of an asterisk ('*'), described below, or a decimal integer. 13125 * An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 13126 and X conversion specifiers; the number of digits to appear after the radix character for the a, 13127 A, e, E, f, and F conversion specifiers; the maximum number of significant digits for the g 13128 XSI and G conversion specifiers; or the maximum number of bytes to be printed from a string in s 13129 and Sconversion specifiers. The precision takes the form of a period ('.') followed either by 13130 an asterisk ('*'), described below, or an optional decimal digit string, where a null digit 13131 string is treated as zero. If a precision appears with any other conversion specifier, the 13132 behavior is undefined. 13133 * An optional length modifier that specifies the size of the argument. 13134 * A conversion specifier character that indicates the type of conversion to be applied. 13135 A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 13136 argument of type int supplies the field width or precision. Applications shall ensure that 13137 arguments specifying field width, or precision, or both appear in that order before the argument, 13138 if any, to be converted. A negative field width is taken as a '-' flag followed by a positive field 13139 XSI width. A negative precision is taken as if the precision were omitted. In format strings 13140 containing the "%n$" form of a conversion specification, a field width or precision may be 13141 indicated by the sequence "*m$", where m is a decimal integer in the range [1,{NL_ARGMAX}] 13142 giving the position in the argument list (after the format argument) of an integer argument 13143 containing the field width or precision, for example: 13144 printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 13145 The flag characters and their meanings are: 13146 XSI ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %F, %g, or %G) 13147 shall be formatted with thousands' grouping characters. For other conversions the 13148 behavior is undefined. The non-monetary grouping character is used. 13149 - The result of the conversion shall be left-justified within the field. The conversion is 13150 right-justified if this flag is not specified. 13151 + The result of a signed conversion shall always begin with a sign ('+' or '-'). The 13152 conversion shall begin with a sign only when a negative value is converted if this flag is 13153 not specified. 13154 If the first character of a signed conversion is not a sign or if a signed conversion results 13155 in no characters, a shall be prefixed to the result. This means that if the 13156 and '+' flags both appear, the flag shall be ignored. 13157 # Specifies that the value is to be converted to an alternative form. For o conversion, it | 13158 increases the precision (if necessary) to force the first digit of the result to be zero. For x 862 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13159 or X conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed to it. For a, A, 13160 e, E, f, F, g, and G conversion specifiers, the result shall always contain a radix 13161 character, even if no digits follow the radix character. Without this flag, a radix 13162 character appears in the result of these conversions only if a digit follows it. For g and G 13163 conversion specifiers, trailing zeros shall not be removed from the result as they 13164 normally are. For other conversion specifiers, the behavior is undefined. 13165 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversion specifiers, leading zeros 13166 (following any indication of sign or base) are used to pad to the field width; no space 13167 padding is performed. If the '0' and '-' flags both appear, the '0' flag is ignored. For 13168 d, i, o, u, x, and X conversion specifiers, if a precision is specified, the '0' flag is 13169 XSI ignored. If the '0' and '\'' flags both appear, the grouping characters are inserted 13170 before zero padding. For other conversions, the behavior is undefined. 13171 The length modifiers and their meanings are: 13172 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a signed char 13173 or unsigned char argument (the argument will have been promoted according to the 13174 integer promotions, but its value shall be converted to signed char or unsigned char 13175 before printing); or that a following n conversion specifier applies to a pointer to a 13176 signed char argument. 13177 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short or 13178 unsigned short argument (the argument will have been promoted according to the 13179 integer promotions, but its value shall be converted to short or unsigned short before 13180 printing); or that a following n conversion specifier applies to a pointer to a short 13181 argument. 13182 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long or 13183 unsigned long argument; that a following n conversion specifier applies to a pointer to 13184 a long argument; that a following c conversion specifier applies to a wint_t argument; 13185 that a following s conversion specifier applies to a pointer to a wchar_t argument; or 13186 has no effect on a following a, A, e, E, f, F, g, or G conversion specifier. 13187 ll (ell-ell) 13188 Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long long or 13189 unsigned long long argument; or that a following n conversion specifier applies to a 13190 pointer to a long long argument. 13191 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to an intmax_t 13192 or uintmax_t argument; or that a following n conversion specifier applies to a pointer 13193 to an intmax_t argument. 13194 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a size_t or the 13195 corresponding signed integer type argument; or that a following n conversion specifier 13196 applies to a pointer to a signed integer type corresponding to size_t argument. 13197 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t or 13198 the corresponding unsigned type argument; or that a following n conversion specifier 13199 applies to a pointer to a ptrdiff_t argument. 13200 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long 13201 double argument. 13202 If a length modifier appears with any conversion specifier other than as specified above, the 13203 behavior is undefined. System Interfaces, Issue 6 863 fprintf( ) System Interfaces 13204 The conversion specifiers and their meanings are: 13205 d, i The int argument shall be converted to a signed decimal in the style "[-]dddd". The | 13206 precision specifies the minimum number of digits to appear; if the value being 13207 converted can be represented in fewer digits, it shall be expanded with leading zeros. 13208 The default precision is 1. The result of converting zero with an explicit precision of | 13209 zero shall be no characters. | 13210 o The unsigned argument shall be converted to unsigned octal format in the style | 13211 "dddd". The precision specifies the minimum number of digits to appear; if the value 13212 being converted can be represented in fewer digits, it shall be expanded with leading 13213 zeros. The default precision is 1. The result of converting zero with an explicit precision | 13214 of zero shall be no characters. | 13215 u The unsigned argument shall be converted to unsigned decimal format in the style | 13216 "dddd". The precision specifies the minimum number of digits to appear; if the value 13217 being converted can be represented in fewer digits, it shall be expanded with leading 13218 zeros. The default precision is 1. The result of converting zero with an explicit precision | 13219 of zero shall be no characters. | 13220 x The unsigned argument shall be converted to unsigned hexadecimal format in the style | 13221 "dddd"; the letters "abcdef" are used. The precision specifies the minimum number | 13222 of digits to appear; if the value being converted can be represented in fewer digits, it 13223 shall be expanded with leading zeros. The default precision is 1. The result of 13224 converting zero with an explicit precision of zero shall be no characters. | 13225 X Equivalent to the x conversion specifier, except that letters "ABCDEF" are used instead | 13226 of "abcdef". 13227 f, F The double argument shall be converted to decimal notation in the style | 13228 "[-]ddd.ddd", where the number of digits after the radix character is equal to the 13229 precision specification. If the precision is missing, it shall be taken as 6; if the precision | 13230 is explicitly zero and no '#' flag is present, no radix character shall appear. If a radix | 13231 character appears, at least one digit appears before it. The low-order digit shall be | 13232 rounded in an implementation-defined manner. | 13233 A double argument representing an infinity shall be converted in one of the styles | 13234 "[-]inf" or "[-]infinity"; which style is implementation-defined. A double | 13235 argument representing a NaN shall be converted in one of the styles "[-]nan(n- | 13236 char-sequence)"; or "[-]nan" which style, and the meaning of any n-char-sequence, 13237 is implementation-defined. The F conversion specifier produces "INF", "INFINITY", 13238 or "NAN" instead of "inf", "infinity", or "nan", respectively. 13239 e, E The double argument shall be converted in the style "[-]d.ddde±dd", where there is | 13240 one digit before the radix character (which is non-zero if the argument is non-zero) and 13241 the number of digits after it is equal to the precision; if the precision is missing, it shall | 13242 be taken as 6; if the precision is zero and no '#' flag is present, no radix character shall | 13243 appear. The low-order digit shall be rounded in an implementation-defined manner. | 13244 The E conversion specifier shall produce a number with 'E' instead of 'e' | 13245 introducing the exponent. The exponent shall always contain at least two digits. If the | 13246 value is zero, the exponent shall be zero. | 13247 A double argument representing an infinity or NaN shall be converted in the style of | 13248 an f or F conversion specifier. | 13249 g, G The double argument shall be converted in the style f or e (or in the style E in the case | 13250 of a G conversion specifier), with the precision specifying the number of significant | 864 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13251 digits. If an explicit precision is zero, it shall be taken as 1. The style used depends on | 13252 the value converted; style e (or E) shall be used only if the exponent resulting from | 13253 such a conversion is less than -4 or greater than or equal to the precision. Trailing zeros | 13254 shall be removed from the fractional portion of the result; a radix character shall appear | 13255 only if it is followed by a digit. | 13256 A double argument representing an infinity or NaN shall be converted in the style of | 13257 an f or F conversion specifier. | 13258 a, A A double argument representing a floating-point number shall be converted in the | 13259 style "[-]0xh.hhhhp±d", where there is one hexadecimal digit (which shall be non- | 13260 zero if the argument is a normalized floating-point number and is otherwise | 13261 unspecified) before the decimal-point character and the number of hexadecimal digits | 13262 after it is equal to the precision; if the precision is missing and FLT_RADIX is a power | 13263 of 2, then the precision shall be sufficient for an exact representation of the value; if the | 13264 precision is missing and FLT_RADIX is not a power of 2, then the precision shall be | 13265 sufficient to distinguish values of type double, except that trailing zeros may be | 13266 omitted; if the precision is zero and the '#' flag is not specified, no decimal-point | 13267 character shall appear. The letters "abcdef" shall be used for a conversion and the | 13268 letters "ABCDEF" for A conversion. The A conversion specifier produces a number with 13269 'X' and 'P' instead of 'x' and 'p'. The exponent shall always contain at least one | 13270 digit, and only as many more digits as necessary to represent the decimal exponent of | 13271 2. If the value is zero, the exponent shall be zero. | 13272 A double argument representing an infinity or NaN shall be converted in the style of | 13273 an f or F conversion specifier. | 13274 c The int argument shall be converted to an unsigned char, and the resulting byte shall | 13275 be written. | 13276 If an l (ell) qualifier is present, the wint_t argument shall be converted as if by an ls | 13277 conversion specification with no precision and an argument that points to a two- 13278 element array of type wchar_t, the first element of which contains the wint_t argument 13279 to the ls conversion specification and the second element contains a null wide 13280 character. 13281 s The argument shall be a pointer to an array of char. Bytes from the array shall be | 13282 written up to (but not including) any terminating null byte. If the precision is specified, | 13283 no more than that many bytes shall be written. If the precision is not specified or is 13284 greater than the size of the array, the application shall ensure that the array contains a 13285 null byte. 13286 If an l (ell) qualifier is present, the argument shall be a pointer to an array of type 13287 wchar_t. Wide characters from the array shall be converted to characters (each as if by | 13288 a call to the wcrtomb( ) function, with the conversion state described by an mbstate_t | 13289 object initialized to zero before the first wide character is converted) up to and 13290 including a terminating null wide character. The resulting characters shall be written 13291 up to (but not including) the terminating null character (byte). If no precision is 13292 specified, the application shall ensure that the array contains a null wide character. If a | 13293 precision is specified, no more than that many characters (bytes) shall be written | 13294 (including shift sequences, if any), and the array shall contain a null wide character if, | 13295 to equal the character sequence length given by the precision, the function would need | 13296 to access a wide character one past the end of the array. In no case shall a partial | 13297 character written. | System Interfaces, Issue 6 865 fprintf( ) System Interfaces 13298 p The argument shall be a pointer to void. The value of the pointer is converted to a 13299 sequence of printable characters, in an implementation-defined manner. 13300 n The argument shall be a pointer to an integer into which is written the number of bytes 13301 written to the output so far by this call to one of the fprintf( ) functions. No argument is 13302 converted. 13303 XSI C Equivalent to lc. | 13304 XSI S Equivalent to ls. | 13305 % Print a '%' character; no argument is converted. The complete conversion specification | 13306 shall be %%. 13307 If a conversion specification does not match one of the above forms, the behavior is undefined. If 13308 any argument is not the correct type for the corresponding conversion specification, the 13309 behavior is undefined. 13310 In no case shall a nonexistent or small field width cause truncation of a field; if the result of a | 13311 conversion is wider than the field width, the field shall be expanded to contain the conversion | 13312 result. Characters generated by fprintf( ) and printf( ) are printed as if fputc( ) had been called. | 13313 For the a and A conversion specifiers, if FLT_RADIX is a power of 2, the value shall be correctly | 13314 rounded to a hexadecimal floating number with the given precision. 13315 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly | 13316 representable in the given precision, the result should be one of the two adjacent numbers in | 13317 hexadecimal floating style with the given precision, with the extra stipulation that the error | 13318 should have a correct sign for the current rounding direction. | 13319 For the e, E, f, F, g, and G conversion specifiers, if the number of significant decimal digits is at 13320 most DECIMAL_DIG, then the result should be correctly rounded. If the number of significant 13321 decimal digits is more than DECIMAL_DIG but the source value is exactly representable with 13322 DECIMAL_DIG digits, then the result should be an exact representation with trailing zeros. 13323 Otherwise, the source value is bounded by two adjacent decimal strings L < U, both having 13324 DECIMAL_DIG significant digits; the value of the resultant decimal string D should satisfy L <= 13325 D <= U, with the extra stipulation that the error should have a correct sign for the current 13326 rounding direction. 13327 CX The st_ctime and st_mtime fields of the file shall be marked for update between the call to a 13328 successful execution of fprintf( ) or printf( ) and the next successful completion of a call to fflush( ) 13329 or fclose( ) on the same stream or a call to exit( ) or abort( ). 13330 RETURN VALUE 13331 Upon successful completion, the fprintf( ) and printf( ) functions shall return the number of bytes 13332 transmitted. 13333 Upon successful completion, the sprintf( ) function shall return the number of bytes written to s, 13334 excluding the terminating null byte. 13335 Upon successful completion, the snprintf( ) function shall return the number of bytes that would 13336 be written to s had n been sufficiently large excluding the terminating null byte. 13337 If an output error was encountered, these functions shall return a negative value. 13338 If the value of n is zero on a call to snprintf( ), nothing shall be written, the number of bytes that 13339 would have been written had n been sufficiently large excluding the terminating null shall be 13340 returned, and s may be a null pointer. 866 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13341 ERRORS 13342 For the conditions under which fprintf( ) and printf( ) fail and may fail, refer to fputc( ) or 13343 fputwc( ). 13344 In addition, all forms of fprintf( ) may fail if: 13345 XSI [EILSEQ] A wide-character code that does not correspond to a valid character has been 13346 detected. 13347 XSI [EINVAL] There are insufficient arguments. 13348 The printf( ) and fprintf( ) functions may fail if: 13349 XSI [ENOMEM] Insufficient storage space is available. 13350 The snprintf( ) function shall fail if: 13351 XSI [EOVERFLOW] The value of n is greater than {INT_MAX} or the number of bytes needed to 13352 hold the output excluding the terminating null is greater than {INT_MAX}. 13353 EXAMPLES 13354 Printing Language-Independent Date and Time 13355 The following statement can be used to print date and time using a language-independent 13356 format: 13357 printf(format, weekday, month, day, hour, min); 13358 For American usage, format could be a pointer to the following string: 13359 "%s, %s %d, %d:%.2d\n" 13360 This example would produce the following message: 13361 Sunday, July 3, 10:02 13362 For German usage, format could be a pointer to the following string: 13363 "%1$s, %3$d. %2$s, %4$d:%5$.2d\n" 13364 This definition of format would produce the following message: 13365 Sonntag, 3. Juli, 10:02 13366 Printing File Information 13367 The following example prints information about the type, permissions, and number of links of a 13368 specific file in a directory. 13369 The first two calls to printf( ) use data decoded from a previous stat( ) call. The user-defined 13370 strperm( ) function shall return a string similar to the one at the beginning of the output for the 13371 following command: 13372 ls -l 13373 The next call to printf( ) outputs the owner's name if it is found using getpwuid( ); the getpwuid( ) 13374 function shall return a passwd structure from which the name of the user is extracted. If the user 13375 name is not found, the program instead prints out the numeric value of the user ID. 13376 The next call prints out the group name if it is found using getgrgid( ); getgrgid( ) is very similar to 13377 getpwuid( ) except that it shall return group information based on the group number. Once 13378 again, if the group is not found, the program prints the numeric value of the group for the entry. System Interfaces, Issue 6 867 fprintf( ) System Interfaces 13379 The final call to printf( ) prints the size of the file. 13380 #include 13381 #include 13382 #include 13383 #include 13384 char *strperm (mode_t); 13385 ... 13386 struct stat statbuf; 13387 struct passwd *pwd; 13388 struct group *grp; 13389 ... 13390 printf("%10.10s", strperm (statbuf.st_mode)); 13391 printf("%4d", statbuf.st_nlink); 13392 if ((pwd = getpwuid(statbuf.st_uid)) != NULL) 13393 printf(" %-8.8s", pwd->pw_name); 13394 else 13395 printf(" %-8ld", (long) statbuf.st_uid); 13396 if ((grp = getgrgid(statbuf.st_gid)) != NULL) 13397 printf(" %-8.8s", grp->gr_name); 13398 else 13399 printf(" %-8ld", (long) statbuf.st_gid); 13400 printf("%9jd", (intmax_t) statbuf.st_size); 13401 ... 13402 Printing a Localized Date String 13403 The following example gets a localized date string. The nl_langinfo ( ) function shall return the 13404 localized date string, which specifies the order and layout of the date. The strftime( ) function 13405 takes this information and, using the tm structure for values, places the date and time 13406 information into datestring. The printf( ) function then outputs datestring and the name of the 13407 entry. 13408 #include 13409 #include 13410 #include 13411 ... 13412 struct dirent *dp; 13413 struct tm *tm; 13414 char datestring[256]; 13415 ... 13416 strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); 13417 printf(" %s %s\n", datestring, dp->d_name); 13418 ... 868 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13419 Printing Error Information 13420 The following example uses fprintf( ) to write error information to standard error. 13421 In the first group of calls, the program tries to open the password lock file named LOCKFILE. If 13422 the file already exists, this is an error, as indicated by the O_EXCL flag on the open( ) function. If 13423 the call fails, the program assumes that someone else is updating the password file, and the 13424 program exits. 13425 The next group of calls saves a new password file as the current password file by creating a link 13426 between LOCKFILE and the new password file PASSWDFILE. 13427 #include 13428 #include 13429 #include 13430 #include 13431 #include 13432 #include 13433 #include 13434 #include 13435 #define LOCKFILE "/etc/ptmp" 13436 #define PASSWDFILE "/etc/passwd" 13437 ... 13438 int pfd; 13439 ... 13440 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, 13441 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 13442 { 13443 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n"); 13444 exit(1); 13445 } 13446 ... 13447 if (link(LOCKFILE,PASSWDFILE) == -1) { 13448 fprintf(stderr, "Link error: %s\n", strerror(errno)); 13449 exit(1); 13450 } 13451 ... 13452 Printing Usage Information 13453 The following example checks to make sure the program has the necessary arguments, and uses 13454 fprintf( ) to print usage information if the expected number of arguments is not present. 13455 #include 13456 #include 13457 ... 13458 char *Options = "hdbtl"; 13459 ... 13460 if (argc < 2) { 13461 fprintf(stderr, "Usage: %s -%s 13469 ... 13470 long i; 13471 char *keystr; 13472 int elementlen, len; 13473 ... 13474 while (len < elementlen) { 13475 ... 13476 printf("%s Element%0*ld\n", keystr, elementlen, i); 13477 ... 13478 } 13479 Creating a Filename 13480 The following example creates a filename using information from a previous getpwnam( ) 13481 function that returned the HOME directory of the user. 13482 #include 13483 #include 13484 #include 13485 ... 13486 char filename[PATH_MAX+1]; 13487 struct passwd *pw; 13488 ... 13489 sprintf(filename, "%s/%d.out", pw->pw_dir, getpid()); 13490 ... 13491 Reporting an Event 13492 The following example loops until an event has timed out. The pause( ) function waits forever 13493 unless it receives a signal. The fprintf( ) statement should never occur due to the possible return 13494 values of pause( ). 13495 #include 13496 #include 13497 #include 13498 #include 13499 ... 13500 while (!event_complete) { 13501 ... 13502 if (pause() != -1 || errno != EINTR) 13503 fprintf(stderr, "pause: unknown error: %s\n", strerror(errno)); 13504 } 13505 ... 870 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fprintf( ) 13506 Printing Monetary Information 13507 The following example uses strfmon( ) to convert a number and store it as a formatted monetary 13508 string named convbuf. If the first number is printed, the program prints the format and the 13509 description; otherwise, it just prints the number. 13510 #include 13511 #include 13512 ... 13513 struct tblfmt { 13514 char *format; 13515 char *description; 13516 }; 13517 struct tblfmt table[] = { 13518 { "%n", "default formatting" }, 13519 { "%11n", "right align within an 11 character field" }, 13520 { "%#5n", "aligned columns for values up to 99,999" }, 13521 { "%=*#5n", "specify a fill character" }, 13522 { "%=0#5n", "fill characters do not use grouping" }, 13523 { "% #5n", "disable the grouping separator" }, 13524 { "% #5.0n", "round off to whole units" }, 13525 { "% #5.4n", "increase the precision" }, 13526 { "%(#5n", "use an alternative pos/neg style" }, 13527 { "%!(#5n", "disable the currency symbol" }, 13528 }; 13529 ... 13530 float input[3]; 13531 int i, j; 13532 char convbuf[100]; 13533 ... 13534 strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]); 13535 if (j == 0) { 13536 printf("%s%s%s\n", table[i].format, 13537 convbuf, table[i].description); 13538 } 13539 else { 13540 printf("%s\n", convbuf); 13541 } 13542 ... 13543 APPLICATION USAGE 13544 If the application calling fprintf( ) has any objects of type wint_t or wchar_t, it must also include 13545 the header to have these objects defined. 13546 RATIONALE 13547 None. 13548 FUTURE DIRECTIONS 13549 None. 13550 SEE ALSO 13551 fputc( ), fscanf( ), setlocale( ), wcrtomb( ), the Base Definitions volume of IEEE Std 1003.1-200x, 13552 , , the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale System Interfaces, Issue 6 871 fprintf( ) System Interfaces 13553 CHANGE HISTORY 13554 First released in Issue 1. Derived from Issue 1 of the SVID. 13555 Issue 5 13556 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the l (ell) qualifier can 13557 now be used with c and s conversion specifiers. 13558 The snprintf( ) function is new in Issue 5. 13559 Issue 6 13560 Extensions beyond the ISO C standard are now marked. 13561 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 13562 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 13563 * The prototypes for fprintf( ), printf( ), snprintf( ), and sprintf( ) are updated, and the XSI 13564 shading is removed from snprintf( ). 13565 * The description of snprintf( ) is aligned with the ISO C standard. Note that this supersedes | 13566 the snprintf( ) description in The Open Group Base Resolution bwg98-006, which changed the | 13567 behavior from Issue 5. | 13568 * The DESCRIPTION is updated. | 13569 The DESCRIPTION is updated to use the terms ``conversion specifier'' and ``conversion 13570 specification'' consistently. | 13571 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 872 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fputc( ) 13572 NAME 13573 fputc - put a byte on a stream 13574 SYNOPSIS 13575 #include 13576 int fputc(int c, FILE *stream); 13577 DESCRIPTION 13578 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13579 conflict between the requirements described here and the ISO C standard is unintentional. This 13580 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13581 The fputc( ) function shall write the byte specified by c (converted to an unsigned char) to the 13582 output stream pointed to by stream, at the position indicated by the associated file-position 13583 indicator for the stream (if defined), and shall advance the indicator appropriately. If the file | 13584 cannot support positioning requests, or if the stream was opened with append mode, the byte | 13585 shall be appended to the output stream. | 13586 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13587 execution of fputc( ) and the next successful completion of a call to fflush( ) or fclose( ) on the same 13588 stream or a call to exit( ) or abort( ). 13589 RETURN VALUE 13590 Upon successful completion, fputc( ) shall return the value it has written. Otherwise, it shall 13591 CX return EOF, the error indicator for the stream shall be set, and errno shall be set to indicate the 13592 error. 13593 ERRORS 13594 The fputc( ) function shall fail if either the stream is unbuffered or the stream's buffer needs to be 13595 flushed, and: 13596 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 13597 process would be delayed in the write operation. 13598 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 13599 writing. 13600 CX [EFBIG] An attempt was made to write to a file that exceeds the maximum file size. 13601 XSI [EFBIG] An attempt was made to write to a file that exceeds the process' file size limit. 13602 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 13603 offset maximum. 13604 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data 13605 was transferred. 13606 CX [EIO] A physical I/O error has occurred, or the process is a member of a 13607 background process group attempting to write to its controlling terminal, 13608 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 13609 process group of the process is orphaned. This error may also be returned 13610 under implementation-defined conditions. 13611 CX [ENOSPC] There was no free space remaining on the device containing the file. 13612 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 13613 any process. A SIGPIPE signal shall also be sent to the thread. 13614 The fputc( ) function may fail if: System Interfaces, Issue 6 873 fputc( ) System Interfaces 13615 CX [ENOMEM] Insufficient storage space is available. 13616 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 13617 capabilities of the device. 13618 EXAMPLES 13619 None. 13620 APPLICATION USAGE 13621 None. 13622 RATIONALE 13623 None. 13624 FUTURE DIRECTIONS 13625 None. 13626 SEE ALSO 13627 ferror( ), fopen( ), getrlimit( ), putc( ), puts( ), setbuf( ), ulimit( ), the Base Definitions volume of 13628 IEEE Std 1003.1-200x, 13629 CHANGE HISTORY 13630 First released in Issue 1. Derived from Issue 1 of the SVID. 13631 Issue 5 13632 Large File Summit extensions are added. 13633 Issue 6 13634 Extensions beyond the ISO C standard are now marked. 13635 The following new requirements on POSIX implementations derive from alignment with the 13636 Single UNIX Specification: 13637 * The [EIO] and [EFBIG] mandatory error conditions are added. 13638 * The [ENOMEM] and [ENXIO] optional error conditions are added. 874 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fputs( ) 13639 NAME 13640 fputs - put a string on a stream 13641 SYNOPSIS 13642 #include 13643 int fputs(const char *restrict s, FILE *restrict stream); 13644 DESCRIPTION 13645 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13646 conflict between the requirements described here and the ISO C standard is unintentional. This 13647 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13648 The fputs( ) function shall write the null-terminated string pointed to by s to the stream pointed 13649 to by stream. The terminating null byte shall not be written. 13650 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13651 execution of fputs( ) and the next successful completion of a call to fflush( ) or fclose( ) on the same 13652 stream or a call to exit( ) or abort( ). 13653 RETURN VALUE 13654 Upon successful completion, fputs( ) shall return a non-negative number. Otherwise, it shall 13655 CX return EOF, set an error indicator for the stream, and set errno to indicate the error. 13656 ERRORS 13657 Refer to fputc( ). 13658 EXAMPLES 13659 Printing to Standard Output 13660 The following example gets the current time, converts it to a string using localtime( ) and 13661 asctime( ), and prints it to standard output using fputs( ). It then prints the number of minutes to 13662 an event for which it is waiting. 13663 #include 13664 #include 13665 ... 13666 time_t now; 13667 int minutes_to_event; 13668 ... 13669 time(&now); 13670 printf("The time is "); 13671 fputs(asctime(localtime(&now)), stdout); 13672 printf("There are still %d minutes to the event.\n", 13673 minutes_to_event); 13674 ... 13675 APPLICATION USAGE 13676 The puts( ) function appends a while fputs( ) does not. 13677 RATIONALE 13678 None. 13679 FUTURE DIRECTIONS 13680 None. System Interfaces, Issue 6 875 fputs( ) System Interfaces 13681 SEE ALSO 13682 fopen( ), putc( ), puts( ), the Base Definitions volume of IEEE Std 1003.1-200x, 13683 CHANGE HISTORY 13684 First released in Issue 1. Derived from Issue 1 of the SVID. 13685 Issue 6 13686 Extensions beyond the ISO C standard are now marked. 13687 The fputs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 876 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fputwc( ) 13688 NAME 13689 fputwc - put a wide-character code on a stream 13690 SYNOPSIS 13691 #include 13692 #include 13693 wint_t fputwc(wchar_t wc, FILE *stream); 13694 DESCRIPTION 13695 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13696 conflict between the requirements described here and the ISO C standard is unintentional. This 13697 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13698 The fputwc( ) function shall write the character corresponding to the wide-character code wc to 13699 the output stream pointed to by stream, at the position indicated by the associated file-position 13700 indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot 13701 support positioning requests, or if the stream was opened with append mode, the character is 13702 appended to the output stream. If an error occurs while writing the character, the shift state of 13703 the output file is left in an undefined state. 13704 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13705 execution of fputwc( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 13706 same stream or a call to exit( ) or abort( ). 13707 RETURN VALUE 13708 Upon successful completion, fputwc( ) shall return wc. Otherwise, it shall return WEOF, the error 13709 CX indicator for the stream shall be set set, and errno shall be set to indicate the error. 13710 ERRORS 13711 The fputwc( ) function shall fail if either the stream is unbuffered or data in the stream's buffer 13712 needs to be written, and: 13713 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the 13714 process would be delayed in the write operation. 13715 CX [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 13716 writing. 13717 CX [EFBIG] An attempt was made to write to a file that exceeds the maximum file size or 13718 the process' file size limit. 13719 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 13720 offset maximum associated with the corresponding stream. | 13721 [EILSEQ] The wide-character code wc does not correspond to a valid character. | 13722 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data 13723 was transferred. 13724 CX [EIO] A physical I/O error has occurred, or the process is a member of a 13725 background process group attempting to write to its controlling terminal, 13726 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 13727 process group of the process is orphaned. This error may also be returned 13728 under implementation-defined conditions. 13729 CX [ENOSPC] There was no free space remaining on the device containing the file. 13730 CX [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 13731 any process. A SIGPIPE signal shall also be sent to the thread. System Interfaces, Issue 6 877 fputwc( ) System Interfaces 13732 The fputwc( ) function may fail if: 13733 CX [ENOMEM] Insufficient storage space is available. 13734 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 13735 capabilities of the device. | 13736 EXAMPLES 13737 None. 13738 APPLICATION USAGE 13739 None. 13740 RATIONALE 13741 None. 13742 FUTURE DIRECTIONS 13743 None. 13744 SEE ALSO 13745 ferror( ), fopen( ), setbuf( ), ulimit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 13746 , 13747 CHANGE HISTORY 13748 First released in Issue 4. Derived from the MSE working draft. 13749 Issue 5 13750 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the type of argument wc 13751 is changed from wint_t to wchar_t. 13752 The Optional Header (OH) marking is removed from . 13753 Large File Summit extensions are added. 13754 Issue 6 13755 Extensions beyond the ISO C standard are now marked. 13756 The following new requirements on POSIX implementations derive from alignment with the 13757 Single UNIX Specification: 13758 * The [EFBIG] and [EIO] mandatory error conditions are added. | 13759 * The [ENOMEM] and [ENXIO] optional error conditions are addd. | 878 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fputws( ) 13760 NAME 13761 fputws - put a wide-character string on a stream 13762 SYNOPSIS 13763 #include 13764 #include 13765 int fputws(const wchar_t *restrict ws, FILE *restrict stream); 13766 DESCRIPTION 13767 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13768 conflict between the requirements described here and the ISO C standard is unintentional. This 13769 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13770 The fputws( ) function shall write a character string corresponding to the (null-terminated) 13771 wide-character string pointed to by ws to the stream pointed to by stream. No character 13772 corresponding to the terminating null wide-character code shall be written. 13773 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 13774 execution of fputws( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 13775 same stream or a call to exit( ) or abort( ). 13776 RETURN VALUE 13777 Upon successful completion, fputws( ) shall return a non-negative number. Otherwise, it shall 13778 CX return -1, set an error indicator for the stream, and set errno to indicate the error. 13779 ERRORS 13780 Refer to fputwc( ). 13781 EXAMPLES 13782 None. 13783 APPLICATION USAGE 13784 The fputws( ) function does not append a . 13785 RATIONALE 13786 None. 13787 FUTURE DIRECTIONS 13788 None. 13789 SEE ALSO 13790 fopen( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 13791 CHANGE HISTORY 13792 First released in Issue 4. Derived from the MSE working draft. 13793 Issue 5 13794 The Optional Header (OH) marking is removed from . 13795 Issue 6 13796 Extensions beyond the ISO C standard are now marked. 13797 The fputws( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 879 fread( ) System Interfaces 13798 NAME 13799 fread - binary input 13800 SYNOPSIS 13801 #include 13802 size_t fread(void *restrict ptr, size_t size, size_t nitems, 13803 FILE *restrict stream); 13804 DESCRIPTION 13805 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13806 conflict between the requirements described here and the ISO C standard is unintentional. This 13807 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13808 The fread( ) function shall read into the array pointed to by ptr up to nitems elements whose size 13809 is specified by size in bytes, from the stream pointed to by stream. For each object, size calls shall 13810 be made to the fgetc( ) function and the results stored, in the order read, in an array of unsigned 13811 char exactly overlaying the object. The file position indicator for the stream (if defined) shall be | 13812 advanced by the number of bytes successfully read. If an error occurs, the resulting value of the | 13813 file position indicator for the stream is unspecified. If a partial element is read, its value is | 13814 unspecified. | 13815 CX The fread( ) function may mark the st_atime field of the file associated with stream for update. The 13816 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 13817 fgetwc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 13818 data not supplied by a prior call to ungetc( ) or ungetwc( ). 13819 RETURN VALUE 13820 Upon successful completion, fread( ) shall return the number of elements successfully read which 13821 is less than nitems only if a read error or end-of-file is encountered. If size or nitems is 0, fread( ) 13822 shall return 0 and the contents of the array and the state of the stream remain unchanged. 13823 CX Otherwise, if a read error occurs, the error indicator for the stream shall be set, and errno shall be 13824 set to indicate the error. 13825 ERRORS 13826 Refer to fgetc( ). 13827 EXAMPLES 13828 Reading from a Stream 13829 The following example reads a single element from the fp stream into the array pointed to by buf. 13830 #include 13831 ... 13832 size_t bytes_read; 13833 char buf[100]; 13834 FILE *fp; 13835 ... 13836 bytes_read = fread(buf, sizeof(buf), 1, fp); 13837 ... 13838 APPLICATION USAGE 13839 The ferror( ) or feof( ) functions must be used to distinguish between an error condition and an 13840 end-of-file condition. 13841 Because of possible differences in element length and byte ordering, files written using fwrite( ) 13842 are application-dependent, and possibly cannot be read using fread( ) by a different application 880 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fread( ) 13843 or by the same application on a different processor. 13844 RATIONALE 13845 None. 13846 FUTURE DIRECTIONS 13847 None. 13848 SEE ALSO 13849 feof( ), ferror( ), fgetc( ), fopen( ), getc( ), gets( ), scanf( ), the Base Definitions volume of 13850 IEEE Std 1003.1-200x, 13851 CHANGE HISTORY 13852 First released in Issue 1. Derived from Issue 1 of the SVID. 13853 Issue 6 13854 Extensions beyond the ISO C standard are now marked. 13855 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 13856 * The fread( ) prototype is updated. 13857 * The DESCRIPTION is updated to describe how the bytes from a call to fgetc( ) are stored. System Interfaces, Issue 6 881 free( ) System Interfaces 13858 NAME 13859 free - free allocated memory 13860 SYNOPSIS 13861 #include 13862 void free(void *ptr); 13863 DESCRIPTION 13864 CX The functionality described on this reference page is aligned with the ISO C standard. Any 13865 conflict between the requirements described here and the ISO C standard is unintentional. This 13866 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 13867 The free( ) function shall cause the space pointed to by ptr to be deallocated; that is, made 13868 available for further allocation. If ptr is a null pointer, no action shall occur. Otherwise, if the 13869 ADV argument does not match a pointer earlier returned by the calloc( ), malloc( ), posix_memalign( ), 13870 XSI realloc( ), or strdup( ), function, or if the space has been deallocated by a call to free( ) or realloc( ), 13871 the behavior is undefined. 13872 Any use of a pointer that refers to freed space results in undefined behavior. 13873 RETURN VALUE 13874 The free( ) function shall not return a value. 13875 ERRORS 13876 No errors are defined. 13877 EXAMPLES 13878 None. 13879 APPLICATION USAGE 13880 There is now no requirement for the implementation to support the inclusion of . 13881 RATIONALE 13882 None. 13883 FUTURE DIRECTIONS 13884 None. 13885 SEE ALSO 13886 calloc( ), malloc( ), realloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 13887 CHANGE HISTORY 13888 First released in Issue 1. Derived from Issue 1 of the SVID. 13889 Issue 6 13890 Reference to the valloc( ) function is removed. 882 Technical Standard (2001) (Draft April 16, 2001) System Interfaces freeaddrinfo( ) 13891 NAME 13892 freeaddrinfo, getaddrinfo - get address information 13893 SYNOPSIS 13894 #include 13895 #include 13896 void freeaddrinfo(struct addrinfo *ai); 13897 int getaddrinfo(const char *restrict nodename, 13898 const char *restrict servname, 13899 const struct addrinfo *restrict hints, 13900 struct addrinfo **restrict res); 13901 DESCRIPTION 13902 The freeaddrinfo( ) function shall free one or more addrinfo structures returned by getaddrinfo( ), | 13903 along with any additional storage associated with those structures. If the ai_next field of the | 13904 structure is not null, the entire list of structures shall be freed. The freeaddrinfo( ) function shall | 13905 support the freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo( ). 13906 The getaddrinfo( ) function shall translate the name of a service location (for example, a host 13907 name) and/or a service name and shall return a set of socket addresses and associated 13908 information to be used in creating a socket with which to address the specified service. 13909 The freeaddrinfo( ) and getaddrinfo( ) functions shall be thread-safe. 13910 The nodename and servname arguments are either null pointers or pointers to null-terminated 13911 strings. One or both of these two arguments shall be supplied by the application as a non-null 13912 pointer. 13913 The format of a valid name depends on the address family or families. If a specific family is not | 13914 given and the name could be interpreted as valid within multiple supported families, the 13915 implementation shall attempt to resolve the name in all supported families and, in absence of 13916 errors, one or more results shall be returned. 13917 If the nodename argument is not null, it can be a descriptive name or can be an address string. If 13918 IP6 the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names 13919 include host names. If the specified address family is AF_INET or AF_UNSPEC, address strings 13920 using Internet standard dot notation as specified in inet_addr( ) are valid. 13921 IP6 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described 13922 in inet_ntop( ) are valid. 13923 If nodename is not null, the requested service location is named by nodename; otherwise, the 13924 requested service location is local to the caller. 13925 If servname is null, the call shall return network-level addresses for the specified nodename. If 13926 servname is not null, it is a null-terminated character string identifying the requested service. This 13927 can be either a descriptive name or a numeric representation suitable for use with the address 13928 IP6 family or families. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the 13929 service can be specified as a string specifying a decimal port number. 13930 If the hints argument is not null, it refers to a structure containing input values that may direct 13931 the operation by providing options and by limiting the returned information to a specific socket 13932 type, address family and/or protocol. In this hints structure every member other than ai_flags, 13933 ai_family , ai_socktype, and ai_protocol shall be set to zero or a null pointer. A value of 13934 AF_UNSPEC for ai_family means that the caller shall accept any address family. A value of zero | 13935 for ai_socktype means that the caller shall accept any socket type. A value of zero for ai_protocol 13936 means that the caller shall accept any protocol. If hints is a null pointer, the behavior shall be as if System Interfaces, Issue 6 883 freeaddrinfo( ) System Interfaces 13937 it referred to a structure containing the value zero for the ai_flags, ai_socktype, and ai_protocol 13938 fields, and AF_UNSPEC for the ai_family field. | 13939 The ai_flags field to which the hints parameter points shall be set to zero or be the bitwise- 13940 inclusive OR of one or more of the values AI_PASSIVE, AI_CANONNAME, | 13941 AI_NUMERICHOST, and AI_NUMERICSERV. | 13942 If the AI_PASSIVE flag is specified, the returned address information shall be suitable for use in 13943 binding a socket for accepting incoming connections for the specified service. In this case, if the 13944 nodename argument is null, then the IP address portion of the socket address structure shall be 13945 set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the 13946 AI_PASSIVE flag is not specified, the returned address information shall be suitable for a call to 13947 connect( ) (for a connection-mode protocol) or for a call to connect( ), sendto( ), or sendmsg( ) (for a 13948 connectionless protocol). In this case, if the nodename argument is null, then the IP address 13949 portion of the socket address structure shall be set to the loopback address. 13950 If the AI_CANONNAME flag is specified and the nodename argument is not null, the function | 13951 shall attempt to determine the canonical name corresponding to nodename (for example, if | 13952 nodename is an alias or shorthand notation for a complete name). 13953 If the AI_NUMERICHOST flag is specified, then a non-null nodename string supplied shall be a 13954 numeric host address string. Otherwise, an [EAI_NONAME] error is returned. This flag shall | 13955 prevent any type of name resolution service (for example, the DNS) from being invoked. | 13956 If the AI_NUMERICSERV flag is specified, then a non-null servname string supplied shall be a 13957 numeric port string. Otherwise, an [EAI_NONAME] error shall be returned. This flag shall | 13958 prevent any type of name resolution service (for example, NIS+) from being invoked. | 13959 IP6 If the AI_V4MAPPED flag is specified along with an ai_family of AF_INET6, then getaddrinfo( ) | 13960 shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 addresses (ai_addrlen | 13961 shall be 16). The AI_V4MAPPED flag shall be ignored unless ai_family equals AF_INET6. If the | 13962 AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo( ) shall return all matching | 13963 IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED flag is ignored. | 13964 The ai_socktype field to which argument hints points specifies the socket type for the service, as | 13965 defined in socket( ). If a specific socket type is not given (for example, a value of zero) and the 13966 service name could be interpreted as valid with multiple supported socket types, the 13967 implementation shall attempt to resolve the service name for all supported socket types and, in 13968 the absence of errors, all possible results shall be returned. A non-zero socket type value shall 13969 limit the returned information to values with the specified socket type. 13970 If the ai_family field to which hints points has the value AF_UNSPEC, addresses shall be | 13971 returned for use with any address family that can be used with the specified nodename and/or | 13972 servname. Otherwise, addresses shall be returned for use only with the specified address family. | 13973 If ai_family is not AF_UNSPEC and ai_protocol is not zero, then addresses are returned for use | 13974 only with the specified address family and protocol; the value of ai_protocol shall be interpreted | 13975 as in a call to the socket( ) function with the corresponding values of ai_family and ai_protocol . | 13976 RETURN VALUE 13977 A zero return value for getaddrinfo( ) indicates successful completion; a non-zero return value 13978 indicates failure. The possible values for the failures are listed in the ERRORS section. 13979 Upon successful return of getaddrinfo( ), the location to which res points shall refer to a linked list | 13980 of addrinfo structures, each of which shall specify a socket address and information for use in | 13981 creating a socket with which to use that socket address. The list shall include at least one | 13982 addrinfo structure. The ai_next field of each structure contains a pointer to the next structure on 13983 the list, or a null pointer if it is the last structure on the list. Each structure on the list shall | 884 Technical Standard (2001) (Draft April 16, 2001) System Interfaces freeaddrinfo( ) 13984 include values for use with a call to the socket( ) function, and a socket address for use with the | 13985 connect( ) function or, if the AI_PASSIVE flag was specified, for use with the bind( ) function. The 13986 fields ai_family , ai_socktype, and ai_protocol shall be usable as the arguments to the socket( ) | 13987 function to create a socket suitable for use with the returned address. The fields ai_addr and 13988 ai_addrlen are usable as the arguments to the connect( ) or bind( ) functions with such a socket, 13989 according to the AI_PASSIVE flag. 13990 If nodename is not null, and if requested by the AI_CANONNAME flag, the ai_canonname field of 13991 the first returned addrinfo structure shall point to a null-terminated string containing the | 13992 canonical name corresponding to the input nodename; if the canonical name is not available, then | 13993 ai_canonname shall refer to the nodename argument or a string with the same contents. The | 13994 contents of the ai_flags field of the returned structures are undefined. 13995 All fields in socket address structures returned by getaddrinfo( ) that are not filled in through an 13996 explicit argument (for example, sin6_flowinfo) shall be set to zero. | 13997 Note: This makes it easier to compare socket address structures. 13998 ERRORS 13999 The getaddrinfo( ) function shall fail and return the corresponding value if: 14000 [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 14001 [EAI_BADFLAGS] 14002 The flags parameter had an invalid value. 14003 [EAI_FAIL] A non-recoverable error occurred when attempting to resolve the name. 14004 [EAI_FAMILY] The address family was not recognized. 14005 [EAI_MEMORY] There was a memory allocation failure when trying to allocate storage for the 14006 return value. 14007 [EAI_NONAME] The name does not resolve for the supplied parameters. 14008 Neither nodename nor servname were supplied. At least one of these shall be 14009 supplied. 14010 [EAI_SERVICE] The service passed was not recognized for the specified socket type. 14011 [EAI_SOCKTYPE] 14012 The intended socket type was not recognized. 14013 [EAI_SYSTEM] A system error occurred; the error code can be found in errno. | 14014 [EAI_OVERFLOW] An argument buffer overflowed. | 14015 EXAMPLES 14016 None. 14017 APPLICATION USAGE 14018 If the caller handles only TCP and not UDP, for example, then the ai_protocol member of the hints | 14019 structure should be set to IPPROTO_TCP when getaddrinfo( ) is called. | 14020 If the caller handles only IPv4 and not IPv6, then the ai_family member of the hints structure | 14021 should be set to AF_INET when getaddrinfo( ) is called. | 14022 RATIONALE 14023 None. System Interfaces, Issue 6 885 freeaddrinfo( ) System Interfaces 14024 FUTURE DIRECTIONS 14025 None. 14026 SEE ALSO 14027 connect( ), gai_strerror( ), gethostbyname( ), getnameinfo( ), getservbyname( ), socket( ), the Base 14028 Definitions volume of IEEE Std 1003.1-200x, , 14029 CHANGE HISTORY 14030 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 14031 The restrict keyword is added to the getaddrinfo( ) prototype for alignment with the 14032 ISO/IEC 9899: 1999 standard. 886 Technical Standard (2001) (Draft April 16, 2001) System Interfaces freopen( ) 14033 NAME 14034 freopen - open a stream 14035 SYNOPSIS 14036 #include 14037 FILE *freopen(const char *restrict filename, const char *restrict mode, 14038 FILE *restrict stream); 14039 DESCRIPTION 14040 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14041 conflict between the requirements described here and the ISO C standard is unintentional. This 14042 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14043 The freopen( ) function shall first attempt to flush the stream and close any file descriptor 14044 associated with stream. Failure to flush or close the file descriptor successfully shall be ignored. 14045 The error and end-of-file indicators for the stream shall be cleared. 14046 The freopen( ) function shall open the file whose pathname is the string pointed to by filename and | 14047 associate the stream pointed to by stream with it. The mode argument shall be used just as in 14048 fopen( ). 14049 The original stream shall be closed regardless of whether the subsequent open succeeds. 14050 If filename is a null pointer, the freopen( ) function shall attempt to change the mode of the stream 14051 to that specified by mode, as if the name of the file currently associated with the stream had been 14052 used. It is implementation-defined which changes of mode are permitted (if any), and under 14053 what circumstances. 14054 XSI After a successful call to the freopen( ) function, the orientation of the stream shall be cleared, the 14055 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 14056 initial conversion state. 14057 CX The largest value that can be represented correctly in an object of type off_t shall be established 14058 as the offset maximum in the open file description. 14059 RETURN VALUE 14060 Upon successful completion, freopen( ) shall return the value of stream. Otherwise, a null pointer 14061 CX shall be returned, and errno shall be set to indicate the error. 14062 ERRORS 14063 The freopen( ) function shall fail if: 14064 CX [EACCES] Search permission is denied on a component of the path prefix, or the file 14065 exists and the permissions specified by mode are denied, or the file does not 14066 exist and write permission is denied for the parent directory of the file to be 14067 created. 14068 CX [EINTR] A signal was caught during freopen( ). 14069 CX [EISDIR] The named file is a directory and mode requires write access. 14070 CX [ELOOP] A loop exists in symbolic links encountered during resolution of the path 14071 argument. 14072 CX [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 14073 CX [ENAMETOOLONG] 14074 The length of the filename argument exceeds {PATH_MAX} or a pathname | 14075 component is longer than {NAME_MAX}. | System Interfaces, Issue 6 887 freopen( ) System Interfaces 14076 CX [ENFILE] The maximum allowable number of files is currently open in the system. 14077 CX [ENOENT] A component of filename does not name an existing file or filename is an empty 14078 string. 14079 CX [ENOSPC] The directory or file system that would contain the new file cannot be 14080 expanded, the file does not exist, and it was to be created. 14081 CX [ENOTDIR] A component of the path prefix is not a directory. 14082 CX [ENXIO] The named file is a character special or block special file, and the device 14083 associated with this special file does not exist. 14084 CX [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented 14085 correctly in an object of type off_t. 14086 CX [EROFS] The named file resides on a read-only file system and mode requires write 14087 access. 14088 The freopen( ) function may fail if: 14089 CX [EINVAL] The value of the mode argument is not valid. 14090 CX [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 14091 resolution of the path argument. 14092 CX [ENAMETOOLONG] 14093 Pathname resolution of a symbolic link produced an intermediate result | 14094 whose length exceeds {PATH_MAX}. 14095 CX [ENOMEM] Insufficient storage space is available. 14096 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 14097 capabilities of the device. 14098 CX [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode 14099 requires write access. 14100 EXAMPLES 14101 Directing Standard Output to a File 14102 The following example logs all standard output to the /tmp/logfile file. 14103 #include 14104 ... 14105 FILE *fp; 14106 ... 14107 fp = freopen ("/tmp/logfile", "a+", stdout); 14108 ... 14109 APPLICATION USAGE 14110 The freopen( ) function is typically used to attach the preopened streams associated with stdin, 14111 stdout, and stderr to other files. 14112 RATIONALE 14113 None. 888 Technical Standard (2001) (Draft April 16, 2001) System Interfaces freopen( ) 14114 FUTURE DIRECTIONS 14115 None. 14116 SEE ALSO 14117 fclose( ), fopen( ), fdopen( ), mbsinit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 14118 14119 CHANGE HISTORY 14120 First released in Issue 1. Derived from Issue 1 of the SVID. 14121 Issue 5 14122 The DESCRIPTION is updated to indicate that the orientation of the stream is cleared and the 14123 conversion state of the stream is set to an initial conversion state by a successful call to the 14124 freopen( ) function. 14125 Large File Summit extensions are added. 14126 Issue 6 14127 Extensions beyond the ISO C standard are now marked. 14128 The following new requirements on POSIX implementations derive from alignment with the | 14129 Single UNIX Specification: 14130 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 14131 description. This change is to support large files. 14132 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 14133 large files. 14134 * The [ELOOP] mandatory error condition is added. 14135 * A second [ENAMETOOLONG] is added as an optional error condition. 14136 * The [EINVAL], [ENOMEM], [ENXIO], and [ETXTBSY] optional error conditions are added. 14137 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 14138 * The freopen( ) prototype is updated. 14139 * The DESCRIPTION is updated. 14140 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 14141 [ELOOP] error condition is added. 14142 The DESCRIPTION is updated regarding failure to close, changing the ``file'' to ``file descriptor''. System Interfaces, Issue 6 889 frexp( ) System Interfaces 14143 NAME 14144 frexp, frexpf, frexpl - extract mantissa and exponent from a double precision number 14145 SYNOPSIS 14146 #include 14147 double frexp(double num, int *exp); 14148 float frexpf(float num, int *exp); 14149 long double frexpl(long double num, int *exp); 14150 DESCRIPTION 14151 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14152 conflict between the requirements described here and the ISO C standard is unintentional. This 14153 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14154 These functions shall break a floating-point number num into a normalized fraction and an | 14155 integral power of 2. The integer exponent shall be stored in the int object pointed to by exp. | 14156 RETURN VALUE 14157 For finite arguments, these functions shall return the value x, such that x has a magnitude in the 14158 interval [1 2,1) or 0, and num equals x times 2 raised to the power *exp. 14159 MX If num is NaN, a NaN shall be returned, and the value of *exp is unspecified. 14160 If num is ±0, ±0 shall be returned, and the value of *exp shall be 0. 14161 If num is ±Inf, num shall be returned, and the value of *exp is unspecified. 14162 ERRORS 14163 No errors are defined. 14164 EXAMPLES 14165 None. 14166 APPLICATION USAGE 14167 None. 14168 RATIONALE 14169 None. 14170 FUTURE DIRECTIONS 14171 None. 14172 SEE ALSO 14173 isnan( ), ldexp( ), modf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 14174 CHANGE HISTORY 14175 First released in Issue 1. Derived from Issue 1 of the SVID. 14176 Issue 5 14177 The DESCRIPTION is updated to indicate how an application should check for an error. This 14178 text was previously published in the APPLICATION USAGE section. 14179 Issue 6 14180 The frexpf( ) and frexpl( ) functions are added for alignment with the ISO/IEC 9899: 1999 14181 standard. | 890 Technical Standard (2001) (Draft April 16, 2001) System Interfaces frexp( ) 14182 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are | 14183 revised to align with the ISO/IEC 9899: 1999 standard. 14184 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 14185 marked. System Interfaces, Issue 6 891 fscanf( ) System Interfaces 14186 NAME 14187 fscanf, scanf, sscanf - convert formatted input 14188 SYNOPSIS 14189 #include 14190 int fscanf(FILE *restrict stream, const char *restrict format, ... ); 14191 int scanf(const char *restrict format, ... ); 14192 int sscanf(const char *restrict s, const char *restrict format, ... ); 14193 DESCRIPTION 14194 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14195 conflict between the requirements described here and the ISO C standard is unintentional. This 14196 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14197 The fscanf( ) function shall read from the named input stream. The scanf( ) function shall read | 14198 from the standard input stream stdin. The sscanf( ) function shall read from the string s. Each | 14199 function reads bytes, interprets them according to a format, and stores the results in its 14200 arguments. Each expects, as arguments, a control string format described below, and a set of 14201 pointer arguments indicating where the converted input should be stored. The result is 14202 undefined if there are insufficient arguments for the format. If the format is exhausted while 14203 arguments remain, the excess arguments shall be evaluated but otherwise ignored. | 14204 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 14205 to the next unused argument. In this case, the conversion specifier character % (see below) is 14206 replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}]. 14207 This feature provides for the definition of format strings that select arguments in an order 14208 appropriate to specific languages. In format strings containing the "%n$" form of conversion 14209 specifications, it is unspecified whether numbered arguments in the argument list can be 14210 referenced from the format string more than once. 14211 The format can contain either form of a conversion specification-that is, % or "%n$"-but the | 14212 two forms cannot be mixed within a single format string. The only exception to this is that %% or | 14213 %* can be mixed with the "%n$" form. When numbered argument specifications are used, | 14214 specifying the Nth argument requires that all the leading arguments, from the first to the | 14215 (N-1)th, are pointers. | 14216 CX The fscanf( ) function in all its forms shall allow detection of a language-dependent radix | 14217 character in the input string. The radix character is defined in the program's locale (category 14218 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 14219 radix character shall default to a period ('.'). 14220 The format is a character string, beginning and ending in its initial shift state, if any, composed 14221 of zero or more directives. Each directive is composed of one of the following: one or more 14222 white-space characters (s, s, s, s, or s); an 14223 ordinary character (neither '%' nor a white-space character); or a conversion specification. Each 14224 XSI conversion specification is introduced by the character '%' or the character sequence "%n$", 14225 after which the following appear in sequence: 14226 * An optional assignment-suppressing character '*'. 14227 * An optional non-zero decimal integer that specifies the maximum field width. 14228 * An option length modifier that specifies the size of the receiving object. 14229 * A conversion specifier character that specifies the type of conversion to be applied. The valid 14230 conversion specifiers are described below. 892 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fscanf( ) 14231 The fscanf( ) functions shall execute each directive of the format in turn. If a directive fails, as | 14232 detailed below, the function shall return. Failures are described as input failures (due to the | 14233 unavailability of input bytes) or matching failures (due to inappropriate input). | 14234 A directive composed of one or more white-space characters shall be executed by reading input | 14235 until no more valid input can be read, or up to the first byte which is not a white-space character, | 14236 which remains unread. | 14237 A directive that is an ordinary character shall be executed as follows: the next byte shall be read | 14238 from the input and compared with the byte that comprises the directive; if the comparison | 14239 shows that they are not equivalent, the directive shall fail, and the differing and subsequent | 14240 bytes shall remain unread. Similarly, if end-of-file, an encoding error, or a read error prevents a | 14241 character from being read, the directive shall fail. | 14242 A directive that is a conversion specification defines a set of matching input sequences, as 14243 described below for each conversion character. A conversion specification shall be executed in | 14244 the following steps. | 14245 Input white-space characters (as specified by isspace( )) shall be skipped, unless the conversion | 14246 specification includes a [, c, C, or n conversion specifier. | 14247 An item shall be read from the input, unless the conversion specification includes an n | 14248 conversion specifier. An input item shall be defined as the longest sequence of input bytes (up to | 14249 any specified maximum field width, which may be measured in characters or bytes dependent | 14250 on the conversion specifier) which is an initial subsequence of a matching sequence. The first | 14251 byte, if any, after the input item shall remain unread. If the length of the input item is 0, the | 14252 execution of the conversion specification shall fail; this condition is a matching failure, unless | 14253 end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is | 14254 an input failure. | 14255 Except in the case of a % conversion specifier, the input item (or, in the case of a %n conversion | 14256 specification, the count of input bytes) shall be converted to a type appropriate to the conversion | 14257 character. If the input item is not a matching sequence, the execution of the conversion | 14258 specification fails; this condition is a matching failure. Unless assignment suppression was | 14259 indicated by a '*', the result of the conversion shall be placed in the object pointed to by the | 14260 first argument following the format argument that has not already received a conversion result if | 14261 XSI the conversion specification is introduced by %, or in the nth argument if introduced by the 14262 character sequence "%n$". If this object does not have an appropriate type, or if the result of the 14263 conversion cannot be represented in the space provided, the behavior is undefined. 14264 The length modifiers and their meanings are: 14265 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14266 argument with type pointer to signed char or unsigned char. 14267 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14268 argument with type pointer to short or unsigned short. 14269 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14270 argument with type pointer to long or unsigned long; that a following a, A, e, E, f, F, g, 14271 or G conversion specifier applies to an argument with type pointer to double; or that a 14272 following c, s,or [ conversion specifier applies to an argument with type pointer to 14273 wchar_t. 14274 ll (ell-ell) 14275 Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14276 argument with type pointer to long long or unsigned long long. System Interfaces, Issue 6 893 fscanf( ) System Interfaces 14277 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14278 argument with type pointer to intmax_t or uintmax_t. 14279 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14280 argument with type pointer to size_t or the corresponding signed integer type. 14281 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 14282 argument with type pointer to ptrdiff_t or the corresponding unsigned type. 14283 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an 14284 argument with type pointer to long double. 14285 If a length modifier appears with any conversion specifier other than as specified above, the 14286 behavior is undefined. 14287 The following conversion specifiers are valid: 14288 d Matches an optionally signed decimal integer, whose format is the same as expected for 14289 the subject sequence of strtol( ) with the value 10 for the base argument. In the absence 14290 of a size modifier, the application shall ensure that the corresponding argument is a 14291 pointer to int. 14292 i Matches an optionally signed integer, whose format is the same as expected for the 14293 subject sequence of strtol( ) with 0 for the base argument. In the absence of a size 14294 modifier, the application shall ensure that the corresponding argument is a pointer to 14295 int. 14296 o Matches an optionally signed octal integer, whose format is the same as expected for 14297 the subject sequence of strtoul( ) with the value 8 for the base argument. In the absence 14298 of a size modifier, the application shall ensure that the corresponding argument is a 14299 pointer to unsigned. 14300 u Matches an optionally signed decimal integer, whose format is the same as expected for 14301 the subject sequence of strtoul( ) with the value 10 for the base argument. In the absence 14302 of a size modifier, the application shall ensure that the corresponding argument is a 14303 pointer to unsigned. 14304 x Matches an optionally signed hexadecimal integer, whose format is the same as 14305 expected for the subject sequence of strtoul( ) with the value 16 for the base argument. In 14306 the absence of a size modifier, the application shall ensure that the corresponding 14307 argument is a pointer to unsigned. 14308 a, e, f, g 14309 Matches an optionally signed floating-point number, infinity, or NaN, whose format is 14310 the same as expected for the subject sequence of strtod( ). In the absence of a size 14311 modifier, the application shall ensure that the corresponding argument is a pointer to 14312 float. 14313 If the fprintf( ) family of functions generates character string representations for infinity 14314 and NaN (a symbolic entity encoded in floating-point format) to support 14315 IEEE Std 754-1985, the fscanf( ) family of functions shall recognize them as input. 14316 s Matches a sequence of bytes that are not white-space characters. The application shall 14317 ensure that the corresponding argument is a pointer to the initial byte of an array of 14318 char, signed char, or unsigned char large enough to accept the sequence and a 14319 terminating null character code, which shall be added automatically. 14320 If an l (ell) qualifier is present, the input is a sequence of characters that begins in the | 14321 initial shift state. Each character shall be converted to a wide character as if by a call to | 894 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fscanf( ) 14322 the mbrtowc( ) function, with the conversion state described by an mbstate_t object | 14323 initialized to zero before the first character is converted. The application shall ensure 14324 that the corresponding argument is a pointer to an array of wchar_t large enough to 14325 accept the sequence and the terminating null wide character, which shall be added 14326 automatically. 14327 [ Matches a non-empty sequence of bytes from a set of expected bytes (the scanset). The | 14328 normal skip over white-space characters shall be suppressed in this case. The | 14329 application shall ensure that the corresponding argument is a pointer to the initial byte | 14330 of an array of char, signed char, or unsigned char large enough to accept the sequence | 14331 and a terminating null byte, which shall be added automatically. 14332 If an l (ell) qualifier is present, the input is a sequence of characters that begins in the | 14333 initial shift state. Each character in the sequence shall be converted to a wide character | 14334 as if by a call to the mbrtowc( ) function, with the conversion state described by an | 14335 mbstate_t object initialized to zero before the first character is converted. The 14336 application shall ensure that the corresponding argument is a pointer to an array of 14337 wchar_t large enough to accept the sequence and the terminating null wide character, 14338 which shall be added automatically. 14339 The conversion specification includes all subsequent bytes in the format string up to 14340 and including the matching right square bracket (']'). The bytes between the square 14341 brackets (the scanlist) comprise the scanset, unless the byte after the left square bracket 14342 is a circumflex (' '), in which case the scanset contains all bytes that do not appear in 14343 the scanlist between the circumflex and the right square bracket. If the conversion 14344 specification begins with "[ ]" or "[ ]", the right square bracket is included in the 14345 scanlist and the next right square bracket is the matching right square bracket that ends 14346 the conversion specification; otherwise, the first right square bracket is the one that 14347 ends the conversion specification. If a '-' is in the scanlist and is not the first character, 14348 nor the second where the first character is a ' ', nor the last character, the behavior is 14349 implementation-defined. 14350 c Matches a sequence of bytes of the number specified by the field width (1 if no field 14351 width is present in the conversion specification). The application shall ensure that the 14352 corresponding argument is a pointer to the initial byte of an array of char, signed char, 14353 or unsigned char large enough to accept the sequence. No null byte is added. The 14354 normal skip over white-space characters shall be suppressed in this case. | 14355 If an l (ell) qualifier is present, the input shall be a sequence of characters that begins in | 14356 the initial shift state. Each character in the sequence is converted to a wide character as | 14357 if by a call to the mbrtowc( ) function, with the conversion state described by an | 14358 mbstate_t object initialized to zero before the first character is converted. The 14359 application shall ensure that the corresponding argument is a pointer to an array of 14360 wchar_t large enough to accept the resulting sequence of wide characters. No null wide 14361 character is added. 14362 p Matches an implementation-defined set of sequences, which shall be the same as the set 14363 of sequences that is produced by the %p conversion specification of the corresponding 14364 fprintf( ) functions. The application shall ensure that the corresponding argument is a 14365 pointer to a pointer to void. The interpretation of the input item is implementation- 14366 defined. If the input item is a value converted earlier during the same program 14367 execution, the pointer that results shall compare equal to that value; otherwise, the 14368 behavior of the %p conversion specification is undefined. 14369 n No input is consumed. The application shall ensure that the corresponding argument is | 14370 a pointer to the integer into which shall be written the number of bytes read from the | System Interfaces, Issue 6 895 fscanf( ) System Interfaces 14371 input so far by this call to the fscanf( ) functions. Execution of a %n conversion | 14372 specification shall not increment the assignment count returned at the completion of | 14373 execution of the function. No argument shall be converted, but one shall be consumed. | 14374 If the conversion specification includes an assignment-suppressing character or a field | 14375 width, the behavior is undefined. | 14376 XSI C Equivalent to lc. | 14377 XSI S Equivalent to ls. | 14378 % Matches a single '%' character; no conversion or assignment occurs. The complete 14379 conversion specification shall be %%. 14380 If a conversion specification is invalid, the behavior is undefined. 14381 The conversion specifiers A, E, F, G, and X are also valid and shall be equivalent to a, e, f, g, and | 14382 x, respectively. | 14383 If end-of-file is encountered during input, conversion shall be terminated. If end-of-file occurs | 14384 before any bytes matching the current conversion specification (except for %n) have been read | 14385 (other than leading white-space characters, where permitted), execution of the current | 14386 conversion specification shall terminate with an input failure. Otherwise, unless execution of the | 14387 current conversion specification is terminated with a matching failure, execution of the | 14388 following conversion specification (if any) shall be terminated with an input failure. | 14389 Reaching the end of the string in sscanf( ) shall be equivalent to encountering end-of-file for | 14390 fscanf( ). 14391 If conversion terminates on a conflicting input, the offending input is left unread in the input. | 14392 Any trailing white space (including s) shall be left unread unless matched by a | 14393 conversion specification. The success of literal matches and suppressed assignments is only | 14394 directly determinable via the %n conversion specification. | 14395 CX The fscanf( ) and scanf( ) functions may mark the st_atime field of the file associated with stream 14396 for update. The st_atime field shall be marked for update by the first successful execution of 14397 fgetc( ), fgets( ), fread( ), getc( ), getchar( ), gets( ), fscanf( ), or fscanf( ) using stream that returns data 14398 not supplied by a prior call to ungetc( ). 14399 RETURN VALUE 14400 Upon successful completion, these functions shall return the number of successfully matched 14401 and assigned input items; this number can be zero in the event of an early matching failure. If 14402 the input ends before the first matching failure or conversion, EOF shall be returned. If a read 14403 CX error occurs, the error indicator for the stream is set, EOF shall be returned, and errno shall be set 14404 to indicate the error. 14405 ERRORS 14406 For the conditions under which the fscanf( ) functions fail and may fail, refer to fgetc( ) or 14407 fgetwc( ). 14408 In addition, fscanf( ) may fail if: 14409 XSI [EILSEQ] Input byte sequence does not form a valid character. 14410 XSI [EINVAL] There are insufficient arguments. 896 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fscanf( ) 14411 EXAMPLES 14412 The call: 14413 int i, n; float x; char name[50]; 14414 n = scanf("%d%f%s", &i, &x, name); 14415 with the input line: 14416 25 54.32E-1 Hamster 14417 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 14418 "Hamster". 14419 The call: 14420 int i; float x; char name[50]; 14421 (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); 14422 with input: 14423 56789 0123 56a72 14424 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0" in name. The next call to 14425 getchar( ) shall return the character 'a'. 14426 Reading Data into an Array 14427 The following call uses fscanf( ) to read three floating-point numbers from standard input into 14428 the input array. 14429 float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2); | 14430 APPLICATION USAGE | 14431 If the application calling fscanf( ) has any objects of type wint_t or wchar_t, it must also include 14432 the header to have these objects defined. 14433 RATIONALE 14434 This function is aligned with the ISO/IEC 9899: 1999 standard, and in doing so a few ``obvious'' | 14435 things were not included. Specifically, the set of characters allowed in a scanset is limited to | 14436 single-byte characters. In other similar places, multi-byte characters have been permitted, but | 14437 for alignment with the ISO/IEC 9899: 1999 standard, it has not been done here. Applications | 14438 needing this could use the corresponding wide-character functions to achieve the desired | 14439 results. | 14440 FUTURE DIRECTIONS 14441 None. 14442 SEE ALSO 14443 getc( ), printf( ), setlocale( ), strtod( ), strtol( ), strtoul( ), wcrtomb( ), the Base Definitions volume of 14444 IEEE Std 1003.1-200x, , , , the Base Definitions volume of 14445 IEEE Std 1003.1-200x, Chapter 7, Locale 14446 CHANGE HISTORY 14447 First released in Issue 1. Derived from Issue 1 of the SVID. 14448 Issue 5 14449 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the l (ell) qualifier is 14450 now defined for the c, s, and [ conversion specifiers. 14451 The DESCRIPTION is updated to indicate that if infinity and NaN can be generated by the 14452 fprintf( ) family of functions, then they are recognized by the fscanf( ) family. System Interfaces, Issue 6 897 fscanf( ) System Interfaces 14453 Issue 6 14454 The Open Group Corrigendum U021/7 and U028/10 are applied. These correct several 14455 occurrences of ``characters'' in the text which have been replaced with the term ``bytes''. 14456 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 14457 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 14458 * The prototypes for fscanf( ), scanf( ), and sscanf( ) are updated. 14459 * The DESCRIPTION is updated. | 14460 * The hh, ll, j, t, and z length modifiers are added. | 14461 * The a, A, and F conversion characters are added. | 14462 The DESCRIPTION is updated to use the terms ``conversion specifier'' and ``conversion 14463 specification'' consistently. 898 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fseek( ) 14464 NAME 14465 fseek, fseeko - reposition a file-position indicator in a stream 14466 SYNOPSIS 14467 #include 14468 int fseek(FILE *stream, long offset, int whence); 14469 CX int fseeko(FILE *stream, off_t offset, int whence); 14470 14471 DESCRIPTION 14472 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14473 conflict between the requirements described here and the ISO C standard is unintentional. This 14474 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14475 The fseek( ) function shall set the file-position indicator for the stream pointed to by stream. If a 14476 read or write error occurs, the error indicator for the stream shall be set and fseek( ) fails. 14477 The new position, measured in bytes from the beginning of the file, shall be obtained by adding 14478 offset to the position specified by whence. The specified point is the beginning of the file for 14479 SEEK_SET, the current value of the file-position indicator for SEEK_CUR, or end-of-file for 14480 SEEK_END. 14481 If the stream is to be used with wide-character input/output functions, the application shall 14482 ensure that offset is either 0 or a value returned by an earlier call to ftell( ) on the same stream and 14483 whence is SEEK_SET. 14484 A successful call to fseek( ) shall clear the end-of-file indicator for the stream and undo any effects 14485 of ungetc( ) and ungetwc( ) on the same stream. After an fseek( ) call, the next operation on an 14486 update stream may be either input or output. 14487 CX If the most recent operation, other than ftell( ), on a given stream is fflush( ), the file offset in the 14488 underlying open file description shall be adjusted to reflect the location specified by fseek( ). 14489 The fseek( ) function shall allow the file-position indicator to be set beyond the end of existing 14490 data in the file. If data is later written at this point, subsequent reads of data in the gap shall 14491 return bytes with the value 0 until data is actually written into the gap. 14492 The behavior of fseek( ) on devices which are incapable of seeking is implementation-defined. 14493 The value of the file offset associated with such a device is undefined. 14494 If the stream is writable and buffered data had not been written to the underlying file, fseek( ) 14495 shall cause the unwritten data to be written to the file and shall mark the st_ctime and st_mtime 14496 fields of the file for update. 14497 In a locale with state-dependent encoding, whether fseek( ) restores the stream's shift state is 14498 implementation-defined. 14499 The fseeko( ) function shall be equivalent to the fseek( ) function except that the offset argument is | 14500 of type off_t. 14501 RETURN VALUE 14502 CX The fseek( ) and fseeko( )functions shall return 0 if they succeed. 14503 CX Otherwise, they shall return -1 and set errno to indicate the error. 14504 ERRORS 14505 CX CX The fseek( ) and fseeko( ) functions shall fail if, either the stream is unbuffered or the stream's 14506 buffer needed to be flushed, and the call to fseek( ) or fseeko( ) causes an underlying lseek( ) or 14507 write( ) to be invoked, and: System Interfaces, Issue 6 899 fseek( ) System Interfaces 14508 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the process would be 14509 delayed in the write operation. 14510 CX [EBADF] The file descriptor underlying the stream file is not open for writing or the 14511 stream's buffer needed to be flushed and the file is not open. 14512 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 14513 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 14514 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 14515 offset maximum associated with the corresponding stream. 14516 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data 14517 was transferred. 14518 CX [EINVAL] The whence argument is invalid. The resulting file-position indicator would be 14519 set to a negative value. 14520 CX [EIO] A physical I/O error has occurred, or the process is a member of a 14521 background process group attempting to perform a write( ) to its controlling 14522 terminal, TOSTOP is set, the process is neither ignoring nor blocking 14523 SIGTTOU, and the process group of the process is orphaned. This error may 14524 also be returned under implementation-defined conditions. 14525 CX [ENOSPC] There was no free space remaining on the device containing the file. 14526 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 14527 capabilities of the device. 14528 CX [EOVERFLOW] For fseek( ), the resulting file offset would be a value which cannot be 14529 represented correctly in an object of type long. 14530 CX [EOVERFLOW] For fseeko( ), the resulting file offset would be a value which cannot be 14531 represented correctly in an object of type off_t. 14532 CX [EPIPE] An attempt was made to write to a pipe or FIFO that is not open for reading 14533 by any process; a SIGPIPE signal shall also be sent to the thread. 14534 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. 14535 EXAMPLES 14536 None. 14537 APPLICATION USAGE 14538 None. 14539 RATIONALE 14540 None. 14541 FUTURE DIRECTIONS 14542 None. 14543 SEE ALSO 14544 fopen( ), fsetpos( ), ftell( ), getrlimit( ), lseek( ), rewind( ), ulimit( ), ungetc( ), write( ), the Base 14545 Definitions volume of IEEE Std 1003.1-200x, 14546 CHANGE HISTORY 14547 First released in Issue 1. Derived from Issue 1 of the SVID. 900 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fseek( ) 14548 Issue 5 14549 Normative text previously in the APPLICATION USAGE section is moved to the 14550 DESCRIPTION. 14551 Large File Summit extensions are added. 14552 Issue 6 14553 Extensions beyond the ISO C standard are now marked. 14554 The following new requirements on POSIX implementations derive from alignment with the 14555 Single UNIX Specification: 14556 * The fseeko( ) function is added. 14557 * The [EFBIG], [EOVERFLOW], and [ENXIO] mandatory error conditions are added. 14558 The following change is incorporated for alignment with the FIPS requirements: 14559 * The [EINTR] error is no longer an indication that the implementation does not report partial 14560 transfers. 14561 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 14562 The DESCRIPTION is updated to explicitly state that fseek( ) sets the file-position indicator, and 14563 then on error the error indicator is set and fseek( ) fails. This is for alignment with the 14564 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 901 fsetpos( ) System Interfaces 14565 NAME 14566 fsetpos - set current file position 14567 SYNOPSIS 14568 #include 14569 int fsetpos(FILE *stream, const fpos_t *pos); 14570 DESCRIPTION 14571 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14572 conflict between the requirements described here and the ISO C standard is unintentional. This 14573 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14574 The fsetpos( ) function shall set the file position and state indicators for the stream pointed to by 14575 stream according to the value of the object pointed to by pos, which the application shall ensure 14576 is a value obtained from an earlier call to fgetpos( ) on the same stream. If a read or write error 14577 occurs, the error indicator for the stream shall be set and fsetpos( ) fails. 14578 A successful call to the fsetpos( ) function shall clear the end-of-file indicator for the stream and 14579 undo any effects of ungetc( ) on the same stream. After an fsetpos( ) call, the next operation on an 14580 update stream may be either input or output. 14581 CX The behavior of fsetpos( ) on devices which are incapable of seeking is implementation-defined. 14582 The value of the file offset associated with such a device is undefined. 14583 RETURN VALUE 14584 The fsetpos( ) function shall return 0 if it succeeds; otherwise, it shall return a non-zero value and 14585 set errno to indicate the error. 14586 ERRORS 14587 CX The fsetpos( ) function shall fail if, either the stream is unbuffered or the stream's buffer needed to 14588 be flushed, and the call to fsetpos( ) causes an underlying lseek( ) or write( ) to be invoked, and: 14589 CX [EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the process would be 14590 delayed in the write operation. 14591 CX [EBADF] The file descriptor underlying the stream file is not open for writing or the 14592 stream's buffer needed to be flushed and the file is not open. 14593 CX [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 14594 XSI [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 14595 CX [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 14596 offset maximum associated with the corresponding stream. 14597 CX [EINTR] The write operation was terminated due to the receipt of a signal, and no data 14598 was transferred. 14599 CX [EINVAL] The whence argument is invalid. The resulting file-position indicator would be 14600 set to a negative value. 14601 CX [EIO] A physical I/O error has occurred, or the process is a member of a 14602 background process group attempting to perform a write( ) to its controlling 14603 terminal, TOSTOP is set, the process is neither ignoring nor blocking 14604 SIGTTOU, and the process group of the process is orphaned. This error may 14605 also be returned under implementation-defined conditions. 14606 CX [ENOSPC] There was no free space remaining on the device containing the file. 902 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fsetpos( ) 14607 CX [ENXIO] A request was made of a nonexistent device, or the request was outside the 14608 capabilities of the device. 14609 CX [EPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. 14610 CX [EPIPE] An attempt was made to write to a pipe or FIFO that is not open for reading 14611 by any process; a SIGPIPE signal shall also be sent to the thread. 14612 EXAMPLES 14613 None. 14614 APPLICATION USAGE 14615 None. 14616 RATIONALE 14617 None. 14618 FUTURE DIRECTIONS 14619 None. 14620 SEE ALSO 14621 fopen( ), ftell( ), lseek( ), rewind( ), ungetc( ), write( ), the Base Definitions volume of 14622 IEEE Std 1003.1-200x, 14623 CHANGE HISTORY 14624 First released in Issue 4. Derived from the ISO C standard. 14625 Issue 6 14626 Extensions beyond the ISO C standard are now marked. 14627 An additional [ESPIPE] error condition is added for sockets. 14628 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 14629 The DESCRIPTION is updated to clarify that the error indicator is set for the stream on a read or 14630 write error. This is for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 903 fstat( ) System Interfaces 14631 NAME 14632 fstat - get file status 14633 SYNOPSIS 14634 #include 14635 int fstat(int fildes, struct stat *buf); 14636 DESCRIPTION 14637 The fstat( ) function shall obtain information about an open file associated with the file | 14638 descriptor fildes, and shall write it to the area pointed to by buf. | 14639 SHM If fildes references a shared memory object, the implementation shall update in the stat structure | 14640 pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the 14641 S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be 14642 valid. The implementation may update other fields and flags. | 14643 TYM If fildes references a typed memory object, the implementation shall update in the stat structure | 14644 pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the 14645 S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits need be | 14646 valid. The implementation may update other fields and flags. | 14647 The buf argument is a pointer to a stat structure, as defined in , into which | 14648 information is placed concerning the file. | 14649 The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime | 14650 shall have meaningful values for all other file types defined in this volume of 14651 IEEE Std 1003.1-200x. The value of the member st_nlink shall be set to the number of links to the 14652 file. 14653 An implementation that provides additional or alternative file access control mechanisms may, | 14654 under implementation-defined conditions, cause fstat( ) to fail. 14655 The fstat( ) function shall update any time-related fields as described in the Base Definitions | 14656 volume of IEEE Std 1003.1-200x, Section 4.7, File Times Update, before writing into the stat | 14657 structure. 14658 RETURN VALUE 14659 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 14660 indicate the error. 14661 ERRORS 14662 The fstat( ) function shall fail if: 14663 [EBADF] The fildes argument is not a valid file descriptor. 14664 [EIO] An I/O error occurred while reading from the file system. 14665 [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 14666 serial number cannot be represented correctly in the structure pointed to by 14667 buf. 14668 The fstat( ) function may fail if: 14669 [EOVERFLOW] One of the values is too large to store into the structure pointed to by the buf 14670 argument. 904 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fstat( ) 14671 EXAMPLES 14672 Obtaining File Status Information 14673 The following example shows how to obtain file status information for a file named 14674 /home/cnd/mod1. The structure variable buffer is defined for the stat structure. The 14675 /home/cnd/mod1 file is opened with read/write privileges and is passed to the open file 14676 descriptor fildes. 14677 #include 14678 #include 14679 #include 14680 struct stat buffer; 14681 int status; 14682 ... 14683 fildes = open("/home/cnd/mod1", O_RDWR); 14684 status = fstat(fildes, &buffer); 14685 APPLICATION USAGE 14686 None. 14687 RATIONALE 14688 None. 14689 FUTURE DIRECTIONS 14690 None. 14691 SEE ALSO 14692 lstat( ), stat( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 14693 CHANGE HISTORY 14694 First released in Issue 1. Derived from Issue 1 of the SVID. 14695 Issue 5 14696 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 14697 Large File Summit extensions are added. 14698 Issue 6 14699 In the SYNOPSIS, the optional include of the header is removed. 14700 The following new requirements on POSIX implementations derive from alignment with the 14701 Single UNIX Specification: 14702 * The requirement to include has been removed. Although was 14703 required for conforming implementations of previous POSIX specifications, it was not 14704 required for UNIX applications. 14705 * The [EIO] mandatory error condition is added. 14706 * The [EOVERFLOW] mandatory error condition is added. This change is to support large 14707 files. 14708 * The [EOVERFLOW] optional error condition is added. 14709 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 14710 shared memory object semantics apply to typed memory objects. System Interfaces, Issue 6 905 fstatvfs( ) System Interfaces 14711 NAME 14712 fstatvfs, statvfs - get file system information 14713 SYNOPSIS 14714 XSI #include 14715 int fstatvfs(int fildes, struct statvfs *buf); 14716 int statvfs(const char *restrict path, struct statvfs *restrict buf); 14717 14718 DESCRIPTION 14719 The fstatvfs( ) function shall obtain information about the file system containing the file | 14720 referenced by fildes. | 14721 The statvfs( ) function shall obtain information about the file system containing the file named by | 14722 path. | 14723 For both functions, the buf argument is a pointer to a statvfs structure that shall be filled. Read, | 14724 write, or execute permission of the named file is not required. | 14725 The following flags can be returned in the f_flag member: | 14726 ST_RDONLY Read-only file system. 14727 ST_NOSUID Setuid/setgid bits ignored by exec. 14728 It is unspecified whether all members of the statvfs structure have meaningful values on all file | 14729 systems. 14730 RETURN VALUE 14731 Upon successful completion, statvfs( ) shall return 0. Otherwise, it shall return -1 and set errno to 14732 indicate the error. 14733 ERRORS 14734 The fstatvfs( ) and statvfs( ) functions shall fail if: 14735 [EIO] An I/O error occurred while reading the file system. 14736 [EINTR] A signal was caught during execution of the function. 14737 [EOVERFLOW] One of the values to be returned cannot be represented correctly in the 14738 structure pointed to by buf. 14739 The fstatvfs( ) function shall fail if: 14740 [EBADF] The fildes argument is not an open file descriptor. 14741 The statvfs( ) function shall fail if: 14742 [EACCES] Search permission is denied on a component of the path prefix. 14743 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 14744 argument. 14745 [ENAMETOOLONG] 14746 The length of a pathname exceeds {PATH_MAX} or a pathname component is | 14747 longer than {NAME_MAX}. | 14748 [ENOENT] A component of path does not name an existing file or path is an empty string. 14749 [ENOTDIR] A component of the path prefix of path is not a directory. 14750 The statvfs( ) function may fail if: 906 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fstatvfs( ) 14751 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 14752 resolution of the path argument. 14753 [ENAMETOOLONG] 14754 Pathname resolution of a symbolic link produced an intermediate result | 14755 whose length exceeds {PATH_MAX}. 14756 EXAMPLES 14757 Obtaining File System Information Using fstatvfs( ) 14758 The following example shows how to obtain file system information for the file system upon 14759 which the file named /home/cnd/mod1 resides, using the fstatvfs( ) function. The 14760 /home/cnd/mod1 file is opened with read/write privileges and the open file descriptor is passed 14761 to the fstatvfs( ) function. 14762 #include 14763 #include 14764 struct statvfs buffer; 14765 int status; 14766 ... 14767 fildes = open("/home/cnd/mod1", O_RDWR); 14768 status = fstatvfs(fildes, &buffer); 14769 Obtaining File System Information Using statvfs( ) 14770 The following example shows how to obtain file system information for the file system upon 14771 which the file named /home/cnd/mod1 resides, using the statvfs( ) function. 14772 #include 14773 struct statvfs buffer; 14774 int status; 14775 ... 14776 status = statvfs("/home/cnd/mod1", &buffer); 14777 APPLICATION USAGE 14778 None. 14779 RATIONALE 14780 None. 14781 FUTURE DIRECTIONS 14782 None. 14783 SEE ALSO 14784 chmod( ), chown( ), creat( ), dup( ), exec, fcntl( ), link( ), mknod( ), open( ), pipe( ), read( ), time( ), 14785 unlink( ), utime( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 14786 CHANGE HISTORY 14787 First released in Issue 4, Version 2. 14788 Issue 5 14789 Moved from X/OPEN UNIX extension to BASE. 14790 Large File Summit extensions are added. System Interfaces, Issue 6 907 fstatvfs( ) System Interfaces 14791 Issue 6 14792 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 14793 The restrict keyword is added to the statvfs( ) prototype for alignment with the 14794 ISO/IEC 9899: 1999 standard. 14795 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 14796 [ELOOP] error condition is added. 908 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fsync( ) 14797 NAME 14798 fsync - synchronize changes to a file 14799 SYNOPSIS 14800 FSC #include 14801 int fsync(int fildes); 14802 14803 DESCRIPTION 14804 The fsync( ) function shall request that all data for the open file descriptor named by fildes is to be | 14805 transferred to the storage device associated with the file described by fildes in an 14806 implementation-defined manner. The fsync( ) function shall not return until the system has 14807 completed that action or until an error is detected. 14808 SIO If _POSIX_SYNCHRONIZED_IO is defined, the fsync( ) function shall force all currently queued 14809 I/O operations associated with the file indicated by file descriptor fildes to the synchronized I/O 14810 completion state. All I/O operations shall be completed as defined for synchronized I/O file 14811 integrity completion. 14812 RETURN VALUE 14813 Upon successful completion, fsync( ) shall return 0. Otherwise, -1 shall be returned and errno set 14814 to indicate the error. If the fsync( ) function fails, outstanding I/O operations are not guaranteed 14815 to have been completed. 14816 ERRORS 14817 The fsync( ) function shall fail if: 14818 [EBADF] The fildes argument is not a valid descriptor. 14819 [EINTR] The fsync( ) function was interrupted by a signal. 14820 [EINVAL] The fildes argument does not refer to a file on which this operation is possible. 14821 [EIO] An I/O error occurred while reading from or writing to the file system. 14822 In the event that any of the queued I/O operations fail, fsync( ) shall return the error conditions 14823 defined for read( ) and write( ). 14824 EXAMPLES 14825 None. 14826 APPLICATION USAGE 14827 The fsync( ) function should be used by programs which require modifications to a file to be 14828 completed before continuing; for example, a program which contains a simple transaction 14829 facility might use it to ensure that all modifications to a file or files caused by a transaction are 14830 recorded. 14831 RATIONALE 14832 The fsync( ) function is intended to force a physical write of data from the buffer cache, and to 14833 assure that after a system crash or other failure that all data up to the time of the fsync( ) call is 14834 recorded on the disk. Since the concepts of ``buffer cache'', ``system crash'', ``physical write'', and 14835 ``non-volatile storage'' are not defined here, the wording has to be more abstract. 14836 If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on the conformance 14837 document to tell the user what can be expected from the system. It is explicitly intended that a 14838 null implementation is permitted. This could be valid in the case where the system cannot assure 14839 non-volatile storage under any circumstances or when the system is highly fault-tolerant and the 14840 functionality is not required. In the middle ground between these extremes, fsync( ) might or 14841 might not actually cause data to be written where it is safe from a power failure. The System Interfaces, Issue 6 909 fsync( ) System Interfaces 14842 conformance document should identify at least that one configuration exists (and how to obtain 14843 that configuration) where this can be assured for at least some files that the user can select to use 14844 for critical data. It is not intended that an exhaustive list is required, but rather sufficient 14845 information is provided to let the user determine that if he or she has critical data he or she can 14846 configure her system to allow it to be written to non-volatile storage. 14847 It is reasonable to assert that the key aspects of fsync( ) are unreasonable to test in a test suite. 14848 That does not make the function any less valuable, just more difficult to test. A formal 14849 conformance test should probably force a system crash (power shutdown) during the test for 14850 this condition, but it needs to be done in such a way that automated testing does not require this 14851 to be done except when a formal record of the results is being made. It would also not be 14852 unreasonable to omit testing for fsync( ), allowing it to be treated as a quality-of-implementation 14853 issue. 14854 FUTURE DIRECTIONS 14855 None. 14856 SEE ALSO 14857 sync( ), the Base Definitions volume of IEEE Std 1003.1-200x, 14858 CHANGE HISTORY 14859 First released in Issue 3. 14860 Issue 5 14861 Aligned with fsync( ) in the POSIX Realtime Extension. Specifically, the DESCRIPTION and 14862 RETURN VALUE sections are much expanded, and the ERRORS section is updated to indicate 14863 that fsync( ) can return the error conditions defined for read( ) and write( ). 14864 Issue 6 14865 This function is marked as part of the File Synchronization option. 14866 The following new requirements on POSIX implementations derive from alignment with the 14867 Single UNIX Specification: 14868 * The [EINVAL] and [EIO] mandatory error conditions are added. 910 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftell( ) 14869 NAME 14870 ftell, ftello - return a file offset in a stream 14871 SYNOPSIS 14872 #include 14873 long ftell(FILE *stream); 14874 CX off_t ftello(FILE *stream); 14875 14876 DESCRIPTION 14877 CX The functionality described on this reference page is aligned with the ISO C standard. Any 14878 conflict between the requirements described here and the ISO C standard is unintentional. This 14879 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 14880 The ftell( ) function shall obtain the current value of the file-position indicator for the stream 14881 pointed to by stream. 14882 CX The ftello( ) function shall be equivalent to ftell( ), except that the return value is of type off_t. | 14883 RETURN VALUE 14884 CX Upon successful completion, ftell( ) and ftello( ) shall return the current value of the file-position 14885 indicator for the stream measured in bytes from the beginning of the file. 14886 CX Otherwise, ftell( ) and ftello( ) shall return -1, cast to long and off_t respectively, and set errno to 14887 indicate the error. 14888 ERRORS 14889 CX The ftell( ) and ftello( )functions shall fail if: 14890 CX [EBADF] The file descriptor underlying stream is not an open file descriptor. 14891 CX [EOVERFLOW] For ftell( ), the current file offset cannot be represented correctly in an object of 14892 type long. 14893 CX [EOVERFLOW] For ftello( ), the current file offset cannot be represented correctly in an object 14894 of type off_t. 14895 CX [ESPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. 14896 The ftell( ) function may fail if: 14897 CX [ESPIPE] The file descriptor underlying stream is associated with a socket. 14898 EXAMPLES 14899 None. 14900 APPLICATION USAGE 14901 None. 14902 RATIONALE 14903 None. 14904 FUTURE DIRECTIONS 14905 None. 14906 SEE ALSO 14907 fgetpos( ), fopen( ), fseek( ), lseek( ), the Base Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 911 ftell( ) System Interfaces 14908 CHANGE HISTORY 14909 First released in Issue 1. Derived from Issue 1 of the SVID. 14910 Issue 5 14911 Large File Summit extensions are added. 14912 Issue 6 14913 Extensions beyond the ISO C standard are now marked. 14914 The following new requirements on POSIX implementations derive from alignment with the 14915 Single UNIX Specification: 14916 * The ftello ( ) function is added. 14917 * The [EOVERFLOW] error conditions are added. 14918 An additional [ESPIPE] error condition is added for sockets. 912 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftime( ) 14919 NAME 14920 ftime - get date and time (LEGACY) 14921 SYNOPSIS 14922 XSI #include 14923 int ftime(struct timeb *tp); 14924 14925 DESCRIPTION 14926 The ftime( ) function shall set the time and millitm members of the timeb structure pointed to by 14927 tp to contain the seconds and milliseconds portions, respectively, of the current time in seconds 14928 since the Epoch. The contents of the timezone and dstflag members of tp after a call to ftime( ) are 14929 unspecified. 14930 The system clock need not have millisecond granularity. Depending on any granularity 14931 (particularly a granularity of one) renders code non-portable. 14932 RETURN VALUE 14933 Upon successful completion, the ftime( ) function shall return 0; otherwise, -1 shall be returned. 14934 ERRORS 14935 No errors are defined. 14936 EXAMPLES 14937 Getting the Current Time and Date 14938 The following example shows how to get the current system time values using the ftime( ) 14939 function. The timeb structure pointed to by tp is filled with the current system time values for 14940 time and millitm. 14941 #include 14942 struct timeb tp; 14943 int status; 14944 ... 14945 status = ftime(&tp); 14946 APPLICATION USAGE 14947 For applications portability, the time( ) function should be used to determine the current time 14948 instead of ftime( ). Realtime applications should use clock_gettime( ) to determine the current 14949 time instead of ftime( ). 14950 RATIONALE 14951 None. 14952 FUTURE DIRECTIONS 14953 This function may be withdrawn in a future version. 14954 SEE ALSO 14955 clock_getres( ), ctime( ), gettimeofday( ), time( ), the Base Definitions volume of 14956 IEEE Std 1003.1-200x, 14957 CHANGE HISTORY 14958 First released in Issue 4, Version 2. System Interfaces, Issue 6 913 ftime( ) System Interfaces 14959 Issue 5 14960 Moved from X/OPEN UNIX extension to BASE. 14961 Normative text previously in the APPLICATION USAGE section is moved to the 14962 DESCRIPTION. 14963 Issue 6 14964 This function is marked LEGACY. 14965 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 14966 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time 14967 functions. 914 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftok( ) 14968 NAME 14969 ftok - generate an IPC key 14970 SYNOPSIS 14971 XSI #include 14972 key_t ftok(const char *path, int id); 14973 14974 DESCRIPTION 14975 The ftok( ) function shall return a key based on path and id that is usable in subsequent calls to 14976 msgget( ), semget( ), and shmget( ). The application shall ensure that the path argument is the | 14977 pathname of an existing file that the process is able to stat( ). | 14978 The ftok( ) function shall return the same key value for all paths that name the same file, when 14979 called with the same id value, and return different key values when called with different id 14980 values or with paths that name different files existing on the same file system at the same time. It 14981 is unspecified whether ftok( ) shall return the same key value when called again after the file 14982 named by path is removed and recreated with the same name. 14983 Only the low order 8-bits of id are significant. The behavior of ftok( ) is unspecified if these bits 14984 are 0. 14985 RETURN VALUE 14986 Upon successful completion, ftok( ) shall return a key. Otherwise, ftok( ) shall return (key_t)-1 14987 and set errno to indicate the error. 14988 ERRORS 14989 The ftok( ) function shall fail if: 14990 [EACCES] Search permission is denied for a component of the path prefix. 14991 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 14992 argument. 14993 [ENAMETOOLONG] 14994 The length of the path argument exceeds {PATH_MAX} or a pathname | 14995 component is longer than {NAME_MAX}. | 14996 [ENOENT] A component of path does not name an existing file or path is an empty string. 14997 [ENOTDIR] A component of the path prefix is not a directory. 14998 The ftok( ) function may fail if: 14999 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 15000 resolution of the path argument. 15001 [ENAMETOOLONG] 15002 Pathname resolution of a symbolic link produced an intermediate result | 15003 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 915 ftok( ) System Interfaces 15004 EXAMPLES 15005 Getting an IPC Key 15006 The following example gets a unique key that can be used by the IPC functions semget( ), 15007 msgget( ), and shmget( ). The key returned by ftok( ) for this example is based on the ID value S | 15008 and the pathname /tmp. | 15009 #include 15010 ... 15011 key_t key; 15012 char *path = "/tmp"; 15013 int id = 'S'; 15014 key = ftok(path, id); 15015 Saving an IPC Key 15016 The following example gets a unique key based on the pathname /tmp and the ID value a. It | 15017 also assigns the value of the resulting key to the semkey variable so that it will be available to a 15018 later call to semget( ), msgget( ), or shmget( ). 15019 #include 15020 ... 15021 key_t semkey; 15022 if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { 15023 perror("IPC error: ftok"); exit(1); 15024 } 15025 APPLICATION USAGE 15026 For maximum portability, id should be a single-byte character. 15027 RATIONALE 15028 None. 15029 FUTURE DIRECTIONS 15030 None. 15031 SEE ALSO 15032 msgget( ), semget( ), shmget( ), the Base Definitions volume of IEEE Std 1003.1-200x, 15033 CHANGE HISTORY 15034 First released in Issue 4, Version 2. 15035 Issue 5 15036 Moved from X/OPEN UNIX extension to BASE. 15037 Issue 6 15038 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 15039 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 15040 [ELOOP] error condition is added. 916 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftruncate( ) 15041 NAME 15042 ftruncate - truncate a file to a specified length 15043 SYNOPSIS 15044 #include 15045 int ftruncate(int fildes, off_t length); 15046 DESCRIPTION 15047 If fildes is not a valid file descriptor open for writing, the ftruncate( ) function shall fail. 15048 If fildes refers to a regular file, the ftruncate( ) function shall cause the size of the file to be 15049 truncated to length. If the size of the file previously exceeded length, the extra data shall no 15050 longer be available to reads on the file. If the file previously was smaller than this size, 15051 XSI ftruncate( ) shall either increase the size of the file or fail. XSI-conformant systems shall increase 15052 the size of the file. If the file size is increased, the extended area shall appear as if it were zero- 15053 filled. The value of the seek pointer shall not be modified by a call to ftruncate( ). 15054 Upon successful completion, if fildes refers to a regular file, the ftruncate( ) function shall mark 15055 for update the st_ctime and st_mtime fields of the file and the S_ISUID and S_ISGID bits of the file 15056 mode may be cleared. If the ftruncate( ) function is unsuccessful, the file is unaffected. 15057 XSI If the request would cause the file size to exceed the soft file size limit for the process, the 15058 request shall fail and the implementation shall generate the SIGXFSZ signal for the thread. 15059 If fildes refers to a directory, ftruncate( ) shall fail. 15060 If fildes refers to any other file type, except a shared memory object, the result is unspecified. 15061 SHM If fildes refers to a shared memory object, ftruncate( ) shall set the size of the shared memory 15062 object to length. 15063 MF|SHM If the effect of ftruncate( ) is to decrease the size of a shared memory object or memory mapped 15064 file and whole pages beyond the new end were previously mapped, then the whole pages 15065 beyond the new end shall be discarded. 15066 MPR If the Memory Protection option is supported, references to discarded pages shall result in the 15067 generation of a SIGBUS signal; otherwise, the result of such references is undefined. 15068 MF|SHM If the effect of ftruncate( ) is to increase the size of a shared memory object, it is unspecified if the 15069 contents of any mapped pages between the old end-of-file and the new are flushed to the 15070 underlying object. 15071 RETURN VALUE 15072 Upon successful completion, ftruncate( ) shall return 0; otherwise, -1 shall be returned and errno 15073 set to indicate the error. 15074 ERRORS 15075 The ftruncate( ) function shall fail if: 15076 [EINTR] A signal was caught during execution. 15077 [EINVAL] The length argument was less than 0. 15078 [EFBIG] or [EINVAL] 15079 The length argument was greater than the maximum file size. 15080 XSI [EFBIG] The file is a regular file and length is greater than the offset maximum 15081 established in the open file description associated with fildes. 15082 [EIO] An I/O error occurred while reading from or writing to a file system. System Interfaces, Issue 6 917 ftruncate( ) System Interfaces 15083 [EBADF] or [EINVAL] 15084 The fildes argument is not a file descriptor open for writing. 15085 [EINVAL] The fildes argument references a file that was opened without write 15086 permission. 15087 [EROFS] The named file resides on a read-only file system. 15088 EXAMPLES 15089 None. 15090 APPLICATION USAGE 15091 None. 15092 RATIONALE 15093 The ftruncate( ) function is part of IEEE Std 1003.1-200x as it was deemed to be more useful than 15094 truncate( ). The truncate( ) function is provided as an XSI extension. 15095 FUTURE DIRECTIONS 15096 None. 15097 SEE ALSO 15098 open( ), truncate( ), the Base Definitions volume of IEEE Std 1003.1-200x, 15099 CHANGE HISTORY 15100 First released in Issue 4, Version 2. 15101 Issue 5 15102 Moved from X/OPEN UNIX extension to BASE and aligned with ftruncate( ) in the POSIX 15103 Realtime Extension. Specifically, the DESCRIPTION is extensively reworded and [EROFS] is 15104 added to the list of mandatory errors that can be returned by ftruncate( ). 15105 Large File Summit extensions are added. 15106 Issue 6 15107 The truncate( ) function has been split out into a separate reference page. 15108 The following new requirements on POSIX implementations derive from alignment with the 15109 Single UNIX Specification: 15110 * The DESCRIPTION is change to indicate that if the file size is changed, and if the file is a 15111 regular file, the S_ISUID and S_ISGID bits in the file mode may be cleared. 15112 The following changes were made to align with the IEEE P1003.1a draft standard: 15113 * The DESCRIPTION text is updated. 15114 XSI-conformant systems are required to increase the size of the file if the file was previously 15115 smaller than the size requested. 918 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftrylockfile( ) 15116 NAME 15117 ftrylockfile - stdio locking functions 15118 SYNOPSIS 15119 TSF #include 15120 int ftrylockfile(FILE *file); 15121 15122 DESCRIPTION 15123 Refer to flockfile ( ). System Interfaces, Issue 6 919 ftw( ) System Interfaces 15124 NAME 15125 ftw - traverse (walk) a file tree 15126 SYNOPSIS 15127 XSI #include 15128 int ftw(const char *path, int (*fn)(const char *, 15129 const struct stat *ptr, int flag), int ndirs); 15130 15131 DESCRIPTION 15132 The ftw( ) function shall recursively descend the directory hierarchy rooted in path. For each | 15133 object in the hierarchy, ftw( ) shall call the function pointed to by fn, passing it a pointer to a 15134 null-terminated character string containing the name of the object, a pointer to a stat structure 15135 containing information about the object, and an integer. Possible values of the integer, defined 15136 in the header, are: 15137 FTW_D For a directory. 15138 FTW_DNR For a directory that cannot be read. 15139 FTW_F For a file. 15140 FTW_SL For a symbolic link (but see also FTW_NS below). 15141 FTW_NS For an object other than a symbolic link on which stat( ) could not successfully be 15142 executed. If the object is a symbolic link and stat( ) failed, it is unspecified whether 15143 ftw( ) passes FTW_SL or FTW_NS to the user-supplied function. 15144 If the integer is FTW_DNR, descendants of that directory shall not be processed. If the integer is 15145 FTW_NS, the stat structure contains undefined values. An example of an object that would 15146 cause FTW_NS to be passed to the function pointed to by fn would be a file in a directory with 15147 read but without execute (search) permission. 15148 The ftw( ) function shall visit a directory before visiting any of its descendants. 15149 The ftw( ) function shall use at most one file descriptor for each level in the tree. 15150 The argument ndirs should be in the range of 1 to {OPEN_MAX}. 15151 The tree traversal shall continue until either the tree is exhausted, an invocation of fn returns a 15152 non-zero value, or some error, other than [EACCES], is detected within ftw( ). 15153 The ndirs argument shall specify the maximum number of directory streams or file descriptors 15154 or both available for use by ftw( ) while traversing the tree. When ftw( ) returns it shall close any 15155 directory streams and file descriptors it uses not counting any opened by the application- 15156 supplied fn function. | 15157 The results are unspecified if the application-supplied fn function does not preserve the current | 15158 working directory. | 15159 The ftw( ) function need not be reentrant. A function that is not required to be reentrant is not | 15160 required to be thread-safe. | 15161 RETURN VALUE 15162 If the tree is exhausted, ftw( ) shall return 0. If the function pointed to by fn returns a non-zero 15163 value, ftw( ) shall stop its tree traversal and return whatever value was returned by the function 15164 pointed to by fn. If ftw( ) detects an error, it shall return -1 and set errno to indicate the error. 15165 If ftw( ) encounters an error other than [EACCES] (see FTW_DNR and FTW_NS above), it shall 15166 return -1 and set errno to indicate the error. The external variable errno may contain any error 920 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ftw( ) 15167 value that is possible when a directory is opened or when one of the stat functions is executed on 15168 a directory or file. 15169 ERRORS 15170 The ftw( ) function shall fail if: 15171 [EACCES] Search permission is denied for any component of path or read permission is 15172 denied for path. 15173 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 15174 argument. 15175 [ENAMETOOLONG] 15176 The length of the path argument exceeds {PATH_MAX} or a pathname | 15177 component is longer than {NAME_MAX}. | 15178 [ENOENT] A component of path does not name an existing file or path is an empty string. 15179 [ENOTDIR] A component of path is not a directory. | 15180 [EOVERFLOW] A field in the stat structure cannot be represented correctly in the current | 15181 programming environment for one or more files found in the file hierarchy. | 15182 The ftw( ) function may fail if: 15183 [EINVAL] The value of the ndirs argument is invalid. 15184 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 15185 resolution of the path argument. 15186 [ENAMETOOLONG] 15187 Pathname resolution of a symbolic link produced an intermediate result | 15188 whose length exceeds {PATH_MAX}. 15189 In addition, if the function pointed to by fn encounters system errors, errno may be set 15190 accordingly. 15191 EXAMPLES 15192 Walking a Directory Structure 15193 The following example walks the current directory structure, calling the fn function for every 15194 directory entry, using at most 10 file descriptors: 15195 #include 15196 ... 15197 if (ftw(".", fn, 10) != 0) { 15198 perror("ftw"); exit(2); 15199 } 15200 APPLICATION USAGE 15201 The ftw( ) function may allocate dynamic storage during its operation. If ftw( ) is forcibly 15202 terminated, such as by longjmp( ) or siglongjmp( ) being executed by the function pointed to by fn 15203 or an interrupt routine, ftw( ) does not have a chance to free that storage, so it remains 15204 permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has 15205 occurred, and arrange to have the function pointed to by fn return a non-zero value at its next 15206 invocation. System Interfaces, Issue 6 921 ftw( ) System Interfaces 15207 RATIONALE 15208 None. 15209 FUTURE DIRECTIONS 15210 None. 15211 SEE ALSO 15212 longjmp( ), lstat( ), malloc( ), nftw( ), opendir( ), siglongjmp( ), stat( ), the Base Definitions volume of 15213 IEEE Std 1003.1-200x, , 15214 CHANGE HISTORY 15215 First released in Issue 1. Derived from Issue 1 of the SVID. 15216 Issue 5 15217 UX codings in the DESCRIPTION, RETURN VALUE, and ERRORS sections have been changed 15218 to EX. 15219 Issue 6 15220 The ERRORS section is updated as follows: | 15221 * The wording of the mandatory [ELOOP] error condition is updated. | 15222 * A second optional [ELOOP] error condition is added. | 15223 * The [EOVERFLOW] mandatory error condition is added. | 15224 Text is added to the DESCRIPTION to say that the ftw( ) function need not be reentrant and that | 15225 the results are unspecified if the application-supplied fn function does not preserve the current | 15226 working directory. | 922 Technical Standard (2001) (Draft April 16, 2001) System Interfaces funlockfile( ) 15227 NAME 15228 funlockfile - stdio locking functions 15229 SYNOPSIS 15230 TSF #include 15231 void funlockfile(FILE *file); 15232 15233 DESCRIPTION 15234 Refer to flockfile ( ). System Interfaces, Issue 6 923 fwide( ) System Interfaces 15235 NAME 15236 fwide - set stream orientation 15237 SYNOPSIS 15238 #include 15239 #include 15240 int fwide(FILE *stream, int mode); 15241 DESCRIPTION 15242 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15243 conflict between the requirements described here and the ISO C standard is unintentional. This 15244 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 15245 The fwide( ) function shall determine the orientation of the stream pointed to by stream. If mode is 15246 greater than zero, the function first attempts to make the stream wide-oriented. If mode is less 15247 than zero, the function first attempts to make the stream byte-oriented. Otherwise, mode is zero 15248 and the function does not alter the orientation of the stream. 15249 If the orientation of the stream has already been determined, fwide( ) shall not change it. 15250 CX Since no return value is reserved to indicate an error, an application wishing to check for error | 15251 situations should set errno to 0, then call fwide( ), then check errno, and if it is non-zero, assume 15252 an error has occurred. 15253 RETURN VALUE 15254 The fwide( ) function shall return a value greater than zero if, after the call, the stream has wide- 15255 orientation, a value less than zero if the stream has byte-orientation, or zero if the stream has no 15256 orientation. 15257 ERRORS 15258 The fwide( ) function may fail if: 15259 CX [EBADF] The stream argument is not a valid stream. 15260 EXAMPLES 15261 None. 15262 APPLICATION USAGE 15263 A call to fwide( ) with mode set to zero can be used to determine the current orientation of a 15264 stream. 15265 RATIONALE 15266 None. 15267 FUTURE DIRECTIONS 15268 None. 15269 SEE ALSO 15270 The Base Definitions volume of IEEE Std 1003.1-200x, 15271 CHANGE HISTORY 15272 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 15273 (E). 15274 Issue 6 15275 Extensions beyond the ISO C standard are now marked. 924 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwprintf( ) 15276 NAME 15277 fwprintf, swprintf, wprintf - print formatted wide-character output 15278 SYNOPSIS 15279 #include 15280 #include 15281 int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...); 15282 int swprintf(wchar_t *restrict ws, size_t n, 15283 const wchar_t *restrict format, ...); 15284 int wprintf(const wchar_t *restrict format, ...); 15285 DESCRIPTION 15286 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15287 conflict between the requirements described here and the ISO C standard is unintentional. This 15288 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 15289 The fwprintf( ) function shall place output on the named output stream. The wprintf( ) function | 15290 shall place output on the standard output stream stdout. The swprintf( ) function shall place | 15291 output followed by the null wide character in consecutive wide characters starting at *ws; no | 15292 more than n wide characters shall be written, including a terminating null wide character, which | 15293 is always added (unless n is zero). 15294 Each of these functions shall convert, format, and print its arguments under control of the format | 15295 wide-character string. The format is composed of zero or more directives: ordinary wide- 15296 characters, which are simply copied to the output stream, and conversion specifications, each of 15297 which results in the fetching of zero or more arguments. The results are undefined if there are 15298 insufficient arguments for the format. If the format is exhausted while arguments remain, the 15299 excess arguments are evaluated but are otherwise ignored. 15300 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 15301 to the next unused argument. In this case, the conversion specifier wide character % (see below) 15302 is replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], 15303 giving the position of the argument in the argument list. This feature provides for the definition 15304 of format wide-character strings that select arguments in an order appropriate to specific 15305 languages (see the EXAMPLES section). 15306 The format can contain either numbered argument specifications (that is, "%n$" and "*m$"), or 15307 unnumbered argument conversion specifications (that is, % and *), but not both. The only | 15308 exception to this is that %% can be mixed with the "%n$" form. The results of mixing numbered | 15309 and unnumbered argument specifications in a format wide-character string are undefined. When 15310 numbered argument specifications are used, specifying the Nth argument requires that all the 15311 leading arguments, from the first to the (N-1)th, are specified in the format wide-character 15312 string. 15313 In format wide-character strings containing the "%n$" form of conversion specification, 15314 numbered arguments in the argument list can be referenced from the format wide-character 15315 string as many times as required. 15316 In format wide-character strings containing the % form of conversion specification, each | 15317 argument in the argument list shall be used exactly once. | 15318 CX All forms of the fwprintf( ) function allow for the insertion of a locale-dependent radix character 15319 in the output string, output as a wide-character value. The radix character is defined in the 15320 program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the radix 15321 character is not defined, the radix character shall default to a period ('.'). System Interfaces, Issue 6 925 fwprintf( ) System Interfaces 15322 XSI Each conversion specification is introduced by the '%' wide character or by the wide-character 15323 sequence "%n$",after which the following appear in sequence: 15324 * Zero or more flags (in any order), which modify the meaning of the conversion specification. 15325 * An optional minimum field width. If the converted value has fewer wide characters than the 15326 field width, it shall be padded with spaces by default on the left; it shall be padded on the 15327 right, if the left-adjustment flag ('-'), described below, is given to the field width. The field 15328 width takes the form of an asterisk ('*'), described below, or a decimal integer. 15329 * An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 15330 and X conversion specifiers; the number of digits to appear after the radix character for the a, 15331 A, e, E, f, and F conversion specifiers; the maximum number of significant digits for the g 15332 and G conversion specifiers; or the maximum number of wide characters to be printed from a 15333 string in the s conversion specifiers. The precision takes the form of a period ('.') followed 15334 either by an asterisk ('*'), described below, or an optional decimal digit string, where a null 15335 digit string is treated as 0. If a precision appears with any other conversion wide character, 15336 the behavior is undefined. 15337 * An optional length modifier that specifies the size of the argument. 15338 * A conversion specifier wide character that indicates the type of conversion to be applied. 15339 A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 15340 argument of type int supplies the field width or precision. Applications shall ensure that 15341 arguments specifying field width, or precision, or both appear in that order before the argument, 15342 if any, to be converted. A negative field width is taken as a '-' flag followed by a positive field 15343 XSI width. A negative precision is taken as if the precision were omitted. In format wide-character 15344 strings containing the "%n$" form of a conversion specification, a field width or precision may 15345 be indicated by the sequence "*m$", where m is a decimal integer in the range 15346 [1,{NL_ARGMAX}] giving the position in the argument list (after the format argument) of an 15347 integer argument containing the field width or precision, for example: 15348 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 15349 The flag wide characters and their meanings are: 15350 XSI ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %F, %g, or %G) 15351 shall be formatted with thousands' grouping wide characters. For other conversions, 15352 the behavior is undefined. The numeric grouping wide character is used. 15353 - The result of the conversion shall be left-justified within the field. The conversion shall 15354 be right-justified if this flag is not specified. 15355 + The result of a signed conversion shall always begin with a sign ('+' or '-'). The 15356 conversion shall begin with a sign only when a negative value is converted if this flag is 15357 not specified. 15358 If the first wide character of a signed conversion is not a sign, or if a signed conversion 15359 results in no wide characters, a shall be prefixed to the result. This means that 15360 if the and '+' flags both appear, the flag shall be ignored. 15361 # Specifies that the value is to be converted to an alternative form. For o conversion, it | 15362 increases the precision (if necessary) to force the first digit of the result to be 0. For x or 15363 X conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed to it. For a, A, e, 15364 E, f, F, g, and G conversion specifiers, the result shall always contain a radix character, 15365 even if no digits follow it. Without this flag, a radix character appears in the result of 15366 these conversions only if a digit follows it. For g and G conversion specifiers, trailing 15367 zeros shall not be removed from the result as they normally are. For other conversion 926 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwprintf( ) 15368 specifiers, the behavior is undefined. | 15369 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversion specifiers, leading zeros | 15370 (following any indication of sign or base) are used to pad to the field width; no space 15371 padding is performed. If the '0' and '-' flags both appear, the '0' flag shall be 15372 ignored. For d, i, o, u, x, and X conversion specifiers, if a precision is specified, the '0' 15373 flag shall be ignored. If the '0' and '\'' flags both appear, the grouping wide 15374 characters are inserted before zero padding. For other conversions, the behavior is 15375 undefined. 15376 The length modifiers and their meanings are: 15377 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a signed char 15378 or unsigned char argument (the argument will have been promoted according to the 15379 integer promotions, but its value shall be converted to signed char or unsigned char 15380 before printing); or that a following n conversion specifier applies to a pointer to a 15381 signed char argument. 15382 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short or 15383 unsigned short argument (the argument will have been promoted according to the 15384 integer promotions, but its value shall be converted to short or unsigned short before 15385 printing); or that a following n conversion specifier applies to a pointer to a short 15386 argument. 15387 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long or 15388 unsigned long argument; that a following n conversion specifier applies to a pointer to 15389 a long argument; that a following c conversion specifier applies to a wint_t argument; 15390 that a following s conversion specifier applies to a pointer to a wchar_t argument; or 15391 has no effect on a following a, A, e, E, f, F, g, or G conversion specifier. 15392 ll (ell-ell) 15393 Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long long or 15394 unsigned long long argument; or that a following n conversion specifier applies to a 15395 pointer to a long long argument. 15396 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to an intmax_t 15397 or uintmax_t argument; or that a following n conversion specifier applies to a pointer 15398 to an intmax_t argument. 15399 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a size_t or the 15400 corresponding signed integer type argument; or that a following n conversion specifier 15401 applies to a pointer to a signed integer type corresponding to size_t argument. 15402 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t or 15403 the corresponding unsigned type argument; or that a following n conversion specifier 15404 applies to a pointer to a ptrdiff_t argument. 15405 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long 15406 double argument. 15407 If a length modifier appears with any conversion specifier other than as specified above, the 15408 behavior is undefined. 15409 The conversion specifiers and their meanings are: 15410 d, i The int argument shall be converted to a signed decimal in the style "[-]dddd". The | 15411 precision specifies the minimum number of digits to appear; if the value being 15412 converted can be represented in fewer digits, it shall be expanded with leading zeros. 15413 The default precision shall be 1. The result of converting zero with an explicit precision | System Interfaces, Issue 6 927 fwprintf( ) System Interfaces 15414 of zero shall be no wide characters. | 15415 o The unsigned argument shall be converted to unsigned octal format in the style | 15416 "dddd". The precision specifies the minimum number of digits to appear; if the value 15417 being converted can be represented in fewer digits, it shall be expanded with leading | 15418 zeros. The default precision shall be 1. The result of converting zero with an explicit | 15419 precision of zero shall be no wide characters. | 15420 u The unsigned argument shall be converted to unsigned decimal format in the style | 15421 "dddd". The precision specifies the minimum number of digits to appear; if the value 15422 being converted can be represented in fewer digits, it shall be expanded with leading | 15423 zeros. The default precision shall be 1. The result of converting zero with an explicit | 15424 precision of zero shall be no wide characters. | 15425 x The unsigned argument shall be converted to unsigned hexadecimal format in the style | 15426 "dddd"; the letters "abcdef" are used. The precision specifies the minimum number 15427 of digits to appear; if the value being converted can be represented in fewer digits, it 15428 shall be expanded with leading zeros. The default precision shall be 1. The result of | 15429 converting zero with an explicit precision of zero shall be no wide characters. | 15430 X Equivalent to the x conversion specifier, except that letters "ABCDEF" are used instead | 15431 of "abcdef". 15432 f, F The double argument shall be converted to decimal notation in the style | 15433 "[-]ddd.ddd", where the number of digits after the radix character shall be equal to | 15434 the precision specification. If the precision is missing, it shall be taken as 6; if the | 15435 precision is explicitly zero and no '#' flag is present, no radix character shall appear. If | 15436 a radix character appears, at least one digit shall appear before it. The value shall be | 15437 rounded in an implementation-defined manner to the appropriate number of digits. | 15438 A double argument representing an infinity shall be converted in one of the styles | 15439 "[-]inf" or "[-]infinity"; which style is implementation-defined. A double | 15440 argument representing a NaN shall be converted in one of the styles "[-]nan" or | 15441 "[-]nan(n-char-sequence)"; which style, and the meaning of any n-char-sequence, 15442 is implementation-defined. The F conversion specifier produces "INF", "INFINITY", 15443 or "NAN" instead of "inf", "infinity", or "nan", respectively. 15444 e, E The double argument shall be converted in the style "[-]d.ddde±dd", where there | 15445 shall be one digit before the radix character (which is non-zero if the argument is non- | 15446 zero) and the number of digits after it shall be equal to the precision; if the precision is | 15447 missing, it shall be taken as 6; if the precision is zero and no '#' flag is present, no | 15448 radix character shall appear. The value shall be rounded in an implementation-defined | 15449 manner to the appropriate number of digits. The E conversion wide character shall | 15450 produce a number with 'E' instead of 'e' introducing the exponent. The exponent | 15451 always shall contain at least two digits. If the value is zero, the exponent shall be zero. | 15452 A double argument representing an infinity or NaN shall be converted in the style of | 15453 an f or F conversion specifier. | 15454 g, G The double argument shall be converted in the style f or e (or in the style F or E in the | 15455 case of a G conversion specifier), with the precision specifying the number of significant | 15456 digits. If an explicit precision is zero, it shall be taken as 1. The style used depends on | 15457 the value converted; style e (or E) shall be used only if the exponent resulting from | 15458 such a conversion is less than -4 or greater than or equal to the precision. Trailing zeros | 15459 shall be removed from the fractional portion of the result; a radix character shall appear | 15460 only if it is followed by a digit. | 928 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwprintf( ) 15461 A double argument representing an infinity or NaN shall be converted in the style of | 15462 an f or F conversion specifier. | 15463 a, A A double argument representing a floating-point number shlal be converted in the | 15464 style "[-]0xh.hhhhp±d", where there shall be one hexadecimal digit (which is non- | 15465 zero if the argument is a normalized floating-point number and is otherwise | 15466 unspecified) before the decimal-point wide character and the number of hexadecimal | 15467 digits after it shall be equal to the precision; if the precision is missing and FLT_RADIX | 15468 is a power of 2, then the precision shall be sufficient for an exact representation of the | 15469 value; if the precision is missing and FLT_RADIX is not a power of 2, then the precision | 15470 shall be sufficient to distinguish values of type double, except that trailing zeros may | 15471 be omitted; if the precision is zero and the '#' flag is not specified, no decimal-point | 15472 wide character shall appear. The letters "abcdef" are used for a conversion and the | 15473 letters "ABCDEF" for A conversion. The A conversion specifier produces a number with 15474 'X' and 'P' instead of 'x' and 'p'. The exponent shall always contain at least one | 15475 digit, and only as many more digits as necessary to represent the decimal exponent of | 15476 2. If the value is zero, the exponent shall be zero. | 15477 A double argument representing an infinity or NaN shall be converted in the style of | 15478 an f or F conversion specifier. | 15479 c If no l (ell) qualifier is present, the int argument shall be converted to a wide character | 15480 as if by calling the btowc( ) function and the resulting wide character shall be written. | 15481 Otherwise, the wint_t argument shall be converted to wchar_t, and written. | 15482 s If no l (ell) qualifier is present, the application shall ensure that the argument is a 15483 pointer to a character array containing a character sequence beginning in the initial 15484 shift state. Characters from the array shall be converted as if by repeated calls to the | 15485 mbrtowc( ) function, with the conversion state described by an mbstate_t object 15486 initialized to zero before the first character is converted, and written up to (but not 15487 including) the terminating null wide character. If the precision is specified, no more 15488 than that many wide characters shall be written. If the precision is not specified, or is | 15489 greater than the size of the array, the application shall ensure that the array contains a | 15490 null wide character. | 15491 If an l (ell) qualifier is present, the application shall ensure that the argument is a 15492 pointer to an array of type wchar_t. Wide characters from the array shall be written up | 15493 to (but not including) a terminating null wide character. If no precision is specified, or | 15494 is greater than the size of the array, the application shall ensure that the array contains | 15495 a null wide character. If a precision is specified, no more than that many wide | 15496 characters shall be written. | 15497 p The application shall ensure that the argument is a pointer to void. The value of the | 15498 pointer shall be converted to a sequence of printable wide characters in an | 15499 implementation-defined manner. | 15500 n The application shall ensure that the argument is a pointer to an integer into which is 15501 written the number of wide characters written to the output so far by this call to one of 15502 the fwprintf( ) functions. No argument shall be converted, but one shall be consumed. If | 15503 the conversion specification includes any flags, a field width, or a precision, the | 15504 behavior is undefined. 15505 XSI C Equivalent to lc. | 15506 XSI S Equivalent to ls. | System Interfaces, Issue 6 929 fwprintf( ) System Interfaces 15507 % Output a '%' wide character; no argument shall be converted. The entire conversion | 15508 specification shall be %%. 15509 If a conversion specification does not match one of the above forms, the behavior is undefined. 15510 In no case does a nonexistent or small field width cause truncation of a field; if the result of a 15511 conversion is wider than the field width, the field shall be expanded to contain the conversion | 15512 result. Characters generated by fwprintf( ) and wprintf( ) shall be printed as if fputwc( ) had been | 15513 called. 15514 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly | 15515 representable in the given precision, the result should be one of the two adjacent numbers in | 15516 hexadecimal floating style with the given precision, with the extra stipulation that the error | 15517 should have a correct sign for the current rounding direction. | 15518 For e, E, f, F, g, and G conversion specifiers, if the number of significant decimal digits is at most | 15519 DECIMAL_DIG, then the result should be correctly rounded. If the number of significant 15520 decimal digits is more than DECIMAL_DIG but the source value is exactly representable with 15521 DECIMAL_DIG digits, then the result should be an exact representation with trailing zeros. 15522 Otherwise, the source value is bounded by two adjacent decimal strings L < U, both having 15523 DECIMAL_DIG significant digits; the value of the resultant decimal string D should satisfy L <= 15524 D <= U, with the extra stipulation that the error should have a correct sign for the current 15525 rounding direction. 15526 CX The st_ctime and st_mtime fields of the file shall be marked for update between the call to a 15527 successful execution of fwprintf( ) or wprintf( ) and the next successful completion of a call to 15528 fflush( ) or fclose( ) on the same stream, or a call to exit( ) or abort( ). 15529 RETURN VALUE 15530 Upon successful completion, these functions shall return the number of wide characters 15531 transmitted, excluding the terminating null wide character in the case of swprintf( ), or a negative 15532 CX value if an output error was encountered, and set errno to indicate the error. 15533 If n or more wide characters were requested to be written, swprintf( ) shall return a negative 15534 CX value, and set errno to indicate the error. 15535 ERRORS 15536 For the conditions under which fwprintf( ) and wprintf( ) fail and may fail, refer to fputwc( ). 15537 In addition, all forms of fwprintf( ) may fail if: 15538 XSI [EILSEQ] A wide-character code that does not correspond to a valid character has been 15539 detected. 15540 XSI [EINVAL] There are insufficient arguments. 15541 In addition, wprintf( ) and fwprintf( ) may fail if: 15542 XSI [ENOMEM] Insufficient storage space is available. 930 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwprintf( ) 15543 EXAMPLES 15544 To print the language-independent date and time format, the following statement could be used: 15545 wprintf(format, weekday, month, day, hour, min); 15546 For American usage, format could be a pointer to the wide-character string: 15547 L"%s, %s %d, %d:%.2d\n" 15548 producing the message: 15549 Sunday, July 3, 10:02 15550 whereas for German usage, format could be a pointer to the wide-character string: 15551 L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n" 15552 producing the message: 15553 Sonntag, 3. Juli, 10:02 15554 APPLICATION USAGE 15555 None. 15556 RATIONALE 15557 None. 15558 FUTURE DIRECTIONS 15559 None. 15560 SEE ALSO 15561 btowc( ), fputwc( ), fwscanf( ), mbrtowc( ), setlocale( ), the Base Definitions volume of 15562 IEEE Std 1003.1-200x, , , the Base Definitions volume of 15563 IEEE Std 1003.1-200x, Chapter 7, Locale 15564 CHANGE HISTORY 15565 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 15566 (E). 15567 Issue 6 15568 The Open Group Corrigendum U040/1 is applied to the RETURN VALUE section, describing 15569 the case if n or more wide characters are requested to be written using swprintf( ). 15570 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 15571 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 15572 * The prototypes for fwprintf( ), swprintf( ), and wprintf( ) are updated. 15573 * The DESCRIPTION is updated. | 15574 * The hh, ll, j, t, and z length modifiers are added. | 15575 * The a, A, and F conversion characters are added. | 15576 * XSI shading is removed from the description of character string representations of infinity | 15577 and NaN floating-point values. | 15578 The DESCRIPTION is updated to use the terms ``conversion specifier'' and ``conversion 15579 specification'' consistently. | 15580 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 931 fwrite( ) System Interfaces 15581 NAME 15582 fwrite - binary output 15583 SYNOPSIS 15584 #include 15585 size_t fwrite(const void *restrict ptr, size_t size, size_t nitems, 15586 FILE *restrict stream); 15587 DESCRIPTION 15588 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15589 conflict between the requirements described here and the ISO C standard is unintentional. This 15590 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 15591 The fwrite( ) function shall write, from the array pointed to by ptr, up to nitems elements whose 15592 size is specified by size, to the stream pointed to by stream. For each object, size calls shall be 15593 made to the fputc( ) function, taking the values (in order) from an array of unsigned char exactly 15594 overlaying the object. The file-position indicator for the stream (if defined) shall be advanced by 15595 the number of bytes successfully written. If an error occurs, the resulting value of the file- | 15596 position indicator for the stream is unspecified. | 15597 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 15598 execution of fwrite( ) and the next successful completion of a call to fflush( ) or fclose( ) on the 15599 same stream, or a call to exit( ) or abort( ). 15600 RETURN VALUE 15601 The fwrite( ) function shall return the number of elements successfully written, which may be 15602 less than nitems if a write error is encountered. If size or nitems is 0, fwrite( ) shall return 0 and the 15603 state of the stream remains unchanged. Otherwise, if a write error occurs, the error indicator for 15604 CX the stream shall be set, and errno shall be set to indicate the error. 15605 ERRORS 15606 Refer to fputc( ). 15607 EXAMPLES 15608 None. 15609 APPLICATION USAGE 15610 Because of possible differences in element length and byte ordering, files written using fwrite( ) 15611 are application-dependent, and possibly cannot be read using fread( ) by a different application 15612 or by the same application on a different processor. 15613 RATIONALE 15614 None. 15615 FUTURE DIRECTIONS 15616 None. 15617 SEE ALSO 15618 ferror( ), fopen( ), printf( ), putc( ), puts( ), write( ), the Base Definitions volume of 15619 IEEE Std 1003.1-200x, 15620 CHANGE HISTORY 15621 First released in Issue 1. Derived from Issue 1 of the SVID. 15622 Issue 6 15623 Extensions beyond the ISO C standard are now marked. 15624 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 932 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwrite( ) 15625 * The fwrite( ) prototype is updated. 15626 * The DESCRIPTION is updated to clarify how the data is written out using fputc( ). System Interfaces, Issue 6 933 fwscanf( ) System Interfaces 15627 NAME 15628 fwscanf, swscanf, wscanf - convert formatted wide-character input 15629 SYNOPSIS 15630 #include 15631 #include 15632 int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ... ); 15633 int swscanf(const wchar_t *restrict ws, 15634 const wchar_t *restrict format, ... ); 15635 int wscanf(const wchar_t *restrict format, ... ); 15636 DESCRIPTION 15637 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15638 conflict between the requirements described here and the ISO C standard is unintentional. This 15639 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 15640 The fwscanf( ) function shall read from the named input stream. The wscanf( ) function shall read | 15641 from the standard input stream stdin. The swscanf( ) function shall read from the wide-character | 15642 string ws. Each function reads wide characters, interprets them according to a format, and stores | 15643 the results in its arguments. Each expects, as arguments, a control wide-character string format 15644 described below, and a set of pointer arguments indicating where the converted input should be 15645 stored. The result is undefined if there are insufficient arguments for the format. If the format is 15646 exhausted while arguments remain, the excess arguments are evaluated but are otherwise 15647 ignored. 15648 XSI Conversions can be applied to the nth argument after the format in the argument list, rather than 15649 to the next unused argument. In this case, the conversion specifier wide character % (see below) 15650 is replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}]. 15651 This feature provides for the definition of format wide-character strings that select arguments in 15652 an order appropriate to specific languages. In format wide-character strings containing the 15653 "%n$" form of conversion specifications, it is unspecified whether numbered arguments in the 15654 argument list can be referenced from the format wide-character string more than once. 15655 The format can contain either form of a conversion specification-that is, % or "%n$"- but the 15656 two forms cannot normally be mixed within a single format wide-character string. The only 15657 exception to this is that %% or %* can be mixed with the "%n$" form. When numbered | 15658 argument specifications are used, specifying the Nth argument requires that all the leading | 15659 arguments, from the first to the (N-1)th, are pointers. | 15660 CX The fwscanf( ) function in all its forms allows for detection of a language-dependent radix 15661 character in the input string, encoded as a wide-character value. The radix character is defined in 15662 the program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the 15663 radix character is not defined, the radix character shall default to a period ('.'). 15664 The format is a wide-character string composed of zero or more directives. Each directive is 15665 composed of one of the following: one or more white-space wide characters (s, s, 15666 s, s, or s); an ordinary wide character (neither '%' nor a 15667 white-space character); or a conversion specification. Each conversion specification is introduced 15668 XSI by a '%' or the sequence "%n$"after which the following appear in sequence: 15669 * An optional assignment-suppressing character '*'. 15670 * An optional non-zero decimal integer that specifies the maximum field width. 15671 * An optional length modifier that specifies the size of the receiving object. 934 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwscanf( ) 15672 * A conversion specifier wide character that specifies the type of conversion to be applied. The 15673 valid conversion specifiers are described below. 15674 The fwscanf( ) functions shall execut each directive of the format in turn. If a directive fails, as | 15675 detailed below, the function shall return. Failures are described as input failures (due to the | 15676 unavailability of input bytes) or matching failures (due to inappropriate input). | 15677 A directive composed of one or more white-space wide characters is executed by reading input 15678 until no more valid input can be read, or up to the first wide character which is not a white- 15679 space wide character, which remains unread. 15680 A directive that is an ordinary wide character shall be executed as follows. The next wide | 15681 character is read from the input and compared with the wide character that comprises the | 15682 directive; if the comparison shows that they are not equivalent, the directive shall fail, and the | 15683 differing and subsequent wide characters remain unread. Similarly, if end-of-file, an encoding | 15684 error, or a read error prevents a wide character from being read, the directive shall fail. | 15685 A directive that is a conversion specification defines a set of matching input sequences, as 15686 described below for each conversion wide character. A conversion specification is executed in 15687 the following steps. 15688 Input white-space wide characters (as specified by iswspace( )) shall be skipped, unless the | 15689 conversion specification includes a [, c, or n conversion specifier. | 15690 An item shall be read from the input, unless the conversion specification includes an n | 15691 conversion specifier wide character. An input item is defined as the longest sequence of input 15692 wide characters, not exceeding any specified field width, which is an initial subsequence of a 15693 matching sequence. The first wide character, if any, after the input item shall remain unread. If | 15694 the length of the input item is zero, the execution of the conversion specification shall fail; this | 15695 condition is a matching failure, unless end-of-file, an encoding error, or a read error prevented | 15696 input from the stream, in which case it is an input failure. | 15697 Except in the case of a % conversion specifier, the input item (or, in the case of a %n conversion | 15698 specification, the count of input wide characters) shall be converted to a type appropriate to the | 15699 conversion wide character. If the input item is not a matching sequence, the execution of the | 15700 conversion specification shall fail; this condition is a matching failure. Unless assignment | 15701 suppression was indicated by a '*', the result of the conversion shall be placed in the object | 15702 pointed to by the first argument following the format argument that has not already received a | 15703 XSI conversion result if the conversion specification is introduced by %, or in the nth argument if 15704 introduced by the wide-character sequence "%n$". If this object does not have an appropriate 15705 type, or if the result of the conversion cannot be represented in the space provided, the behavior 15706 is undefined. 15707 The length modifiers and their meanings are: 15708 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15709 argument with type pointer to signed char or unsigned char. 15710 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15711 argument with type pointer to short or unsigned short. 15712 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15713 argument with type pointer to long or unsigned long; that a following a, A, e, E, f, F, g, 15714 or G conversion specifier applies to an argument with type pointer to double; or that a 15715 following c, s, or [ conversion specifier applies to an argument with type pointer to 15716 wchar_t. System Interfaces, Issue 6 935 fwscanf( ) System Interfaces 15717 ll (ell-ell) 15718 Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15719 argument with type pointer to long long or unsigned long long. 15720 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15721 argument with type pointer to intmax_t or uintmax_t. 15722 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15723 argument with type pointer to size_t or the corresponding signed integer type. 15724 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an 15725 argument with type pointer to ptrdiff_t or the corresponding unsigned type. 15726 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an 15727 argument with type pointer to long double. 15728 If a length modifier appears with any conversion specifier other than as specified above, the 15729 behavior is undefined. 15730 The following conversion specifier wide characters are valid: 15731 d Matches an optionally signed decimal integer, whose format is the same as expected for 15732 the subject sequence of wcstol( ) with the value 10 for the base argument. In the absence 15733 of a size modifier, the application shall ensure that the corresponding argument is a 15734 pointer to int. 15735 i Matches an optionally signed integer, whose format is the same as expected for the 15736 subject sequence of wcstol( ) with 0 for the base argument. In the absence of a size 15737 modifier, the application shall ensure that the corresponding argument is a pointer to 15738 int. 15739 o Matches an optionally signed octal integer, whose format is the same as expected for 15740 the subject sequence of wcstoul( ) with the value 8 for the base argument. In the absence 15741 of a size modifier, the application shall ensure that the corresponding argument is a 15742 pointer to unsigned. 15743 u Matches an optionally signed decimal integer, whose format is the same as expected for 15744 the subject sequence of wcstoul( ) with the value 10 for the base argument. In the absence 15745 of a size modifier, the application shall ensure that the corresponding argument is a 15746 pointer to unsigned. 15747 x Matches an optionally signed hexadecimal integer, whose format is the same as 15748 expected for the subject sequence of wcstoul( ) with the value 16 for the base argument. 15749 In the absence of a size modifier, the application shall ensure that the corresponding 15750 argument is a pointer to unsigned. 15751 a, e, f, g 15752 Matches an optionally signed floating-point number, infinity, or NaN whose format is 15753 the same as expected for the subject sequence of wcstod( ). In the absence of a size 15754 modifier, the application shall ensure that the corresponding argument is a pointer to 15755 float. 15756 If the fwprintf( ) family of functions generates character string representations for 15757 infinity and NaN (a symbolic entity encoded in floating-point format) to support 15758 IEEE Std 754-1985, the fwscanf( ) family of functions shall recognize them as input. 15759 s Matches a sequence of non white-space wide characters. If no l (ell) qualifier is present, | 15760 characters from the input field shall be converted as if by repeated calls to the | 15761 wcrtomb( ) function, with the conversion state described by an mbstate_t object 936 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwscanf( ) 15762 initialized to zero before the first wide character is converted. The application shall 15763 ensure that the corresponding argument is a pointer to a character array large enough 15764 to accept the sequence and the terminating null character, which shall be added 15765 automatically. 15766 Otherwise, the application shall ensure that the corresponding argument is a pointer to 15767 an array of wchar_t large enough to accept the sequence and the terminating null wide 15768 character, which shall be added automatically. 15769 [ Matches a non-empty sequence of wide characters from a set of expected wide 15770 characters (the scanset). If no l (ell) qualifier is present, wide characters from the input | 15771 field shall be converted as if by repeated calls to the wcrtomb( ) function, with the | 15772 conversion state described by an mbstate_t object initialized to zero before the first 15773 wide character is converted. The application shall ensure that the corresponding 15774 argument is a pointer to a character array large enough to accept the sequence and the 15775 terminating null character, which shall be added automatically. 15776 If an l (ell) qualifier is present, the application shall ensure that the corresponding 15777 argument is a pointer to an array of wchar_t large enough to accept the sequence and 15778 the terminating null wide character, which shall be added automatically. 15779 The conversion specification includes all subsequent wide characters in the format 15780 string up to and including the matching right square bracket (']'). The wide 15781 characters between the square brackets (the scanlist) comprise the scanset, unless the 15782 wide character after the left square bracket is a circumflex (' '), in which case the 15783 scanset contains all wide characters that do not appear in the scanlist between the 15784 circumflex and the right square bracket. If the conversion specification begins with 15785 "[ ]" or "[ ]", the right square bracket is included in the scanlist and the next right 15786 square bracket is the matching right square bracket that ends the conversion 15787 specification; otherwise, the first right square bracket is the one that ends the 15788 conversion specification. If a '-' is in the scanlist and is not the first wide character, 15789 nor the second where the first wide character is a ' ', nor the last wide character, the 15790 behavior is implementation-defined. 15791 c Matches a sequence of wide characters of exactly the number specified by the field 15792 width (1 if no field width is present in the conversion specification). 15793 If no l (ell) length modifier is present, characters from the input field shall be converted | 15794 as if by repeated calls to the wcrtomb( ) function, with the conversion state described by | 15795 an mbstate_t object initialized to zero before the first wide character is converted. The 15796 corresponding argument shall be a pointer to the initial element of a character array 15797 large enough to accept the sequence. No null character is added. 15798 If an l (ell) length modifier is present, the corresponding argument shall be a pointer to 15799 the initial element of an array of wchar_t large enough to accept the sequence. No null 15800 wide character is added. 15801 Otherwise, the application shall ensure that the corresponding argument is a pointer to 15802 an array of wchar_t large enough to accept the sequence. No null wide character is 15803 added. 15804 p Matches an implementation-defined set of sequences, which shall be the same as the set 15805 of sequences that is produced by the %p conversion specification of the corresponding 15806 fwprintf( ) functions. The application shall ensure that the corresponding argument is a 15807 pointer to a pointer to void. The interpretation of the input item is implementation- 15808 defined. If the input item is a value converted earlier during the same program 15809 execution, the pointer that results shall compare equal to that value; otherwise, the System Interfaces, Issue 6 937 fwscanf( ) System Interfaces 15810 behavior of the %p conversion is undefined. 15811 n No input is consumed. The application shall ensure that the corresponding argument is 15812 a pointer to the integer into which is to be written the number of wide characters read 15813 from the input so far by this call to the fwscanf( ) functions. Execution of a %n | 15814 conversion specification shall not increment the assignment count returned at the | 15815 completion of execution of the function. No argument shall be converted, but one shall | 15816 be consumed. If the conversion specification includes an assignment-suppressing wide | 15817 character or a field width, the behavior is undefined. | 15818 XSI C Equivalent to lc. | 15819 XSI S Equivalent to ls. | 15820 % Matches a single '%' wide character; no conversion or assignment shall occur. The | 15821 complete conversion specification shall be %%. | 15822 If a conversion specification is invalid, the behavior is undefined. 15823 The conversion specifiers A, E, F, G, and X are also valid and shall be equivalent to, respectively, | 15824 a, e, f, g, and x. 15825 If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before 15826 any wide characters matching the current conversion specification (except for %n) have been 15827 read (other than leading white-space, where permitted), execution of the current conversion | 15828 specification shall terminate with an input failure. Otherwise, unless execution of the current | 15829 conversion specification is terminated with a matching failure, execution of the following | 15830 conversion specification (if any) shall be terminated with an input failure. | 15831 Reaching the end of the string in swscanf( ) shall be equivalent to encountering end-of-file for | 15832 fwscanf( ). 15833 If conversion terminates on a conflicting input, the offending input shall be left unread in the | 15834 input. Any trailing white space (including ) shall be left unread unless matched by a | 15835 conversion specification. The success of literal matches and suppressed assignments is only | 15836 directly determinable via the %n conversion specification. 15837 CX The fwscanf( ) and wscanf( ) functions may mark the st_atime field of the file associated with 15838 stream for update. The st_atime field shall be marked for update by the first successful execution 15839 of fgetc( ), fgetwc( ), fgets( ), fgetws( ), fread( ), getc( ), getwc( ), getchar( ), getwchar( ), gets( ), fscanf( ), 15840 or fwscanf( ) using stream that returns data not supplied by a prior call to ungetc( ). 15841 RETURN VALUE 15842 Upon successful completion, these functions shall return the number of successfully matched 15843 and assigned input items; this number can be zero in the event of an early matching failure. If 15844 the input ends before the first matching failure or conversion, EOF shall be returned. If a read 15845 CX error occurs the error indicator for the stream is set, EOF shall be returned, and errno shall be set 15846 to indicate the error. 15847 ERRORS 15848 For the conditions under which the fwscanf( ) functions shall fail and may fail, refer to fgetwc( ). 15849 In addition, fwscanf( ) may fail if: 15850 XSI [EILSEQ] Input byte sequence does not form a valid character. 15851 XSI [EINVAL] There are insufficient arguments. 938 Technical Standard (2001) (Draft April 16, 2001) System Interfaces fwscanf( ) 15852 EXAMPLES 15853 The call: 15854 int i, n; float x; char name[50]; 15855 n = wscanf(L"%d%f%s", &i, &x, name); 15856 with the input line: 15857 25 54.32E-1 Hamster 15858 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 15859 "Hamster". 15860 The call: 15861 int i; float x; char name[50]; 15862 (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); 15863 with input: 15864 56789 0123 56a72 15865 assigns 56 to i, 789.0 to x, skip 0123, and place the string "56\0" in name. The next call to 15866 getchar( ) shall return the character 'a'. 15867 APPLICATION USAGE 15868 In format strings containing the '%' form of conversion specifications, each argument in the 15869 argument list is used exactly once. 15870 RATIONALE 15871 None. 15872 FUTURE DIRECTIONS 15873 None. 15874 SEE ALSO 15875 getwc( ), fwprintf( ), setlocale( ), wcstod( ), wcstol( ), wcstoul( ), wcrtomb( ), the Base Definitions 15876 volume of IEEE Std 1003.1-200x, , , , the Base Definitions 15877 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 15878 CHANGE HISTORY 15879 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 15880 (E). 15881 Issue 6 15882 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 15883 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 15884 * The prototypes for fwscanf( ) and swscanf( ) are updated. 15885 * The DESCRIPTION is updated. | 15886 * The hh, ll, j, t, and z length modifiers are added. | 15887 * The a, A, and F conversion characters are added. | 15888 The DESCRIPTION is updated to use the terms ``conversion specifier'' and ``conversion 15889 specification'' consistently. System Interfaces, Issue 6 939 gai_strerror( ) System Interfaces 15890 NAME 15891 gai_strerror - address and name information error description 15892 SYNOPSIS 15893 #include 15894 const char *gai_strerror(int ecode); | 15895 DESCRIPTION | 15896 The gai_strerror( ) function shall return a text string describing an error value for the getaddrinfo( ) 15897 and getnameinfo( ) functions listed in the header. 15898 When the ecode argument is one of the following values listed in the header: 15899 [EAI_AGAIN] | 15900 [EAI_BADFLAGS] | 15901 [EAI_FAIL] | 15902 [EAI_FAMILY] | 15903 [EAI_MEMORY] | 15904 [EAI_NONAME] | 15905 [EAI_SERVICE] | 15906 [EAI_SOCKTYPE] | 15907 [EAI_SYSTEM] | 15908 the function return value shall point to a string describing the error. If the argument is not one | 15909 of those values, the function shall return a pointer to a string whose contents indicate an | 15910 unknown error. 15911 RETURN VALUE 15912 Upon successful completion, gai_strerror( ) shall return a pointer to an implementation-defined 15913 string. 15914 ERRORS 15915 No errors are defined. 15916 EXAMPLES 15917 None. 15918 APPLICATION USAGE 15919 None. 15920 RATIONALE 15921 None. 15922 FUTURE DIRECTIONS 15923 None. 15924 SEE ALSO 15925 getaddrinfo( ), the Base Definitions volume of IEEE Std 1003.1-200x, 15926 CHANGE HISTORY 15927 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 15928 The Open Group Base Resolution bwg2001-009 is applied, which changes the return type from | 15929 char * to const char *. This is for coordination with the IPnG Working Group. | 940 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gcvt( ) 15930 NAME 15931 gcvt - convert a floating-point number to a string (LEGACY) 15932 SYNOPSIS 15933 XSI #include 15934 char *gcvt(double value, int ndigit, char *buf); 15935 15936 DESCRIPTION 15937 Refer to ecvt( ). System Interfaces, Issue 6 941 getaddrinfo( ) System Interfaces 15938 NAME 15939 getaddrinfo - get address information 15940 SYNOPSIS 15941 #include 15942 #include 15943 int getaddrinfo(const char *restrict nodename, 15944 const char *restrict servname, 15945 const struct addrinfo *restrict hints, 15946 struct addrinfo **restrict res); 15947 DESCRIPTION 15948 Refer to freeaddrinfo( ). 942 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getc( ) 15949 NAME 15950 getc - get a byte from a stream 15951 SYNOPSIS 15952 #include 15953 int getc(FILE *stream); 15954 DESCRIPTION 15955 CX The functionality described on this reference page is aligned with the ISO C standard. Any 15956 conflict between the requirements described here and the ISO C standard is unintentional. This 15957 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 15958 The getc( ) function shall be equivalent to fgetc( ), except that if it is implemented as a macro it 15959 may evaluate stream more than once, so the argument should never be an expression with side 15960 effects. 15961 RETURN VALUE 15962 Refer to fgetc( ). 15963 ERRORS 15964 Refer to fgetc( ). 15965 EXAMPLES 15966 None. 15967 APPLICATION USAGE 15968 If the integer value returned by getc( ) is stored into a variable of type char and then compared 15969 against the integer constant EOF, the comparison may never succeed, because sign-extension of 15970 a variable of type char on widening to integer is implementation-defined. 15971 Since it may be implemented as a macro, getc( ) may treat incorrectly a stream argument with | 15972 side effects. In particular, getc(*f++) does not necessarily work as expected. Therefore, use of this 15973 function should be preceded by "#undef getc" in such situations; fgetc( ) could also be used. 15974 RATIONALE 15975 None. 15976 FUTURE DIRECTIONS 15977 None. 15978 SEE ALSO 15979 fgetc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 15980 CHANGE HISTORY 15981 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 943 getc_unlocked( ) System Interfaces 15982 NAME 15983 getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - stdio with explicit client 15984 locking 15985 SYNOPSIS 15986 TSF #include 15987 int getc_unlocked(FILE *stream); 15988 int getchar_unlocked(void); 15989 int putc_unlocked(int c, FILE *stream); 15990 int putchar_unlocked(int c); 15991 15992 DESCRIPTION 15993 Versions of the functions getc( ), getchar( ), putc( ), and putchar( ) respectively named 15994 getc_unlocked( ), getchar_unlocked( ), putc_unlocked( ), and putchar_unlocked( ) shall be provided | 15995 which are functionally equivalent to the original versions, with the exception that they are not | 15996 required to be implemented in a thread-safe manner. They may only safely be used within a 15997 scope protected by flockfile ( ) (or ftrylockfile ( )) and funlockfile ( ). These functions may safely be 15998 used in a multi-threaded program if and only if they are called while the invoking thread owns 15999 the (FILE *) object, as is the case after a successful call of the flockfile ( ) or ftrylockfile ( ) functions. 16000 RETURN VALUE 16001 See getc( ), getchar( ), putc( ), and putchar( ). 16002 ERRORS 16003 See getc( ), getchar( ), putc( ), and putchar( ). | 16004 EXAMPLES 16005 None. 16006 APPLICATION USAGE 16007 Since they may be implemented as macros, getc_unlocked( ) and putc_unlocked( ) may treat | 16008 incorrectly a stream argument with side effects. In particular, getc_unlocked(*f++) and 16009 putc_unlocked(*f++) do not necessarily work as expected. Therefore, use of these functions in 16010 such situations should be preceded by the following statement as appropriate: 16011 #undef getc_unlocked 16012 #undef putc_unlocked 16013 RATIONALE 16014 Some I/O functions are typically implemented as macros for performance reasons (for example, 16015 putc( ) and getc( )). For safety, they need to be synchronized, but it is often too expensive to 16016 synchronize on every character. Nevertheless, it was felt that the safety concerns were more 16017 important; consequently, the getc( ), getchar( ), putc( ), and putchar( ) functions are required to be 16018 thread-safe. However, unlocked versions are also provided with names that clearly indicate the 16019 unsafe nature of their operation but can be used to exploit their higher performance. These 16020 unlocked versions can be safely used only within explicitly locked program regions, using 16021 exported locking primitives. In particular, a sequence such as: 16022 flockfile(fileptr); 16023 putc_unlocked('1', fileptr); 16024 putc_unlocked('\n', fileptr); 16025 fprintf(fileptr, "Line 2\n"); 16026 funlockfile(fileptr); 16027 is permissible, and results in the text sequence: 944 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getc_unlocked( ) 16028 1 16029 Line 2 16030 being printed without being interspersed with output from other threads. 16031 It would be wrong to have the standard names such as getc( ), putc( ), and so on, map to the 16032 ``faster, but unsafe'' rather than the ``slower, but safe'' versions. In either case, you would still 16033 want to inspect all uses of getc( ), putc( ), and so on, by hand when converting existing code. 16034 Choosing the safe bindings as the default, at least, results in correct code and maintains the 16035 ``atomicity at the function'' invariant. To do otherwise would introduce gratuitous 16036 synchronization errors into converted code. Other routines that modify the stdio (FILE *) 16037 structures or buffers are also safely synchronized. 16038 Note that there is no need for functions of the form getc_locked( ), putc_locked( ), and so on, since 16039 this is the functionality of getc( ), putc( ), et al. It would be inappropriate to use a feature test 16040 macro to switch a macro definition of getc( ) between getc_locked( ) and getc_unlocked( ), since the 16041 ISO C standard requires an actual function to exist, a function whose behavior could not be 16042 changed by the feature test macro. Also, providing both the xxx_locked( ) and xxx_unlocked( ) 16043 forms leads to the confusion of whether the suffix describes the behavior of the function or the 16044 circumstances under which it should be used. 16045 Three additional routines, flockfile ( ), ftrylockfile ( ), and funlockfile ( ) (which may be macros), are 16046 provided to allow the user to delineate a sequence of I/O statements that are executed 16047 synchronously. 16048 The ungetc( ) function is infrequently called relative to the other functions/macros so no 16049 unlocked variation is needed. 16050 FUTURE DIRECTIONS 16051 None. 16052 SEE ALSO 16053 getc( ), getchar( ), putc( ), putchar( ), the Base Definitions volume of IEEE Std 1003.1-200x, 16054 16055 CHANGE HISTORY 16056 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 16057 Issue 6 16058 These functions are marked as part of the Thread-Safe Functions option. 16059 The Open Group Corrigendum U030/2 is applied, adding APPLICATION USAGE describing 16060 how applications should be written to avoid the case when the functions are implemented as 16061 macros. System Interfaces, Issue 6 945 getchar( ) System Interfaces 16062 NAME 16063 getchar - get a byte from a stdin stream 16064 SYNOPSIS 16065 #include 16066 int getchar(void); 16067 DESCRIPTION 16068 CX The functionality described on this reference page is aligned with the ISO C standard. Any 16069 conflict between the requirements described here and the ISO C standard is unintentional. This 16070 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 16071 The getchar( ) function shall be equivalent to getc(stdin). 16072 RETURN VALUE 16073 Refer to fgetc( ). 16074 ERRORS 16075 Refer to fgetc( ). 16076 EXAMPLES 16077 None. 16078 APPLICATION USAGE 16079 If the integer value returned by getchar( ) is stored into a variable of type char and then 16080 compared against the integer constant EOF, the comparison may never succeed, because sign- 16081 extension of a variable of type char on widening to integer is implementation-defined. 16082 RATIONALE 16083 None. 16084 FUTURE DIRECTIONS 16085 None. 16086 SEE ALSO 16087 getc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 16088 CHANGE HISTORY 16089 First released in Issue 1. Derived from Issue 1 of the SVID. 946 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getchar_unlocked( ) 16090 NAME 16091 getchar_unlocked - stdio with explicit client locking 16092 SYNOPSIS 16093 TSF #include 16094 int getchar_unlocked(void); 16095 16096 DESCRIPTION 16097 Refer to getc_unlocked( ). System Interfaces, Issue 6 947 getcontext( ) System Interfaces 16098 NAME 16099 getcontext, setcontext - get and set current user context 16100 SYNOPSIS 16101 XSI #include 16102 int getcontext(ucontext_t *ucp); 16103 int setcontext(const ucontext_t *ucp); 16104 16105 DESCRIPTION 16106 The getcontext( ) function shall initialize the structure pointed to by ucp to the current user 16107 context of the calling thread. The ucontext_t type that ucp points to defines the user context and 16108 includes the contents of the calling thread's machine registers, the signal mask, and the current 16109 execution stack. 16110 The setcontext( ) function shall restore the user context pointed to by ucp. A successful call to 16111 setcontext( ) shall not return; program execution resumes at the point specified by the ucp 16112 argument passed to setcontext( ). The ucp argument should be created either by a prior call to 16113 getcontext( ) or makecontext( ), or by being passed as an argument to a signal handler. If the ucp 16114 argument was created with getcontext( ), program execution continues as if the corresponding 16115 call of getcontext( ) had just returned. If the ucp argument was created with makecontext( ), 16116 program execution continues with the function passed to makecontext( ). When that function 16117 returns, the thread shall continue as if after a call to setcontext( ) with the ucp argument that was 16118 input to makecontext( ). If the uc_link member of the ucontext_t structure pointed to by the ucp 16119 argument is equal to 0, then this context is the main context, and the thread shall exit when this 16120 context returns. The effects of passing a ucp argument obtained from any other source are 16121 unspecified. 16122 RETURN VALUE 16123 Upon successful completion, setcontext( ) shall not return and getcontext( ) shall return 0; 16124 otherwise, a value of -1 shall be returned. 16125 ERRORS 16126 No errors are defined. 16127 EXAMPLES 16128 Refer to makecontext( ). | 16129 APPLICATION USAGE 16130 When a signal handler is executed, the current user context is saved and a new context is 16131 created. If the thread leaves the signal handler via longjmp( ), then it is unspecified whether the 16132 context at the time of the corresponding setjmp( ) call is restored and thus whether future calls to 16133 getcontext( ) provide an accurate representation of the current context, since the context restored 16134 by longjmp( ) does not necessarily contain all the information that setcontext( ) requires. Signal 16135 handlers should use siglongjmp( ) or setcontext( ) instead. 16136 Conforming applications should not modify or access the uc_mcontext member of ucontext_t. A | 16137 conforming application cannot assume that context includes any process-wide static data, | 16138 possibly including errno. Users manipulating contexts should take care to handle these 16139 explicitly when required. 16140 Use of contexts to create alternate stacks is not defined by this volume of IEEE Std 1003.1-200x. 948 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getcontext( ) 16141 RATIONALE 16142 None. 16143 FUTURE DIRECTIONS 16144 None. 16145 SEE ALSO 16146 bsd_signal( ), makecontext( ), setjmp( ), sigaction( ), sigaltstack( ), sigprocmask( ), sigsetjmp( ), the Base 16147 Definitions volume of IEEE Std 1003.1-200x, 16148 CHANGE HISTORY 16149 First released in Issue 4, Version 2. 16150 Issue 5 16151 Moved from X/OPEN UNIX extension to BASE. 16152 The following sentence was removed from the DESCRIPTION: ``If the ucp argument was passed 16153 to a signal handler, program execution continues with the program instruction following the 16154 instruction interrupted by the signal.'' System Interfaces, Issue 6 949 getcwd( ) System Interfaces 16155 NAME 16156 getcwd - get the pathname of the current working directory | 16157 SYNOPSIS 16158 #include 16159 char *getcwd(char *buf, size_t size); 16160 DESCRIPTION 16161 The getcwd( ) function shall place an absolute pathname of the current working directory in the | 16162 array pointed to by buf, and return buf. The pathname copied to the array shall contain no | 16163 components that are symbolic links. The size argument is the size in bytes of the character array | 16164 pointed to by the buf argument. If buf is a null pointer, the behavior of getcwd( ) is unspecified. 16165 RETURN VALUE 16166 Upon successful completion, getcwd( ) shall return the buf argument. Otherwise, getcwd( ) shall 16167 return a null pointer and set errno to indicate the error. The contents of the array pointed to by 16168 buf are then undefined. 16169 ERRORS 16170 The getcwd( ) function shall fail if: 16171 [EINVAL] The size argument is 0. 16172 [ERANGE] The size argument is greater than 0, but is smaller than the length of the | 16173 pathname +1. | 16174 The getcwd( ) function may fail if: 16175 [EACCES] Read or search permission was denied for a component of the pathname. | 16176 [ENOMEM] Insufficient storage space is available. 16177 EXAMPLES 16178 Determining the Absolute Pathname of the Current Working Directory | 16179 The following example returns a pointer to an array that holds the absolute pathname of the | 16180 current working directory. The pointer is returned in the ptr variable, which points to the buf | 16181 array where the pathname is stored. | 16182 #include 16183 #include 16184 ... 16185 long size; 16186 char *buf; 16187 char *ptr; 16188 size = pathconf(".", _PC_PATH_MAX); 16189 if ((buf = (char *)malloc((size_t)size)) != NULL) 16190 ptr = getcwd(buf, (size_t)size); 16191 ... 16192 APPLICATION USAGE 16193 None. 950 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getcwd( ) 16194 RATIONALE 16195 Since the maximum pathname length is arbitrary unless {PATH_MAX} is defined, an application | 16196 generally cannot supply a buf with size {{PATH_MAX}+1}. 16197 Having getcwd( ) take no arguments and instead use the malloc( ) function to produce space for 16198 the returned argument was considered. The advantage is that getcwd( ) knows how big the | 16199 working directory pathname is and can allocate an appropriate amount of space. But the | 16200 programmer would have to use the free( ) function to free the resulting object, or each use of 16201 getcwd( ) would further reduce the available memory. Also, malloc( ) and free( ) are used nowhere 16202 else in this volume of IEEE Std 1003.1-200x. Finally, getcwd( ) is taken from the SVID where it has 16203 the two arguments used in this volume of IEEE Std 1003.1-200x. 16204 The older function getwd( ) was rejected for use in this context because it had only a buffer 16205 argument and no size argument, and thus had no way to prevent overwriting the buffer, except 16206 to depend on the programmer to provide a large enough buffer. 16207 On some implementations, if buf is a null pointer, getcwd( ) may obtain size bytes of memory 16208 using malloc( ). In this case, the pointer returned by getcwd( ) may be used as the argument in a 16209 subsequent call to free( ). Invoking getcwd( ) with buf as a null pointer is not recommended in | 16210 conforming applications. | 16211 If a program is operating in a directory where some (grand)parent directory does not permit 16212 reading, getcwd( ) may fail, as in most implementations it must read the directory to determine 16213 the name of the file. This can occur if search, but not read, permission is granted in an 16214 intermediate directory, or if the program is placed in that directory by some more privileged 16215 process (for example, login). Including the [EACCES] error condition makes the reporting of the 16216 error consistent and warns the application writer that getcwd( ) can fail for reasons beyond the 16217 control of the application writer or user. Some implementations can avoid this occurrence (for 16218 example, by implementing getcwd( ) using pwd, where pwd is a set-user-root process), thus the | 16219 error was made optional. Since this volume of IEEE Std 1003.1-200x permits the addition of other | 16220 errors, this would be a common addition and yet one that applications could not be expected to | 16221 deal with without this addition. | 16222 FUTURE DIRECTIONS 16223 None. 16224 SEE ALSO 16225 malloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 16226 CHANGE HISTORY 16227 First released in Issue 1. Derived from Issue 1 of the SVID. 16228 Issue 6 16229 The following new requirements on POSIX implementations derive from alignment with the 16230 Single UNIX Specification: 16231 * The [ENOMEM] optional error condition is added. System Interfaces, Issue 6 951 getdate( ) System Interfaces 16232 NAME 16233 getdate - convert user format date and time 16234 SYNOPSIS 16235 XSI #include 16236 struct tm *getdate(const char *string); 16237 16238 DESCRIPTION 16239 The getdate( ) function shall convert a string representation of a date or time into a broken-down 16240 time. 16241 The external variable or macro getdate_err is used by getdate( ) to return error values. 16242 Templates are used to parse and interpret the input string. The templates are contained in a text 16243 file identified by the environment variable DATEMSK. The DATEMSK variable should be set to | 16244 indicate the full pathname of the file that contains the templates. The first line in the template | 16245 that matches the input specification is used for interpretation and conversion into the internal 16246 time format. 16247 The following conversion specifications shall be supported: | 16248 %% Equivalent to %. | 16249 %a Abbreviated weekday name. 16250 %A Full weekday name. 16251 %b Abbreviated month name. 16252 %B Full month name. 16253 %c Locale's appropriate date and time representation. 16254 %C Century number [00,99]; leading zeros are permitted but not required. | 16255 %d Day of month [01,31]; the leading 0 is optional. | 16256 %D Date as %m/%d/%y. 16257 %e Equivalent to %d. | 16258 %h Abbreviated month name. 16259 %H Hour [00,23]. | 16260 %I Hour [01,12]. | 16261 %m Month number [01,12]. | 16262 %M Minute [00,59]. | 16263 %n Equivalent to . | 16264 %p Locale's equivalent of either AM or PM. 16265 %r The locale's appropriate representation of time in AM and PM notation. In the POSIX | 16266 locale, this shall be equivalent to %I:%M:%S %p. | 16267 %R Time as %H:%M. 16268 %S Seconds [00,60]. The range goes to 60 (rather than stopping at 59) to allow positive leap | 16269 seconds to be expressed. Since leap seconds cannot be predicted by any algorithm, leap | 16270 second data must come from some external source. | 952 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getdate( ) 16271 %t Equivalent to . | 16272 %T Time as %H:%M:%S. 16273 %w Weekday number (Sunday = [0,6]). | 16274 %x Locale's appropriate date representation. 16275 %X Locale's appropriate time representation. 16276 %y Year within century. When a century is not otherwise specified, values in the range | 16277 [69,99] shall refer to years 1969 to 1999 inclusive, and values in the range [00,68] shall | 16278 refer to years 2000 to 2068 inclusive. | 16279 Note: It is expected that in a future version of IEEE Std 1003.1-200x the default century | 16280 inferred from a 2-digit year will change. (This would apply to all commands | 16281 accepting a 2-digit year as input.) | 16282 %Y Year as "ccyy" (for example, 2001). | 16283 %Z Timezone name or no characters if no timezone exists. If the timezone supplied by %Z is 16284 not the timezone that getdate( ) expects, an invalid input specification error shall result. 16285 The getdate( ) function calculates an expected timezone based on information supplied 16286 to the function (such as the hour, day, and month). 16287 The match between the template and input specification performed by getdate( ) shall be case- | 16288 insensitive. | 16289 The month and weekday names can consist of any combination of upper and lowercase letters. 16290 The process can request that the input date or time specification be in a specific language by 16291 setting the LC_TIME category (see setlocale( )). 16292 Leading 0s are not necessary for the descriptors that allow leading 0s. However, at most two 16293 digits are allowed for those descriptors, including leading 0s. Extra whitespace in either the 16294 template file or in string shall be ignored. 16295 The results are undefined if the conversion specifications %c, %x, and %X include unsupported | 16296 conversion specifications. | 16297 The following rules apply for converting the input specification into the internal format: 16298 * If %Z is being scanned, then getdate( ) shall initialize the broken-down time to be the current 16299 time in the scanned timezone. Otherwise, it shall initialize the broken-down time based on 16300 the current local time as if localtime( ) had been called. 16301 * If only the weekday is given, the day chosen shall be the day, starting with today and moving | 16302 into the future, which first matches the named day. | 16303 * If only the month (and no year) is given, the month chosen shall be the month, starting with | 16304 the current month and moving into the future, which first matches the named month. The | 16305 first day of the month shall be assumed if no day is given. | 16306 * If no hour, minute, and second are given the current hour, minute, and second shall be 16307 assumed. 16308 * If no date is given, the hour chosen shall be the hour, starting with the current hour and | 16309 moving into the future, which first matches the named hour. | 16310 If a conversion specification in the DATEMSK file does not correspond to one of the conversion | 16311 specifications above, the behavior is unspecified. 16312 The getdate( ) function need not be reentrant. A function that is not required to be reentrant is not 16313 required to be thread-safe. System Interfaces, Issue 6 953 getdate( ) System Interfaces 16314 RETURN VALUE 16315 Upon successful completion, getdate( ) shall return a pointer to a struct tm. Otherwise, it shall 16316 return a null pointer and set getdate_err to indicate the error. 16317 ERRORS 16318 The getdate( ) function shall fail in the following cases, setting getdate_err to the value shown in 16319 the list below. Any changes to errno are unspecified. 16320 1. The DATEMSK environment variable is null or undefined. 16321 2. The template file cannot be opened for reading. 16322 3. Failed to get file status information. 16323 4. The template file is not a regular file. 16324 5. An I/O error is encountered while reading the template file. 16325 6. Memory allocation failed (not enough memory available). 16326 7. There is no line in the template that matches the input. 16327 8. Invalid input specification. For example, February 31; or a time is specified that cannot be 16328 represented in a time_t (representing the time in seconds since the Epoch). 16329 EXAMPLES 16330 1. The following example shows the possible contents of a template: 16331 %m 16332 %A %B %d, %Y, %H:%M:%S 16333 %A 16334 %B 16335 %m/%d/%y %I %p 16336 %d,%m,%Y %H:%M 16337 at %A the %dst of %B in %Y 16338 run job at %I %p,%B %dnd 16339 %A den %d. %B %Y %H.%M Uhr 16340 2. The following are examples of valid input specifications for the template in Example 1: 16341 getdate("10/1/87 4 PM"); 16342 getdate("Friday"); 16343 getdate("Friday September 18, 1987, 10:30:30"); 16344 getdate("24,9,1986 10:30"); 16345 getdate("at monday the 1st of december in 1986"); 16346 getdate("run job at 3 PM, december 2nd"); 16347 If the LC_TIME category is set to a German locale that includes freitag as a weekday name 16348 and oktober as a month name, the following would be valid: 16349 getdate("freitag den 10. oktober 1986 10.30 Uhr"); 16350 3. The following example shows how local date and time specification can be defined in the 16351 template: 954 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getdate( ) 16352 ____________________________________________________ 16353 _ Invocation Line in Template ___________________________________________________ 16354 getdate("11/27/86") %m/%d/%y 16355 getdate("27.11.86") %d.%m.%y 16356 getdate("86-11-27") %y-%m-%d 16357 _ getdate("Friday 12:00:00") %A %H:%M:%S ___________________________________________________ 16358 4. The following examples help to illustrate the above rules assuming that the current date is 16359 Mon Sep 22 12:19:47 EDT 1986 and the LC_TIME category is set to the default C locale: 16360 _________________________________________________________________ 16361 _ Input Line in Template Date ________________________________________________________________ 16362 Mon %a Mon Sep 22 12:19:47 EDT 1986 16363 Sun %a Sun Sep 28 12:19:47 EDT 1986 16364 Fri %a Fri Sep 26 12:19:47 EDT 1986 16365 September %B Mon Sep 1 12:19:47 EDT 1986 16366 January %B Thu Jan 1 12:19:47 EST 1987 16367 December %B Mon Dec 1 12:19:47 EST 1986 16368 Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986 16369 Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987 16370 Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986 16371 Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989 16372 Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986 16373 Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987 16374 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986 16375 _ 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986 ________________________________________________________________ 16376 APPLICATION USAGE 16377 Although historical versions of getdate( ) did not require that declare the external 16378 variable getdate_err, this volume of IEEE Std 1003.1-200x does require it. The standard | 16379 developers encourage applications to remove declarations of getdate_err and instead incorporate | 16380 the declaration by including . 16381 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 16382 RATIONALE 16383 In standard locales, the conversion specifications %c, %x, and %X do not include unsupported | 16384 conversion specifiers and so the text regarding results being undefined is not a problem in that | 16385 case. | 16386 FUTURE DIRECTIONS 16387 None. 16388 SEE ALSO 16389 ctime( ), localtime( ), setlocale( ), strftime( ), times( ), the Base Definitions volume of 16390 IEEE Std 1003.1-200x, 16391 CHANGE HISTORY 16392 First released in Issue 4, Version 2. 16393 Issue 5 16394 Moved from X/OPEN UNIX extension to BASE. 16395 The last paragraph of the DESCRIPTION is added. 16396 The %C conversion specification is added, and the exact meaning of the %y conversion 16397 specification is clarified in the DESCRIPTION. System Interfaces, Issue 6 955 getdate( ) System Interfaces 16398 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 16399 The %R conversion specifications is changed to follow historical practice. 16400 Issue 6 16401 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 16402 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time 16403 functions. 16404 The description of %S is updated so that the valid range [00,60] rather than [00,61]. | 16405 The DESCRIPTION is updated to refer to conversion specifications instead of field descriptors | 16406 for consistency with other functions. 956 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getegid( ) 16407 NAME 16408 getegid - get the effective group ID 16409 SYNOPSIS 16410 #include 16411 gid_t getegid(void); 16412 DESCRIPTION 16413 The getegid( ) function shall return the effective group ID of the calling process. 16414 RETURN VALUE 16415 The getegid( ) function shall always be successful and no return value is reserved to indicate an | 16416 error. 16417 ERRORS 16418 No errors are defined. 16419 EXAMPLES 16420 None. 16421 APPLICATION USAGE 16422 None. 16423 RATIONALE 16424 None. 16425 FUTURE DIRECTIONS 16426 None. 16427 SEE ALSO 16428 geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base 16429 Definitions volume of IEEE Std 1003.1-200x, , 16430 CHANGE HISTORY 16431 First released in Issue 1. Derived from Issue 1 of the SVID. 16432 Issue 6 16433 In the SYNOPSIS, the optional include of the header is removed. 16434 The following new requirements on POSIX implementations derive from alignment with the 16435 Single UNIX Specification: 16436 * The requirement to include has been removed. Although was 16437 required for conforming implementations of previous POSIX specifications, it was not 16438 required for UNIX applications. System Interfaces, Issue 6 957 getenv( ) System Interfaces 16439 NAME 16440 getenv - get value of an environment variable 16441 SYNOPSIS 16442 #include 16443 char *getenv(const char *name); 16444 DESCRIPTION 16445 CX The functionality described on this reference page is aligned with the ISO C standard. Any 16446 conflict between the requirements described here and the ISO C standard is unintentional. This 16447 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 16448 The getenv( ) function shall search the environment of the calling process (see the Base 16449 Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables) for the 16450 environment variable name if it exists and return a pointer to the value of the environment 16451 variable. If the specified environment variable cannot be found, a null pointer shall be returned. 16452 The application shall ensure that it does not modify the string pointed to by the getenv( ) 16453 function. 16454 CX The string pointed to may be overwritten by a subsequent call to getenv( ),setenv( ), or unsetenv( ), 16455 but shall not be overwritten by a call to any other function in this volume of 16456 IEEE Std 1003.1-200x. 16457 CX If the application modifies environ or the pointers to which it points, the behavior of getenv( ) is | 16458 undefined. 16459 The getenv( ) function need not be reentrant. A function that is not required to be reentrant is not 16460 required to be thread-safe. 16461 RETURN VALUE 16462 Upon successful completion, getenv( ) shall return a pointer to a string containing the value for 16463 the specified name. If the specified name cannot be found in the environment of the calling 16464 process, a null pointer shall be returned. 16465 The return value from getenv( ) may point to static data which may be overwritten by 16466 CX subsequent calls to getenv( ),setenv( ), or unsetenv( ). 16467 XSI On XSI-conformant systems, the return value from getenv( ) may point to static data which may 16468 also be overwritten by subsequent calls to putenv( ). 16469 ERRORS 16470 No errors are defined. 16471 EXAMPLES 16472 Getting the Value of an Environment Variable 16473 The following example gets the value of the HOME environment variable. 16474 #include 16475 ... 16476 const char *name = "HOME"; 16477 char *value; 16478 value = getenv(name); 958 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getenv( ) 16479 APPLICATION USAGE 16480 None. 16481 RATIONALE 16482 The clearenv( ) function was considered but rejected. The putenv( ) function has now been 16483 included for alignment with the Single UNIX Specification. 16484 The getenv( ) function is inherently not reentrant because it returns a value pointing to static 16485 data. 16486 Conforming applications are required not to modify environ directly, but to use only the 16487 functions described here to manipulate the process environment as an abstract object. Thus, the 16488 implementation of the environment access functions has complete control over the data 16489 structure used to represent the environment (subject to the requirement that environ be 16490 maintained as a list of strings with embedded equal signs for applications that wish to scan the 16491 environment). This constraint allows the implementation to properly manage the memory it 16492 allocates, either by using allocated storage for all variables (copying them on the first invocation 16493 of setenv( ) or unsetenv( )), or keeping track of which strings are currently in allocated space and 16494 which are not, via a separate table or some other means. This enables the implementation to free 16495 any allocated space used by strings (and perhaps the pointers to them) stored in environ when 16496 unsetenv( ) is called. A C runtime start-up procedure (that which invokes main( ) and perhaps 16497 initializes environ) can also initialize a flag indicating that none of the environment has yet been 16498 copied to allocated storage, or that the separate table has not yet been initialized. 16499 In fact, for higher performance of getenv( ), the implementation could also maintain a separate 16500 copy of the environment in a data structure that could be searched much more quickly (such as 16501 an indexed hash table, or a binary tree), and update both it and the linear list at environ when 16502 setenv( ) or unsetenv( ) is invoked. 16503 Performance of getenv( ) can be important for applications which have large numbers of 16504 environment variables. Typically, applications like this use the environment as a resource | 16505 database of user-configurable parameters. The fact that these variables are in the user's shell | 16506 environmentt usually means that any other program that uses environment variables (such as ls, 16507 which attempts to use COLUMNS, or really almost any utility (LANG, LC_ALL, and so on) is 16508 similarly slowed down by the linear search through the variables. 16509 An implementation that maintains separate data structures, or even one that manages the 16510 memory it consumes, is not currently required as it was thought it would reduce consensus 16511 among implementors who do not want to change their historical implementations. 16512 The POSIX Threads Extension states that multi-threaded applications must not modify environ 16513 directly, and that IEEE Std 1003.1-200x is providing functions which such applications can use in 16514 the future to manipulate the environment in a thread-safe manner. Thus, moving away from 16515 application use of environ is desirable from that standpoint as well. 16516 FUTURE DIRECTIONS 16517 None. 16518 SEE ALSO 16519 exec, putenv( ), setenv( ), unsetenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 16520 , the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment 16521 Variables 16522 CHANGE HISTORY 16523 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 959 getenv( ) System Interfaces 16524 Issue 5 16525 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16526 VALUE section. 16527 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 16528 Issue 6 16529 The following changes were made to align with the IEEE P1003.1a draft standard: 16530 * References added to the new setenv( ) and unsetenv( ) functions. 16531 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 960 Technical Standard (2001) (Draft April 16, 2001) System Interfaces geteuid( ) 16532 NAME 16533 geteuid - get the effective user ID 16534 SYNOPSIS 16535 #include 16536 uid_t geteuid(void); 16537 DESCRIPTION 16538 The geteuid( ) function shall return the effective user ID of the calling process. 16539 RETURN VALUE 16540 The geteuid( ) function shall always be successful and no return value is reserved to indicate an | 16541 error. 16542 ERRORS 16543 No errors are defined. 16544 EXAMPLES 16545 None. 16546 APPLICATION USAGE 16547 None. 16548 RATIONALE 16549 None. 16550 FUTURE DIRECTIONS 16551 None. 16552 SEE ALSO 16553 getegid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base 16554 Definitions volume of IEEE Std 1003.1-200x, , 16555 CHANGE HISTORY 16556 First released in Issue 1. Derived from Issue 1 of the SVID. 16557 Issue 6 16558 In the SYNOPSIS, the optional include of the header is removed. 16559 The following new requirements on POSIX implementations derive from alignment with the 16560 Single UNIX Specification: 16561 * The requirement to include has been removed. Although was 16562 required for conforming implementations of previous POSIX specifications, it was not 16563 required for UNIX applications. System Interfaces, Issue 6 961 getgid( ) System Interfaces 16564 NAME 16565 getgid - get the real group ID 16566 SYNOPSIS 16567 #include 16568 gid_t getgid(void); 16569 DESCRIPTION 16570 The getgid( ) function shall return the real group ID of the calling process. 16571 RETURN VALUE 16572 The getgid( ) function shall always be successful and no return value is reserved to indicate an | 16573 error. 16574 ERRORS 16575 No errors are defined. 16576 EXAMPLES 16577 None. 16578 APPLICATION USAGE 16579 None. 16580 RATIONALE 16581 None. 16582 FUTURE DIRECTIONS 16583 None. 16584 SEE ALSO 16585 getegid( ), geteuid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base 16586 Definitions volume of IEEE Std 1003.1-200x, , 16587 CHANGE HISTORY 16588 First released in Issue 1. Derived from Issue 1 of the SVID. 16589 Issue 6 16590 In the SYNOPSIS, the optional include of the header is removed. 16591 The following new requirements on POSIX implementations derive from alignment with the 16592 Single UNIX Specification: 16593 * The requirement to include has been removed. Although was 16594 required for conforming implementations of previous POSIX specifications, it was not 16595 required for UNIX applications. 962 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getgrent( ) 16596 NAME 16597 getgrent - get the group database entry 16598 SYNOPSIS 16599 XSI #include 16600 struct group *getgrent(void); 16601 16602 DESCRIPTION 16603 Refer to endgrent( ). System Interfaces, Issue 6 963 getgrgid( ) System Interfaces 16604 NAME 16605 getgrgid, getgrgid_r - get group database entry for a group ID 16606 SYNOPSIS 16607 #include 16608 struct group *getgrgid(gid_t gid); 16609 TSF int getgrgid_r(gid_t gid, struct group *grp, char *buffer, 16610 size_t bufsize, struct group **result); 16611 16612 DESCRIPTION 16613 The getgrgid( ) function shall search the group database for an entry with a matching gid. 16614 The getgrgid( ) function need not be reentrant. A function that is not required to be reentrant is 16615 not required to be thread-safe. 16616 TSF The getgrgid_r( ) function shall update the group structure pointed to by grp and store a pointer | 16617 to that structure at the location pointed to by result. The structure shall contain an entry from | 16618 the group database with a matching gid. Storage referenced by the group structure is allocated | 16619 from the memory provided with the buffer parameter, which is bufsize bytes in size. The 16620 maximum size needed for this buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} 16621 sysconf( ) parameter. A NULL pointer shall be returned at the location pointed to by result on | 16622 error or if the requested entry is not found. 16623 RETURN VALUE 16624 Upon successful completion, getgrgid( ) shall return a pointer to a struct group with the structure 16625 defined in with a matching entry if one is found. The getgrgid( ) function shall return a 16626 null pointer if either the requested entry was not found, or an error occurred. On error, errno 16627 shall be set to indicate the error. 16628 The return value may point to a static area which is overwritten by a subsequent call to 16629 getgrent( ), getgrgid( ), or getgrnam( ). 16630 TSF If successful, the getgrgid_r( ) function shall return zero; otherwise, an error number shall be 16631 returned to indicate the error. 16632 ERRORS 16633 The getgrgid( ) and getgrgid_r( ) functions may fail if: 16634 [EIO] An I/O error has occurred. 16635 [EINTR] A signal was caught during getgrgid( ). 16636 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 16637 [ENFILE] The maximum allowable number of files is currently open in the system. 16638 TSF The getgrgid_r( ) function may fail if: 16639 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 16640 be referenced by the resulting group structure. 964 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getgrgid( ) 16641 EXAMPLES 16642 Finding an Entry in the Group Database 16643 The following example uses getgrgid( ) to search the group database for a group ID that was 16644 previously stored in a stat structure, then prints out the group name if it is found. If the group is 16645 not found, the program prints the numeric value of the group for the entry. 16646 #include 16647 #include 16648 #include 16649 ... 16650 struct stat statbuf; 16651 struct group *grp; 16652 ... 16653 if ((grp = getgrgid(statbuf.st_gid)) != NULL) 16654 printf(" %-8.8s", grp->gr_name); 16655 else 16656 printf(" %-8d", statbuf.st_gid); 16657 ... 16658 APPLICATION USAGE 16659 Applications wishing to check for error situations should set errno to 0 before calling getgrgid( ). 16660 If errno is set on return, an error occurred. 16661 The getgrgid_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 16662 of possibly using a static data area that may be overwritten by each call. 16663 RATIONALE 16664 None. 16665 FUTURE DIRECTIONS 16666 None. 16667 SEE ALSO 16668 endgrent( ), getgrnam( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 16669 , 16670 CHANGE HISTORY 16671 First released in Issue 1. Derived from System V Release 2.0. 16672 Issue 5 16673 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16674 VALUE section. 16675 The getgrgid_r( ) function is included for alignment with the POSIX Threads Extension. 16676 A note indicating that the getgrgid( ) function need not be reentrant is added to the 16677 DESCRIPTION. 16678 Issue 6 16679 The getgrgid_r( ) function is marked as part of the Thread-Safe Functions option. 16680 The Open Group Corrigendum U028/3 is applied, correcting text in the DESCRIPTION 16681 describing matching the gid. 16682 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 16683 In the SYNOPSIS, the optional include of the header is removed. System Interfaces, Issue 6 965 getgrgid( ) System Interfaces 16684 The following new requirements on POSIX implementations derive from alignment with the 16685 Single UNIX Specification: 16686 * The requirement to include has been removed. Although was 16687 required for conforming implementations of previous POSIX specifications, it was not 16688 required for UNIX applications. 16689 * In the RETURN VALUE section, the requirement to set errno on error is added. 16690 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 16691 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 16692 its avoidance of possibly using a static data area. 16693 IEEE PASC Interpretation 1003.1 #116 is applied, changing the description of the size of the 16694 buffer from bufsize characters to bytes. 966 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getgrnam( ) 16695 NAME 16696 getgrnam, getgrnam_r - search group database for a name 16697 SYNOPSIS 16698 #include 16699 struct group *getgrnam(const char *name); 16700 TSF int getgrnam_r(const char *name, struct group *grp, char *buffer, 16701 size_t bufsize, struct group **result); 16702 16703 DESCRIPTION 16704 The getgrnam( ) function shall search the group database for an entry with a matching name. 16705 The getgrnam( ) function need not be reentrant. A function that is not required to be reentrant is 16706 not required to be thread-safe. 16707 TSF The getgrnam_r( ) function shall update the group structure pointed to by grp and store a pointer | 16708 to that structure at the location pointed to by result. The structure shall contain an entry from | 16709 the group database with a matching gid or name. Storage referenced by the group structure is | 16710 allocated from the memory provided with the buffer parameter, which is bufsize bytes in size. The 16711 maximum size needed for this buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} 16712 sysconf( ) parameter. A NULL pointer is returned at the location pointed to by result on error or if 16713 the requested entry is not found. 16714 RETURN VALUE 16715 The getgrnam( ) function shall return a pointer to a struct group with the structure defined in 16716 with a matching entry if one is found. The getgrnam( ) function shall return a null 16717 pointer if either the requested entry was not found, or an error occurred. On error, errno shall be 16718 set to indicate the error. 16719 The return value may point to a static area which is overwritten by a subsequent call to 16720 getgrent( ), getgrgid( ), or getgrnam( ). 16721 TSF If successful, the getgrnam_r( ) function shall return zero; otherwise, an error number shall be 16722 returned to indicate the error. 16723 ERRORS 16724 The getgrnam( ) and getgrnam_r( ) functions may fail if: 16725 [EIO] An I/O error has occurred. 16726 [EINTR] A signal was caught during getgrnam( ). 16727 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 16728 [ENFILE] The maximum allowable number of files is currently open in the system. 16729 The getgrnam_r( ) function may fail if: 16730 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 16731 be referenced by the resulting group structure. System Interfaces, Issue 6 967 getgrnam( ) System Interfaces 16732 EXAMPLES 16733 None. 16734 APPLICATION USAGE 16735 Applications wishing to check for error situations should set errno to 0 before calling getgrnam( ). 16736 If errno is set on return, an error occurred. 16737 The getgrnam_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 16738 of possibly using a static data area that may be overwritten by each call. 16739 RATIONALE 16740 None. 16741 FUTURE DIRECTIONS 16742 None. 16743 SEE ALSO 16744 endgrent( ), getgrgid( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 16745 16746 CHANGE HISTORY 16747 First released in Issue 1. Derived from System V Release 2.0. 16748 Issue 5 16749 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 16750 VALUE section. 16751 The getgrnam_r( ) function is included for alignment with the POSIX Threads Extension. 16752 A note indicating that the getgrnam( ) function need not be reentrant is added to the 16753 DESCRIPTION. 16754 Issue 6 16755 The getgrnam_r( ) function is marked as part of the Thread-Safe Functions option. 16756 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 16757 In the SYNOPSIS, the optional include of the header is removed. 16758 The following new requirements on POSIX implementations derive from alignment with the 16759 Single UNIX Specification: 16760 * The requirement to include has been removed. Although was 16761 required for conforming implementations of previous POSIX specifications, it was not 16762 required for UNIX applications. 16763 * In the RETURN VALUE section, the requirement to set errno on error is added. 16764 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 16765 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 16766 its avoidance of possibly using a static data area. 16767 IEEE PASC Interpretation 1003.1 #116 is applied, changing the description of the size of the 16768 buffer from bufsize characters to bytes. 968 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getgroups( ) 16769 NAME 16770 getgroups - get supplementary group IDs 16771 SYNOPSIS 16772 #include 16773 int getgroups(int gidsetsize, gid_t grouplist[]); 16774 DESCRIPTION 16775 The getgroups( ) function shall fill in the array grouplist with the current supplementary group | 16776 IDs of the calling process. It is implementation-defined whether getgroups( ) also returns the 16777 effective group ID in the grouplist array. 16778 The gidsetsize argument specifies the number of elements in the array grouplist. The actual | 16779 number of group IDs stored in the array shall be returned. The values of array entries with | 16780 indices greater than or equal to the value returned are undefined. | 16781 If gidsetsize is 0, getgroups( ) shall return the number of group IDs that it would otherwise return 16782 without modifying the array pointed to by grouplist. 16783 If the effective group ID of the process is returned with the supplementary group IDs, the value 16784 returned shall always be greater than or equal to one and less than or equal to the value of 16785 {NGROUPS_MAX}+1. 16786 RETURN VALUE 16787 Upon successful completion, the number of supplementary group IDs shall be returned. A 16788 return value of -1 indicates failure and errno shall be set to indicate the error. 16789 ERRORS 16790 The getgroups( ) function shall fail if: 16791 [EINVAL] The gidsetsize argument is non-zero and less than the number of group IDs 16792 that would have been returned. 16793 EXAMPLES 16794 Getting the Supplementary Group IDs of the Calling Process 16795 The following example places the current supplementary group IDs of the calling process into 16796 the group array. 16797 #include 16798 #include 16799 ... 16800 gid_t *group; 16801 int nogroups; 16802 long ngroups_max; 16803 ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; 16804 group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); 16805 ngroups = getgroups(ngroups_max, group); 16806 APPLICATION USAGE 16807 None. 16808 RATIONALE 16809 The related function setgroups( ) is a privileged operation and therefore is not covered by this 16810 volume of IEEE Std 1003.1-200x. System Interfaces, Issue 6 969 getgroups( ) System Interfaces 16811 As implied by the definition of supplementary groups, the effective group ID may appear in the 16812 array returned by getgroups( ) or it may be returned only by getegid( ). Duplication may exist, but 16813 the application needs to call getegid( ) to be sure of getting all of the information. Various 16814 implementation variations and administrative sequences cause the set of groups appearing in 16815 the result of getgroups( ) to vary in order and as to whether the effective group ID is included, 16816 even when the set of groups is the same (in the mathematical sense of ``set''). (The history of a 16817 process and its parents could affect the details of result.) 16818 Applications writers should note that {NGROUPS_MAX} is not necessarily a constant on all 16819 implementations. 16820 FUTURE DIRECTIONS 16821 None. 16822 SEE ALSO 16823 getegid( ), setgid( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 16824 16825 CHANGE HISTORY 16826 First released in Issue 3. 16827 Entry included for alignment with the POSIX.1-1988 standard. 16828 Issue 5 16829 Normative text previously in the APPLICATION USAGE section is moved to the 16830 DESCRIPTION. 16831 Issue 6 16832 In the SYNOPSIS, the optional include of the header is removed. 16833 The following new requirements on POSIX implementations derive from alignment with the 16834 Single UNIX Specification: 16835 * The requirement to include has been removed. Although was 16836 required for conforming implementations of previous POSIX specifications, it was not 16837 required for UNIX applications. 16838 * A return value of 0 is not permitted, because {NGROUPS_MAX} cannot be 0. This is a FIPS 16839 requirement. 16840 The following changes were made to align with the IEEE P1003.1a draft standard: 16841 * Explanation added that the effective group ID may be included in the supplementary group 16842 list. 970 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gethostbyaddr( ) 16843 NAME 16844 gethostbyaddr, gethostbyname - network host database functions 16845 SYNOPSIS 16846 #include 16847 OB struct hostent *gethostbyaddr(const void *addr, socklen_t len, 16848 int type); 16849 struct hostent *gethostbyname(const char *name); 16850 16851 DESCRIPTION 16852 These functions shall retrieve information about hosts. This information is considered to be | 16853 stored in a database that can be accessed sequentially or randomly. Implementation of this | 16854 database is unspecified. | 16855 Note: In many cases it is implemented by the Domain Name System, as documented in RFC 1034, 16856 RFC 1035, and RFC 1886. 16857 Entries shall be returned in hostent structures. | 16858 The gethostbyaddr( ) function shall return an entry containing addresses of address family type for 16859 the host with address addr. The len argument contains the length of the address pointed to by | 16860 addr. The gethostbyaddr( ) function need not be reentrant. A function that is not required to be 16861 reentrant is not required to be thread-safe. 16862 The gethostbyname( ) function shall return an entry containing addresses of address family 16863 AF_INET for the host with name name. The gethostbyname( ) function need not be reentrant. A 16864 function that is not required to be reentrant is not required to be thread-safe. 16865 The addr argument of gethostbyaddr( ) shall be an in_addr structure when type is AF_INET. It | 16866 contains a binary format (that is, not null-terminated) address in network byte order. The | 16867 gethostbyaddr( ) function is not guaranteed to return addresses of address families other than 16868 AF_INET, even when such addresses exist in the database. 16869 If gethostbyaddr( ) returns successfully, then the h_addrtype field in the result shall be the same as | 16870 the type argument that was passed to the function, and the h_addr_list field shall list a single | 16871 address that is a copy of the addr argument that was passed to the function. | 16872 The name argument of gethostbyname( ) shall be a node name; the behavior of gethostbyname( ) | 16873 when passed a numeric address string is unspecified. For IPv4, a numeric address string shall be 16874 in the dotted-decimal notation described in inet_addr( ). | 16875 If name is not a numeric address string and is an alias for a valid host name, then gethostbyname( ) | 16876 shall return information about the host name to which the alias refers, and name shall be 16877 included in the list of aliases returned. 16878 RETURN VALUE 16879 Upon successful completion, these functions shall return a pointer to a hostent structure if the 16880 requested entry was found, and a null pointer if the end of the database was reached or the 16881 requested entry was not found. 16882 Upon unsuccessful completion, gethostbyaddr( ) and gethostbyname( ) shall set h_errno to indicate 16883 the error. 16884 ERRORS 16885 These functions shall fail in the following cases. The gethostbyaddr( ) and gethostbyname( ) 16886 functions shall set h_errno to the value shown in the list below. Any changes to errno are 16887 unspecified. System Interfaces, Issue 6 971 gethostbyaddr( ) System Interfaces 16888 [HOST_NOT_FOUND] 16889 No such host is known. 16890 [NO_DATA] The server recognized the request and the name, but no address is available. 16891 Another type of request to the name server for the domain might return an 16892 answer. 16893 [NO_RECOVERY] 16894 An unexpected server failure occurred which cannot be recovered. 16895 [TRY_AGAIN] A temporary and possibly transient error occurred, such as a failure of a 16896 server to respond. 16897 EXAMPLES 16898 None. 16899 APPLICATION USAGE 16900 The gethostbyaddr( ) and gethostbyname( ) functions may return pointers to static data, which may 16901 be overwritten by subsequent calls to any of these functions. 16902 The getaddrinfo( ) and getnameinfo( ) functions are preferred over the gethostbyaddr( ) and 16903 gethostbyname( ) functions. 16904 RATIONALE 16905 None. 16906 FUTURE DIRECTIONS 16907 The gethostbyaddr( ) and gethostbyname( ) functions may be withdrawn in a future version. 16908 SEE ALSO 16909 endhostent( ), endservent( ), gai_strerror( ), getaddrinfo( ), h_errno, inet_addr( ), the Base Definitions 16910 volume of IEEE Std 1003.1-200x, 16911 CHANGE HISTORY 16912 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 972 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gethostbyname( ) 16913 NAME 16914 gethostbyname - network host database functions 16915 SYNOPSIS 16916 #include 16917 OB struct hostent *gethostbyname(const char *name); 16918 16919 DESCRIPTION 16920 Refer to gethostbyaddr( ). System Interfaces, Issue 6 973 gethostent( ) System Interfaces 16921 NAME 16922 gethostent - network host database functions 16923 SYNOPSIS 16924 #include 16925 struct hostent *gethostent(void); 16926 DESCRIPTION 16927 Refer to endhostent( ). 974 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gethostid( ) 16928 NAME 16929 gethostid - get an identifier for the current host 16930 SYNOPSIS 16931 XSI #include 16932 long gethostid(void); 16933 16934 DESCRIPTION 16935 The gethostid( ) function shall retrieve a 32-bit identifier for the current host. | 16936 RETURN VALUE 16937 Upon successful completion, gethostid( ) shall return an identifier for the current host. 16938 ERRORS 16939 No errors are defined. 16940 EXAMPLES 16941 None. 16942 APPLICATION USAGE 16943 This volume of IEEE Std 1003.1-200x does not define the domain in which the return value is 16944 unique. 16945 RATIONALE 16946 None. 16947 FUTURE DIRECTIONS 16948 None. 16949 SEE ALSO 16950 random( ), the Base Definitions volume of IEEE Std 1003.1-200x, 16951 CHANGE HISTORY 16952 First released in Issue 4, Version 2. 16953 Issue 5 16954 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 975 gethostname( ) System Interfaces 16955 NAME 16956 gethostname - get name of current host 16957 SYNOPSIS 16958 #include 16959 int gethostname(char *name, size_t namelen); | 16960 DESCRIPTION | 16961 The gethostname( ) function shall return the standard host name for the current machine. The 16962 namelen argument shall specify the size of the array pointed to by the name argument. The 16963 returned name shall be null-terminated, except that if namelen is an insufficient length to hold 16964 the host name, then the returned name shall be truncated and it is unspecified whether the 16965 returned name is null-terminated. 16966 Host names are limited to {HOST_NAME_MAX} bytes. | 16967 RETURN VALUE 16968 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned. 16969 ERRORS 16970 No errors are defined. 16971 EXAMPLES 16972 None. 16973 APPLICATION USAGE 16974 None. 16975 RATIONALE 16976 None. 16977 FUTURE DIRECTIONS 16978 None. 16979 SEE ALSO 16980 gethostid( ), uname( ), the Base Definitions volume of IEEE Std 1003.1-200x, 16981 CHANGE HISTORY 16982 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. | 16983 The Open Group Base Resolution bwg2001-008 is applied, changing the namelen parameter from | 16984 socklen_t to size_t. | 976 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getitimer( ) 16985 NAME 16986 getitimer, setitimer - get and set value of interval timer 16987 SYNOPSIS 16988 XSI #include 16989 int getitimer(int which, struct itimerval *value); 16990 int setitimer(int which, const struct itimerval *restrict value, 16991 struct itimerval *restrict ovalue); 16992 16993 DESCRIPTION 16994 The getitimer( ) function shall store the current value of the timer specified by which into the 16995 structure pointed to by value. The setitimer( ) function shall set the timer specified by which to 16996 the value specified in the structure pointed to by value, and if ovalue is not a null pointer, stores 16997 the previous value of the timer in the structure pointed to by ovalue. 16998 A timer value is defined by the itimerval structure, specified in . If it_value is non- 16999 zero, it shall indicate the time to the next timer expiration. If it_interval is non-zero, it shall 17000 specify a value to be used in reloading it_value when the timer expires. Setting it_value to 0 shall 17001 disable a timer, regardless of the value of it_interval. Setting it_interval to 0 shall disable a timer 17002 after its next expiration (assuming it_value is non-zero). 17003 Implementations may place limitations on the granularity of timer values. For each interval 17004 timer, if the requested timer value requires a finer granularity than the implementation supports, 17005 the actual timer value shall be rounded up to the next supported value. 17006 An XSI-conforming implementation provides each process with at least three interval timers, 17007 which are indicated by the which argument: 17008 ITIMER_REAL Decrements in real time. A SIGALRM signal is delivered when this timer 17009 expires. 17010 ITIMER_VIRTUAL Decrements in process virtual time. It runs only when the process is 17011 executing. A SIGVTALRM signal is delivered when it expires. 17012 ITIMER_PROF Decrements both in process virtual time and when the system is running 17013 on behalf of the process. It is designed to be used by interpreters in 17014 statistically profiling the execution of interpreted programs. Each time the 17015 ITIMER_PROF timer expires, the SIGPROF signal is delivered. 17016 The interaction between setitimer( ) and any of alarm( ), sleep( ), or usleep( ) is unspecified. 17017 RETURN VALUE 17018 Upon successful completion, getitimer( ) or setitimer( ) shall return 0; otherwise, -1 shall be 17019 returned and errno set to indicate the error. 17020 ERRORS 17021 The setitimer( ) function shall fail if: 17022 [EINVAL] The value argument is not in canonical form. (In canonical form, the number of 17023 microseconds is a non-negative integer less than 1,000,000 and the number of 17024 seconds is a non-negative integer.) 17025 The getitimer( ) and setitimer( ) functions may fail if: 17026 [EINVAL] The which argument is not recognized. System Interfaces, Issue 6 977 getitimer( ) System Interfaces 17027 EXAMPLES 17028 None. 17029 APPLICATION USAGE 17030 None. 17031 RATIONALE 17032 None. 17033 FUTURE DIRECTIONS 17034 None. 17035 SEE ALSO 17036 alarm( ), sleep( ), timer_getoverrun( ), ualarm( ), usleep( ), the Base Definitions volume of 17037 IEEE Std 1003.1-200x, , 17038 CHANGE HISTORY 17039 First released in Issue 4, Version 2. 17040 Issue 5 17041 Moved from X/OPEN UNIX extension to BASE. 17042 Issue 6 17043 The restrict keyword is added to the setitimer( ) prototype for alignment with the 17044 ISO/IEC 9899: 1999 standard. 978 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getlogin( ) 17045 NAME 17046 getlogin, getlogin_r - get login name 17047 SYNOPSIS 17048 #include 17049 char *getlogin(void); 17050 TSF int getlogin_r(char *name, size_t namesize); 17051 17052 DESCRIPTION 17053 The getlogin( ) function shall return a pointer to a string containing the user name associated by 17054 the login activity with the controlling terminal of the current process. If getlogin( ) returns a non- 17055 null pointer, then that pointer points to the name that the user logged in under, even if there are 17056 several login names with the same user ID. 17057 The getlogin( ) function need not be reentrant. A function that is not required to be reentrant is 17058 not required to be thread-safe. 17059 TSF The getlogin_r( ) function shall put the name associated by the login activity with the controlling | 17060 terminal of the current process in the character array pointed to by name. The array is namesize 17061 characters long and should have space for the name and the terminating null character. The 17062 maximum size of the login name is {LOGIN_NAME_MAX}. 17063 If getlogin_r( ) is successful, name points to the name the user used at login, even if there are 17064 several login names with the same user ID. 17065 RETURN VALUE 17066 Upon successful completion, getlogin( ) shall return a pointer to the login name or a null pointer 17067 if the user's login name cannot be found. Otherwise, it shall return a null pointer and set errno to 17068 indicate the error. 17069 The return value from getlogin( ) may point to static data whose content is overwritten by each 17070 call. 17071 TSF If successful, the getlogin_r( ) function shall return zero; otherwise, an error number shall be 17072 returned to indicate the error. 17073 ERRORS 17074 The getlogin( ) and getlogin_r( ) functions may fail if: 17075 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 17076 [ENFILE] The maximum allowable number of files is currently open in the system. 17077 [ENXIO] The calling process has no controlling terminal. 17078 The getlogin_r( ) function may fail if: 17079 TSF [ERANGE] The value of namesize is smaller than the length of the string to be returned 17080 including the terminating null character. System Interfaces, Issue 6 979 getlogin( ) System Interfaces 17081 EXAMPLES 17082 Getting the User Login Name 17083 The following example calls the getlogin( ) function to obtain the name of the user associated 17084 with the calling process, and passes this information to the getpwnam( ) function to get the 17085 associated user database information. 17086 #include 17087 #include 17088 #include 17089 #include 17090 ... 17091 char *lgn; 17092 struct passwd *pw; 17093 ... 17094 if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { 17095 fprintf(stderr, "Get of user information failed.\n"); exit(1); 17096 } 17097 APPLICATION USAGE 17098 Three names associated with the current process can be determined: getpwuid(geteuid( )) shall 17099 return the name associated with the effective user ID of the process; getlogin( ) shall return the 17100 name associated with the current login activity; and getpwuid(getuid( )) shall return the name 17101 associated with the real user ID of the process. 17102 The getlogin_r( ) function is thread-safe and returns values in a user-supplied buffer instead of 17103 possibly using a static data area that may be overwritten by each call. 17104 RATIONALE 17105 The getlogin( ) function returns a pointer to the user's login name. The same user ID may be 17106 shared by several login names. If it is desired to get the user database entry that is used during 17107 login, the result of getlogin( ) should be used to provide the argument to the getpwnam( ) 17108 function. (This might be used to determine the user's login shell, particularly where a single user 17109 has multiple login shells with distinct login names, but the same user ID.) 17110 The information provided by the cuserid( ) function, which was originally defined in the 17111 POSIX.1-1988 standard and subsequently removed, can be obtained by the following: 17112 getpwuid(geteuid()) 17113 while the information provided by historical implementations of cuserid( ) can be obtained by: 17114 getpwuid(getuid()) 17115 The thread-safe version of this function places the user name in a user-supplied buffer and 17116 returns a non-zero value if it fails. The non-thread-safe version may return the name in a static 17117 data area that may be overwritten by each call. 17118 FUTURE DIRECTIONS 17119 None. 17120 SEE ALSO 17121 getpwnam( ), getpwuid( ), geteuid( ), getuid( ), the Base Definitions volume of IEEE Std 1003.1-200x, 17122 , 980 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getlogin( ) 17123 CHANGE HISTORY 17124 First released in Issue 1. Derived from System V Release 2.0. 17125 Issue 5 17126 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 17127 VALUE section. 17128 The getlogin_r( ) function is included for alignment with the POSIX Threads Extension. 17129 A note indicating that the getlogin( ) function need not be reentrant is added to the 17130 DESCRIPTION. 17131 Issue 6 17132 The getlogin_r( ) function is marked as part of the Thread-Safe Functions option. 17133 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 17134 The following new requirements on POSIX implementations derive from alignment with the 17135 Single UNIX Specification: 17136 * In the RETURN VALUE section, the requirement to set errno on error is added. 17137 * The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 17138 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 17139 its avoidance of possibly using a static data area. System Interfaces, Issue 6 981 getmsg( ) System Interfaces 17140 NAME 17141 getmsg, getpmsg - receive next message from a STREAMS file (STREAMS) 17142 SYNOPSIS 17143 XSR #include 17144 int getmsg(int fildes, struct strbuf *restrict ctlptr, 17145 struct strbuf *restrict dataptr, int *restrict flagsp); 17146 int getpmsg(int fildes, struct strbuf *restrict ctlptr, 17147 struct strbuf *restrict dataptr, int *restrict bandp, 17148 int *restrict flagsp); 17149 17150 DESCRIPTION 17151 The getmsg( ) function shall retrieve the contents of a message located at the head of the 17152 STREAM head read queue associated with a STREAMS file and place the contents into one or 17153 more buffers. The message contains either a data part, a control part, or both. The data and 17154 control parts of the message shall be placed into separate buffers, as described below. The | 17155 semantics of each part are defined by the originator of the message. 17156 The getpmsg( ) function shall be equivalent to getmsg( ), except that it provides finer control over | 17157 the priority of the messages received. Except where noted, all requirements on getmsg( ) also | 17158 pertain to getpmsg( ). 17159 The fildes argument specifies a file descriptor referencing a STREAMS-based file. 17160 The ctlptr and dataptr arguments each point to a strbuf structure, in which the buf member points 17161 to a buffer in which the data or control information is to be placed, and the maxlen member 17162 indicates the maximum number of bytes this buffer can hold. On return, the len member shall | 17163 contain the number of bytes of data or control information actually received. The len member | 17164 shall be set to 0 if there is a zero-length control or data part and len shall be set to -1 if no data or | 17165 control information is present in the message. | 17166 When getmsg( ) is called, flagsp should point to an integer that indicates the type of message the 17167 process is able to receive. This is described further below. 17168 The ctlptr argument is used to hold the control part of the message, and dataptr is used to hold 17169 the data part of the message. If ctlptr (or dataptr) is a null pointer or the maxlen member is -1, the | 17170 control (or data) part of the message shall not be processed and shall be left on the STREAM | 17171 head read queue, and if the ctlptr (or dataptr) is not a null pointer, len shall be set to -1. If the | 17172 maxlen member is set to 0 and there is a zero-length control (or data) part, that zero-length part | 17173 shall be removed from the read queue and len shall be set to 0. If the maxlen member is set to 0 | 17174 and there are more than 0 bytes of control (or data) information, that information shall be left on | 17175 the read queue and len shall be set to 0. If the maxlen member in ctlptr (or dataptr) is less than the | 17176 control (or data) part of the message, maxlen bytes shall be retrieved. In this case, the remainder | 17177 of the message shall be left on the STREAM head read queue and a non-zero return value shall | 17178 be provided. | 17179 By default, getmsg( ) shall process the first available message on the STREAM head read queue. | 17180 However, a process may choose to retrieve only high-priority messages by setting the integer | 17181 pointed to by flagsp to RS_HIPRI. In this case, getmsg( ) shall only process the next message if it is | 17182 a high-priority message. When the integer pointed to by flagsp is 0, any available message shall | 17183 be retrieved. In this case, on return, the integer pointed to by flagsp shall be set to RS_HIPRI if a | 17184 high-priority message was retrieved, or 0 otherwise. | 17185 For getpmsg( ), the flags are different. The flagsp argument points to a bitmask with the following 17186 mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. Like getmsg( ), 982 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getmsg( ) 17187 getpmsg( ) shall process the first available message on the STREAM head read queue. A process | 17188 may choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to | 17189 MSG_HIPRI and the integer pointed to by bandp to 0. In this case, getpmsg( ) shall only process | 17190 the next message if it is a high-priority message. In a similar manner, a process may choose to | 17191 retrieve a message from a particular priority band by setting the integer pointed to by flagsp to | 17192 MSG_BAND and the integer pointed to by bandp to the priority band of interest. In this case, 17193 getpmsg( ) shall only process the next message if it is in a priority band equal to, or greater than, | 17194 the integer pointed to by bandp, or if it is a high-priority message. If a process wants to get the | 17195 first message off the queue, the integer pointed to by flagsp should be set to MSG_ANY and the 17196 integer pointed to by bandp should be set to 0. On return, if the message retrieved was a high- 17197 priority message, the integer pointed to by flagsp shall be set to MSG_HIPRI and the integer | 17198 pointed to by bandp shall be set to 0. Otherwise, the integer pointed to by flagsp shall be set to | 17199 MSG_BAND and the integer pointed to by bandp shall be set to the priority band of the message. 17200 If O_NONBLOCK is not set, getmsg( ) and getpmsg( ) shall block until a message of the type 17201 specified by flagsp is available at the front of the STREAM head read queue. If O_NONBLOCK is 17202 set and a message of the specified type is not present at the front of the read queue, getmsg( ) and 17203 getpmsg( ) shall fail and set errno to [EAGAIN]. 17204 If a hangup occurs on the STREAM from which messages are retrieved, getmsg( ) and getpmsg( ) | 17205 shall continue to operate normally, as described above, until the STREAM head read queue is | 17206 empty. Thereafter, they shall return 0 in the len members of ctlptr and dataptr. | 17207 RETURN VALUE 17208 Upon successful completion, getmsg( ) and getpmsg( ) shall return a non-negative value. A value 17209 of 0 indicates that a full message was read successfully. A return value of MORECTL indicates 17210 that more control information is waiting for retrieval. A return value of MOREDATA indicates 17211 that more data is waiting for retrieval. A return value of the bitwise-logical OR of MORECTL 17212 and MOREDATA indicates that both types of information remain. Subsequent getmsg( ) and 17213 getpmsg( ) calls shall retrieve the remainder of the message. However, if a message of higher 17214 priority has come in on the STREAM head read queue, the next call to getmsg( ) or getpmsg( ) 17215 shall retrieve that higher-priority message before retrieving the remainder of the previous 17216 message. 17217 If the high priority control part of the message is consumed, the message shall be placed back on 17218 the queue as a normal message of band 0. Subsequent getmsg( ) and getpmsg( ) calls shall retrieve 17219 the remainder of the message. If, however, a priority message arrives or already exists on the 17220 STREAM head, the subsequent call to getmsg( ) or getpmsg( ) shall retrieve the higher-priority | 17221 message before retrieving the remainder of the message that was put back. | 17222 Upon failure, getmsg( ) and getpmsg( ) shall return -1 and set errno to indicate the error. 17223 ERRORS 17224 The getmsg( ) and getpmsg( ) functions shall fail if: 17225 [EAGAIN] The O_NONBLOCK flag is set and no messages are available. 17226 [EBADF] The fildes argument is not a valid file descriptor open for reading. 17227 [EBADMSG] The queued message to be read is not valid for getmsg( ) or getpmsg( ) or a 17228 pending file descriptor is at the STREAM head. 17229 [EINTR] A signal was caught during getmsg( ) or getpmsg( ). 17230 [EINVAL] An illegal value was specified by flagsp, or the STREAM or multiplexer 17231 referenced by fildes is linked (directly or indirectly) downstream from a 17232 multiplexer. System Interfaces, Issue 6 983 getmsg( ) System Interfaces 17233 [ENOSTR] A STREAM is not associated with fildes. 17234 In addition, getmsg( ) and getpmsg( ) shall fail if the STREAM head had processed an 17235 asynchronous error before the call. In this case, the value of errno does not reflect the result of 17236 getmsg( ) or getpmsg( ) but reflects the prior error. 17237 EXAMPLES 17238 Getting Any Message 17239 In the following example, the value of fd is assumed to refer to an open STREAMS file. The call 17240 to getmsg( ) retrieves any available message on the associated STREAM-head read queue, 17241 returning control and data information to the buffers pointed to by ctrlbuf and databuf, 17242 respectively. 17243 #include 17244 ... 17245 int fd; 17246 char ctrlbuf[128]; 17247 char databuf[512]; 17248 struct strbuf ctrl; 17249 struct strbuf data; 17250 int flags = 0; 17251 int ret; 17252 ctrl.buf = ctrlbuf; 17253 ctrl.maxlen = sizeof(ctrlbuf); 17254 data.buf = databuf; 17255 data.maxlen = sizeof(databuf); 17256 ret = getmsg (fd, &ctrl, &data, &flags); 17257 Getting the First Message off the Queue 17258 In the following example, the call to getpmsg( ) retrieves the first available message on the 17259 associated STREAM-head read queue. 17260 #include 17261 ... 17262 int fd; 17263 char ctrlbuf[128]; 17264 char databuf[512]; 17265 struct strbuf ctrl; 17266 struct strbuf data; 17267 int band = 0; 17268 int flags = MSG_ANY; 17269 int ret; 17270 ctrl.buf = ctrlbuf; 17271 ctrl.maxlen = sizeof(ctrlbuf); 17272 data.buf = databuf; 17273 data.maxlen = sizeof(databuf); 17274 ret = getpmsg (fd, &ctrl, &data, &band, &flags); 984 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getmsg( ) 17275 APPLICATION USAGE 17276 None. 17277 RATIONALE 17278 None. 17279 FUTURE DIRECTIONS 17280 None. 17281 SEE ALSO 17282 poll( ), putmsg( ), read( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 17283 , Section 2.6 (on page 488) 17284 CHANGE HISTORY 17285 First released in Issue 4, Version 2. 17286 Issue 5 17287 Moved from X/OPEN UNIX extension to BASE. 17288 A paragraph regarding ``high-priority control parts of messages'' is added to the RETURN 17289 VALUE section. 17290 Issue 6 17291 This function is marked as part of the XSI STREAMS Option Group. 17292 The restrict keyword is added to the getmsg( ) and getpmsg( ) prototypes for alignment with the 17293 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 985 getnameinfo( ) System Interfaces 17294 NAME 17295 getnameinfo - get name information | 17296 SYNOPSIS 17297 #include 17298 #include 17299 int getnameinfo(const struct sockaddr *restrict sa, socklen_t salen, 17300 char *restrict node, socklen_t nodelen, char *restrict service, 17301 socklen_t servicelen, unsigned flags); 17302 DESCRIPTION 17303 The getnameinfo( ) function shall translate a socket address to a node name and service location, | 17304 all of which are defined as in getaddrinfo( ). 17305 The sa argument points to a socket address structure to be translated. 17306 If the node argument is non-NULL and the nodelen argument is non-zero, then the node argument 17307 points to a buffer able to contain up to nodelen characters that receives the node name as a null- 17308 terminated string. If the node argument is NULL or the nodelen argument is zero, the node name 17309 shall not be returned. If the node's name cannot be located, the numeric form of the node's 17310 address is returned instead of its name. 17311 If the service argument is non-NULL and the servicelen argument is non-zero, then the service 17312 argument points to a buffer able to contain up to servicelen bytes that receives the service name | 17313 as a null-terminated string. If the service argument is NULL or the servicelen argument is zero, | 17314 the service name shall not be returned. If the service's name cannot be located, the numeric form 17315 of the service address (for example, its port number) shall be returned instead of its name. | 17316 The flags argument is a flag that changes the default actions of the function. By default the fully- | 17317 qualified domain name (FQDN) for the host shall be returned, but: | 17318 * If the flag bit NI_NOFQDN is set, only the node name portion of the FQDN shall be returned 17319 for local hosts. 17320 * If the flag bit NI_NUMERICHOST is set, the numeric form of the host's address shall be 17321 returned instead of its name, under all circumstances. 17322 * If the flag bit NI_NAMEREQD is set, an error shall be returned if the host's name cannot be 17323 located. 17324 * If the flag bit NI_NUMERICSERV is set, the numeric form of the service address shall be 17325 returned (for example, its port number) instead of its name, under all circumstances. 17326 * If the flag bit NI_DGRAM is set, this indicates that the service is a datagram service 17327 (SOCK_DGRAM). The default behavior shall assume that the service is a stream service 17328 (SOCK_STREAM). 17329 Notes: 17330 1. The two NI_NUMERICxxx flags are required to support the -n flag that many 17331 commands provide. 17332 2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port numbers (for | 17333 example, [512,514]) that represent different services for UDP and TCP. | 17334 The getnameinfo( ) function shall be thread-safe. 986 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getnameinfo( ) 17335 RETURN VALUE 17336 A zero return value for getnameinfo( ) indicates successful completion; a non-zero return value 17337 indicates failure. The possible values for the failures are listed in the ERRORS section. 17338 Upon successful completion, getnameinfo( ) shall return the node and service names, if requested, 17339 in the buffers provided. The returned names are always null-terminated strings. | 17340 ERRORS 17341 The getnameinfo( ) function shall fail and return the corresponding value if: 17342 [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 17343 [EAI_BADFLAGS] 17344 The flags had an invalid value. 17345 [EAI_FAIL] A non-recoverable error occurred. 17346 [EAI_FAMILY] The address family was not recognized or the address length was invalid for 17347 the specified family. 17348 [EAI_MEMORY] There was a memory allocation failure. 17349 [EAI_NONAME] The name does not resolve for the supplied parameters. 17350 NI_NAMEREQD is set and the host's name cannot be located, or both 17351 nodename and servname were null. 17352 [EAI_SYSTEM] A system error occurred. The error code can be found in errno. 17353 EXAMPLES 17354 None. 17355 APPLICATION USAGE 17356 If the returned values are to be used as part of any further name resolution (for example, passed 17357 to getaddrinfo( )), applications should provide buffers large enough to store any result possible | 17358 on the system. | 17359 RATIONALE 17360 None. 17361 FUTURE DIRECTIONS 17362 None. 17363 SEE ALSO 17364 gai_strerror( ), getaddrinfo( ), getservbyname( ), getservbyport( ), inet_ntop( ), socket( ), the Base 17365 Definitions volume of IEEE Std 1003.1-200x, , 17366 CHANGE HISTORY 17367 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 17368 The restrict keyword is added to the getnameinfo( ) prototype for alignment with the 17369 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 987 getnetbyaddr( ) System Interfaces 17370 NAME 17371 getnetbyaddr - network database functions 17372 SYNOPSIS 17373 #include 17374 struct netent *getnetbyaddr(uint32_t net, int type); 17375 DESCRIPTION 17376 Refer to endnetent( ). 988 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getnetbyname( ) 17377 NAME 17378 getnetbyname - network database functions 17379 SYNOPSIS 17380 #include 17381 struct netent *getnetbyname(const char *name); 17382 DESCRIPTION 17383 Refer to endnetent( ). System Interfaces, Issue 6 989 getnetent( ) System Interfaces 17384 NAME 17385 getnetent - network database functions 17386 SYNOPSIS 17387 #include 17388 struct netent *getnetent(void); 17389 DESCRIPTION 17390 Refer to endnetent( ). 990 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getopt( ) 17391 NAME 17392 getopt, optarg, opterr, optind, optopt - command option parsing 17393 SYNOPSIS 17394 #include 17395 int getopt(int argc, char * const argv[], const char *optstring); 17396 extern char *optarg; 17397 extern int optind, opterr, optopt; 17398 DESCRIPTION 17399 The getopt( ) function is a command-line parser that shall follow Utility Syntax Guidelines 3, 4, 5, | 17400 6, 7, 9, and 10 in the Base Definitions volume of IEEE Std 1003.1-200x, Section 12.2, Utility Syntax | 17401 Guidelines. | 17402 The parameters argc and argv are the argument count and argument array as passed to main( ) 17403 (see exec). The argument optstring is a string of recognized option characters; if a character is 17404 followed by a colon, the option takes an argument. All option characters allowed by Utility 17405 Syntax Guideline 3 are allowed in optstring. The implementation may accept other characters as 17406 an extension. 17407 The variable optind is the index of the next element of the argv[] vector to be processed. It shall | 17408 be initialized to 1 by the system, and getopt( ) shall update it when it finishes with each element | 17409 of argv[ ]. When an element of argv[ ] contains multiple option characters, it is unspecified how | 17410 getopt( ) determines which options have already been processed. 17411 The getopt( ) function shall return the next option character (if one is found) from argv that 17412 matches a character in optstring, if there is one that matches. If the option takes an argument, 17413 getopt( ) shall set the variable optarg to point to the option-argument as follows: 17414 1. If the option was the last character in the string pointed to by an element of argv, then 17415 optarg shall contain the next element of argv, and optind shall be incremented by 2. If the | 17416 resulting value of optind is greater than argc, this indicates a missing option-argument, and | 17417 getopt( ) shall return an error indication. 17418 2. Otherwise, optarg shall point to the string following the option character in that element of | 17419 argv, and optind shall be incremented by 1. | 17420 If, when getopt( ) is called: 17421 argv[optind] is a null pointer 17422 *argv[optind] is not the character - 17423 argv[optind] points to the string "-" 17424 getopt( ) shall return -1 without changing optind. If: 17425 argv[optind] points to the string "- -" 17426 getopt( ) shall return -1 after incrementing optind. 17427 If getopt( ) encounters an option character that is not contained in optstring, it shall return the 17428 question-mark ('?') character. If it detects a missing option-argument, it shall return the colon 17429 character (':') if the first character of optstring was a colon, or a question-mark character ('?') 17430 otherwise. In either case, getopt( ) shall set the variable optopt to the option character that caused 17431 the error. If the application has not set the variable opterr to 0 and the first character of optstring 17432 is not a colon, getopt( ) shall also print a diagnostic message to stderr in the format specified for 17433 the getopts utility. 17434 The getopt( ) function need not be reentrant. A function that is not required to be reentrant is not 17435 required to be thread-safe. System Interfaces, Issue 6 991 getopt( ) System Interfaces 17436 RETURN VALUE 17437 The getopt( ) function shall return the next option character specified on the command line. 17438 A colon (':') shall be returned if getopt( ) detects a missing argument and the first character of 17439 optstring was a colon (':'). 17440 A question mark ('?') shall be returned if getopt( ) encounters an option character not in 17441 optstring or detects a missing argument and the first character of optstring was not a colon (':'). 17442 Otherwise, getopt( ) shall return -1 when all command line options are parsed. 17443 ERRORS 17444 No errors are defined. 17445 EXAMPLES 17446 Parsing Command Line Options 17447 The following code fragment shows how you might process the arguments for a utility that can 17448 take the mutually-exclusive options a and b and the options f and o, both of which require 17449 arguments: 17450 #include 17451 int 17452 main(int argc, char *argv[ ]) 17453 { 17454 int c; 17455 int bflg, aflg, errflg; 17456 char *ifile; 17457 char *ofile; 17458 extern char *optarg; 17459 extern int optind, optopt; 17460 . . . 17461 while ((c = getopt(argc, argv, ":abf:o:")) != -1) { 17462 switch(c) { 17463 case 'a': 17464 if (bflg) 17465 errflg++; 17466 else 17467 aflg++; 17468 break; 17469 case 'b': 17470 if (aflg) 17471 errflg++; 17472 else { 17473 bflg++; 17474 bproc(); 17475 } 17476 break; 17477 case 'f': 17478 ifile = optarg; 17479 break; 17480 case 'o': 17481 ofile = optarg; 17482 break; 992 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getopt( ) 17483 case ':': /* -f or -o without operand */ 17484 fprintf(stderr, 17485 "Option -%c requires an operand\n", optopt); 17486 errflg++; 17487 break; 17488 case '?': 17489 fprintf(stderr, 17490 "Unrecognized option: -%c\n", optopt); 17491 errflg++; 17492 } 17493 } 17494 if (errflg) { 17495 fprintf(stderr, "usage: . . . "); 17496 exit(2); 17497 } 17498 for ( ; optind < argc; optind++) { 17499 if (access(argv[optind], R_OK)) { 17500 . . . 17501 } 17502 This code accepts any of the following as equivalent: 17503 cmd -ao arg path path 17504 cmd -a -o arg path path 17505 cmd -o arg -a path path 17506 cmd -a -o arg - - path path 17507 cmd -a -oarg path path 17508 cmd -aoarg path path 17509 Checking Options and Arguments 17510 The following example parses a set of command line options and prints messages to standard 17511 output for each option and argument that it encounters. 17512 #include 17513 #include 17514 ... 17515 int c; 17516 char *filename; 17517 extern char *optarg; 17518 extern int optind, optopt, opterr; 17519 ... 17520 while ((c = getopt(argc, argv, ":abf:")) != -1) { 17521 switch(c) { 17522 case 'a': 17523 printf("a is set\n"); 17524 break; 17525 case 'b': 17526 printf("b is set\n"); 17527 break; 17528 case 'f': 17529 filename = optarg; 17530 printf("filename is %s\n", filename); 17531 break; System Interfaces, Issue 6 993 getopt( ) System Interfaces 17532 case ':': 17533 printf("-%c without filename\n", optopt); 17534 break; 17535 case '?': 17536 printf("unknown arg %c\n", optopt); 17537 break; 17538 } 17539 } 17540 Selecting Options from the Command Line 17541 The following example selects the type of database routines the user wants to use based on the 17542 Options argument. 17543 #include 17544 #include 17545 ... 17546 char *Options = "hdbtl"; 17547 ... 17548 int dbtype, i; 17549 char c; 17550 char *st; 17551 ... 17552 dbtype = 0; 17553 while ((c = getopt(argc, argv, Options)) != -1) { 17554 if ((st = strchr(Options, c)) != NULL) { 17555 dbtype = st - Options; 17556 break; 17557 } 17558 } 17559 APPLICATION USAGE 17560 The getopt( ) function is only required to support option characters included in Utility Syntax 17561 Guideline 3. Many historical implementations of getopt( ) support other characters as options. 17562 This is an allowed extension, but applications that use extensions are not maximally portable. 17563 Note that support for multi-byte option characters is only possible when such characters can be 17564 represented as type int. 17565 RATIONALE 17566 The optopt variable represents historical practice and allows the application to obtain the identity 17567 of the invalid option. 17568 The description has been written to make it clear that getopt( ), like the getopts utility, deals with 17569 option-arguments whether separated from the option by s or not. Note that the 17570 requirements on getopt( ) and getopts are more stringent than the Utility Syntax Guidelines. 17571 The getopt( ) function shall return -1, rather than EOF, so that is not required. 17572 The special significance of a colon as the first character of optstring makes getopt( ) consistent 17573 with the getopts utility. It allows an application to make a distinction between a missing 17574 argument and an incorrect option letter without having to examine the option letter. It is true 17575 that a missing argument can only be detected in one case, but that is a case that has to be 17576 considered. 994 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getopt( ) 17577 FUTURE DIRECTIONS 17578 None. 17579 SEE ALSO 17580 exec, the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell and Utilities 17581 volume of IEEE Std 1003.1-200x 17582 CHANGE HISTORY 17583 First released in Issue 1. Derived from Issue 1 of the SVID. 17584 Issue 5 17585 A note indicating that the getopt( ) function need not be reentrant is added to the DESCRIPTION. 17586 Issue 6 17587 IEEE PASC Interpretation 1003.2 #150 is applied. System Interfaces, Issue 6 995 getpeername( ) System Interfaces 17588 NAME 17589 getpeername - get the name of the peer socket 17590 SYNOPSIS 17591 #include 17592 int getpeername(int socket, struct sockaddr *restrict address, 17593 socklen_t *restrict address_len); 17594 DESCRIPTION 17595 The getpeername( ) function shall retrieve the peer address of the specified socket, store this 17596 address in the sockaddr structure pointed to by the address argument, and store the length of this 17597 address in the object pointed to by the address_len argument. 17598 If the actual length of the address is greater than the length of the supplied sockaddr structure, 17599 the stored address shall be truncated. 17600 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 17601 stored in the object pointed to by address is unspecified. 17602 RETURN VALUE 17603 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 17604 indicate the error. 17605 ERRORS 17606 The getpeername( ) function shall fail if: 17607 [EBADF] The socket argument is not a valid file descriptor. 17608 [EINVAL] The socket has been shut down. 17609 [ENOTCONN] The socket is not connected or otherwise has not had the peer prespecified. 17610 [ENOTSOCK] The socket argument does not refer to a socket. 17611 [EOPNOTSUPP] The operation is not supported for the socket protocol. 17612 The getpeername( ) function may fail if: 17613 [ENOBUFS] Insufficient resources were available in the system to complete the call. 17614 EXAMPLES 17615 None. 17616 APPLICATION USAGE 17617 None. 17618 RATIONALE 17619 None. 17620 FUTURE DIRECTIONS 17621 None. 17622 SEE ALSO 17623 accept( ), bind( ), getsockname( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 17624 17625 CHANGE HISTORY 17626 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 17627 The restrict keyword is added to the getpeername( ) prototype for alignment with the 17628 ISO/IEC 9899: 1999 standard. 996 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpgid( ) 17629 NAME 17630 getpgid - get the process group ID for a process 17631 SYNOPSIS 17632 XSI #include 17633 pid_t getpgid(pid_t pid); 17634 17635 DESCRIPTION 17636 The getpgid( ) function shall return the process group ID of the process whose process ID is equal 17637 to pid. If pid is equal to 0, getpgid( ) shall return the process group ID of the calling process. 17638 RETURN VALUE 17639 Upon successful completion, getpgid( ) shall return a process group ID. Otherwise, it shall return 17640 (pid_t)-1 and set errno to indicate the error. 17641 ERRORS 17642 The getpgid( ) function shall fail if: 17643 [EPERM] The process whose process ID is equal to pid is not in the same session as the 17644 calling process, and the implementation does not allow access to the process 17645 group ID of that process from the calling process. 17646 [ESRCH] There is no process with a process ID equal to pid. 17647 The getpgid( ) function may fail if: 17648 [EINVAL] The value of the pid argument is invalid. 17649 EXAMPLES 17650 None. 17651 APPLICATION USAGE 17652 None. 17653 RATIONALE 17654 None. 17655 FUTURE DIRECTIONS 17656 None. 17657 SEE ALSO 17658 exec, fork( ), getpgrp( ), getpid( ), getsid( ), setpgid( ), setsid( ), the Base Definitions volume of 17659 IEEE Std 1003.1-200x, 17660 CHANGE HISTORY 17661 First released in Issue 4, Version 2. 17662 Issue 5 17663 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 997 getpgrp( ) System Interfaces 17664 NAME 17665 getpgrp - get the process group ID of the calling process 17666 SYNOPSIS 17667 #include 17668 pid_t getpgrp(void); 17669 DESCRIPTION 17670 The getpgrp( ) function shall return the process group ID of the calling process. 17671 RETURN VALUE 17672 The getpgrp( ) function shall always be successful and no return value is reserved to indicate an | 17673 error. | 17674 ERRORS 17675 No errors are defined. 17676 EXAMPLES 17677 None. 17678 APPLICATION USAGE 17679 None. 17680 RATIONALE 17681 4.3 BSD provides a getpgrp( ) function that returns the process group ID for a specified process. | 17682 Although this function supports job control, all known job control shells always specify the | 17683 calling process with this function. Thus, the simpler System V getpgrp( ) suffices, and the added 17684 complexity of the 4.3 BSD getpgrp( ) is provided by the XSI extension getpgid( ). 17685 FUTURE DIRECTIONS 17686 None. 17687 SEE ALSO 17688 exec, fork( ), getpgid( ), getpid( ), getppid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of 17689 IEEE Std 1003.1-200x, , 17690 CHANGE HISTORY 17691 First released in Issue 1. Derived from Issue 1 of the SVID. 17692 Issue 6 17693 In the SYNOPSIS, the optional include of the header is removed. 17694 The following new requirements on POSIX implementations derive from alignment with the 17695 Single UNIX Specification: 17696 * The requirement to include has been removed. Although was 17697 required for conforming implementations of previous POSIX specifications, it was not 17698 required for UNIX applications. 998 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpid( ) 17699 NAME 17700 getpid - get the process ID 17701 SYNOPSIS 17702 #include 17703 pid_t getpid(void); 17704 DESCRIPTION 17705 The getpid( ) function shall return the process ID of the calling process. 17706 RETURN VALUE 17707 The getpid( ) function shall always be successful and no return value is reserved to indicate an | 17708 error. 17709 ERRORS 17710 No errors are defined. 17711 EXAMPLES 17712 None. 17713 APPLICATION USAGE 17714 None. 17715 RATIONALE 17716 None. 17717 FUTURE DIRECTIONS 17718 None. 17719 SEE ALSO 17720 exec, fork( ), getpgrp( ), getppid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of 17721 IEEE Std 1003.1-200x, , 17722 CHANGE HISTORY 17723 First released in Issue 1. Derived from Issue 1 of the SVID. 17724 Issue 6 17725 In the SYNOPSIS, the optional include of the header is removed. 17726 The following new requirements on POSIX implementations derive from alignment with the 17727 Single UNIX Specification: 17728 * The requirement to include has been removed. Although was 17729 required for conforming implementations of previous POSIX specifications, it was not 17730 required for UNIX applications. System Interfaces, Issue 6 999 getpmsg( ) System Interfaces 17731 NAME 17732 getpmsg - receive next message from a STREAMS file 17733 SYNOPSIS 17734 XSI #include 17735 int getpmsg(int fildes, struct strbuf *restrict ctlptr, 17736 struct strbuf *restrict dataptr, int *restrict bandp, 17737 int *restrict flagsp); 17738 17739 DESCRIPTION 17740 Refer to getmsg( ). 1000 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getppid( ) 17741 NAME 17742 getppid - get the parent process ID 17743 SYNOPSIS 17744 #include 17745 pid_t getppid(void); 17746 DESCRIPTION 17747 The getppid( ) function shall return the parent process ID of the calling process. 17748 RETURN VALUE 17749 The getppid( ) function shall always be successful and no return value is reserved to indicate an | 17750 error. 17751 ERRORS 17752 No errors are defined. 17753 EXAMPLES 17754 None. 17755 APPLICATION USAGE 17756 None. 17757 RATIONALE 17758 None. 17759 FUTURE DIRECTIONS 17760 None. 17761 SEE ALSO 17762 exec, fork( ), getpgid( ), getpgrp( ), getpid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of 17763 IEEE Std 1003.1-200x, , 17764 CHANGE HISTORY 17765 First released in Issue 1. Derived from Issue 1 of the SVID. 17766 Issue 6 17767 In the SYNOPSIS, the optional include of the header is removed. 17768 The following new requirements on POSIX implementations derive from alignment with the 17769 Single UNIX Specification: 17770 * The requirement to include has been removed. Although was 17771 required for conforming implementations of previous POSIX specifications, it was not 17772 required for UNIX applications. System Interfaces, Issue 6 1001 getpriority( ) System Interfaces 17773 NAME 17774 getpriority, setpriority - get and set the nice value 17775 SYNOPSIS 17776 XSI #include 17777 int getpriority(int which, id_t who); 17778 int setpriority(int which, id_t who, int value); 17779 17780 DESCRIPTION 17781 The getpriority( ) function shall obtain the nice value of a process, process group, or user. The 17782 setpriority( ) function shall set the nice value of a process, process group, or user to 17783 value+{NZERO}. 17784 Target processes are specified by the values of the which and who arguments. The which 17785 argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, 17786 indicating that the who argument is to be interpreted as a process ID, a process group ID, or an 17787 effective user ID, respectively. A 0 value for the who argument specifies the current process, 17788 process group, or user. 17789 The nice value set with setpriority( ) shall be applied to the process. If the process is multi- 17790 threaded, the nice value shall affect all system scope threads in the process. 17791 If more than one process is specified, getpriority( ) shall return value {NZERO} less than the 17792 lowest nice value pertaining to any of the specified processes, and setpriority( ) shall set the nice | 17793 values of all of the specified processes to value+{NZERO}. | 17794 The default nice value is {NZERO}; lower nice values shall cause more favorable scheduling. 17795 While the range of valid nice values is [0,{NZERO}*2-1], implementations may enforce more 17796 restrictive limits. If value+{NZERO} is less than the system's lowest supported nice value, 17797 setpriority( ) shalls et the nice value to the lowest supported value; if value+{NZERO} is greater | 17798 than the system's highest supported nice value, setpriority( ) shall set the nice value to the highest | 17799 supported value. | 17800 Only a process with appropriate privileges can lower its nice value. 17801 PS|TPS Any processes or threads using SCHED_FIFO or SCHED_RR shall be unaffected by a call to | 17802 setpriority( ). This is not considered an error. A process which subsequently reverts to | 17803 SCHED_OTHER need not have its priority affected by such a setpriority( ) call. | 17804 The effect of changing the nice value may vary depending on the process-scheduling algorithm 17805 in effect. 17806 Since getpriority( ) can return the value -1 on successful completion, it is necessary to set errno to | 17807 0 prior to a call to getpriority( ). If getpriority( ) returns the value -1, then errno can be checked to 17808 see if an error occurred or if the value is a legitimate nice value. 17809 RETURN VALUE 17810 Upon successful completion, getpriority( ) shall return an integer in the range from -{NZERO} to 17811 {NZERO}-1. Otherwise, -1 shall be returned and errno set to indicate the error. 17812 Upon successful completion, setpriority( ) shall return 0; otherwise, -1 shall be returned and errno 17813 set to indicate the error. 17814 ERRORS 17815 The getpriority( ) and setpriority( ) functions shall fail if: 17816 [ESRCH] No process could be located using the which and who argument values 17817 specified. 1002 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpriority( ) 17818 [EINVAL] The value of the which argument was not recognized, or the value of the who 17819 argument is not a valid process ID, process group ID, or user ID. 17820 In addition, setpriority( ) may fail if: 17821 [EPERM] A process was located, but neither the real nor effective user ID of the 17822 executing process match the effective user ID of the process whose nice value 17823 is being changed. 17824 [EACCES] A request was made to change the nice value to a lower numeric value and 17825 the current process does not have appropriate privileges. 17826 EXAMPLES 17827 Using getpriority( ) 17828 The following example returns the current scheduling priority for the process ID returned by the 17829 call to getpid( ). 17830 #include 17831 ... 17832 int which = PRIO_PROCESS; 17833 id_t pid; 17834 int ret; 17835 pid = getpid(); 17836 ret = getpriority(which, pid); 17837 Using setpriority( ) 17838 The following example sets the priority for the current process ID to -20. 17839 #include 17840 ... 17841 int which = PRIO_PROCESS; 17842 id_t pid; 17843 int priority = -20; 17844 int ret; 17845 pid = getpid(); 17846 ret = setpriority(which, pid, priority); 17847 APPLICATION USAGE 17848 The getpriority( ) and setpriority( ) functions work with an offset nice value (nice value 17849 -{NZERO}). The nice value is in the range [0,2*{NZERO} -1], while the return value for 17850 getpriority( ) and the third parameter for setpriority( ) are in the range [-{NZERO},{NZERO} -1]. 17851 RATIONALE 17852 None. 17853 FUTURE DIRECTIONS 17854 None. 17855 SEE ALSO 17856 nice( ), sched_get_priority_max( ), sched_setscheduler( ), the Base Definitions volume of 17857 IEEE Std 1003.1-200x, System Interfaces, Issue 6 1003 getpriority( ) System Interfaces 17858 CHANGE HISTORY 17859 First released in Issue 4, Version 2. 17860 Issue 5 17861 Moved from X/OPEN UNIX extension to BASE. 17862 The DESCRIPTION is reworded in terms of the nice value rather than priority to avoid confusion 17863 with functionality in the POSIX Realtime Extension. 1004 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getprotobyname( ) 17864 NAME 17865 getprotobyname - network protocol database functions 17866 SYNOPSIS 17867 #include 17868 struct protoent *getprotobyname(const char *name); 17869 DESCRIPTION 17870 Refer to endprotoent( ). System Interfaces, Issue 6 1005 getprotobynumber( ) System Interfaces 17871 NAME 17872 getprotobynumber - network protocol database functions 17873 SYNOPSIS 17874 #include 17875 struct protoent *getprotobynumber(int proto); 17876 DESCRIPTION 17877 Refer to endprotoent( ). 1006 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getprotoent( ) 17878 NAME 17879 getprotoent - network protocol database functions 17880 SYNOPSIS 17881 #include 17882 struct protoent *getprotoent(void); 17883 DESCRIPTION 17884 Refer to endprotoent( ). System Interfaces, Issue 6 1007 getpwent( ) System Interfaces 17885 NAME 17886 getpwent - get user database entry 17887 SYNOPSIS 17888 XSI #include 17889 struct passwd *getpwent(void); 17890 17891 DESCRIPTION 17892 Refer to endpwent( ). 1008 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpwnam( ) 17893 NAME 17894 getpwnam, getpwnam_r - search user database for a name 17895 SYNOPSIS 17896 #include 17897 struct passwd *getpwnam(const char *name); 17898 TSF int getpwnam_r(const char *name, struct passwd *pwd, char *buffer, 17899 size_t bufsize, struct passwd **result); 17900 17901 DESCRIPTION 17902 The getpwnam( ) function shall search the user database for an entry with a matching name. 17903 The getpwnam( ) function need not be reentrant. A function that is not required to be reentrant is 17904 not required to be thread-safe. 17905 Applications wishing to check for error situations should set errno to 0 before calling 17906 getpwnam( ). If getpwnam( ) returns a null pointer and errno is non-zero, an error occurred. 17907 TSF The getpwnam_r( ) function shall update the passwd structure pointed to by pwd and store a | 17908 pointer to that structure at the location pointed to by result. The structure shall contain an entry | 17909 from the user database with a matching name. Storage referenced by the structure is allocated 17910 from the memory provided with the buffer parameter, which is bufsize bytes in size. The 17911 maximum size needed for this buffer can be determined with the {_SC_GETPW_R_SIZE_MAX} 17912 sysconf( ) parameter. A NULL pointer shall be returned at the location pointed to by result on 17913 error or if the requested entry is not found. 17914 RETURN VALUE 17915 The getpwnam( ) function shall return a pointer to a struct passwd with the structure as defined 17916 in with a matching entry if found. A null pointer shall be returned if the requested 17917 entry is not found, or an error occurs. On error, errno shall be set to indicate the error. 17918 The return value may point to a static area which is overwritten by a subsequent call to 17919 getpwent( ), getpwnam( ), or getpwuid( ). 17920 TSF If successful, the getpwnam_r( ) function shall return zero; otherwise, an error number shall be 17921 returned to indicate the error. 17922 ERRORS 17923 The getpwnam( ) and getpwnam_r( ) functions may fail if: 17924 [EIO] An I/O error has occurred. 17925 [EINTR] A signal was caught during getpwnam( ). 17926 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 17927 [ENFILE] The maximum allowable number of files is currently open in the system. 17928 The getpwnam_r( ) function may fail if: 17929 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 17930 be referenced by the resulting passwd structure. System Interfaces, Issue 6 1009 getpwnam( ) System Interfaces 17931 EXAMPLES 17932 Getting an Entry for the Login Name 17933 The following example uses the getlogin( ) function to return the name of the user who logged in; 17934 this information is passed to the getpwnam( ) function to get the user database entry for that user. 17935 #include 17936 #include 17937 #include 17938 #include 17939 #include 17940 ... 17941 char *lgn; 17942 struct passwd *pw; 17943 ... 17944 if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { 17945 fprintf(stderr, "Get of user information failed.\n"); exit(1); 17946 } 17947 ... 17948 APPLICATION USAGE 17949 Three names associated with the current process can be determined: getpwuid(geteuid( )) returns 17950 the name associated with the effective user ID of the process; getlogin( ) returns the name 17951 associated with the current login activity; and getpwuid(getuid( )) returns the name associated 17952 with the real user ID of the process. 17953 The getpwnam_r( ) function is thread-safe and returns values in a user-supplied buffer instead of 17954 possibly using a static data area that may be overwritten by each call. 17955 RATIONALE 17956 None. 17957 FUTURE DIRECTIONS 17958 None. 17959 SEE ALSO 17960 getpwuid( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 17961 17962 CHANGE HISTORY 17963 First released in Issue 1. Derived from System V Release 2.0. 17964 Issue 5 17965 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 17966 VALUE section. 17967 The getpwnam_r( ) function is included for alignment with the POSIX Threads Extension. 17968 A note indicating that the getpwnam( ) function need not be reentrant is added to the 17969 DESCRIPTION. 17970 Issue 6 17971 The getpwnam_r( ) function is marked as part of the Thread-Safe Functions option. 17972 The Open Group Corrigendum U028/3 is applied, correcting text in the DESCRIPTION 17973 describing matching the name. 1010 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpwnam( ) 17974 In the SYNOPSIS, the optional include of the header is removed. 17975 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 17976 The following new requirements on POSIX implementations derive from alignment with the 17977 Single UNIX Specification: 17978 * The requirement to include has been removed. Although was 17979 required for conforming implementations of previous POSIX specifications, it was not 17980 required for UNIX applications. 17981 * In the RETURN VALUE section, the requirement to set errno on error is added. 17982 * The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 17983 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 17984 its avoidance of possibly using a static data area. 17985 IEEE PASC Interpretation 1003.1 #116 is applied, changing the description of the size of the 17986 buffer from bufsize characters to bytes. System Interfaces, Issue 6 1011 getpwuid( ) System Interfaces 17987 NAME 17988 getpwuid, getpwuid_r - search user database for a user ID 17989 SYNOPSIS 17990 #include 17991 struct passwd *getpwuid(uid_t uid); 17992 TSF int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer, 17993 size_t bufsize, struct passwd **result); 17994 17995 DESCRIPTION 17996 The getpwuid( ) function shall search the user database for an entry with a matching uid. 17997 The getpwuid( ) function need not be reentrant. A function that is not required to be reentrant is 17998 not required to be thread-safe. 17999 Applications wishing to check for error situations should set errno to 0 before calling getpwuid( ). 18000 If getpwuid( ) returns a null pointer and errno is set to non-zero, an error occurred. 18001 TSF The getpwuid_r( ) function shall update the passwd structure pointed to by pwd and store a | 18002 pointer to that structure at the location pointed to by result. The structure shall contain an entry | 18003 from the user database with a matching uid. Storage referenced by the structure is allocated 18004 from the memory provided with the buffer parameter, which is bufsize bytes in size. The 18005 maximum size needed for this buffer can be determined with the {_SC_GETPW_R_SIZE_MAX} 18006 sysconf( ) parameter. A NULL pointer shall be returned at the location pointed to by result on 18007 error or if the requested entry is not found. 18008 RETURN VALUE 18009 The getpwuid( ) function shall return a pointer to a struct passwd with the structure as defined in 18010 with a matching entry if found. A null pointer shall be returned if the requested entry 18011 is not found, or an error occurs. On error, errno shall be set to indicate the error. 18012 The return value may point to a static area which is overwritten by a subsequent call to 18013 getpwent( ), getpwnam( ), or getpwuid( ). 18014 TSF If successful, the getpwuid_r( ) function shall return zero; otherwise, an error number shall be 18015 returned to indicate the error. 18016 ERRORS 18017 The getpwuid( ) and getpwuid_r( ) functions may fail if: 18018 [EIO] An I/O error has occurred. 18019 [EINTR] A signal was caught during getpwuid( ). 18020 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 18021 [ENFILE] The maximum allowable number of files is currently open in the system. 18022 The getpwuid_r( ) function may fail if: 18023 TSF [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 18024 be referenced by the resulting passwd structure. 1012 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getpwuid( ) 18025 EXAMPLES 18026 Getting an Entry for the Root User 18027 The following example gets the user database entry for the user with user ID 0 (root). 18028 #include 18029 #include 18030 ... 18031 uid_t id = 0; 18032 struct passwd *pwd; 18033 pwd = getpwuid(id); 18034 Finding the Name for the Effective User ID 18035 The following example defines pws as a pointer to a structure of type passwd, which is used to 18036 store the structure pointer returned by the call to the getpwuid( ) function. The geteuid( ) function 18037 shall return the effective user ID of the calling process; this is used as the search criteria for the 18038 getpwuid( ) function. The call to getpwuid( ) shall return a pointer to the structure containing that 18039 user ID value. 18040 #include 18041 #include 18042 #include 18043 ... 18044 struct passwd *pws; 18045 pws = getpwuid(geteuid()); 18046 Finding an Entry in the User Database 18047 The following example uses getpwuid( ) to search the user database for a user ID that was 18048 previously stored in a stat structure, then prints out the user name if it is found. If the user is not 18049 found, the program prints the numeric value of the user ID for the entry. 18050 #include 18051 #include 18052 #include 18053 ... 18054 struct stat statbuf; 18055 struct passwd *pwd; 18056 ... 18057 if ((pwd = getpwuid(statbuf.st_uid)) != NULL) 18058 printf(" %-8.8s", pwd->pw_name); 18059 else 18060 printf(" %-8d", statbuf.st_uid); 18061 APPLICATION USAGE 18062 Three names associated with the current process can be determined: getpwuid(geteuid( )) returns 18063 the name associated with the effective user ID of the process; getlogin( ) returns the name 18064 associated with the current login activity; and getpwuid(getuid( )) returns the name associated 18065 with the real user ID of the process. 18066 The getpwuid_r( ) function is thread-safe and returns values in a user-supplied buffer instead of 18067 possibly using a static data area that may be overwritten by each call. System Interfaces, Issue 6 1013 getpwuid( ) System Interfaces 18068 RATIONALE 18069 None. 18070 FUTURE DIRECTIONS 18071 None. 18072 SEE ALSO 18073 getpwnam( ), geteuid( ), getuid( ), getlogin( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18074 , , 18075 CHANGE HISTORY 18076 First released in Issue 1. Derived from System V Release 2.0. 18077 Issue 5 18078 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 18079 VALUE section. 18080 The getpwuid_r( ) function is included for alignment with the POSIX Threads Extension. 18081 A note indicating that the getpwuid( ) function need not be reentrant is added to the 18082 DESCRIPTION. 18083 Issue 6 18084 The getpwuid_r( ) function is marked as part of the Thread-Safe Functions option. 18085 The Open Group Corrigendum U028/3 is applied, correcting text in the DESCRIPTION 18086 describing matching the uid. 18087 In the SYNOPSIS, the optional include of the header is removed. 18088 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 18089 The following new requirements on POSIX implementations derive from alignment with the 18090 Single UNIX Specification: 18091 * The requirement to include has been removed. Although was 18092 required for conforming implementations of previous POSIX specifications, it was not 18093 required for UNIX applications. 18094 * In the RETURN VALUE section, the requirement to set errno on error is added. 18095 * The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 18096 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 18097 its avoidance of possibly using a static data area. 18098 IEEE PASC Interpretation 1003.1 #116 is applied, changing the description of the size of the 18099 buffer from bufsize characters to bytes. 1014 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getrlimit( ) 18100 NAME 18101 getrlimit, setrlimit - control maximum resource consumption 18102 SYNOPSIS 18103 XSI #include 18104 int getrlimit(int resource, struct rlimit *rlp); 18105 int setrlimit(int resource, const struct rlimit *rlp); 18106 18107 DESCRIPTION 18108 The getrlimit( ) function shall get, and the setrlimit( ) function shall set, limits on the consumption | 18109 of a variety of resources. | 18110 Each call to either getrlimit( ) or setrlimit( ) identifies a specific resource to be operated upon as 18111 well as a resource limit. A resource limit is represented by an rlimit structure. The rlim_cur 18112 member specifies the current or soft limit and the rlim_max member specifies the maximum or 18113 hard limit. Soft limits may be changed by a process to any value that is less than or equal to the 18114 hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or 18115 equal to the soft limit. Only a process with appropriate privileges can raise a hard limit. Both 18116 hard and soft limits can be changed in a single call to setrlimit( ) subject to the constraints 18117 described above. 18118 The value RLIM_INFINITY, defined in , shall be considered to be larger than 18119 any other limit value. If a call to getrlimit( ) returns RLIM_INFINITY for a resource, it means the 18120 implementation shall not enforce limits on that resource. Specifying RLIM_INFINITY as any 18121 resource limit value on a successful call to setrlimit( ) shall inhibit enforcement of that resource 18122 limit. 18123 The following resources are defined: 18124 RLIMIT_CORE This is the maximum size of a core file, in bytes, that may be created by a | 18125 process. A limit of 0 shall prevent the creation of a core file. If this limit is 18126 exceeded, the writing of a core file shall terminate at this size. 18127 RLIMIT_CPU This is the maximum amount of CPU time, in seconds, used by a process. | 18128 If this limit is exceeded, SIGXCPU shall be generated for the process. If 18129 the process is catching or ignoring SIGXCPU, or all threads belonging to 18130 that process are blocking SIGXCPU, the behavior is unspecified. 18131 RLIMIT_DATA This is the maximum size of a process' data segment, in bytes. If this limit | 18132 is exceeded, the malloc( ) function shall fail with errno set to [ENOMEM]. 18133 RLIMIT_FSIZE This is the maximum size of a file, in bytes, that may be created by a | 18134 process. If a write or truncate operation would cause this limit to be 18135 exceeded, SIGXFSZ shall be generated for the thread. If the thread is 18136 blocking, or the process is catching or ignoring SIGXFSZ, continued 18137 attempts to increase the size of a file from end-of-file to beyond the limit 18138 shall fail with errno set to [EFBIG]. 18139 RLIMIT_NOFILE This is a number one greater than the maximum value that the system 18140 may assign to a newly-created descriptor. If this limit is exceeded, 18141 functions that allocate new file descriptors may fail with errno set to 18142 [EMFILE]. This limit constrains the number of file descriptors that a 18143 process may allocate. 18144 RLIMIT_STACK This is the maximum size of a process' stack, in bytes. The | 18145 implementation does not automatically grow the stack beyond this limit. System Interfaces, Issue 6 1015 getrlimit( ) System Interfaces 18146 If this limit is exceeded, SIGSEGV shall be generated for the thread. If the 18147 thread is blocking SIGSEGV, or the process is ignoring or catching 18148 SIGSEGV and has not made arrangements to use an alternate stack, the 18149 disposition of SIGSEGV shall be set to SIG_DFL before it is generated. 18150 RLIMIT_AS This is the maximum size of a process' total available memory, in bytes. If 18151 this limit is exceeded, the malloc( ) and mmap( ) functions shall fail with 18152 errno set to [ENOMEM]. In addition, the automatic stack growth fails 18153 with the effects outlined above. 18154 When using the getrlimit( ) function, if a resource limit can be represented correctly in an object 18155 of type rlim_t, then its representation is returned; otherwise, if the value of the resource limit is 18156 equal to that of the corresponding saved hard limit, the value returned shall be 18157 RLIM_SAVED_MAX; otherwise, the value returned shall be RLIM_SAVED_CUR. 18158 When using the setrlimit( ) function, if the requested new limit is RLIM_INFINITY, the new limit 18159 shall be ``no limit''; otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit 18160 shall be the corresponding saved hard limit; otherwise, if the requested new limit is 18161 RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft limit; otherwise, the 18162 new limit shall be the requested value. In addition, if the corresponding saved limit can be 18163 represented correctly in an object of type rlim_t then it shall be overwritten with the new limit. 18164 The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is unspecified unless 18165 a previous call to getrlimit( ) returned that value as the soft or hard limit for the corresponding 18166 resource limit. 18167 The determination of whether a limit can be correctly represented in an object of type rlim_t is 18168 implementation-defined. For example, some implementations permit a limit whose value is 18169 greater than RLIM_INFINITY and others do not. 18170 The exec family of functions shall cause resource limits to be saved. | 18171 RETURN VALUE 18172 Upon successful completion, getrlimit( ) and setrlimit( ) shall return 0. Otherwise, these functions 18173 shall return -1 and set errno to indicate the error. 18174 ERRORS 18175 The getrlimit( ) and setrlimit( ) functions shall fail if: 18176 [EINVAL] An invalid resource was specified; or in a setrlimit( ) call, the new rlim_cur 18177 exceeds the new rlim_max. 18178 [EPERM] The limit specified to setrlimit( ) would have raised the maximum limit value, 18179 and the calling process does not have appropriate privileges. 18180 The setrlimit( ) function may fail if: 18181 [EINVAL] The limit specified cannot be lowered because current usage is already higher 18182 than the limit. 1016 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getrlimit( ) 18183 EXAMPLES 18184 None. 18185 APPLICATION USAGE 18186 If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE to less than the value 18187 of {_POSIX_OPEN_MAX} from , unexpected behavior may occur. 18188 RATIONALE 18189 None. 18190 FUTURE DIRECTIONS 18191 None. 18192 SEE ALSO 18193 exec, fork( ), malloc( ), open( ), sigaltstack( ), sysconf( ), ulimit( ), the Base Definitions volume of 18194 IEEE Std 1003.1-200x, , 18195 CHANGE HISTORY 18196 First released in Issue 4, Version 2. 18197 Issue 5 18198 Moved from X/OPEN UNIX extension to BASE and an APPLICATION USAGE section is added. 18199 Large File Summit extensions are added. System Interfaces, Issue 6 1017 getrusage( ) System Interfaces 18200 NAME 18201 getrusage - get information about resource utilization 18202 SYNOPSIS 18203 XSI #include 18204 int getrusage(int who, struct rusage *r_usage); 18205 18206 DESCRIPTION 18207 The getrusage( ) function shall provide measures of the resources used by the current process or | 18208 its terminated and waited-for child processes. If the value of the who argument is | 18209 RUSAGE_SELF, information shall be returned about resources used by the current process. If the 18210 value of the who argument is RUSAGE_CHILDREN, information shall be returned about 18211 resources used by the terminated and waited-for children of the current process. If the child is 18212 never waited for (for example, if the parent has SA_NOCLDWAIT set or sets SIGCHLD to 18213 SIG_IGN), the resource information for the child process is discarded and not included in the 18214 resource information provided by getrusage( ). 18215 The r_usage argument is a pointer to an object of type struct rusage in which the returned 18216 information is stored. 18217 RETURN VALUE 18218 Upon successful completion, getrusage( ) shall return 0; otherwise, -1 shall be returned and errno 18219 set to indicate the error. 18220 ERRORS 18221 The getrusage( ) function shall fail if: 18222 [EINVAL] The value of the who argument is not valid. 18223 EXAMPLES 18224 Using getrusage( ) 18225 The following example returns information about the resources used by the current process. 18226 #include 18227 ... 18228 int who = RUSAGE_SELF; 18229 struct rusage usage; 18230 int ret; 18231 ret = getrusage(who, &usage); 18232 APPLICATION USAGE 18233 None. 18234 RATIONALE 18235 None. 18236 FUTURE DIRECTIONS 18237 None. 18238 SEE ALSO 18239 exit( ), sigaction( ), time( ), times( ), wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18240 1018 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getrusage( ) 18241 CHANGE HISTORY 18242 First released in Issue 4, Version 2. 18243 Issue 5 18244 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1019 gets( ) System Interfaces 18245 NAME 18246 gets - get a string from a stdin stream 18247 SYNOPSIS 18248 #include 18249 char *gets(char *s); 18250 DESCRIPTION 18251 CX The functionality described on this reference page is aligned with the ISO C standard. Any 18252 conflict between the requirements described here and the ISO C standard is unintentional. This 18253 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 18254 The gets( ) function shall read bytes from the standard input stream, stdin, into the array pointed 18255 to by s, until a newline is read or an end-of-file condition is encountered. Any shall | 18256 be discarded and a null byte shall be placed immediately after the last byte read into the array. | 18257 CX The gets( ) function may mark the st_atime field of the file associated with stream for update. The 18258 st_atime field shall be marked for update by the first successful execution of fgetc( ), fgets( ), 18259 fread( ), getc( ), getchar( ), gets( ), fscanf( ), or scanf( ) using stream that returns data not supplied by 18260 a prior call to ungetc( ). 18261 RETURN VALUE 18262 Upon successful completion, gets( ) shall return s. If the stream is at end-of-file, the end-of-file 18263 indicator for the stream shall be set and gets( ) shall return a null pointer. If a read error occurs, 18264 CX the error indicator for the stream shall be set, gets( ) shall return a null pointer and set errno to 18265 indicate the error. 18266 ERRORS 18267 Refer to fgetc( ). 18268 EXAMPLES 18269 None. 18270 APPLICATION USAGE 18271 Reading a line that overflows the array pointed to by s results in undefined behavior. The use of 18272 fgets( ) is recommended. 18273 Since the user cannot specify the length of the buffer passed to gets( ), use of this function is 18274 discouraged. The length of the string read is unlimited. It is possible to overflow this buffer in 18275 such a way as to cause applications to fail, or possible system security violations. 18276 It is recommended that the fgets( ) function should be used to read input lines. 18277 RATIONALE 18278 None. 18279 FUTURE DIRECTIONS 18280 None. 18281 SEE ALSO 18282 feof( ), ferror( ), fgets( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18283 CHANGE HISTORY 18284 First released in Issue 1. Derived from Issue 1 of the SVID. 18285 Issue 6 18286 Extensions beyond the ISO C standard are now marked. 1020 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getservbyname( ) 18287 NAME 18288 getservbyname - network services database functions 18289 SYNOPSIS 18290 #include 18291 struct servent *getservbyname(const char *name, const char *proto); 18292 DESCRIPTION 18293 Refer to endservent( ). System Interfaces, Issue 6 1021 getservbyport( ) System Interfaces 18294 NAME 18295 getservbyport - network services database functions 18296 SYNOPSIS 18297 #include 18298 struct servent *getservbyport(int port, const char *proto); 18299 DESCRIPTION 18300 Refer to endservent( ). 1022 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getservent( ) 18301 NAME 18302 getservent - network services database functions 18303 SYNOPSIS 18304 #include 18305 struct servent *getservent(void); 18306 DESCRIPTION 18307 Refer to endservent( ). System Interfaces, Issue 6 1023 getsid( ) System Interfaces 18308 NAME 18309 getsid - get the process group ID of a session leader 18310 SYNOPSIS 18311 XSI #include 18312 pid_t getsid(pid_t pid); 18313 18314 DESCRIPTION 18315 The getsid( ) function shall obtain the process group ID of the process that is the session leader of | 18316 the process specified by pid. If pid is (pid_t)0, it specifies the calling process. 18317 RETURN VALUE 18318 Upon successful completion, getsid( ) shall return the process group ID of the session leader of 18319 the specified process. Otherwise, it shall return (pid_t)-1 and set errno to indicate the error. 18320 ERRORS 18321 The getsid( ) function shall fail if: 18322 [EPERM] The process specified by pid is not in the same session as the calling process, 18323 and the implementation does not allow access to the process group ID of the 18324 session leader of that process from the calling process. 18325 [ESRCH] There is no process with a process ID equal to pid. 18326 EXAMPLES 18327 None. 18328 APPLICATION USAGE 18329 None. 18330 RATIONALE 18331 None. 18332 FUTURE DIRECTIONS 18333 None. 18334 SEE ALSO 18335 exec, fork( ), getpid( ), getpgid( ), setpgid( ), setsid( ), the Base Definitions volume of 18336 IEEE Std 1003.1-200x, 18337 CHANGE HISTORY 18338 First released in Issue 4, Version 2. 18339 Issue 5 18340 Moved from X/OPEN UNIX extension to BASE. 1024 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getsockname( ) 18341 NAME 18342 getsockname - get the socket name 18343 SYNOPSIS 18344 #include 18345 int getsockname(int socket, struct sockaddr *restrict address, 18346 socklen_t *restrict address_len); 18347 DESCRIPTION 18348 The getsockname( ) function shall retrieve the locally-bound name of the specified socket, store 18349 this address in the sockaddr structure pointed to by the address argument, and store the length of 18350 this address in the object pointed to by the address_len argument. 18351 If the actual length of the address is greater than the length of the supplied sockaddr structure, 18352 the stored address shall be truncated. 18353 If the socket has not been bound to a local name, the value stored in the object pointed to by 18354 address is unspecified. 18355 RETURN VALUE 18356 Upon successful completion, 0 shall be returned, the address argument shall point to the address 18357 of the socket, and the address_len argument shall point to the length of the address. Otherwise, -1 18358 shall be returned and errno set to indicate the error. 18359 ERRORS 18360 The getsockname( ) function shall fail if: 18361 [EBADF] The socket argument is not a valid file descriptor. 18362 [ENOTSOCK] The socket argument does not refer to a socket. 18363 [EOPNOTSUPP] The operation is not supported for this socket's protocol. 18364 The getsockname( ) function may fail if: 18365 [EINVAL] The socket has been shut down. 18366 [ENOBUFS] Insufficient resources were available in the system to complete the function. 18367 EXAMPLES 18368 None. 18369 APPLICATION USAGE 18370 None. 18371 RATIONALE 18372 None. 18373 FUTURE DIRECTIONS 18374 None. 18375 SEE ALSO 18376 accept( ), bind( ), getpeername( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18377 18378 CHANGE HISTORY 18379 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 18380 The restrict keyword is added to the getsockname( ) prototype for alignment with the 18381 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1025 getsockopt( ) System Interfaces 18382 NAME 18383 getsockopt - get the socket options 18384 SYNOPSIS 18385 #include 18386 int getsockopt(int socket, int level, int option_name, 18387 void *restrict option_value, socklen_t *restrict option_len); 18388 DESCRIPTION 18389 The getsockopt( ) function manipulates options associated with a socket. 18390 The getsockopt( ) function shall retrieve the value for the option specified by the option_name 18391 argument for the socket specified by the socket argument. If the size of the option value is greater 18392 than option_len, the value stored in the object pointed to by the option_value argument shall be 18393 silently truncated. Otherwise, the object pointed to by the option_len argument shall be modified 18394 to indicate the actual length of the value. 18395 The level argument specifies the protocol level at which the option resides. To retrieve options at 18396 the socket level, specify the level argument as SOL_SOCKET. To retrieve options at other levels, 18397 supply the appropriate level identifier for the protocol controlling the option. For example, to 18398 indicate that an option is interpreted by the TCP (Transmission Control Protocol), set level to 18399 IPPROTO_TCP as defined in the header. 18400 The socket in use may require the process to have appropriate privileges to use the getsockopt( ) 18401 function. 18402 The option_name argument specifies a single option to be retrieved. It can be one of the following 18403 values defined in : 18404 SO_DEBUG Reports whether debugging information is being recorded. This option | 18405 shall store an int value. This is a Boolean option. | 18406 SO_ACCEPTCONN Reports whether socket listening is enabled. This option shall store an int | 18407 value. This is a Boolean option. 18408 SO_BROADCAST Reports whether transmission of broadcast messages is supported, if this | 18409 is supported by the protocol. This option shall store an int value. This is a | 18410 Boolean option. 18411 SO_REUSEADDR Reports whether the rules used in validating addresses supplied to bind( ) 18412 should allow reuse of local addresses, if this is supported by the protocol. | 18413 This option shall store an int value. This is a Boolean option. | 18414 SO_KEEPALIVE Reports whether connections are kept active with periodic transmission 18415 of messages, if this is supported by the protocol. 18416 If the connected socket fails to respond to these messages, the connection | 18417 shall be broken and threads writing to that socket shall be notified with a | 18418 SIGPIPE signal. This option shall store an int value. This is a Boolean | 18419 option. | 18420 SO_LINGER Reports whether the socket lingers on close( ) if data is present. If 18421 SO_LINGER is set, the system blocks the process during close( ) until it 18422 can transmit the data or until the end of the interval indicated by the 18423 l_linger member, whichever comes first. If SO_LINGER is not specified, 18424 and close( ) is issued, the system handles the call in a way that allows the 18425 process to continue as quickly as possible. This option shall store a linger | 18426 structure. 1026 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getsockopt( ) 18427 SO_OOBINLINE Reports whether the socket leaves received out-of-band data (data | 18428 marked urgent) inline. This option shalls tore an int value. This is a | 18429 Boolean option. 18430 SO_SNDBUF Reports send buffer size information. This option shall store an int value. | 18431 SO_RCVBUF Reports receive buffer size information. This option shall store an int | 18432 value. 18433 SO_ERROR Reports information about error status and clears it. This option shall | 18434 store an int value. | 18435 SO_TYPE Reports the socket type. This option shall store an int value. Socket types | 18436 are described in Section 2.10.6 (on page 509). | 18437 SO_DONTROUTE Reports whether outgoing messages bypass the standard routing 18438 facilities. The destination shall be on a directly-connected network, and 18439 messages are directed to the appropriate network interface according to 18440 the destination address. The effect, if any, of this option depends on what | 18441 protocol is in use. This option shall store an int value. This is a Boolean | 18442 option. 18443 SO_RCVLOWAT Reports the minimum number of bytes to process for socket input 18444 operations. The default value for SO_RCVLOWAT is 1. If 18445 SO_RCVLOWAT is set to a larger value, blocking receive calls normally 18446 wait until they have received the smaller of the low water mark value or 18447 the requested amount. (They may return less than the low water mark if 18448 an error occurs, a signal is caught, or the type of data next in the receive | 18449 queue is different from that returned; for example, out-of-band data.) | 18450 This option shall store an int value. Note that not all implementations | 18451 allow this option to be retrieved. 18452 SO_RCVTIMEO Reports the timeout value for input operations. This option shall store a | 18453 timeval structure with the number of seconds and microseconds 18454 specifying the limit on how long to wait for an input operation to 18455 complete. If a receive operation has blocked for this much time without 18456 receiving additional data, it shall return with a partial count or errno set to 18457 [EAGAIN] or [EWOULDBLOCK] if no data was received. The default for 18458 this option is zero, which indicates that a receive operation shall not time 18459 out. Note that not all implementations allow this option to be retrieved. 18460 SO_SNDLOWAT Reports the minimum number of bytes to process for socket output 18461 operations. Non-blocking output operations shall process no data if flow 18462 control does not allow the smaller of the send low water mark value or | 18463 the entire request to be processed. This option shall store an int value. | 18464 Note that not all implementations allow this option to be retrieved. 18465 SO_SNDTIMEO Reports the timeout value specifying the amount of time that an output 18466 function blocks because flow control prevents data from being sent. If a 18467 send operation has blocked for this time, it shall return with a partial 18468 count or with errno set to [EAGAIN] or [EWOULDBLOCK] if no data 18469 were sent. The default for this option is zero, which indicates that a send | 18470 operation shall not time out. The option shall store a timeval structure. | 18471 Note that not all implementations allow this option to be retrieved. 18472 For Boolean options, a zero value indicates that the option is disabled and a non-zero value 18473 indicates that the option is enabled. System Interfaces, Issue 6 1027 getsockopt( ) System Interfaces 18474 Options at other protocol levels vary in format and name. 18475 The socket in use may require the process to have appropriate privileges to use the getsockopt( ) 18476 function. 18477 RETURN VALUE 18478 Upon successful completion, getsockopt( ) shall return 0; otherwise, -1 shall be returned and errno 18479 set to indicate the error. 18480 ERRORS 18481 The getsockopt( ) function shall fail if: 18482 [EBADF] The socket argument is not a valid file descriptor. 18483 [EINVAL] The specified option is invalid at the specified socket level. 18484 [ENOPROTOOPT] 18485 The option is not supported by the protocol. 18486 [ENOTSOCK] The socket argument does not refer to a socket. 18487 The getsockopt( ) function may fail if: 18488 [EACCES] The calling process does not have the appropriate privileges. 18489 [EINVAL] The socket has been shut down. 18490 [ENOBUFS] Insufficient resources are available in the system to complete the function. 18491 EXAMPLES 18492 None. 18493 APPLICATION USAGE 18494 None. 18495 RATIONALE 18496 None. 18497 FUTURE DIRECTIONS 18498 None. 18499 SEE ALSO 18500 bind( ), close( ), endprotoent( ), setsockopt( ), socket( ), the Base Definitions volume of 18501 IEEE Std 1003.1-200x, , 18502 CHANGE HISTORY 18503 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 18504 The restrict keyword is added to the getsockopt( ) prototype for alignment with the 18505 ISO/IEC 9899: 1999 standard. 1028 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getsubopt( ) 18506 NAME 18507 getsubopt - parse suboption arguments from a string 18508 SYNOPSIS 18509 XSI #include 18510 int getsubopt(char **optionp, char * const *tokens, char **valuep); 18511 18512 DESCRIPTION 18513 The getsubopt( ) function shall parse suboption arguments in a flag argument. Such options often | 18514 result from the use of getopt( ). | 18515 The getsubopt( ) argument optionp is a pointer to a pointer to the option argument string. The | 18516 suboption arguments shall be separated by commas and each may consist of either a single | 18517 token, or a token-value pair separated by an equal sign. | 18518 The keylistp argument shall be a pointer to a vector of strings. The end of the vector is identified | 18519 by a null pointer. Each entry in the vector is one of the possible tokens that might be found in | 18520 *optionp. Since commas delimit suboption arguments in optionp, they should not appear in any of | 18521 the strings pointed to by keylistp. Similarly, because an equal sign separates a token from its | 18522 value, the application should not include an equal sign in any of the strings pointed to by | 18523 keylistp. | 18524 The valuep argument is the address of a value string pointer. | 18525 If a comma appears in optionp, it shall be interpreted as a suboption separator. After commas | 18526 have been processed, if there are one or more equal signs in a suboption string, the first equal | 18527 sign in any suboption string shall be interpreted as a separator between a token and a value. | 18528 Subsequent equal signs in a suboption string shall be interpreted as part of the value. | 18529 If the string at *optionp contains only one suboption argument (equivalently, no commas), | 18530 getsubopt( ) shall update *optionp to point to the nul character at the end of the string. Otherwise, | 18531 it shall isolate the suboption argument by replacing the comma separator with a nul character, | 18532 and shall update *optionp to point to the start of the next suboption argument. If the suboption | 18533 argument has an associated value (equivalently, contains an equal sign), getsubopt( ) shall update | 18534 *valuep to point to the value's first character. Otherwise, it shall set *valuep to a null pointer. The | 18535 calling application may use this information to determine whether the presence or absence of a | 18536 value for the suboption is an error. | 18537 Additionally, when getsubopt( ) fails to match the suboption argument with a token in the keylistp | 18538 array, the calling application should decide if this is an error, or if the unrecognized option | 18539 should be processed in another way. | 18540 RETURN VALUE 18541 The getsubopt( ) function shall return the index of the matched token string, or -1 if no token 18542 strings were matched. 18543 ERRORS 18544 No errors are defined. System Interfaces, Issue 6 1029 getsubopt( ) System Interfaces 18545 EXAMPLES 18546 #include 18547 #include 18548 int do_all; 18549 const char *type; 18550 int read_size; 18551 int write_size; 18552 int read_only; 18553 enum 18554 { 18555 RO_OPTION = 0, 18556 RW_OPTION, 18557 READ_SIZE_OPTION, 18558 WRITE_SIZE_OPTION 18559 }; 18560 const char *mount_opts[] = | 18561 { 18562 [RO_OPTION] = "ro", 18563 [RW_OPTION] = "rw", 18564 [READ_SIZE_OPTION] = "rsize", 18565 [WRITE_SIZE_OPTION] = "wsize", 18566 NULL 18567 }; 18568 int 18569 main(int argc, char *argv[]) 18570 { 18571 char *subopts, *value; 18572 int opt; 18573 while ((opt = getopt(argc, argv, "at:o:")) != -1) 18574 switch(opt) 18575 { 18576 case 'a': 18577 do_all = 1; 18578 break; 18579 case 't': 18580 type = optarg; 18581 break; 18582 case 'o': 18583 subopts = optarg; 18584 while (*subopts != '\0') | 18585 switch(getsubopt(&subopts, mount_opts, &value)) | 18586 { 18587 case RO_OPTION: 18588 read_only = 1; 18589 break; 18590 case RW_OPTION: 18591 read_only = 0; 18592 break; 18593 case READ_SIZE_OPTION: 1030 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getsubopt( ) 18594 if (value == NULL) 18595 abort(); 18596 read_size = atoi(value); 18597 break; 18598 case WRITE_SIZE_OPTION: 18599 if (value == NULL) 18600 abort(); 18601 write_size = atoi(value); 18602 break; 18603 default: 18604 /* Unknown suboption. */ 18605 printf("Unknown suboption `%s'\n", value); | 18606 break; | 18607 } 18608 break; 18609 default: 18610 abort(); 18611 } 18612 /* Do the real work. */ 18613 return 0; 18614 } 18615 Parsing Suboptions 18616 The following example uses the getsubopt( ) function to parse a value argument in the optarg 18617 external variable returned by a call to getopt( ). 18618 #include 18619 ... 18620 char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL }; 18621 char *value; 18622 int opt, index; 18623 while ((opt = getopt(argc, argv, "e:")) != -1) { 18624 switch(opt) { 18625 case 'e' : 18626 while ((index = getsubopt(&optarg, tokens, &value)) != -1) { 18627 switch(index) { 18628 ... 18629 } 18630 break; 18631 ... 18632 } 18633 } 18634 ... 18635 APPLICATION USAGE 18636 None. 18637 RATIONALE 18638 None. System Interfaces, Issue 6 1031 getsubopt( ) System Interfaces 18639 FUTURE DIRECTIONS 18640 None. 18641 SEE ALSO 18642 getopt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18643 CHANGE HISTORY 18644 First released in Issue 4, Version 2. 18645 Issue 5 18646 Moved from X/OPEN UNIX extension to BASE. 1032 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gettimeofday( ) 18647 NAME 18648 gettimeofday - get the date and time 18649 SYNOPSIS 18650 XSI #include 18651 int gettimeofday(struct timeval *restrict tp, void *restrict tzp); 18652 18653 DESCRIPTION 18654 The gettimeofday( ) function shall obtain the current time, expressed as seconds and | 18655 microseconds since the Epoch, and store it in the timeval structure pointed to by tp. The | 18656 resolution of the system clock is unspecified. 18657 If tzp is not a null pointer, the behavior is unspecified. 18658 RETURN VALUE 18659 The gettimeofday( ) function shall return 0 and no value shall be reserved to indicate an error. 18660 ERRORS 18661 No errors are defined. 18662 EXAMPLES 18663 None. 18664 APPLICATION USAGE 18665 None. 18666 RATIONALE 18667 None. 18668 FUTURE DIRECTIONS 18669 None. 18670 SEE ALSO 18671 ctime( ), ftime( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18672 CHANGE HISTORY 18673 First released in Issue 4, Version 2. 18674 Issue 5 18675 Moved from X/OPEN UNIX extension to BASE. 18676 Issue 6 18677 The DESCRIPTION is updated to refer to ``seconds since the Epoch'' rather than ``seconds since 18678 00:00:00 UTC (Coordinated Universal Time), January 1 1970'' for consistency with other time 18679 functions. 18680 The restrict keyword is added to the gettimeofday( ) prototype for alignment with the 18681 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1033 getuid( ) System Interfaces 18682 NAME 18683 getuid - get a real user ID 18684 SYNOPSIS 18685 #include 18686 uid_t getuid(void); 18687 DESCRIPTION 18688 The getuid( ) function shall return the real user ID of the calling process. 18689 RETURN VALUE 18690 The getuid( ) function shall always be successful and no return value is reserved to indicate the | 18691 error. 18692 ERRORS 18693 No errors are defined. 18694 EXAMPLES 18695 Setting the Effective User ID to the Real User ID 18696 The following example sets the effective user ID and the real user ID of the current process to the 18697 real user ID of the caller. 18698 #include 18699 #include 18700 ... 18701 setreuid(getuid(), getuid()); 18702 ... 18703 APPLICATION USAGE 18704 None. 18705 RATIONALE 18706 None. 18707 FUTURE DIRECTIONS 18708 None. 18709 SEE ALSO 18710 getegid( ), geteuid( ), getgid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the Base 18711 Definitions volume of IEEE Std 1003.1-200x, , 18712 CHANGE HISTORY 18713 First released in Issue 1. Derived from Issue 1 of the SVID. 18714 Issue 6 18715 In the SYNOPSIS, the optional include of the header is removed. 18716 The following new requirements on POSIX implementations derive from alignment with the 18717 Single UNIX Specification: 18718 * The requirement to include has been removed. Although was 18719 required for conforming implementations of previous POSIX specifications, it was not 18720 required for UNIX applications. 1034 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getutxent( ) 18721 NAME 18722 getutxent, getutxid, getutxline - get user accounting database entries 18723 SYNOPSIS 18724 XSI #include 18725 struct utmpx *getutxent(void); 18726 struct utmpx *getutxid(const struct utmpx *id); 18727 struct utmpx *getutxline(const struct utmpx *line); 18728 18729 DESCRIPTION 18730 Refer to endutxent( ). System Interfaces, Issue 6 1035 getwc( ) System Interfaces 18731 NAME 18732 getwc - get a wide character from a stream 18733 SYNOPSIS 18734 #include 18735 #include 18736 wint_t getwc(FILE *stream); 18737 DESCRIPTION 18738 CX The functionality described on this reference page is aligned with the ISO C standard. Any 18739 conflict between the requirements described here and the ISO C standard is unintentional. This 18740 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 18741 The getwc( ) function shall be equivalent to fgetwc( ), except that if it is implemented as a macro it | 18742 may evaluate stream more than once, so the argument should never be an expression with side 18743 effects. 18744 RETURN VALUE 18745 Refer to fgetwc( ). 18746 ERRORS 18747 Refer to fgetwc( ). 18748 EXAMPLES 18749 None. 18750 APPLICATION USAGE 18751 Since it may be implemented as a macro, getwc( ) may treat incorrectly a stream argument with | 18752 side effects. In particular, getwc(*f++) does not necessarily work as expected. Therefore, use of 18753 this function is not recommended; fgetwc( ) should be used instead. 18754 RATIONALE 18755 None. 18756 FUTURE DIRECTIONS 18757 None. 18758 SEE ALSO 18759 fgetwc( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 18760 CHANGE HISTORY 18761 First released as a World-wide Portability Interface in Issue 4. Derived from the MSE working 18762 draft. 18763 Issue 5 18764 The Optional Header (OH) marking is removed from . 1036 Technical Standard (2001) (Draft April 16, 2001) System Interfaces getwchar( ) 18765 NAME 18766 getwchar - get a wide character from a stdin stream 18767 SYNOPSIS 18768 #include 18769 wint_t getwchar(void); 18770 DESCRIPTION 18771 CX The functionality described on this reference page is aligned with the ISO C standard. Any 18772 conflict between the requirements described here and the ISO C standard is unintentional. This 18773 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 18774 The getwchar( ) function shall be equivalent to getwc(stdin). | 18775 RETURN VALUE 18776 Refer to fgetwc( ). 18777 ERRORS 18778 Refer to fgetwc( ). 18779 EXAMPLES 18780 None. 18781 APPLICATION USAGE 18782 If the wint_t value returned by getwchar( ) is stored into a variable of type wchar_t and then 18783 compared against the wint_t macro WEOF, the result may be incorrect. Only the wint_t type is 18784 guaranteed to be able to represent any wide character and WEOF. 18785 RATIONALE 18786 None. 18787 FUTURE DIRECTIONS 18788 None. 18789 SEE ALSO 18790 fgetwc( ), getwc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18791 CHANGE HISTORY 18792 First released as a World-wide Portability Interface in Issue 4. Derived from the MSE working 18793 draft. System Interfaces, Issue 6 1037 getwd( ) System Interfaces 18794 NAME 18795 getwd - get the current working directory pathname (LEGACY) | 18796 SYNOPSIS 18797 XSI #include 18798 char *getwd(char *path_name); 18799 18800 DESCRIPTION 18801 The getwd( ) function shall determine an absolute pathname of the current working directory of | 18802 the calling process, and copy a string containing that pathname into the array pointed to by the | 18803 path_name argument. 18804 If the length of the pathname of the current working directory is greater than ({PATH_MAX}+1) | 18805 including the null byte, getwd( ) shall fail and return a null pointer. 18806 RETURN VALUE 18807 Upon successful completion, a pointer to the string containing the absolute pathname of the | 18808 current working directory shall be returned. Otherwise, getwd( ) shall return a null pointer and | 18809 the contents of the array pointed to by path_name are undefined. 18810 ERRORS 18811 No errors are defined. 18812 EXAMPLES 18813 None. 18814 APPLICATION USAGE 18815 For applications portability, the getcwd( ) function should be used to determine the current 18816 working directory instead of getwd( ). 18817 RATIONALE 18818 Since the user cannot specify the length of the buffer passed to getwd( ), use of this function is | 18819 discouraged. The length of a pathname described in {PATH_MAX} is file system-dependent and | 18820 may vary from one mount point to another, or might even be unlimited. It is possible to 18821 overflow this buffer in such a way as to cause applications to fail, or possible system security 18822 violations. 18823 It is recommended that the getcwd( ) function should be used to determine the current working 18824 directory. 18825 FUTURE DIRECTIONS 18826 This function may be withdrawn in a future version. 18827 SEE ALSO 18828 getcwd( ), the Base Definitions volume of IEEE Std 1003.1-200x, 18829 CHANGE HISTORY 18830 First released in Issue 4, Version 2. 18831 Issue 5 18832 Moved from X/OPEN UNIX extension to BASE. 18833 Issue 6 18834 This function is marked LEGACY. 1038 Technical Standard (2001) (Draft April 16, 2001) System Interfaces glob( ) 18835 NAME 18836 glob, globfree - generate pathnames matching a pattern | 18837 SYNOPSIS 18838 #include 18839 int glob(const char *restrict pattern, int flags, 18840 int(*errfunc)(const char *epath, int eerrno), 18841 glob_t *restrict pglob); 18842 void globfree(glob_t *pglob); 18843 DESCRIPTION 18844 The glob( ) function is a pathname generator that shall implement the rules defined in the Shell | 18845 and Utilities volume of IEEE Std 1003.1-200x, Section 2.13, Pattern Matching Notation, with | 18846 optional support for rule 3 in the Shell and Utilities volume of IEEE Std 1003.1-200x, Section | 18847 2.13.3, Patterns Used for Filename Expansion. | 18848 The structure type glob_t is defined in and includes at least the following members: | 18849 _________________________________________________________________________ 18850 _ Member Type Member Name Description ________________________________________________________________________ 18851 size_t gl_pathc Count of paths matched by pattern. 18852 char ** gl_pathv Pointer to a list of matched pathnames. | 18853 _ size_t gl_offs Slots to reserve at the beginning of gl_pathv. ________________________________________________________________________ | 18854 The argument pattern is a pointer to a pathname pattern to be expanded. The glob( ) function | 18855 shall match all accessible pathnames against this pattern and develop a list of all pathnames that | 18856 match. In order to have access to a pathname, glob( ) requires search permission on every | 18857 component of a path except the last, and read permission on each directory of any filename 18858 component of pattern that contains any of the following special characters: '*', '?', and '['. 18859 The glob( ) function shall store the number of matched pathnames into pglob->gl_pathc and a | 18860 pointer to a list of pointers to path names into pglob->gl_pathv. The pathnames shall be in sort | 18861 order as defined by the current setting of the LC_COLLATE category; see the Base Definitions | 18862 volume of IEEE Std 1003.1-200x, Section 7.3.2, LC_COLLATE. The first pointer after the last | 18863 pathname shall be a null pointer. If the pattern does not match any pathnames, the returned | 18864 number of matched paths is set to 0, and the contents of pglob->gl_pathv are implementation- 18865 defined. 18866 It is the caller's responsibility to create the structure pointed to by pglob. The glob( ) function shall 18867 allocate other space as needed, including the memory pointed to by gl_pathv. The globfree( ) 18868 function shall free any space associated with pglob from a previous call to glob( ). 18869 The flags argument is used to control the behavior of glob( ). The value of flags is a bitwise- 18870 inclusive OR of zero or more of the following constants, which are defined in : | 18871 GLOB_APPEND Append pathnames generated to the ones from a previous call to glob( ). | 18872 GLOB_DOOFFS Make use of pglob->gl_offs. If this flag is set, pglob->gl_offs is used to 18873 specify how many null pointers to add to the beginning of pglob- 18874 >gl_pathv. In other words, pglob->gl_pathv shall point to pglob->gl_offs null 18875 pointers, followed by pglob->gl_pathc pathname pointers, followed by a | 18876 null pointer. | 18877 GLOB_ERR Cause glob( ) to return when it encounters a directory that it cannot open | 18878 or read. Ordinarily, glob( ) continues to find matches. System Interfaces, Issue 6 1039 glob( ) System Interfaces 18879 GLOB_MARK Each pathname that is a directory that matches pattern shall have a slash | 18880 appended. | 18881 GLOB_NOCHECK Supports rule 3 in the Shell and Utilities volume of IEEE Std 1003.1-200x, 18882 Section 2.13.3, Patterns Used for Filename Expansion. If pattern does not | 18883 match any pathname, then glob( ) shall return a list consisting of only | 18884 pattern, and the number of matched pathnames is 1. | 18885 GLOB_NOESCAPE Disable backslash escaping. 18886 GLOB_NOSORT Ordinarily, glob( ) sorts the matching pathnames according to the current | 18887 setting of the LC_COLLATE category, see the Base Definitions volume of | 18888 IEEE Std 1003.1-200x, Section 7.3.2, LC_COLLATE . When this flag is 18889 used, the order of path names returned is unspecified. 18890 The GLOB_APPEND flag can be used to append a new set of pathnames to those found in a | 18891 previous call to glob( ). The following rules apply to applications when two or more calls to 18892 glob( ) are made with the same value of pglob and without intervening calls to globfree( ): 18893 1. The first such call shall not set GLOB_APPEND. All subsequent calls shall set it. 18894 2. All the calls shall set GLOB_DOOFFS, or all shall not set it. 18895 3. After the second call, pglob->gl_pathv points to a list containing the following: 18896 a. Zero or more null pointers, as specified by GLOB_DOOFFS and pglob->gl_offs. 18897 b. Pointers to the pathnames that were in the pglob->gl_pathv list before the call, in the | 18898 same order as before. 18899 c. Pointers to the new pathnames generated by the second call, in the specified order. | 18900 4. The count returned in pglob->gl_pathc shall be the total number of pathnames from the two | 18901 calls. | 18902 5. The application can change any of the fields after a call to glob( ). If it does, the application 18903 shall reset them to the original value before a subsequent call, using the same pglob value, 18904 to globfree( ) or glob( ) with the GLOB_APPEND flag. 18905 If, during the search, a directory is encountered that cannot be opened or read and errfunc is not 18906 a null pointer, glob( ) calls (*errfunc( )) with two arguments: 18907 1. The epath argument is a pointer to the path that failed. 18908 2. The eerrno argument is the value of errno from the failure, as set by opendir( ), readdir( ), or 18909 stat( ). (Other values may be used to report other errors not explicitly documented for 18910 those functions.) 18911 If (*errfunc( )) is called and returns non-zero, or if the GLOB_ERR flag is set in flags, glob( ) shall 18912 stop the scan and return GLOB_ABORTED after setting gl_pathc and gl_pathv in pglob to reflect 18913 the paths already scanned. If GLOB_ERR is not set and either errfunc is a null pointer or 18914 (*errfunc( )) returns 0, the error shall be ignored. | 18915 The glob( ) function shall not fail because of large files. | 18916 RETURN VALUE 18917 Upon successful completion, glob( ) shall return 0. The argument pglob->gl_pathc shall return the | 18918 number of matched pathnames and the argument pglob->gl_pathv shall contain a pointer to a | 18919 null-terminated list of matched and sorted pathnames. However, if pglob->gl_pathc is 0, the | 18920 content of pglob->gl_pathv is undefined. 1040 Technical Standard (2001) (Draft April 16, 2001) System Interfaces glob( ) 18921 The globfree( ) function shall not return a value. 18922 If glob( ) terminates due to an error, it shall return one of the non-zero constants defined in 18923 . The arguments pglob->gl_pathc and pglob->gl_pathv are still set as defined above. 18924 ERRORS 18925 The glob( ) function shall fail and return the corresponding value if: 18926 GLOB_ABORTED The scan was stopped because GLOB_ERR was set or (*errfunc( )) 18927 returned non-zero. 18928 GLOB_NOMATCH The pattern does not match any existing pathname, and | 18929 GLOB_NOCHECK was not set in flags. | 18930 GLOB_NOSPACE An attempt to allocate memory failed. 18931 EXAMPLES 18932 One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with 18933 execv( ), execve( ), or execvp( ). Suppose, for example, that an application wants to do the 18934 equivalent of: 18935 ls -l *.c 18936 but for some reason: 18937 system("ls -l *.c") 18938 is not acceptable. The application could obtain approximately the same result using the 18939 sequence: 18940 globbuf.gl_offs = 2; 18941 glob("*.c", GLOB_DOOFFS, NULL, &globbuf); 18942 globbuf.gl_pathv[0] = "ls"; 18943 globbuf.gl_pathv[1] = "-l"; 18944 execvp("ls", &globbuf.gl_pathv[0]); 18945 Using the same example: 18946 ls -l *.c *.h 18947 could be approximately simulated using GLOB_APPEND as follows: 18948 globbuf.gl_offs = 2; 18949 glob("*.c", GLOB_DOOFFS, NULL, &globbuf); 18950 glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); 18951 ... 18952 APPLICATION USAGE 18953 This function is not provided for the purpose of enabling utilities to perform pathname | 18954 expansion on their arguments, as this operation is performed by the shell, and utilities are | 18955 explicitly not expected to redo this. Instead, it is provided for applications that need to do | 18956 pathname expansion on strings obtained from other sources, such as a pattern typed by a user or | 18957 read from a file. 18958 If a utility needs to see if a pathname matches a given pattern, it can use fnmatch( ). | 18959 Note that gl_pathc and gl_pathv have meaning even if glob( ) fails. This allows glob( ) to report 18960 partial results in the event of an error. However, if gl_pathc is 0, gl_pathv is unspecified even if 18961 glob( ) did not return an error. 18962 The GLOB_NOCHECK option could be used when an application wants to expand a pathname | 18963 if wildcards are specified, but wants to treat the pattern as just a string otherwise. The sh utility | System Interfaces, Issue 6 1041 glob( ) System Interfaces 18964 might use this for option-arguments, for example. 18965 The new pathnames generated by a subsequent call with GLOB_APPEND are not sorted | 18966 together with the previous pathnames. This mirrors the way that the shell handles pathname | 18967 expansion when multiple expansions are done on a command line. | 18968 Applications that need tilde and parameter expansion should use wordexp( ). 18969 RATIONALE 18970 It was claimed that the GLOB_DOOFFS flag is unnecessary because it could be simulated using: 18971 new = (char **)malloc((n + pglob->gl_pathc + 1) 18972 * sizeof(char *)); 18973 (void) memcpy(new+n, pglob->gl_pathv, 18974 pglob->gl_pathc * sizeof(char *)); 18975 (void) memset(new, 0, n * sizeof(char *)); 18976 free(pglob->gl_pathv); 18977 pglob->gl_pathv = new; 18978 However, this assumes that the memory pointed to by gl_pathv is a block that was separately 18979 created using malloc( ). This is not necessarily the case. An application should make no 18980 assumptions about how the memory referenced by fields in pglob was allocated. It might have 18981 been obtained from malloc( ) in a large chunk and then carved up within glob( ), or it might have 18982 been created using a different memory allocator. It is not the intent of the standard developers to 18983 specify or imply how the memory used by glob( ) is managed. 18984 The GLOB_APPEND flag would be used when an application wants to expand several different 18985 patterns into a single list. 18986 FUTURE DIRECTIONS 18987 None. 18988 SEE ALSO 18989 exec, fnmatch( ), opendir( ), readdir( ), stat( ), wordexp( ), the Base Definitions volume of 18990 IEEE Std 1003.1-200x, , the Shell and Utilities volume of IEEE Std 1003.1-200x 18991 CHANGE HISTORY 18992 First released in Issue 4. Derived from the ISO POSIX-2 standard. 18993 Issue 5 18994 Moved from POSIX2 C-language Binding to BASE. 18995 Issue 6 18996 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 18997 The restrict keyword is added to the glob( ) prototype for alignment with the ISO/IEC 9899: 1999 18998 standard. 1042 Technical Standard (2001) (Draft April 16, 2001) System Interfaces gmtime( ) 18999 NAME 19000 gmtime, gmtime_r - convert a time value to a broken-down UTC time 19001 SYNOPSIS 19002 #include 19003 struct tm *gmtime(const time_t *timer); 19004 TSF struct tm *gmtime_r(const time_t *restrict timer, 19005 struct tm *restrict result); 19006 19007 DESCRIPTION 19008 CX For gmtime( ): The functionality described on this reference page is aligned with the ISO C 19009 standard. Any conflict between the requirements described here and the ISO C standard is 19010 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 19011 The gmtime( ) function shall convert the time in seconds since the Epoch pointed to by timer into 19012 a broken-down time, expressed as Coordinated Universal Time (UTC). 19013 CX The relationship between a time in seconds since the Epoch used as an argument to gmtime( ) | 19014 and the tm structure (defined in the header) is that the result shall be as specified in the | 19015 expression given in the definition of seconds since the Epoch (see the Base Definitions volume of | 19016 IEEE Std 1003.1-200x, Section 4.14, Seconds Since the Epoch), where the names in the structure | 19017 and in the expression correspond. | 19018 TSF The same relationship shall apply for gmtime_r( ). | 19019 CX The gmtime( ) function need not be reentrant. A function that is not required to be reentrant is not | 19020 required to be thread-safe. | 19021 The asctime( ), ctime( ), gmtime( ), and localtime( ) functions shall return values in one of two static | 19022 objects: a broken-down time structure and an array of type char. Execution of any of the | 19023 functions may overwrite the information returned in either of these objects by any of the other | 19024 functions. | 19025 TSF The gmtime_r( ) function shall convert the time in seconds since the Epoch pointed to by timer 19026 into a broken-down time expressed as Coordinated Universal Time (UTC). The broken-down 19027 time is stored in the structure referred to by result. The gmtime_r( ) function shall also return the 19028 address of the same structure. 19029 RETURN VALUE 19030 The gmtime( ) function shall return a pointer to a struct tm. 19031 TSF Upon successful completion, gmtime_r( ) shall return the address of the structure pointed to by 19032 the argument result. If an error is detected, or UTC is not available, gmtime_r( ) shall return a null 19033 pointer. 19034 ERRORS 19035 No errors are defined. System Interfaces, Issue 6 1043 gmtime( ) System Interfaces 19036 EXAMPLES 19037 None. 19038 APPLICATION USAGE 19039 The gmtime_r( ) function is thread-safe and returns values in a user-supplied buffer instead of | 19040 possibly using a static data area that may be overwritten by each call. 19041 RATIONALE 19042 None. 19043 FUTURE DIRECTIONS 19044 None. 19045 SEE ALSO 19046 asctime( ), clock( ), ctime( ), difftime( ), localtime( ), mktime( ), strftime( ), strptime( ), time( ), utime( ), 19047 the Base Definitions volume of IEEE Std 1003.1-200x, 19048 CHANGE HISTORY 19049 First released in Issue 1. Derived from Issue 1 of the SVID. 19050 Issue 5 19051 A note indicating that the gmtime( ) function need not be reentrant is added to the 19052 DESCRIPTION. 19053 The gmtime_r( ) function is included for alignment with the POSIX Threads Extension. 19054 Issue 6 19055 The gmtime_r( ) function is marked as part of the Thread-Safe Functions option. 19056 Extensions beyond the ISO C standard are now marked. 19057 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 19058 its avoidance of possibly using a static data area. 19059 The restrict keyword is added to the gmtime_r( ) prototype for alignment with the 19060 ISO/IEC 9899: 1999 standard. 1044 Technical Standard (2001) (Draft April 16, 2001) System Interfaces grantpt( ) 19061 NAME 19062 grantpt - grant access to the slave pseudo-terminal device 19063 SYNOPSIS 19064 XSI #include 19065 int grantpt(int fildes); 19066 19067 DESCRIPTION 19068 The grantpt( ) function shall change the mode and ownership of the slave pseudo-terminal 19069 device associated with its master pseudo-terminal counterpart. The fildes argument is a file 19070 descriptor that refers to a master pseudo-terminal device. The user ID of the slave shall be set to 19071 the real UID of the calling process and the group ID shall be set to an unspecified group ID. The 19072 permission mode of the slave pseudo-terminal shall be set to readable and writable by the 19073 owner, and writable by the group. 19074 The behavior of the grantpt( ) function is unspecified if the application has installed a signal 19075 handler to catch SIGCHLD signals. 19076 RETURN VALUE 19077 Upon successful completion, grantpt( ) shall return 0; otherwise, it shall return -1 and set errno to 19078 indicate the error. 19079 ERRORS 19080 The grantpt( ) function may fail if: 19081 [EBADF] The fildes argument is not a valid open file descriptor. 19082 [EINVAL] The fildes argument is not associated with a master pseudo-terminal device. 19083 [EACCES] The corresponding slave pseudo-terminal device could not be accessed. 19084 EXAMPLES 19085 None. 19086 APPLICATION USAGE 19087 None. 19088 RATIONALE 19089 None. 19090 FUTURE DIRECTIONS 19091 None. 19092 SEE ALSO 19093 open( ), ptsname( ), unlockpt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19094 CHANGE HISTORY 19095 First released in Issue 4, Version 2. 19096 Issue 5 19097 Moved from X/OPEN UNIX extension to BASE. 19098 The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section in 19099 previous issues. System Interfaces, Issue 6 1045 h_errno System Interfaces 19100 NAME 19101 h_errno - error return value for network database operations 19102 SYNOPSIS 19103 OB #include 19104 19105 DESCRIPTION 19106 Note that this method of returning errors is used only in connection with obsolescent functions. 19107 The header provides a declaration of h_errno as a modifiable l-value of type int. 19108 It is unspecified whether h_errno is a macro or an identifier declared with external linkage. If a 19109 macro definition is suppressed in order to access an actual object, or a program defines an 19110 identifier with the name h_errno, the behavior is undefined. 19111 RETURN VALUE 19112 None. 19113 ERRORS 19114 No errors are defined. 19115 EXAMPLES 19116 None. 19117 APPLICATION USAGE 19118 Applications should obtain the definition of h_errno by the inclusion of the header. 19119 RATIONALE 19120 None. 19121 FUTURE DIRECTIONS 19122 h_errno may be withdrawn in a future version. 19123 SEE ALSO 19124 endhostent( ), errno, the Base Definitions volume of IEEE Std 1003.1-200x, 19125 CHANGE HISTORY 19126 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1046 Technical Standard (2001) (Draft April 16, 2001) System Interfaces hcreate( ) 19127 NAME 19128 hcreate, hdestroy, hsearch - manage hash search table 19129 SYNOPSIS 19130 XSI #include 19131 int hcreate(size_t nel); 19132 void hdestroy(void); 19133 ENTRY *hsearch(ENTRY item, ACTION action); 19134 19135 DESCRIPTION 19136 The hcreate( ), hdestroy( ), and hsearch( ) functions shall manage hash search tables. | 19137 The hcreate( ) function shall allocate sufficient space for the table, and the application shall | 19138 ensure it is called before hsearch( ) is used. The nel argument is an estimate of the maximum | 19139 number of entries that the table shall contain. This number may be adjusted upward by the 19140 algorithm in order to obtain certain mathematically favorable circumstances. 19141 The hdestroy( ) function shall dispose of the search table, and may be followed by another call to | 19142 hcreate( ). After the call to hdestroy( ), the data can no longer be considered accessible. 19143 The hsearch( ) function is a hash-table search routine. It shall return a pointer into a hash table 19144 indicating the location at which an entry can be found. The item argument is a structure of type 19145 ENTRY (defined in the header) containing two pointers: item.key points to the 19146 comparison key (a char *), and item.data (a void *) points to any other data to be associated with 19147 that key. The comparison function used by hsearch( ) is strcmp( ). The action argument is a 19148 member of an enumeration type ACTION indicating the disposition of the entry if it cannot be 19149 found in the table. ENTER indicates that the item should be inserted in the table at an 19150 appropriate point. FIND indicates that no entry should be made. Unsuccessful resolution is 19151 indicated by the return of a null pointer. 19152 These functions need not be reentrant. A function that is not required to be reentrant is not 19153 required to be thread-safe. 19154 RETURN VALUE 19155 The hcreate( ) function shall return 0 if it cannot allocate sufficient space for the table; otherwise, 19156 it shall return non-zero. 19157 The hdestroy( ) function shall not return a value. 19158 The hsearch( ) function shall return a null pointer if either the action is FIND and the item could 19159 not be found or the action is ENTER and the table is full. 19160 ERRORS 19161 The hcreate( ) and hsearch( ) functions may fail if: 19162 [ENOMEM] Insufficient storage space is available. 19163 EXAMPLES 19164 The following example reads in strings followed by two numbers and stores them in a hash 19165 table, discarding duplicates. It then reads in strings and finds the matching entry in the hash 19166 table and prints it out. 19167 #include 19168 #include 19169 #include 19170 struct info { /* This is the info stored in the table */ 19171 int age, room; /* other than the key. */ System Interfaces, Issue 6 1047 hcreate( ) System Interfaces 19172 }; 19173 #define NUM_EMPL 5000 /* # of elements in search table. */ 19174 int main(void) 19175 { 19176 char string_space[NUM_EMPL*20]; /* Space to store strings. */ 19177 struct info info_space[NUM_EMPL]; /* Space to store employee info. */ 19178 char *str_ptr = string_space; /* Next space in string_space. */ 19179 struct info *info_ptr = info_space; 19180 /* Next space in info_space. */ 19181 ENTRY item; 19182 ENTRY *found_item; /* Name to look for in table. */ 19183 char name_to_find[30]; 19184 int i = 0; 19185 /* Create table; no error checking is performed. */ 19186 (void) hcreate(NUM_EMPL); 19187 while (scanf("%s%d%d", str_ptr, &info_ptr->age, 19188 &info_ptr->room) != EOF && i++ < NUM_EMPL) { 19189 /* Put information in structure, and structure in item. */ 19190 item.key = str_ptr; 19191 item.data = info_ptr; 19192 str_ptr += strlen(str_ptr) + 1; 19193 info_ptr++; 19194 /* Put item into table. */ 19195 (void) hsearch(item, ENTER); 19196 } 19197 /* Access table. */ 19198 item.key = name_to_find; 19199 while (scanf("%s", item.key) != EOF) { 19200 if ((found_item = hsearch(item, FIND)) != NULL) { 19201 /* If item is in the table. */ 19202 (void)printf("found %s, age = %d, room = %d\n", 19203 found_item->key, 19204 ((struct info *)found_item->data)->age, 19205 ((struct info *)found_item->data)->room); 19206 } else 19207 (void)printf("no such employee %s\n", name_to_find); 19208 } 19209 return 0; 19210 } 19211 APPLICATION USAGE 19212 The hcreate( ) and hsearch( ) functions may use malloc( ) to allocate space. 19213 RATIONALE 19214 None. 1048 Technical Standard (2001) (Draft April 16, 2001) System Interfaces hcreate( ) 19215 FUTURE DIRECTIONS 19216 None. 19217 SEE ALSO 19218 bsearch( ), lsearch( ), malloc( ), strcmp( ), tsearch( ), the Base Definitions volume of 19219 IEEE Std 1003.1-200x, 19220 CHANGE HISTORY 19221 First released in Issue 1. Derived from Issue 1 of the SVID. 19222 Issue 6 19223 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 19224 A note indicating that this function need not be reentrant is added to the DESCRIPTION. System Interfaces, Issue 6 1049 hdestroy( ) System Interfaces 19225 NAME 19226 hdestroy - manage hash search table 19227 SYNOPSIS 19228 XSI #include 19229 void hdestroy(void); 19230 19231 DESCRIPTION 19232 Refer to hcreate( ). 1050 Technical Standard (2001) (Draft April 16, 2001) System Interfaces hsearch( ) 19233 NAME 19234 hsearch - manage hash search table 19235 SYNOPSIS 19236 XSI #include 19237 ENTRY *hsearch(ENTRY item, ACTION action); 19238 19239 DESCRIPTION 19240 Refer to hcreate( ). System Interfaces, Issue 6 1051 htonl( ) System Interfaces 19241 NAME 19242 htonl, htons, ntohl, ntohs - convert values between host and network byte order 19243 SYNOPSIS 19244 #include 19245 uint32_t htonl(uint32_t hostlong); 19246 uint16_t htons(uint16_t hostshort); 19247 uint32_t ntohl(uint32_t netlong); 19248 uint16_t ntohs(uint16_t netshort); 19249 DESCRIPTION 19250 These functions shall convert 16-bit and 32-bit quantities between network byte order and host 19251 byte order. 19252 On some implementations, these functions are defined as macros. 19253 The uint32_t and uint16_t types are defined in . | 19254 RETURN VALUE 19255 The htonl( ) and htons( ) functions shall return the argument value converted from host to 19256 network byte order. 19257 The ntohl( ) and ntohs( ) functions shall return the argument value converted from network to 19258 host byte order. 19259 ERRORS 19260 No errors are defined. 19261 EXAMPLES 19262 None. 19263 APPLICATION USAGE 19264 These functions are most often used in conjunction with IPv4 addresses and ports as returned by 19265 gethostent( ) and getservent( ). 19266 RATIONALE 19267 None. 19268 FUTURE DIRECTIONS 19269 None. 19270 SEE ALSO 19271 endhostent( ), endservent( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 19272 19273 CHANGE HISTORY 19274 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1052 Technical Standard (2001) (Draft April 16, 2001) System Interfaces htons( ) 19275 NAME 19276 htons - convert values between host and network byte order 19277 SYNOPSIS 19278 #include 19279 uint16_t htons(uint16_t hostshort); 19280 DESCRIPTION 19281 Refer to htonl( ). System Interfaces, Issue 6 1053 hypot( ) System Interfaces 19282 NAME 19283 hypot, hypotf, hypotl - Euclidean distance function 19284 SYNOPSIS 19285 #include 19286 double hypot(double x, double y); 19287 float hypotf(float x, float y); 19288 long double hypotl(long double x, long double y); 19289 DESCRIPTION 19290 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19291 conflict between the requirements described here and the ISO C standard is unintentional. This 19292 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 19293 These functions shall compute the value of the square root of x2+y2 without undue overflow or | 19294 underflow. | 19295 An application wishing to check for error situations should set errno to zero and call 19296 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 19297 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 19298 zero, an error has occurred. 19299 RETURN VALUE 19300 Upon successful completion, these functions shall return the length of the hypotenuse of a 19301 right-angled triangle with sides of length x and y. 19302 If the correct value would cause overflow, a range error shall occur and hypot( ), hypotf( ), and 19303 hypotl( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 19304 respectively. 19305 MX If x or y is ±Inf, +Inf shall be returned (even if one of x or y is NaN). 19306 If x or y is NaN, and the other is not ±Inf, a NaN shall be returned. 19307 If both arguments are subnormal and the correct result is subnormal, a range error may occur 19308 and the correct result is returned. 19309 ERRORS 19310 These functions shall fail if: 19311 Range Error The result overflows. 19312 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 19313 then errno shall be set to [ERANGE]. If the integer expression | 19314 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 19315 floating-point exception shall be raised. | 19316 These functions may fail if: 19317 MX Range Error The result underflows. 19318 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 19319 then errno shall be set to [ERANGE]. If the integer expression | 19320 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 19321 floating-point exception shall be raised. | 1054 Technical Standard (2001) (Draft April 16, 2001) System Interfaces hypot( ) 19322 EXAMPLES 19323 None. 19324 APPLICATION USAGE 19325 hypot(x,y), hypot(y,x), and hypot(x, -y) are equivalent. 19326 hypot(x, ±0) is equivalent to fabs(x). 19327 Underflow only happens when both x and y are subnormal and the (inexact) result is also 19328 subnormal. 19329 These functions take precautions against overflow during intermediate steps of the 19330 computation. 19331 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 19332 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 19333 RATIONALE 19334 None. 19335 FUTURE DIRECTIONS 19336 None. 19337 SEE ALSO 19338 feclearexcept( ), fetestexcept( ), isnan( ), sqrt( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 19339 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 19340 CHANGE HISTORY 19341 First released in Issue 1. Derived from Issue 1 of the SVID. 19342 Issue 5 19343 The DESCRIPTION is updated to indicate how an application should check for an error. This 19344 text was previously published in the APPLICATION USAGE section. 19345 Issue 6 19346 The hypot( ) function is no longer marked as an extension. 19347 The hypotf( ) and hypotl( ) functions are added for alignment with the ISO/IEC 9899: 1999 19348 standard. 19349 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 19350 revised to align with the ISO/IEC 9899: 1999 standard. 19351 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 19352 marked. System Interfaces, Issue 6 1055 iconv( ) System Interfaces 19353 NAME 19354 iconv - codeset conversion function 19355 SYNOPSIS 19356 XSI #include 19357 size_t iconv(iconv_t cd, char **restrict inbuf, 19358 size_t *restrict inbytesleft, char **restrict outbuf, 19359 size_t *restrict outbytesleft); 19360 19361 DESCRIPTION 19362 The iconv( ) function shall convert the sequence of characters from one codeset, in the array 19363 specified by inbuf, into a sequence of corresponding characters in another codeset, in the array 19364 specified by outbuf. The codesets are those specified in the iconv_open( ) call that returned the 19365 conversion descriptor, cd. The inbuf argument points to a variable that points to the first 19366 character in the input buffer and inbytesleft indicates the number of bytes to the end of the buffer 19367 to be converted. The outbuf argument points to a variable that points to the first available byte in 19368 the output buffer and outbytesleft indicates the number of the available bytes to the end of the 19369 buffer. 19370 For state-dependent encodings, the conversion descriptor cd is placed into its initial shift state by 19371 a call for which inbuf is a null pointer, or for which inbuf points to a null pointer. When iconv( ) is 19372 called in this way, and if outbuf is not a null pointer or a pointer to a null pointer, and outbytesleft 19373 points to a positive value, iconv( ) shall place, into the output buffer, the byte sequence to change 19374 the output buffer to its initial shift state. If the output buffer is not large enough to hold the 19375 entire reset sequence, iconv( ) shall fail and set errno to [E2BIG]. Subsequent calls with inbuf as 19376 other than a null pointer or a pointer to a null pointer cause the conversion to take place from 19377 the current state of the conversion descriptor. 19378 If a sequence of input bytes does not form a valid character in the specified codeset, conversion | 19379 shall stop after the previous successfully converted character. If the input buffer ends with an | 19380 incomplete character or shift sequence, conversion shall stop after the previous successfully | 19381 converted bytes. If the output buffer is not large enough to hold the entire converted input, | 19382 conversion shall stop just prior to the input bytes that would cause the output buffer to | 19383 overflow. The variable pointed to by inbuf shall be updated to point to the byte following the last | 19384 byte successfully used in the conversion. The value pointed to by inbytesleft shall be | 19385 decremented to reflect the number of bytes still not converted in the input buffer. The variable | 19386 pointed to by outbuf shall be updated to point to the byte following the last byte of converted | 19387 output data. The value pointed to by outbytesleft shall be decremented to reflect the number of | 19388 bytes still available in the output buffer. For state-dependent encodings, the conversion | 19389 descriptor shall be updated to reflect the shift state in effect at the end of the last successfully | 19390 converted byte sequence. 19391 If iconv( ) encounters a character in the input buffer that is valid, but for which an identical 19392 character does not exist in the target codeset, iconv( ) shall perform an implementation-defined | 19393 conversion on this character. | 19394 RETURN VALUE 19395 The iconv( ) function shall update the variables pointed to by the arguments to reflect the extent 19396 of the conversion and return the number of non-identical conversions performed. If the entire 19397 string in the input buffer is converted, the value pointed to by inbytesleft shall be 0. If the input 19398 conversion is stopped due to any conditions mentioned above, the value pointed to by inbytesleft 19399 shall be non-zero and errno shall be set to indicate the condition. If an error occurs iconv( ) shall 19400 return (size_t)-1 and set errno to indicate the error. 1056 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iconv( ) 19401 ERRORS 19402 The iconv( ) function shall fail if: 19403 [EILSEQ] Input conversion stopped due to an input byte that does not belong to the 19404 input codeset. 19405 [E2BIG] Input conversion stopped due to lack of space in the output buffer. 19406 [EINVAL] Input conversion stopped due to an incomplete character or shift sequence at 19407 the end of the input buffer. 19408 The iconv( ) function may fail if: 19409 [EBADF] The cd argument is not a valid open conversion descriptor. 19410 EXAMPLES 19411 None. 19412 APPLICATION USAGE 19413 The inbuf argument indirectly points to the memory area which contains the conversion input 19414 data. The outbuf argument indirectly points to the memory area which is to contain the result of 19415 the conversion. The objects indirectly pointed to by inbuf and outbuf are not restricted to 19416 containing data that is directly representable in the ISO C standard language char data type. The 19417 type of inbuf and outbuf, char **, does not imply that the objects pointed to are interpreted as 19418 null-terminated C strings or arrays of characters. Any interpretation of a byte sequence that 19419 represents a character in a given character set encoding scheme is done internally within the 19420 codeset converters. For example, the area pointed to indirectly by inbuf and/or outbuf can 19421 contain all zero octets that are not interpreted as string terminators but as coded character data 19422 according to the respective codeset encoding scheme. The type of the data (char, short, long, and 19423 so on) read or stored in the objects is not specified, but may be inferred for both the input and 19424 output data by the converters determined by the fromcode and tocode arguments of iconv_open( ). 19425 Regardless of the data type inferred by the converter, the size of the remaining space in both 19426 input and output objects (the intbytesleft and outbytesleft arguments) is always measured in bytes. 19427 For implementations that support the conversion of state-dependent encodings, the conversion 19428 descriptor must be able to accurately reflect the shift-state in effect at the end of the last 19429 successful conversion. It is not required that the conversion descriptor itself be updated, which 19430 would require it to be a pointer type. Thus, implementations are free to implement the 19431 descriptor as a handle (other than a pointer type) by which the conversion information can be 19432 accessed and updated. 19433 RATIONALE 19434 None. 19435 FUTURE DIRECTIONS 19436 None. 19437 SEE ALSO 19438 iconv_open( ), iconv_close( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19439 CHANGE HISTORY 19440 First released in Issue 4. Derived from the HP-UX Manual. 19441 Issue 6 19442 The SYNOPSIS has been corrected to align with the reference page. 19443 The restrict keyword is added to the iconv( ) prototype for alignment with the 19444 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1057 iconv_close( ) System Interfaces 19445 NAME 19446 iconv_close - codeset conversion deallocation function 19447 SYNOPSIS 19448 XSI #include 19449 int iconv_close(iconv_t cd); 19450 19451 DESCRIPTION 19452 The iconv_close( ) function shall deallocate the conversion descriptor cd and all other associated | 19453 resources allocated by iconv_open( ). 19454 If a file descriptor is used to implement the type iconv_t, that file descriptor shall be closed. | 19455 RETURN VALUE 19456 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 19457 indicate the error. 19458 ERRORS 19459 The iconv_close( ) function may fail if: 19460 [EBADF] The conversion descriptor is invalid. 19461 EXAMPLES 19462 None. 19463 APPLICATION USAGE 19464 None. 19465 RATIONALE 19466 None. 19467 FUTURE DIRECTIONS 19468 None. 19469 SEE ALSO 19470 iconv( ), iconv_open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19471 CHANGE HISTORY 19472 First released in Issue 4. Derived from the HP-UX Manual. 1058 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iconv_open( ) 19473 NAME 19474 iconv_open - codeset conversion allocation function 19475 SYNOPSIS 19476 XSI #include 19477 iconv_t iconv_open(const char *tocode, const char *fromcode); 19478 19479 DESCRIPTION 19480 The iconv_open( ) function shall return a conversion descriptor that describes a conversion from 19481 the codeset specified by the string pointed to by the fromcode argument to the codeset specified 19482 by the string pointed to by the tocode argument. For state-dependent encodings, the conversion 19483 descriptor shall be in a codeset-dependent initial shift state, ready for immediate use with | 19484 iconv( ). 19485 Settings of fromcode and tocode and their permitted combinations are implementation-defined. 19486 A conversion descriptor shall remain valid until it is closed by iconv_close( ) or an implicit close. | 19487 If a file descriptor is used to implement conversion descriptors, the FD_CLOEXEC flag shall be 19488 set; see . 19489 RETURN VALUE 19490 Upon successful completion, iconv_open( ) shall return a conversion descriptor for use on 19491 subsequent calls to iconv( ). Otherwise, iconv_open( ) shall return (iconv_t)-1 and set errno to 19492 indicate the error. 19493 ERRORS 19494 The iconv_open( ) function may fail if: 19495 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 19496 [ENFILE] Too many files are currently open in the system. 19497 [ENOMEM] Insufficient storage space is available. 19498 [EINVAL] The conversion specified by fromcode and tocode is not supported by the 19499 implementation. 19500 EXAMPLES 19501 None. 19502 APPLICATION USAGE 19503 Some implementations of iconv_open( ) use malloc( ) to allocate space for internal buffer areas. 19504 The iconv_open( ) function may fail if there is insufficient storage space to accommodate these 19505 buffers. 19506 Conforming applications must assume that conversion descriptors are not valid after a call to | 19507 one of the exec functions. 19508 RATIONALE 19509 None. 19510 FUTURE DIRECTIONS 19511 None. 19512 SEE ALSO 19513 iconv( ), iconv_close( ), the Base Definitions volume of IEEE Std 1003.1-200x, , System Interfaces, Issue 6 1059 iconv_open( ) System Interfaces 19514 CHANGE HISTORY 19515 First released in Issue 4. Derived from the HP-UX Manual. 1060 Technical Standard (2001) (Draft April 16, 2001) System Interfaces if_freenameindex( ) 19516 NAME 19517 if_freenameindex - free memory allocated by if_nameindex( ) 19518 SYNOPSIS 19519 #include 19520 void if_freenameindex(struct if_nameindex *ptr); 19521 DESCRIPTION 19522 The if_freenameindex( ) function shall free the memory allocated by if_nameindex( ). The ptr 19523 argument shall be a pointer that was returned by if_nameindex( ). After if_freenameindex( ) has | 19524 been called, the application shall not use the array of which ptr is the address. | 19525 RETURN VALUE 19526 None. 19527 ERRORS 19528 No errors are defined. 19529 EXAMPLES 19530 None. 19531 APPLICATION USAGE 19532 None. 19533 RATIONALE 19534 None. 19535 FUTURE DIRECTIONS 19536 None. 19537 SEE ALSO 19538 getsockopt( ), if_indextoname( ), if_nameindex( ), if_nametoindex( ), setsockopt( ), the Base Definitions 19539 volume of IEEE Std 1003.1-200x, 19540 CHANGE HISTORY 19541 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1061 if_indextoname( ) System Interfaces 19542 NAME 19543 if_indextoname - map a network interface index to its corresponding name 19544 SYNOPSIS 19545 #include 19546 char *if_indextoname(unsigned ifindex, char *ifname); 19547 DESCRIPTION 19548 The if_indextoname( ) function shall map an interface index to its corresponding name. 19549 When this function is called, ifname shall point to a buffer of at least {IFNAMSIZ} bytes. The 19550 function shall place in this buffer the name of the interface with index ifindex. 19551 RETURN VALUE 19552 If ifindex is an interface index, then the function shall return the value supplied in ifname, which 19553 points to a buffer now containing the interface name. Otherwise, the function shall return a 19554 NULL pointer and set errno to indicate the error. 19555 ERRORS 19556 The if_indextoname( ) function shall fail if: 19557 [ENXIO] The interface does not exist. 19558 EXAMPLES 19559 None. 19560 APPLICATION USAGE 19561 None. 19562 RATIONALE 19563 None. 19564 FUTURE DIRECTIONS 19565 None. 19566 SEE ALSO 19567 getsockopt( ), if_freenameindex( ), if_nameindex( ), if_nametoindex( ), setsockopt( ), the Base 19568 Definitions volume of IEEE Std 1003.1-200x, 19569 CHANGE HISTORY 19570 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1062 Technical Standard (2001) (Draft April 16, 2001) System Interfaces if_nameindex( ) 19571 NAME 19572 if_nameindex - return all network interface names and indexes 19573 SYNOPSIS 19574 #include 19575 struct if_nameindex *if_nameindex(void); 19576 DESCRIPTION 19577 The if_nameindex( ) function shall return an array of if_nameindex structures, one structure per 19578 interface. The end of the array is indicated by a structure with an if_index field of zero and an 19579 if_name field of NULL. 19580 Applications should call if_freenameindex( ) to release the memory that may be dynamically 19581 allocated by this function, after they have finished using it. 19582 RETURN VALUE 19583 Array of structures identifying local interfaces. A NULL pointer is returned upon an error, with 19584 errno set to indicate the error. 19585 ERRORS 19586 The if_nameindex( ) function may fail if: 19587 [ENOBUFS] Insufficient resources are available to complete the function. 19588 EXAMPLES 19589 None. 19590 APPLICATION USAGE 19591 None. 19592 RATIONALE 19593 None. 19594 FUTURE DIRECTIONS 19595 None. 19596 SEE ALSO 19597 getsockopt( ), if_freenameindex( ), if_indextoname( ), if_nametoindex( ), setsockopt( ), the Base 19598 Definitions volume of IEEE Std 1003.1-200x, 19599 CHANGE HISTORY 19600 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1063 if_nametoindex( ) System Interfaces 19601 NAME 19602 if_nametoindex - map a network interface name to its corresponding index 19603 SYNOPSIS 19604 #include 19605 unsigned if_nametoindex(const char *ifname); 19606 DESCRIPTION 19607 The if_nametoindex( ) function shall return the interface index corresponding to name ifname. 19608 RETURN VALUE 19609 The corresponding index if ifname is the name of an interface; otherwise, zero. 19610 ERRORS 19611 No errors are defined. 19612 EXAMPLES 19613 None. 19614 APPLICATION USAGE 19615 None. 19616 RATIONALE 19617 None. 19618 FUTURE DIRECTIONS 19619 None. 19620 SEE ALSO 19621 getsockopt( ), if_freenameindex( ), if_indextoname( ), if_nameindex( ), setsockopt( ), the Base 19622 Definitions volume of IEEE Std 1003.1-200x, 19623 CHANGE HISTORY 19624 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1064 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ilogb( ) 19625 NAME 19626 ilogb, ilogbf, ilogbl - return an unbiased exponent 19627 SYNOPSIS 19628 #include 19629 int ilogb(double x); 19630 int ilogbf(float x); 19631 int ilogbl(long double x); 19632 DESCRIPTION 19633 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19634 conflict between the requirements described here and the ISO C standard is unintentional. This 19635 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 19636 These functions shall return the exponent part of their argument x. Formally, the return value is 19637 the integral part of logr | x | as a signed integral value, for non-zero x, where r is the radix of the 19638 machine's floating-point arithmetic, which is the value of FLT_RADIX defined in . 19639 An application wishing to check for error situations should set errno to zero and call 19640 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 19641 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 19642 zero, an error has occurred. 19643 RETURN VALUE 19644 Upon successful completion, these functions shall return the exponent part of x as a signed 19645 integer value. They are equivalent to calling the corresponding logb( ) function and casting the 19646 returned value to type int. 19647 XSI If x is 0, a domain error shall occur, andthe value FP_ILOGB0 shall be returned. 19648 XSI If x is ±Inf, a domain error shall occur, andthe value {INT_MAX} shall be returned. 19649 XSI If x is a NaN, a domain error shall occur, andthe value FP_ILOGBNAN shall be returned. 19650 XSI If the correct value is greater than {INT_MAX}, {INT_MAX} shall be returned and a domain error | 19651 shall occur. 19652 If the correct value is less than {INT_MIN}, {INT_MIN} shall be returned and a domain error | 19653 shall occur. 19654 ERRORS 19655 These functions shall fail if: 19656 XSI Domain Error The x argument is zero, NaN, or ±Inf, or the correct value is not representable 19657 as an integer. 19658 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 19659 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 19660 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 19661 shall be raised. | System Interfaces, Issue 6 1065 ilogb( ) System Interfaces 19662 EXAMPLES 19663 None. 19664 APPLICATION USAGE 19665 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 19666 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 19667 RATIONALE 19668 The errors come from taking the expected floating-point value and converting it to int, which is 19669 invalid operation in IEEE Std 754-1985 (since overflow, infinity, and NaN are not representable 19670 in a type int), so should be a domain error. 19671 There are no known implementations that overflow. For overflow to happen, {INT_MAX} must 19672 be less than LDBL_MAX_EXP*log2(FLT_RADIX) or {INT_MIN} must be greater than 19673 LDBL_MIN_EXP*log2(FLT_RADIX) if subnormals are not supported, or {INT_MIN} must be 19674 greater than (LDBL_MIN_EXP-LDBL_MANT_DIG)*log2(FLT_RADIX) if subnormals are 19675 supported. 19676 FUTURE DIRECTIONS 19677 None. 19678 SEE ALSO 19679 feclearexcept( ), fetestexcept( ), logb( ), scalb( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 19680 Section 4.18, Treatment of Error Conditions for Mathematical Functions, , | 19681 CHANGE HISTORY 19682 First released in Issue 4, Version 2. 19683 Issue 5 19684 Moved from X/OPEN UNIX extension to BASE. 19685 Issue 6 19686 The ilogb( ) function is no longer marked as an extension. 19687 The ilogbf( ) and ilogbl( ) functions are added for alignment with the ISO/IEC 9899: 1999 19688 standard. 19689 The RETURN VALUE section is revised for alignment with the ISO/IEC 9899: 1999 standard. 19690 XSI extensions are marked. 1066 Technical Standard (2001) (Draft April 16, 2001) System Interfaces imaxabs( ) 19691 NAME 19692 imaxabs - return absolute value 19693 SYNOPSIS 19694 #include 19695 intmax_t imaxabs(intmax_t j); 19696 DESCRIPTION 19697 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19698 conflict between the requirements described here and the ISO C standard is unintentional. This 19699 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 19700 The imaxabs( ) function shall compute the absolute value of an integer j. If the result cannot be 19701 represented, the behavior is undefined. 19702 RETURN VALUE 19703 The imaxabs( ) function shall return the absolute value. 19704 ERRORS 19705 No errors are defined. 19706 EXAMPLES 19707 None. 19708 APPLICATION USAGE 19709 The absolute value of the most negative number cannot be represented in two's complement. 19710 RATIONALE 19711 None. 19712 FUTURE DIRECTIONS 19713 None. 19714 SEE ALSO 19715 imaxdiv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19716 CHANGE HISTORY 19717 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1067 imaxdiv( ) System Interfaces 19718 NAME 19719 imaxdiv - return quotient and remainder 19720 SYNOPSIS 19721 #include 19722 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom); 19723 DESCRIPTION 19724 CX The functionality described on this reference page is aligned with the ISO C standard. Any 19725 conflict between the requirements described here and the ISO C standard is unintentional. This 19726 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 19727 The imaxdiv( ) function shall compute numer / denom and numer % denom in a single operation. 19728 RETURN VALUE 19729 The imaxdiv( ) function shall return a structure of type imaxdiv_t, comprising both the quotient 19730 and the remainder. The structure shall contain (in either order) the members quot (the quotient) 19731 and rem (the remainder), each of which has type intmax_t. 19732 If either part of the result cannot be represented, the behavior is undefined. 19733 ERRORS 19734 No errors are defined. 19735 EXAMPLES 19736 None. 19737 APPLICATION USAGE 19738 None. 19739 RATIONALE 19740 None. 19741 FUTURE DIRECTIONS 19742 None. 19743 SEE ALSO 19744 imaxabs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19745 CHANGE HISTORY 19746 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1068 Technical Standard (2001) (Draft April 16, 2001) System Interfaces index( ) 19747 NAME 19748 index - character string operations (LEGACY) 19749 SYNOPSIS 19750 XSI #include 19751 char *index(const char *s, int c); 19752 19753 DESCRIPTION 19754 The index( ) function shall be equivalent to strchr( ). | 19755 RETURN VALUE 19756 See strchr( ). 19757 ERRORS 19758 See strchr( ). 19759 EXAMPLES 19760 None. 19761 APPLICATION USAGE 19762 strchr( ) is preferred over this function. 19763 For maximum portability, it is recommended to replace the function call to index( ) as follows: 19764 #define index(a,b) strchr((a),(b)) 19765 RATIONALE 19766 None. 19767 FUTURE DIRECTIONS 19768 This function may be withdrawn in a future version. 19769 SEE ALSO 19770 strchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19771 CHANGE HISTORY 19772 First released in Issue 4, Version 2. 19773 Issue 5 19774 Moved from X/OPEN UNIX extension to BASE. 19775 Issue 6 19776 This function is marked LEGACY. System Interfaces, Issue 6 1069 inet_addr( ) System Interfaces 19777 NAME 19778 inet_addr, inet_ntoa - IPv4 address manipulation 19779 SYNOPSIS 19780 #include 19781 in_addr_t inet_addr(const char *cp); 19782 char *inet_ntoa(struct in_addr in); 19783 DESCRIPTION 19784 The inet_addr( ) function shall convert the string pointed to by cp, in the standard IPv4 dotted 19785 decimal notation, to an integer value suitable for use as an Internet address. 19786 The inet_ntoa( ) function shall convert the Internet host address specified by in to a string in the 19787 Internet standard dot notation. 19788 The inet_ntoa( ) function need not be reentrant. A function that is not required to be reentrant is 19789 not required to be thread-safe. 19790 All Internet addresses shall be returned in network order (bytes ordered from left to right). 19791 Values specified using IPv4 dotted decimal notation take one of the following forms: 19792 a.b.c.d When four parts are specified, each shall be interpreted as a byte of data and | 19793 assigned, from left to right, to the four bytes of an Internet address. | 19794 a.b.c When a three-part address is specified, the last part shall be interpreted as a 16-bit | 19795 quantity and placed in the rightmost two bytes of the network address. This makes | 19796 the three-part address format convenient for specifying Class B network addresses | 19797 as 128.net.host. | 19798 a.b When a two-part address is supplied, the last part shall be interpreted as a 24-bit | 19799 quantity and placed in the rightmost three bytes of the network address. This | 19800 makes the two-part address format convenient for specifying Class A network | 19801 addresses as net.host. 19802 a When only one part is given, the value shall be stored directly in the network | 19803 address without any byte rearrangement. 19804 All numbers supplied as parts in IPv4 dotted decimal notation may be decimal, octal, or 19805 hexadecimal, as specified in the ISO C standard (that is, a leading 0x or 0X implies hexadecimal; 19806 otherwise, a leading '0' implies octal; otherwise, the number is interpreted as decimal). 19807 RETURN VALUE 19808 Upon successful completion, inet_addr( ) shall return the Internet address. Otherwise, it shall 19809 return (in_addr_t)(-1). 19810 The inet_ntoa( ) function shall return a pointer to the network address in Internet standard dot 19811 notation. 19812 ERRORS 19813 No errors are defined. 1070 Technical Standard (2001) (Draft April 16, 2001) System Interfaces inet_addr( ) 19814 EXAMPLES 19815 None. 19816 APPLICATION USAGE 19817 The return value of inet_ntoa( ) may point to static data that may be overwritten by subsequent 19818 calls to inet_ntoa( ). 19819 RATIONALE 19820 None. 19821 FUTURE DIRECTIONS 19822 None. 19823 SEE ALSO 19824 endhostent( ), endnetent( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19825 CHANGE HISTORY 19826 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1071 inet_ntoa( ) System Interfaces 19827 NAME 19828 inet_ntoa - IPv4 address manipulation 19829 SYNOPSIS 19830 #include 19831 char *inet_ntoa(struct in_addr in); 19832 DESCRIPTION 19833 Refer to inet_addr( ). 1072 Technical Standard (2001) (Draft April 16, 2001) System Interfaces inet_ntop( ) 19834 NAME 19835 inet_ntop, inet_pton - convert IPv4 and IPv6 addresses between binary and text form 19836 SYNOPSIS 19837 #include 19838 const char *inet_ntop(int af, const void *restrict src, 19839 char *restrict dst, socklen_t size); 19840 int inet_pton(int af, const char *restrict src, void *restrict dst); 19841 DESCRIPTION 19842 The inet_ntop( ) function shall convert a numeric address into a text string suitable for | 19843 IP6 presentation. The af argument shall specify the family of the address. This can be AF_INET or | 19844 AF_INET6. The src argument points to a buffer holding an IPv4 address if the af argument is 19845 IP6 AF_INET, or an IPv6 address if the af argument is AF_INET6. The dst argument points to a 19846 buffer where the function stores the resulting text string; it shall not be NULL. The size argument 19847 specifies the size of this buffer, which shall be large enough to hold the text string 19848 IP6 (INET_ADDRSTRLEN characters for IPv4, INET6_ADDRSTRLEN characters for IPv6). 19849 The inet_pton( ) function shall convert an address in its standard text presentation form into its | 19850 IP6 numeric binary form. The af argument shall specify the family of the address. The AF_INET and | 19851 AF_INET6 address families shall be supported. The src argument points to the string being | 19852 passed in. The dst argument points to a buffer into which the function stores the numeric 19853 IP6 address; this shall be large enough to hold the numeric address (32 bits for AF_INET, 128 bits for 19854 AF_INET6). 19855 If the af argument of inet_pton( ) is AF_INET, the src string shall be in the standard IPv4 dotted- 19856 decimal form: 19857 ddd.ddd.ddd.ddd 19858 where "ddd" is a one to three digit decimal number between 0 and 255 (see inet_addr( )). The 19859 inet_pton( ) function does not accept other formats (such as the octal numbers, hexadecimal 19860 numbers, and fewer than four numbers that inet_addr( ) accepts). 19861 IP6 If the af argument of inet_pton( ) is AF_INET6, the src string shall be in one of the following 19862 standard IPv6 text forms: 19863 1. The preferred form is "x:x:x:x:x:x:x:x", where the 'x's are the hexadecimal values 19864 of the eight 16-bit pieces of the address. Leading zeros in individual fields can be omitted, 19865 but there shall be at least one numeral in every field. 19866 2. A string of contiguous zero fields in the preferred form can be shown as "::". The "::" 19867 can only appear once in an address. Unspecified addresses ("0:0:0:0:0:0:0:0") may 19868 be represented simply as "::". 19869 3. A third form that is sometimes more convenient when dealing with a mixed environment 19870 of IPv4 and IPv6 nodes is "x:x:x:x:x:x:d.d.d.d", where the 'x's are the 19871 hexadecimal values of the six high-order 16-bit pieces of the address, and the 'd's are the 19872 decimal values of the four low-order 8-bit pieces of the address (standard IPv4 19873 representation). 19874 Note: A more extensive description of the standard representations of IPv6 addresses can be found in 19875 RFC 2373. 19876 System Interfaces, Issue 6 1073 inet_ntop( ) System Interfaces 19877 RETURN VALUE 19878 The inet_ntop( ) function shall return a pointer to the buffer containing the text string if the 19879 conversion succeeds, and NULL otherwise, and set errno to indicate the error. 19880 The inet_pton( ) function shall return 1 if the conversion succeeds, with the address pointed to by 19881 IP6 dst in network byte order. It shall return 0 if the input is not a valid IPv4 dotted-decimal string or 19882 a valid IPv6 address string, or -1 with errno set to [EAFNOSUPPORT] if the af argument is 19883 unknown. 19884 ERRORS 19885 The inet_ntop( ) and inet_pton( ) functions shall fail if: 19886 [EAFNOSUPPORT] 19887 The af argument is invalid. 19888 [ENOSPC] The size of the inet_ntop( ) result buffer is inadequate. 19889 EXAMPLES 19890 None. 19891 APPLICATION USAGE 19892 None. 19893 RATIONALE 19894 None. 19895 FUTURE DIRECTIONS 19896 None. 19897 SEE ALSO 19898 The Base Definitions volume of IEEE Std 1003.1-200x, 19899 CHANGE HISTORY 19900 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 19901 IPv6 extensions are marked. 19902 The restrict keyword is added to the inet_ntop( ) and inet_pton( ) prototypes for alignment with 19903 the ISO/IEC 9899: 1999 standard. 1074 Technical Standard (2001) (Draft April 16, 2001) System Interfaces initstate( ) 19904 NAME 19905 initstate, random, setstate, srandom - pseudo-random number functions 19906 SYNOPSIS 19907 XSI #include 19908 char *initstate(unsigned seed, char *state, size_t size); 19909 long random(void); 19910 char *setstate(const char *state); 19911 void srandom(unsigned seed); 19912 19913 DESCRIPTION 19914 The random( ) function shall use a non-linear additive feedback random-number generator | 19915 employing a default state array size of 31 long integers to return successive pseudo-random | 19916 numbers in the range from 0 to 231-1. The period of this random-number generator is 19917 approximately 16 x (231-1). The size of the state array determines the period of the random- 19918 number generator. Increasing the state array size shall increase the period. | 19919 With 256 bytes of state information, the period of the random-number generator shall be greater | 19920 than 269. | 19921 Like rand( ), random( ) shall produce by default a sequence of numbers that can be duplicated by | 19922 calling srandom( ) with 1 as the seed. | 19923 The srandom( ) function shall initialize the current state array using the value of seed. | 19924 The initstate( ) and setstate( ) functions handle restarting and changing random-number 19925 generators. The initstate( ) function allows a state array, pointed to by the state argument, to be 19926 initialized for future use. The size argument, which specifies the size in bytes of the state array, | 19927 shall be used by initstate( ) to decide what type of random-number generator to use; the larger | 19928 the state array, the more random the numbers. Values for the amount of state information are 8, 19929 32, 64, 128, and 256 bytes. Other values greater than 8 bytes are rounded down to the nearest one 19930 of these values. If initstate( ) is called with 8 size<32, then random( ) shall use a simple linear | 19931 congruential random number generator. The seed argument specifies a starting point for the | 19932 random-number sequence and provides for restarting at the same point. The initstate( ) function 19933 shall return a pointer to the previous state information array. 19934 If initstate( ) has not been called, then random( ) shall behave as though initstate( ) had been called | 19935 with seed=1 and size=128. 19936 Once a state has been initialized, setstate( ) allows switching between state arrays. The array 19937 defined by the state argument shall be used for further random-number generation until | 19938 initstate( ) is called or setstate( ) is called again. The setstate( ) function shall return a pointer to the 19939 previous state array. 19940 RETURN VALUE 19941 If initstate( ) is called with size less than 8, it shall return NULL. 19942 The random( ) function shall return the generated pseudo-random number. 19943 The srandom( ) function shall not return a value. 19944 Upon successful completion, initstate( ) and setstate( ) shall return a pointer to the previous state 19945 array; otherwise, a null pointer shall be returned. System Interfaces, Issue 6 1075 initstate( ) System Interfaces 19946 ERRORS 19947 No errors are defined. 19948 EXAMPLES 19949 None. 19950 APPLICATION USAGE 19951 After initialization, a state array can be restarted at a different point in one of two ways: 19952 1. The initstate( ) function can be used, with the desired seed, state array, and size of the 19953 array. 19954 2. The setstate( ) function, with the desired state, can be used, followed by srandom( ) with the 19955 desired seed. The advantage of using both of these functions is that the size of the state 19956 array does not have to be saved once it is initialized. 19957 Although some implementations of random( ) have written messages to standard error, such 19958 implementations do not conform to this volume of IEEE Std 1003.1-200x. 19959 Issue 5 restores the historical behavior of this function. 19960 Threaded applications should use rand_r( ), erand48( ), nrand48( ), or jrand48( ) instead of 19961 random( ) when an independent random number sequence in multiple threads is required. 19962 RATIONALE 19963 None. 19964 FUTURE DIRECTIONS 19965 None. 19966 SEE ALSO 19967 drand48( ), rand( ), the Base Definitions volume of IEEE Std 1003.1-200x, 19968 CHANGE HISTORY 19969 First released in Issue 4, Version 2. 19970 Issue 5 19971 Moved from X/OPEN UNIX extension to BASE. 19972 In the DESCRIPTION, the phrase ``values smaller than 8'' is replaced with ``values greater than 19973 or equal to 8, or less than 32'', ``size<8'' is replaced with ``8 size <32'', and a new first paragraph 19974 is added to the RETURN VALUE section. A note is added to the APPLICATION USAGE 19975 indicating that these changes restore the historical behavior of the function. 19976 Issue 6 19977 In the DESCRIPTION, duplicate text ``For values greater than or equal to 8 . . .'' is removed. 1076 Technical Standard (2001) (Draft April 16, 2001) System Interfaces insque( ) 19978 NAME 19979 insque, remque - insert or remove an element in a queue 19980 SYNOPSIS 19981 XSI #include 19982 void insque(void *element, void *pred); 19983 void remque(void *element); 19984 19985 DESCRIPTION 19986 The insque( ) and remque( ) functions shall manipulate queues built from doubly-linked lists. The | 19987 queue can be either circular or linear. An application using insque( ) or remque( ) shall ensure it | 19988 defines a structure in which the first two members of the structure are pointers to the same type 19989 of structure, and any further members are application-specific. The first member of the structure 19990 is a forward pointer to the next entry in the queue. The second member is a backward pointer to 19991 the previous entry in the queue. If the queue is linear, the queue is terminated with null 19992 pointers. The names of the structure and of the pointer members are not subject to any special 19993 restriction. 19994 The insque( ) function shall insert the element pointed to by element into a queue immediately | 19995 after the element pointed to by pred. 19996 The remque( ) function shall remove the element pointed to by element from a queue. | 19997 If the queue is to be used as a linear list, invoking insque(&element, NULL), where element is the 19998 initial element of the queue, shall initialize the forward and backward pointers of element to null 19999 pointers. 20000 If the queue is to be used as a circular list, the application shall ensure it initializes the forward 20001 pointer and the backward pointer of the initial element of the queue to the element's own 20002 address. 20003 RETURN VALUE 20004 The insque( ) and remque( ) functions do not return a value. 20005 ERRORS 20006 No errors are defined. 20007 EXAMPLES 20008 Creating a Linear Linked List 20009 The following example creates a linear linked list. 20010 #include 20011 ... 20012 struct myque element1; 20013 struct myque element2; 20014 char *data1 = "DATA1"; 20015 char *data2 = "DATA2"; 20016 ... 20017 element1.data = data1; 20018 element2.data = data2; 20019 insque (&element1, NULL); 20020 insque (&element2, &element1); System Interfaces, Issue 6 1077 insque( ) System Interfaces 20021 Creating a Circular Linked List 20022 The following example creates a circular linked list. 20023 #include 20024 ... 20025 struct myque element1; 20026 struct myque element2; 20027 char *data1 = "DATA1"; 20028 char *data2 = "DATA2"; 20029 ... 20030 element1.data = data1; 20031 element2.data = data2; 20032 element1.fwd = &element1; 20033 element1.bck = &element1; 20034 insque (&element2, &element1); 20035 Removing an Element 20036 The following example removes the element pointed to by element1. 20037 #include 20038 ... 20039 struct myque element1; 20040 ... 20041 remque (&element1); 20042 APPLICATION USAGE 20043 The historical implementations of these functions described the arguments as being of type 20044 struct qelem * rather than as being of type void * as defined here. In those implementations, 20045 struct qelem was commonly defined in as: 20046 struct qelem { 20047 struct qelem *q_forw; 20048 struct qelem *q_back; 20049 }; 20050 Applications using these functions, however, were never able to use this structure directly since 20051 it provided no room for the actual data contained in the elements. Most applications defined 20052 structures that contained the two pointers as the initial elements and also provided space for, or 20053 pointers to, the object's data. Applications that used these functions to update more than one 20054 type of table also had the problem of specifying two or more different structures with the same 20055 name, if they literally used struct qelem as specified. 20056 As described here, the implementations were actually expecting a structure type where the first 20057 two members were forward and backward pointers to structures. With C compilers that didn't 20058 provide function prototypes, applications used structures as specified in the DESCRIPTION 20059 above and the compiler did what the application expected. 20060 If this method had been carried forward with an ISO C standard compiler and the historical 20061 function prototype, most applications would have to be modified to cast pointers to the 20062 structures actually used to be pointers to struct qelem to avoid compilation warnings. By 20063 specifying void * as the argument type, applications do not need to change (unless they 20064 specifically referenced struct qelem and depended on it being defined in ). 1078 Technical Standard (2001) (Draft April 16, 2001) System Interfaces insque( ) 20065 RATIONALE 20066 None. 20067 FUTURE DIRECTIONS 20068 None. 20069 SEE ALSO 20070 The Base Definitions volume of IEEE Std 1003.1-200x, 20071 CHANGE HISTORY 20072 First released in Issue 4, Version 2. 20073 Issue 5 20074 Moved from X/OPEN UNIX extension to BASE. 20075 Issue 6 20076 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1079 ioctl( ) System Interfaces 20077 NAME 20078 ioctl - control a STREAMS device (STREAMS) 20079 SYNOPSIS 20080 XSR #include 20081 int ioctl(int fildes, int request, ... /* arg */); 20082 20083 DESCRIPTION 20084 The ioctl( ) function shall perform a variety of control functions on STREAMS devices. For non- | 20085 STREAMS devices, the functions performed by this call are unspecified. The request argument | 20086 and an optional third argument (with varying type) shall be passed to and interpreted by the 20087 appropriate part of the STREAM associated with fildes. 20088 The fildes argument is an open file descriptor that refers to a device. 20089 The request argument selects the control function to be performed and shall depend on the 20090 STREAMS device being addressed. 20091 The arg argument represents additional information that is needed by this specific STREAMS 20092 device to perform the requested function. The type of arg depends upon the particular control 20093 request, but it shall be either an integer or a pointer to a device-specific data structure. 20094 The ioctl( ) commands applicable to STREAMS, their arguments, and error conditions that apply 20095 to each individual command are described below. 20096 The following ioctl( ) commands, with error values indicated, are applicable to all STREAMS 20097 files: 20098 I_PUSH Pushes the module whose name is pointed to by arg onto the top of the 20099 current STREAM, just below the STREAM head. It then calls the open( ) 20100 function of the newly-pushed module. 20101 The ioctl( ) function with the I_PUSH command shall fail if: 20102 [EINVAL] Invalid module name. 20103 [ENXIO] Open function of new module failed. 20104 [ENXIO] Hangup received on fildes. 20105 I_POP Removes the module just below the STREAM head of the STREAM pointed to 20106 by fildes. The arg argument should be 0 in an I_POP request. 20107 The ioctl( ) function with the I_POP command shall fail if: 20108 [EINVAL] No module present in the STREAM. 20109 [ENXIO] Hangup received on fildes. 20110 I_LOOK Retrieves the name of the module just below the STREAM head of the 20111 STREAM pointed to by fildes, and places it in a character string pointed to by 20112 arg. The buffer pointed to by arg should be at least FMNAMESZ+1 bytes long, 20113 where FMNAMESZ is defined in . 20114 The ioctl( ) function with the I_LOOK command shall fail if: 20115 [EINVAL] No module present in the STREAM. 20116 I_FLUSH Flushes read and/or write queues, depending on the value of arg. Valid arg | 20117 values are: 1080 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20118 FLUSHR Flush all read queues. 20119 FLUSHW Flush all write queues. 20120 FLUSHRW Flush all read and all write queues. 20121 The ioctl( ) function with the I_FLUSH command shall fail if: 20122 [EINVAL] Invalid arg value. 20123 [EAGAIN] or [ENOSR] 20124 Unable to allocate buffers for flush message. 20125 [ENXIO] Hangup received on fildes. 20126 I_FLUSHBAND Flushes a particular band of messages. The arg argument points to a bandinfo 20127 structure. The bi_flag member may be one of FLUSHR, FLUSHW, or 20128 FLUSHRW as described above. The bi_pri member determines the priority 20129 band to be flushed. 20130 I_SETSIG Requests that the STREAMS implementation send the SIGPOLL signal to the 20131 calling process when a particular event has occurred on the STREAM 20132 associated with fildes. I_SETSIG supports an asynchronous processing 20133 capability in STREAMS. The value of arg is a bitmask that specifies the events 20134 for which the process should be signaled. It is the bitwise-inclusive OR of any 20135 combination of the following constants: 20136 S_RDNORM A normal (priority band set to 0) message has arrived at the 20137 head of a STREAM head read queue. A signal shall be 20138 generated even if the message is of zero length. 20139 S_RDBAND A message with a non-zero priority band has arrived at the 20140 head of a STREAM head read queue. A signal shall be 20141 generated even if the message is of zero length. 20142 S_INPUT A message, other than a high-priority message, has arrived 20143 at the head of a STREAM head read queue. A signal shall be 20144 generated even if the message is of zero length. 20145 S_HIPRI A high-priority message is present on a STREAM head read 20146 queue. A signal shall be generated even if the message is of 20147 zero length. 20148 S_OUTPUT The write queue for normal data (priority band 0) just 20149 below the STREAM head is no longer full. This notifies the 20150 process that there is room on the queue for sending (or 20151 writing) normal data downstream. 20152 S_WRNORM Equivalent to S_OUTPUT. | 20153 S_WRBAND The write queue for a non-zero priority band just below the 20154 STREAM head is no longer full. This notifies the process 20155 that there is room on the queue for sending (or writing) 20156 priority data downstream. 20157 S_MSG A STREAMS signal message that contains the SIGPOLL 20158 signal has reached the front of the STREAM head read 20159 queue. 20160 S_ERROR Notification of an error condition has reached the STREAM 20161 head. System Interfaces, Issue 6 1081 ioctl( ) System Interfaces 20162 S_HANGUP Notification of a hangup has reached the STREAM head. 20163 S_BANDURG When used in conjunction with S_RDBAND, SIGURG is 20164 generated instead of SIGPOLL when a priority message 20165 reaches the front of the STREAM head read queue. 20166 If arg is 0, the calling process shall be unregistered and shall not receive 20167 further SIGPOLL signals for the stream associated with fildes. 20168 Processes that wish to receive SIGPOLL signals shall ensure that they 20169 explicitly register to receive them using I_SETSIG. If several processes register 20170 to receive this signal for the same event on the same STREAM, each process 20171 shall be signaled when the event occurs. 20172 The ioctl( ) function with the I_SETSIG command shall fail if: 20173 [EINVAL] The value of arg is invalid. 20174 [EINVAL] The value of arg is 0 and the calling process is not registered 20175 to receive the SIGPOLL signal. 20176 [EAGAIN] There were insufficient resources to store the signal request. 20177 I_GETSIG Returns the events for which the calling process is currently registered to be 20178 sent a SIGPOLL signal. The events are returned as a bitmask in an int pointed 20179 to by arg, where the events are those specified in the description of I_SETSIG 20180 above. 20181 The ioctl( ) function with the I_GETSIG command shall fail if: 20182 [EINVAL] Process is not registered to receive the SIGPOLL signal. 20183 I_FIND Compares the names of all modules currently present in the STREAM to the | 20184 name pointed to by arg, and returns 1 if the named module is present in the | 20185 STREAM, or returns 0 if the named module is not present. | 20186 The ioctl( ) function with the I_FIND command shall fail if: 20187 [EINVAL] arg does not contain a valid module name. 20188 I_PEEK Retrieves the information in the first message on the STREAM head read | 20189 queue without taking the message off the queue. It is analogous to getmsg( ) | 20190 except that this command does not remove the message from the queue. The 20191 arg argument points to a strpeek structure. 20192 The application shall ensure that the maxlen member in the ctlbuf and databuf 20193 strbuf structures is set to the number of bytes of control information and/or 20194 data information, respectively, to retrieve. The flags member may be marked 20195 RS_HIPRI or 0, as described by getmsg( ). If the process sets flags to RS_HIPRI, 20196 for example, I_PEEK shall only look for a high-priority message on the 20197 STREAM head read queue. 20198 I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was 20199 found on the STREAM head read queue, or if the RS_HIPRI flag was set in 20200 flags and a high-priority message was not present on the STREAM head read 20201 queue. It does not wait for a message to arrive. On return, ctlbuf specifies 20202 information in the control buffer, databuf specifies information in the data 20203 buffer, and flags contains the value RS_HIPRI or 0. 20204 I_SRDOPT Sets the read mode using the value of the argument arg. Read modes are 20205 described in read( ). Valid arg flags are: 1082 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20206 RNORM Byte-stream mode, the default. 20207 RMSGD Message-discard mode. 20208 RMSGN Message-nondiscard mode. 20209 The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The 20210 bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall result in 20211 the other flag overriding RNORM which is the default. 20212 In addition, treatment of control messages by the STREAM head may be 20213 changed by setting any of the following flags in arg: 20214 RPROTNORM Fail read( ) with [EBADMSG] if a message containing a 20215 control part is at the front of the STREAM head read queue. 20216 RPROTDAT Deliver the control part of a message as data when a 20217 process issues a read( ). 20218 RPROTDIS Discard the control part of a message, delivering any data 20219 portion, when a process issues a read( ). 20220 The ioctl( ) function with the I_SRDOPT command shall fail if: 20221 [EINVAL] The arg argument is not valid. 20222 I_GRDOPT Returns the current read mode setting as, described above, in an int pointed to 20223 by the argument arg. Read modes are described in read( ). 20224 I_NREAD Counts the number of data bytes in the data part of the first message on the 20225 STREAM head read queue and places this value in the int pointed to by arg. 20226 The return value for the command shall be the number of messages on the 20227 STREAM head read queue. For example, if 0 is returned in arg, but the ioctl( ) 20228 return value is greater than 0, this indicates that a zero-length message is next 20229 on the queue. 20230 I_FDINSERT Creates a message from specified buffer(s), adds information about another 20231 STREAM, and sends the message downstream. The message contains a 20232 control part and an optional data part. The data and control parts to be sent 20233 are distinguished by placement in separate buffers, as described below. The 20234 arg argument points to a strfdinsert structure. 20235 The application shall ensure that the len member in the ctlbuf strbuf structure 20236 is set to the size of a t_uscalar_t plus the number of bytes of control 20237 information to be sent with the message. The fildes member specifies the file 20238 descriptor of the other STREAM, and the offset member, which must be 20239 suitably aligned for use as a t_uscalar_t, specifies the offset from the start of 20240 the control buffer where I_FDINSERT shall store a t_uscalar_t whose 20241 interpretation is specific to the STREAM end. The application shall ensure that 20242 the len member in the databuf strbuf structure is set to the number of bytes of 20243 data information to be sent with the message, or to 0 if no data part is to be 20244 sent. 20245 The flags member specifies the type of message to be created. A normal 20246 message is created if flags is set to 0, and a high-priority message is created if 20247 flags is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if 20248 the STREAM write queue is full due to internal flow control conditions. For 20249 priority messages, I_FDINSERT does not block on this condition. For non- 20250 priority messages, I_FDINSERT does not block when the write queue is full System Interfaces, Issue 6 1083 ioctl( ) System Interfaces 20251 and O_NONBLOCK is set. Instead, it fails and sets errno to [EAGAIN]. 20252 I_FDINSERT also blocks, unless prevented by lack of internal resources, 20253 waiting for the availability of message blocks in the STREAM, regardless of 20254 priority or whether O_NONBLOCK has been specified. No partial message is 20255 sent. 20256 The ioctl( ) function with the I_FDINSERT command shall fail if: 20257 [EAGAIN] A non-priority message is specified, the O_NONBLOCK 20258 flag is set, and the STREAM write queue is full due to 20259 internal flow control conditions. 20260 [EAGAIN] or [ENOSR] 20261 Buffers cannot be allocated for the message that is to be 20262 created. 20263 [EINVAL] One of the following: 20264 - The fildes member of the strfdinsert structure is not a 20265 valid, open STREAM file descriptor. 20266 - The size of a t_uscalar_t plus offset is greater than the len 20267 member for the buffer specified through ctlbuf. 20268 - The offset member does not specify a properly-aligned 20269 location in the data buffer. 20270 - An undefined value is stored in flags. 20271 [ENXIO] Hangup received on the STREAM identified by either the 20272 fildes argument or the fildes member of the strfdinsert 20273 structure. 20274 [ERANGE] The len member for the buffer specified through databuf 20275 does not fall within the range specified by the maximum 20276 and minimum packet sizes of the topmost STREAM module 20277 or the len member for the buffer specified through databuf 20278 is larger than the maximum configured size of the data part 20279 of a message; or the len member for the buffer specified 20280 through ctlbuf is larger than the maximum configured size 20281 of the control part of a message. 20282 I_STR Constructs an internal STREAMS ioctl( ) message from the data pointed to by 20283 arg, and sends that message downstream. 20284 This mechanism is provided to send ioctl( ) requests to downstream modules 20285 and drivers. It allows information to be sent with ioctl( ), and returns to the 20286 process any information sent upstream by the downstream recipient. I_STR 20287 shall block until the system responds with either a positive or negative 20288 acknowledgement message, or until the request times out after some period of 20289 time. If the request times out, it shall fail with errno set to [ETIME]. 20290 At most, one I_STR can be active on a STREAM. Further I_STR calls shall 20291 block until the active I_STR completes at the STREAM head. The default 20292 timeout interval for these requests is 15 seconds. The O_NONBLOCK flag has 20293 no effect on this call. 20294 To send requests downstream, the application shall ensure that arg points to a 20295 strioctl structure. 1084 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20296 The ic_cmd member is the internal ioctl( ) command intended for a 20297 downstream module or driver and ic_timout is the number of seconds 20298 (-1=infinite, 0=use implementation-defined timeout interval, >0=as specified) 20299 an I_STR request shall wait for acknowledgement before timing out. ic_len is 20300 the number of bytes in the data argument, and ic_dp is a pointer to the data 20301 argument. The ic_len member has two uses: on input, it contains the length of 20302 the data argument passed in, and on return from the command, it contains the 20303 number of bytes being returned to the process (the buffer pointed to by ic_dp 20304 should be large enough to contain the maximum amount of data that any 20305 module or the driver in the STREAM can return). 20306 The STREAM head shall convert the information pointed to by the strioctl 20307 structure to an internal ioctl( ) command message and sends it downstream. 20308 The ioctl( ) function with the I_STR command shall fail if: 20309 [EAGAIN] or [ENOSR] 20310 Unable to allocate buffers for the ioctl( ) message. 20311 [EINVAL] The ic_len member is less than 0 or larger than the 20312 maximum configured size of the data part of a message, or 20313 ic_timout is less than -1. 20314 [ENXIO] Hangup received on fildes. 20315 [ETIME] A downstream ioctl( ) timed out before acknowledgement 20316 was received. 20317 An I_STR can also fail while waiting for an acknowledgement if a message 20318 indicating an error or a hangup is received at the STREAM head. In addition, 20319 an error code can be returned in the positive or negative acknowledgement 20320 message, in the event the ioctl( ) command sent downstream fails. For these 20321 cases, I_STR shall fail with errno set to the value in the message. 20322 I_SWROPT Sets the write mode using the value of the argument arg. Valid bit settings for 20323 arg are: 20324 SNDZERO Send a zero-length message downstream when a write( ) of 20325 0 bytes occurs. To not send a zero-length message when a 20326 write( ) of 0 bytes occurs, the application shall ensure that 20327 this bit is not set in arg (for example, arg would be set to 0). 20328 The ioctl( ) function with the I_SWROPT command shall fail if: 20329 [EINVAL] arg is not the above value. 20330 I_GWROPT Returns the current write mode setting, as described above, in the int that is 20331 pointed to by the argument arg. 20332 I_SENDFD Creates a new reference to the open file description associated with the file | 20333 descriptor arg, and writes a message on the STREAMS-based pipe fildes | 20334 containing this reference, together with the user ID and group ID of the calling 20335 process. 20336 The ioctl( ) function with the I_SENDFD command shall fail if: 20337 [EAGAIN] The sending STREAM is unable to allocate a message block 20338 to contain the file pointer; or the read queue of the receiving 20339 STREAM head is full and cannot accept the message sent by 20340 I_SENDFD. System Interfaces, Issue 6 1085 ioctl( ) System Interfaces 20341 [EBADF] The arg argument is not a valid, open file descriptor. 20342 [EINVAL] The fildes argument is not connected to a STREAM pipe. 20343 [ENXIO] Hangup received on fildes. 20344 I_RECVFD Retrieves the reference to an open file description from a message written to a 20345 STREAMS-based pipe using the I_SENDFD command, and allocates a new 20346 file descriptor in the calling process that refers to this open file description. 20347 The arg argument is a pointer to a strrecvfd data structure as defined in 20348 . 20349 The fd member is a file descriptor. The uid and gid members are the effective 20350 user ID and effective group ID, respectively, of the sending process. 20351 If O_NONBLOCK is not set, I_RECVFD shall block until a message is present 20352 at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail with errno 20353 set to [EAGAIN] if no message is present at the STREAM head. 20354 If the message at the STREAM head is a message sent by an I_SENDFD, a new 20355 file descriptor shall be allocated for the open file descriptor referenced in the 20356 message. The new file descriptor is placed in the fd member of the strrecvfd 20357 structure pointed to by arg. 20358 The ioctl( ) function with the I_RECVFD command shall fail if: 20359 [EAGAIN] A message is not present at the STREAM head read queue 20360 and the O_NONBLOCK flag is set. 20361 [EBADMSG] The message at the STREAM head read queue is not a 20362 message containing a passed file descriptor. 20363 [EMFILE] The process has the maximum number of file descriptors 20364 currently open that it is allowed. 20365 [ENXIO] Hangup received on fildes. 20366 I_LIST Allows the process to list all the module names on the STREAM, up to and | 20367 including the topmost driver name. If arg is a null pointer, the return value | 20368 shall be the number of modules, including the driver, that are on the STREAM 20369 pointed to by fildes. This lets the process allocate enough space for the 20370 module names. Otherwise, it should point to a str_list structure. 20371 The sl_nmods member indicates the number of entries the process has 20372 allocated in the array. Upon return, the sl_modlist member of the str_list 20373 structure shall contain the list of module names, and the number of entries 20374 that have been filled into the sl_modlist array is found in the sl_nmods member 20375 (the number includes the number of modules including the driver). The return 20376 value from ioctl( ) shall be 0. The entries are filled in starting at the top of the 20377 STREAM and continuing downstream until either the end of the STREAM is 20378 reached, or the number of requested modules (sl_nmods) is satisfied. 20379 The ioctl( ) function with the I_LIST command shall fail if: 20380 [EINVAL] The sl_nmods member is less than 1. 20381 [EAGAIN] or [ENOSR] 20382 Unable to allocate buffers. 20383 I_ATMARK Allows the process to see if the message at the head of the STREAM head read | 20384 queue is marked by some module downstream. The arg argument determines | 1086 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20385 how the checking is done when there may be multiple marked messages on 20386 the STREAM head read queue. It may take on the following values: 20387 ANYMARK Check if the message is marked. 20388 LASTMARK Check if the message is the last one marked on the queue. 20389 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is 20390 permitted. 20391 The return value shall be 1 if the mark condition is satisfied; otherwise, the 20392 value shall be 0. 20393 The ioctl( ) function with the I_ATMARK command shall fail if: 20394 [EINVAL] Invalid arg value. 20395 I_CKBAND Checks if the message of a given priority band exists on the STREAM head | 20396 read queue. This shall return 1 if a message of the given priority exists, 0 if no | 20397 such message exists, or -1 on error. arg should be of type int. 20398 The ioctl( ) function with the I_CKBAND command shall fail if: 20399 [EINVAL] Invalid arg value. 20400 I_GETBAND Returns the priority band of the first message on the STREAM head read | 20401 queue in the integer referenced by arg. 20402 The ioctl( ) function with the I_GETBAND command shall fail if: 20403 [ENODATA] No message on the STREAM head read queue. 20404 I_CANPUT Checks if a certain band is writable. arg is set to the priority band in question. | 20405 The return value shall be 0 if the band is flow-controlled, 1 if the band is 20406 writable, or -1 on error. 20407 The ioctl( ) function with the I_CANPUT command shall fail if: 20408 [EINVAL] Invalid arg value. 20409 I_SETCLTIME This request allows the process to set the time the STREAM head shall delay 20410 when a STREAM is closing and there is data on the write queues. Before 20411 closing each module or driver, if there is data on its write queue, the STREAM 20412 head shall delay for the specified amount of time to allow the data to drain. If, 20413 after the delay, data is still present, it shall be flushed. The arg argument is a 20414 pointer to an integer specifying the number of milliseconds to delay, rounded 20415 up to the nearest valid value. If I_SETCLTIME is not performed on a STREAM, 20416 an implementation-defined default timeout interval is used. 20417 The ioctl( ) function with the I_SETCLTIME command shall fail if: 20418 [EINVAL] Invalid arg value. 20419 I_GETCLTIME Returns the close time delay in the integer pointed to by arg. | System Interfaces, Issue 6 1087 ioctl( ) System Interfaces 20420 Multiplexed STREAMS Configurations 20421 The following commands are used for connecting and disconnecting multiplexed STREAMS 20422 configurations. These commands use an implementation-defined default timeout interval. 20423 I_LINK Connects two STREAMs, where fildes is the file descriptor of the STREAM 20424 connected to the multiplexing driver, and arg is the file descriptor of the 20425 STREAM connected to another driver. The STREAM designated by arg is 20426 connected below the multiplexing driver. I_LINK requires the multiplexing 20427 driver to send an acknowledgement message to the STREAM head regarding 20428 the connection. This call shall return a multiplexer ID number (an identifier 20429 used to disconnect the multiplexer; see I_UNLINK) on success, and -1 on 20430 failure. 20431 The ioctl( ) function with the I_LINK command shall fail if: 20432 [ENXIO] Hangup received on fildes. 20433 [ETIME] Timeout before acknowledgement message was received at 20434 STREAM head. 20435 [EAGAIN] or [ENOSR] 20436 Unable to allocate STREAMS storage to perform the 20437 I_LINK. 20438 [EBADF] The arg argument is not a valid, open file descriptor. 20439 [EINVAL] The fildes argument does not support multiplexing; or arg is 20440 not a STREAM or is already connected downstream from a 20441 multiplexer; or the specified I_LINK operation would 20442 connect the STREAM head in more than one place in the 20443 multiplexed STREAM. 20444 An I_LINK can also fail while waiting for the multiplexing driver to 20445 acknowledge the request, if a message indicating an error or a hangup is 20446 received at the STREAM head of fildes. In addition, an error code can be 20447 returned in the positive or negative acknowledgement message. For these 20448 cases, I_LINK fails with errno set to the value in the message. 20449 I_UNLINK Disconnects the two STREAMs specified by fildes and arg. fildes is the file 20450 descriptor of the STREAM connected to the multiplexing driver. The arg 20451 argument is the multiplexer ID number that was returned by the I_LINK 20452 ioctl( ) command when a STREAM was connected downstream from the 20453 multiplexing driver. If arg is MUXID_ALL, then all STREAMs that were 20454 connected to fildes shall be disconnected. As in I_LINK, this command 20455 requires acknowledgement. 20456 The ioctl( ) function with the I_UNLINK command shall fail if: 20457 [ENXIO] Hangup received on fildes. 20458 [ETIME] Timeout before acknowledgement message was received at 20459 STREAM head. 20460 [EAGAIN] or [ENOSR] 20461 Unable to allocate buffers for the acknowledgement 20462 message. 20463 [EINVAL] Invalid multiplexer ID number. 1088 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20464 An I_UNLINK can also fail while waiting for the multiplexing driver to 20465 acknowledge the request if a message indicating an error or a hangup is 20466 received at the STREAM head of fildes. In addition, an error code can be 20467 returned in the positive or negative acknowledgement message. For these 20468 cases, I_UNLINK shall fail with errno set to the value in the message. 20469 I_PLINK Creates a persistent connection between two STREAMs, where fildes is the file 20470 descriptor of the STREAM connected to the multiplexing driver, and arg is the 20471 file descriptor of the STREAM connected to another driver. This call shall 20472 create a persistent connection which can exist even if the file descriptor fildes 20473 associated with the upper STREAM to the multiplexing driver is closed. The 20474 STREAM designated by arg gets connected via a persistent connection below 20475 the multiplexing driver. I_PLINK requires the multiplexing driver to send an 20476 acknowledgement message to the STREAM head. This call shall return a 20477 multiplexer ID number (an identifier that may be used to disconnect the 20478 multiplexer; see I_PUNLINK) on success, and -1 on failure. 20479 The ioctl( ) function with the I_PLINK command shall fail if: 20480 [ENXIO] Hangup received on fildes. 20481 [ETIME] Timeout before acknowledgement message was received at 20482 STREAM head. 20483 [EAGAIN] or [ENOSR] 20484 Unable to allocate STREAMS storage to perform the 20485 I_PLINK. 20486 [EBADF] The arg argument is not a valid, open file descriptor. 20487 [EINVAL] The fildes argument does not support multiplexing; or arg is 20488 not a STREAM or is already connected downstream from a 20489 multiplexer; or the specified I_PLINK operation would 20490 connect the STREAM head in more than one place in the 20491 multiplexed STREAM. 20492 An I_PLINK can also fail while waiting for the multiplexing driver to 20493 acknowledge the request, if a message indicating an error or a hangup is 20494 received at the STREAM head of fildes. In addition, an error code can be 20495 returned in the positive or negative acknowledgement message. For these 20496 cases, I_PLINK shall fail with errno set to the value in the message. 20497 I_PUNLINK Disconnects the two STREAMs specified by fildes and arg from a persistent 20498 connection. The fildes argument is the file descriptor of the STREAM 20499 connected to the multiplexing driver. The arg argument is the multiplexer ID 20500 number that was returned by the I_PLINK ioctl( ) command when a STREAM 20501 was connected downstream from the multiplexing driver. If arg is 20502 MUXID_ALL, then all STREAMs which are persistent connections to fildes 20503 shall be disconnected. As in I_PLINK, this command requires the multiplexing 20504 driver to acknowledge the request. 20505 The ioctl( ) function with the I_PUNLINK command shall fail if: 20506 [ENXIO] Hangup received on fildes. 20507 [ETIME] Timeout before acknowledgement message was received at 20508 STREAM head. System Interfaces, Issue 6 1089 ioctl( ) System Interfaces 20509 [EAGAIN] or [ENOSR] 20510 Unable to allocate buffers for the acknowledgement 20511 message. 20512 [EINVAL] Invalid multiplexer ID number. 20513 An I_PUNLINK can also fail while waiting for the multiplexing driver to 20514 acknowledge the request if a message indicating an error or a hangup is 20515 received at the STREAM head of fildes. In addition, an error code can be 20516 returned in the positive or negative acknowledgement message. For these 20517 cases, I_PUNLINK shall fail with errno set to the value in the message. 20518 RETURN VALUE 20519 Upon successful completion, ioctl( ) shall return a value other than -1 that depends upon the 20520 STREAMS device control function. Otherwise, it shall return -1 and set errno to indicate the 20521 error. 20522 ERRORS 20523 Under the following general conditions, ioctl( ) shall fail if: 20524 [EBADF] The fildes argument is not a valid open file descriptor. 20525 [EINTR] A signal was caught during the ioctl( ) operation. 20526 [EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or 20527 indirectly) downstream from a multiplexer. 20528 If an underlying device driver detects an error, then ioctl( ) shall fail if: 20529 [EINVAL] The request or arg argument is not valid for this device. 20530 [EIO] Some physical I/O error has occurred. 20531 [ENOTTY] The fildes argument is not associated with a STREAMS device that accepts 20532 control functions. 20533 [ENXIO] The request and arg arguments are valid for this device driver, but the service 20534 requested cannot be performed on this particular sub-device. 20535 [ENODEV] The fildes argument refers to a valid STREAMS device, but the corresponding 20536 device driver does not support the ioctl( ) function. 20537 If a STREAM is connected downstream from a multiplexer, any ioctl( ) command except 20538 I_UNLINK and I_PUNLINK shall set errno to [EINVAL]. 20539 EXAMPLES 20540 None. 20541 APPLICATION USAGE 20542 The implementation-defined timeout interval for STREAMS has historically been 15 seconds. 20543 RATIONALE 20544 None. 20545 FUTURE DIRECTIONS 20546 None. 20547 SEE ALSO 20548 close( ), fcntl( ), getmsg( ), open( ), pipe( ), poll( ), putmsg( ), read( ), sigaction( ), write( ), the Base 20549 Definitions volume of IEEE Std 1003.1-200x, , Section 2.6 (on page 488) 1090 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ioctl( ) 20550 CHANGE HISTORY 20551 First released in Issue 4, Version 2. 20552 Issue 5 20553 Moved from X/OPEN UNIX extension to BASE. 20554 Issue 6 20555 The Open Group Corrigendum U028/4 is applied, correcting text in the I_FDINSERT, [EINVAL] 20556 case to refer to ctlbuf. 20557 This function is marked as part of the XSI STREAMS Option Group. 20558 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1091 isalnum( ) System Interfaces 20559 NAME 20560 isalnum - test for an alphanumeric character 20561 SYNOPSIS 20562 #include 20563 int isalnum(int c); 20564 DESCRIPTION 20565 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20566 conflict between the requirements described here and the ISO C standard is unintentional. This 20567 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20568 The isalnum( ) function shall test whether c is a character of class alpha or digit in the program's | 20569 current locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20570 The c argument is an int, the value of which the application shall ensure is representable as an | 20571 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the 20572 behavior is undefined. 20573 RETURN VALUE 20574 The isalnum( ) function shall return non-zero if c is an alphanumeric character; otherwise, it shall 20575 return 0. 20576 ERRORS 20577 No errors are defined. 20578 EXAMPLES 20579 None. 20580 APPLICATION USAGE 20581 To ensure applications portability, especially across natural languages, only this function and 20582 those listed in the SEE ALSO section should be used for character classification. 20583 RATIONALE 20584 None. 20585 FUTURE DIRECTIONS 20586 None. 20587 SEE ALSO 20588 isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), 20589 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the Base 20590 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 20591 CHANGE HISTORY 20592 First released in Issue 1. Derived from Issue 1 of the SVID. 20593 Issue 6 20594 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1092 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isalpha( ) 20595 NAME 20596 isalpha - test for an alphabetic character 20597 SYNOPSIS 20598 #include 20599 int isalpha(int c); 20600 DESCRIPTION 20601 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20602 conflict between the requirements described here and the ISO C standard is unintentional. This 20603 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20604 The isalpha( ) function shall test whether c is a character of class alpha in the program's current 20605 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20606 The c argument is an int, the value of which the application shall ensure is representable as an | 20607 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the 20608 behavior is undefined. 20609 RETURN VALUE 20610 The isalpha( ) function shall return non-zero if c is an alphabetic character; otherwise, it shall 20611 return 0. 20612 ERRORS 20613 No errors are defined. 20614 EXAMPLES 20615 None. 20616 APPLICATION USAGE 20617 To ensure applications portability, especially across natural languages, only this function and 20618 those listed in the SEE ALSO section should be used for character classification. 20619 RATIONALE 20620 None. 20621 FUTURE DIRECTIONS 20622 None. 20623 SEE ALSO 20624 isalnum( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 20625 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 20626 the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 20627 CHANGE HISTORY 20628 First released in Issue 1. Derived from Issue 1 of the SVID. 20629 Issue 6 20630 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1093 isascii( ) System Interfaces 20631 NAME 20632 isascii - test for a 7-bit US-ASCII character 20633 SYNOPSIS 20634 XSI #include 20635 int isascii(int c); 20636 20637 DESCRIPTION 20638 The isascii( ) function shall test whether c is a 7-bit US-ASCII character code. 20639 The isascii( ) function is defined on all integer values. 20640 RETURN VALUE 20641 The isascii( ) function shall return non-zero if c is a 7-bit US-ASCII character code between 0 and 20642 octal 0177 inclusive; otherwise, it shall return 0. 20643 ERRORS 20644 No errors are defined. 20645 EXAMPLES 20646 None. 20647 APPLICATION USAGE 20648 None. 20649 RATIONALE 20650 None. 20651 FUTURE DIRECTIONS 20652 None. 20653 SEE ALSO 20654 The Base Definitions volume of IEEE Std 1003.1-200x, 20655 CHANGE HISTORY 20656 First released in Issue 1. Derived from Issue 1 of the SVID. 1094 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isastream( ) 20657 NAME 20658 isastream - test a file descriptor (STREAMS) 20659 SYNOPSIS 20660 XSR #include 20661 int isastream(int fildes); 20662 20663 DESCRIPTION 20664 The isastream( ) function shall test whether fildes, an open file descriptor, is associated with a 20665 STREAMS-based file. 20666 RETURN VALUE 20667 Upon successful completion, isastream( ) shall return 1 if fildes refers to a STREAMS-based file 20668 and 0 if not. Otherwise, isastream( ) shall return -1 and set errno to indicate the error. 20669 ERRORS 20670 The isastream( ) function shall fail if: 20671 [EBADF] The fildes argument is not a valid open file descriptor. 20672 EXAMPLES 20673 None. 20674 APPLICATION USAGE 20675 None. 20676 RATIONALE 20677 None. 20678 FUTURE DIRECTIONS 20679 None. 20680 SEE ALSO 20681 The Base Definitions volume of IEEE Std 1003.1-200x, 20682 CHANGE HISTORY 20683 First released in Issue 4, Version 2. 20684 Issue 5 20685 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1095 isatty( ) System Interfaces 20686 NAME 20687 isatty - test for a terminal device 20688 SYNOPSIS 20689 #include 20690 int isatty(int fildes); 20691 DESCRIPTION 20692 The isatty( ) function shall test whether fildes, an open file descriptor, is associated with a 20693 terminal device. 20694 RETURN VALUE 20695 The isatty( ) function shall return 1 if fildes is associated with a terminal; otherwise, it shall return 20696 0 and may set errno to indicate the error. 20697 ERRORS 20698 The isatty( ) function may fail if: 20699 [EBADF] The fildes argument is not a valid open file descriptor. 20700 [ENOTTY] The fildes argument is not associated with a terminal. 20701 EXAMPLES 20702 None. 20703 APPLICATION USAGE 20704 The isatty( ) function does not necessarily indicate that a human being is available for interaction 20705 via fildes. It is quite possible that non-terminal devices are connected to the communications 20706 line. 20707 RATIONALE 20708 None. 20709 FUTURE DIRECTIONS 20710 None. 20711 SEE ALSO 20712 The Base Definitions volume of IEEE Std 1003.1-200x, 20713 CHANGE HISTORY 20714 First released in Issue 1. Derived from Issue 1 of the SVID. 20715 Issue 6 20716 The following new requirements on POSIX implementations derive from alignment with the 20717 Single UNIX Specification: 20718 * The optional setting of errno to indicate an error is added. 20719 * The [EBADF] and [ENOTTY] optional error conditions are added. 1096 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isblank( ) 20720 NAME 20721 isblank - test for a blank character 20722 SYNOPSIS 20723 #include 20724 int isblank(int c); 20725 DESCRIPTION 20726 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20727 conflict between the requirements described here and the ISO C standard is unintentional. This 20728 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20729 The isblank( ) function shall test whether c is a character of class blank in the program's current 20730 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20731 The c argument is a type int, the value of which the application shall ensure is a character | 20732 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 20733 any other value, the behavior is undefined. 20734 RETURN VALUE 20735 The isblank( ) function shall return non-zero if c is a ; otherwise, it shall return 0. 20736 ERRORS 20737 No errors are defined. 20738 EXAMPLES 20739 None. 20740 APPLICATION USAGE 20741 To ensure applications portability, especially across natural languages, only this function and 20742 those listed in the SEE ALSO section should be used for character classification. 20743 RATIONALE 20744 None. 20745 FUTURE DIRECTIONS 20746 None. 20747 SEE ALSO 20748 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 20749 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, 20750 CHANGE HISTORY 20751 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1097 iscntrl( ) System Interfaces 20752 NAME 20753 iscntrl - test for a control character 20754 SYNOPSIS 20755 #include 20756 int iscntrl(int c); 20757 DESCRIPTION 20758 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20759 conflict between the requirements described here and the ISO C standard is unintentional. This 20760 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20761 The iscntrl( ) function shall test whether c is a character of class cntrl in the program's current 20762 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20763 The c argument is a type int, the value of which the application shall ensure is a character | 20764 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 20765 any other value, the behavior is undefined. 20766 RETURN VALUE 20767 The iscntrl( ) function shall return non-zero if c is a control character; otherwise, it shall return 0. 20768 ERRORS 20769 No errors are defined. 20770 EXAMPLES 20771 None. 20772 APPLICATION USAGE 20773 To ensure applications portability, especially across natural languages, only this function and 20774 those listed in the SEE ALSO section should be used for character classification. 20775 RATIONALE 20776 None. 20777 FUTURE DIRECTIONS 20778 None. 20779 SEE ALSO 20780 isalnum( ), isalpha( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 20781 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 20782 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 20783 CHANGE HISTORY 20784 First released in Issue 1. Derived from Issue 1 of the SVID. 20785 Issue 6 20786 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1098 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isdigit( ) 20787 NAME 20788 isdigit - test for a decimal digit 20789 SYNOPSIS 20790 #include 20791 int isdigit(int c); 20792 DESCRIPTION 20793 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20794 conflict between the requirements described here and the ISO C standard is unintentional. This 20795 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20796 The isdigit( ) function shall test whether c is a character of class digit in the program's current 20797 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20798 The c argument is an int, the value of which the application shall ensure is a character | 20799 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 20800 any other value, the behavior is undefined. 20801 RETURN VALUE 20802 The isdigit( ) function shall return non-zero if c is a decimal digit; otherwise, it shall return 0. 20803 ERRORS 20804 No errors are defined. 20805 EXAMPLES 20806 None. 20807 APPLICATION USAGE 20808 To ensure applications portability, especially across natural languages, only this function and 20809 those listed in the SEE ALSO section should be used for character classification. 20810 RATIONALE 20811 None. 20812 FUTURE DIRECTIONS 20813 None. 20814 SEE ALSO 20815 isalnum( ), isalpha( ), iscntrl( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 20816 isxdigit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 20817 CHANGE HISTORY 20818 First released in Issue 1. Derived from Issue 1 of the SVID. 20819 Issue 6 20820 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1099 isfinite( ) System Interfaces 20821 NAME 20822 isfinite - test for finite value 20823 SYNOPSIS 20824 #include 20825 int isfinite(real-floating x); 20826 DESCRIPTION 20827 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20828 conflict between the requirements described here and the ISO C standard is unintentional. This 20829 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20830 The isfinite( ) macro shall determine whether its argument has a finite value (zero, subnormal, or 20831 normal, and not infinite or NaN). First, an argument represented in a format wider than its 20832 semantic type is converted to its semantic type. Then determination is based on the type of the 20833 argument. 20834 RETURN VALUE 20835 The isfinite( ) macro shall return a non-zero value if and only if its argument has a finite value. 20836 ERRORS 20837 No errors are defined. 20838 EXAMPLES 20839 None. 20840 APPLICATION USAGE 20841 None. 20842 RATIONALE 20843 None. 20844 FUTURE DIRECTIONS 20845 None. 20846 SEE ALSO 20847 fpclassify( ), isinf( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of 20848 IEEE Std 1003.1-200x 20849 CHANGE HISTORY 20850 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1100 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isgraph( ) 20851 NAME 20852 isgraph - test for a visible character 20853 SYNOPSIS 20854 #include 20855 int isgraph(int c); 20856 DESCRIPTION 20857 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20858 conflict between the requirements described here and the ISO C standard is unintentional. This 20859 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20860 The isgraph( ) function shall test whether c is a character of class graph in the program's current 20861 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 20862 The c argument is an int, the value of which the application shall ensure is a character | 20863 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 20864 any other value, the behavior is undefined. 20865 RETURN VALUE 20866 The isgraph( ) function shall return non-zero if c is a character with a visible representation; 20867 otherwise, it shall return 0. 20868 ERRORS 20869 No errors are defined. 20870 EXAMPLES 20871 None. 20872 APPLICATION USAGE 20873 To ensure applications portability, especially across natural languages, only this function and 20874 those listed in the SEE ALSO section should be used for character classification. 20875 RATIONALE 20876 None. 20877 FUTURE DIRECTIONS 20878 None. 20879 SEE ALSO 20880 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), isxdigit( ), 20881 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 20882 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 20883 CHANGE HISTORY 20884 First released in Issue 1. Derived from Issue 1 of the SVID. 20885 Issue 6 20886 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1101 isgreater( ) System Interfaces 20887 NAME 20888 isgreater - test if x greater than y 20889 SYNOPSIS 20890 #include 20891 int isgreater(real-floating x, real-floating y); 20892 DESCRIPTION 20893 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20894 conflict between the requirements described here and the ISO C standard is unintentional. This 20895 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20896 The isgreater( ) macro shall determine whether its first argument is greater than its second 20897 argument. The value of isgreater(x, y) shall be equal to (x) > (y); however, unlike (x) > (y), 20898 isgreater(x, y) shall not raise the invalid floating-point exception when x and y are unordered. 20899 RETURN VALUE 20900 Upon successful completion, the isgreater( ) macro shall return the value of (x) > (y). 20901 If x or y is NaN, 0 shall be returned. 20902 ERRORS 20903 No errors are defined. 20904 EXAMPLES 20905 None. 20906 APPLICATION USAGE 20907 The relational and equality operators support the usual mathematical relationships between 20908 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 20909 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 20910 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 20911 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 20912 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 20913 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 20914 indicates that the argument shall be an expression of real-floating type. 20915 RATIONALE 20916 None. 20917 FUTURE DIRECTIONS 20918 None. 20919 SEE ALSO 20920 isgreaterequal( ), isless( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume of 20921 IEEE Std 1003.1-200x 20922 CHANGE HISTORY 20923 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1102 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isgreaterequal( ) 20924 NAME 20925 isgreaterequal - test if x greater than or equal to y 20926 SYNOPSIS 20927 #include 20928 int isgreaterequal(real-floating x, real-floating y); 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 isgreaterequal( ) macro shall determine whether its first argument is greater than or equal to 20934 its second argument. The value of isgreaterequal(x, y) shall be equal to (x) >= (y); however, unlike 20935 (x) >= (y), isgreaterequal(x, y) shall not raise the invalid floating-point exception when x and y are 20936 unordered. 20937 RETURN VALUE 20938 Upon successful completion, the isgreaterequal( ) macro shall return the value of (x) >= (y). 20939 If x or y is NaN, 0 shall be returned. 20940 ERRORS 20941 No errors are defined. 20942 EXAMPLES 20943 None. 20944 APPLICATION USAGE 20945 The relational and equality operators support the usual mathematical relationships between 20946 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 20947 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 20948 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 20949 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 20950 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 20951 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 20952 indicates that the argument shall be an expression of real-floating type. 20953 RATIONALE 20954 None. 20955 FUTURE DIRECTIONS 20956 None. 20957 SEE ALSO 20958 isgreater( ), isless( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume of 20959 IEEE Std 1003.1-200x 20960 CHANGE HISTORY 20961 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1103 isinf( ) System Interfaces 20962 NAME 20963 isinf - test for infinity 20964 SYNOPSIS 20965 #include 20966 int isinf(real-floating x); 20967 DESCRIPTION 20968 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20969 conflict between the requirements described here and the ISO C standard is unintentional. This 20970 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 20971 The isinf( ) macro shall determine whether its argument value is an infinity (positive or 20972 negative). First, an argument represented in a format wider than its semantic type is converted 20973 to its semantic type. Then determination is based on the type of the argument. 20974 RETURN VALUE 20975 The isinf( ) macro shall return a non-zero value if and only if its argument has an infinite value. 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 fpclassify( ), isfinite( ), isnan( ), isnormal( ), signbit( ), the Base Definitions volume of 20988 IEEE Std 1003.1-200x 20989 CHANGE HISTORY 20990 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1104 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isless( ) 20991 NAME 20992 isless - test if x is less than y 20993 SYNOPSIS 20994 #include 20995 int isless(real-floating x, real-floating y); 20996 DESCRIPTION 20997 CX The functionality described on this reference page is aligned with the ISO C standard. Any 20998 conflict between the requirements described here and the ISO C standard is unintentional. This 20999 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21000 The isless( ) macro shall determine whether its first argument is less than its second argument. 21001 The value of isless(x, y) shall be equal to (x) < (y); however, unlike (x) < (y), isless(x, y) shall not 21002 raise the invalid floating-point exception when x and y are unordered. 21003 RETURN VALUE 21004 Upon successful completion, the isless( ) macro shall return the value of (x) < (y). 21005 If x or y is NaN, 0 shall be returned. 21006 ERRORS 21007 No errors are defined. 21008 EXAMPLES 21009 None. 21010 APPLICATION USAGE 21011 The relational and equality operators support the usual mathematical relationships between 21012 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 21013 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 21014 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 21015 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 21016 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 21017 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 21018 indicates that the argument shall be an expression of real-floating type. 21019 RATIONALE 21020 None. 21021 FUTURE DIRECTIONS 21022 None. 21023 SEE ALSO 21024 isgreater( ), isgreaterequal( ), islessequal( ), islessgreater( ), isunordered( ), the Base Definitions volume 21025 of IEEE Std 1003.1-200x, 21026 CHANGE HISTORY 21027 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1105 islessequal( ) System Interfaces 21028 NAME 21029 islessequal - test if x is less than or equal to y 21030 SYNOPSIS 21031 #include 21032 int islessequal(real-floating x, real-floating y); 21033 DESCRIPTION 21034 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21035 conflict between the requirements described here and the ISO C standard is unintentional. This 21036 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21037 The islessequal( ) macro shall determine whether its first argument is less than or equal to its 21038 second argument. The value of islessequal(x, y) shall be equal to (x) <= (y); however, unlike 21039 (x) <= (y), islessequal(x, y) shall not raise the invalid floating-point exception when x and y are 21040 unordered. 21041 RETURN VALUE 21042 Upon successful completion, the islessequal( ) macro shall return the value of (x) <= (y). 21043 If x or y is NaN, 0 shall be returned. 21044 ERRORS 21045 No errors are defined. 21046 EXAMPLES 21047 None. 21048 APPLICATION USAGE 21049 The relational and equality operators support the usual mathematical relationships between 21050 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 21051 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 21052 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 21053 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 21054 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 21055 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 21056 indicates that the argument shall be an expression of real-floating type. 21057 RATIONALE 21058 None. 21059 FUTURE DIRECTIONS 21060 None. 21061 SEE ALSO 21062 isgreater( ), isgreaterequal( ), isless( ), islessgreater( ), isunordered( ), the Base Definitions volume of 21063 IEEE Std 1003.1-200x 21064 CHANGE HISTORY 21065 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1106 Technical Standard (2001) (Draft April 16, 2001) System Interfaces islessgreater( ) 21066 NAME 21067 islessgreater - test if x is less than or greater than y 21068 SYNOPSIS 21069 #include 21070 int islessgreater(real-floating x, real-floating y); 21071 DESCRIPTION 21072 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21073 conflict between the requirements described here and the ISO C standard is unintentional. This 21074 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21075 The islessgreater( ) macro shall determine whether its first argument is less than or greater than 21076 its second argument. The islessgreater(x, y) macro is similar to (x) < (y) || (x) > (y); however, 21077 islessgreater(x, y) shall not raise the invalid floating-point exception when x and y are unordered 21078 (nor shall it evaluate x and y twice). 21079 RETURN VALUE 21080 Upon successful completion, the islessgreater( ) macro shall return the value of 21081 (x) < (y) || (x) > (y). 21082 If x or y is NaN, 0 shall be returned. 21083 ERRORS 21084 No errors are defined. 21085 EXAMPLES 21086 None. 21087 APPLICATION USAGE 21088 The relational and equality operators support the usual mathematical relationships between 21089 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 21090 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 21091 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 21092 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 21093 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 21094 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 21095 indicates that the argument shall be an expression of real-floating type. 21096 RATIONALE 21097 None. 21098 FUTURE DIRECTIONS 21099 None. 21100 SEE ALSO 21101 isgreater( ), isgreaterequal( ), isless( ), islessequal( ), isunordered( ), the Base Definitions volume of 21102 IEEE Std 1003.1-200x 21103 CHANGE HISTORY 21104 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1107 islower( ) System Interfaces 21105 NAME 21106 islower - test for a lowercase letter 21107 SYNOPSIS 21108 #include 21109 int islower(int c); 21110 DESCRIPTION 21111 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21112 conflict between the requirements described here and the ISO C standard is unintentional. This 21113 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21114 The islower( ) function shall test whether c is a character of class lower in the program's current 21115 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21116 The c argument is an int, the value of which the application shall ensure is a character | 21117 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21118 any other value, the behavior is undefined. 21119 RETURN VALUE 21120 The islower( ) function shall return non-zero if c is a lowercase letter; otherwise, it shall return 0. 21121 ERRORS 21122 No errors are defined. 21123 EXAMPLES 21124 Testing for a Lowercase Letter 21125 The following example tests whether the value is a lowercase letter, based on the locale of the 21126 user, then uses it as part of a key value. 21127 #include 21128 #include 21129 #include 21130 ... 21131 char *keystr; 21132 int elementlen, len; 21133 char c; 21134 ... 21135 setlocale(LC_ALL, ""); 21136 ... 21137 len = 0; 21138 while (len < elementlen) { 21139 c = (char) (rand() % 256); 21140 ... 21141 if (islower(c)) 21142 keystr[len++] = c; 21143 } 21144 ... 21145 APPLICATION USAGE 21146 To ensure applications portability, especially across natural languages, only this function and 21147 those listed in the SEE ALSO section should be used for character classification. 1108 Technical Standard (2001) (Draft April 16, 2001) System Interfaces islower( ) 21148 RATIONALE 21149 None. 21150 FUTURE DIRECTIONS 21151 None. 21152 SEE ALSO 21153 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), isprint( ), ispunct( ), isspace( ), isupper( ), 21154 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 21155 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 21156 CHANGE HISTORY 21157 First released in Issue 1. Derived from Issue 1 of the SVID. 21158 Issue 6 21159 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 21160 An example is added. | System Interfaces, Issue 6 1109 isnan( ) System Interfaces 21161 NAME 21162 isnan - test for a NaN 21163 SYNOPSIS 21164 #include 21165 int isnan(real-floating x); 21166 DESCRIPTION 21167 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21168 conflict between the requirements described here and the ISO C standard is unintentional. This 21169 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21170 The isnan( ) macro shall determine whether its argument value is a NaN. First, an argument 21171 represented in a format wider than its semantic type is converted to its semantic type. Then 21172 determination is based on the type of the argument. 21173 RETURN VALUE 21174 The isnan( ) macro shall return a non-zero value if and only if its argument has a NaN value. 21175 ERRORS 21176 No errors are defined. 21177 EXAMPLES 21178 None. 21179 APPLICATION USAGE 21180 None. 21181 RATIONALE 21182 None. 21183 FUTURE DIRECTIONS 21184 None. 21185 SEE ALSO 21186 fpclassify( ), isfinite( ), isinf( ), isnormal( ), signbit( ), the Base Definitions volume of 21187 IEEE Std 1003.1-200x, 21188 CHANGE HISTORY 21189 First released in Issue 3. 21190 Issue 5 21191 The DESCRIPTION is updated to indicate the return value when NaN is not supported. This 21192 text was previously published in the APPLICATION USAGE section. 21193 Issue 6 21194 Entry re-written for alignment with the ISO/IEC 9899: 1999 standard. 1110 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isnormal( ) 21195 NAME 21196 isnormal - test for a normal value 21197 SYNOPSIS 21198 #include 21199 int isnormal(real-floating x); 21200 DESCRIPTION 21201 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21202 conflict between the requirements described here and the ISO C standard is unintentional. This 21203 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21204 The isnormal( ) macro shall determine whether its argument value is normal (neither zero, 21205 subnormal, infinite, nor NaN). First, an argument represented in a format wider than its 21206 semantic type is converted to its semantic type. Then determination is based on the type of the 21207 argument. 21208 RETURN VALUE 21209 The isnormal( ) macro shall return a non-zero value if and only if its argument has a normal 21210 value. 21211 ERRORS 21212 No errors are defined. 21213 EXAMPLES 21214 None. 21215 APPLICATION USAGE 21216 None. 21217 RATIONALE 21218 None. 21219 FUTURE DIRECTIONS 21220 None. 21221 SEE ALSO 21222 fpclassify( ), isfinite( ), isinf( ), isnan( ), signbit( ), the Base Definitions volume of 21223 IEEE Std 1003.1-200x, 21224 CHANGE HISTORY 21225 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1111 isprint( ) System Interfaces 21226 NAME 21227 isprint - test for a printable character | 21228 SYNOPSIS 21229 #include 21230 int isprint(int c); 21231 DESCRIPTION 21232 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21233 conflict between the requirements described here and the ISO C standard is unintentional. This 21234 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21235 The isprint( ) function shall test whether c is a character of class print in the program's current 21236 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21237 The c argument is an int, the value of which the application shall ensure is a character | 21238 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21239 any other value, the behavior is undefined. 21240 RETURN VALUE 21241 The isprint( ) function shall return non-zero if c is a printable character; otherwise, it shall return | 21242 0. | 21243 ERRORS 21244 No errors are defined. 21245 EXAMPLES 21246 None. 21247 APPLICATION USAGE 21248 To ensure applications portability, especially across natural languages, only this function and 21249 those listed in the SEE ALSO section should be used for character classification. 21250 RATIONALE 21251 None. 21252 FUTURE DIRECTIONS 21253 None. 21254 SEE ALSO 21255 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), ispunct( ), isspace( ), isupper( ), 21256 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 21257 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 21258 CHANGE HISTORY 21259 First released in Issue 1. Derived from Issue 1 of the SVID. 21260 Issue 6 21261 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1112 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ispunct( ) 21262 NAME 21263 ispunct - test for a punctuation character 21264 SYNOPSIS 21265 #include 21266 int ispunct(int c); 21267 DESCRIPTION 21268 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21269 conflict between the requirements described here and the ISO C standard is unintentional. This 21270 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21271 The ispunct( ) function shall test whether c is a character of class punct in the program's current 21272 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21273 The c argument is an int, the value of which the application shall ensure is a character | 21274 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21275 any other value, the behavior is undefined. 21276 RETURN VALUE 21277 The ispunct( ) function shall return non-zero if c is a punctuation character; otherwise, it shall 21278 return 0. 21279 ERRORS 21280 No errors are defined. 21281 EXAMPLES 21282 None. 21283 APPLICATION USAGE 21284 To ensure applications portability, especially across natural languages, only this function and 21285 those listed in the SEE ALSO section should be used for character classification. 21286 RATIONALE 21287 None. 21288 FUTURE DIRECTIONS 21289 None. 21290 SEE ALSO 21291 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), isspace( ), isupper( ), isxdigit( ), 21292 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 21293 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 21294 CHANGE HISTORY 21295 First released in Issue 1. Derived from Issue 1 of the SVID. 21296 Issue 6 21297 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1113 isspace( ) System Interfaces 21298 NAME 21299 isspace - test for a white-space character 21300 SYNOPSIS 21301 #include 21302 int isspace(int c); 21303 DESCRIPTION 21304 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21305 conflict between the requirements described here and the ISO C standard is unintentional. This 21306 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21307 The isspace( ) function shall test whether c is a character of class space in the program's current 21308 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21309 The c argument is an int, the value of which the application shall ensure is a character | 21310 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21311 any other value, the behavior is undefined. 21312 RETURN VALUE 21313 The isspace( ) function shall return non-zero if c is a white-space character; otherwise, it shall 21314 return 0. 21315 ERRORS 21316 No errors are defined. 21317 EXAMPLES 21318 None. 21319 APPLICATION USAGE 21320 To ensure applications portability, especially across natural languages, only this function and 21321 those listed in the SEE ALSO section should be used for character classification. 21322 RATIONALE 21323 None. 21324 FUTURE DIRECTIONS 21325 None. 21326 SEE ALSO 21327 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isupper( ), 21328 isxdigit( ), setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 21329 Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 21330 CHANGE HISTORY 21331 First released in Issue 1. Derived from Issue 1 of the SVID. 21332 Issue 6 21333 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1114 Technical Standard (2001) (Draft April 16, 2001) System Interfaces isunordered( ) 21334 NAME 21335 isunordered - test if arguments are unordered 21336 SYNOPSIS 21337 #include 21338 int isunordered(real-floating x, real-floating y); 21339 DESCRIPTION 21340 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21341 conflict between the requirements described here and the ISO C standard is unintentional. This 21342 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21343 The isunordered( ) macro shall determine whether its arguments are unordered. 21344 RETURN VALUE 21345 Upon successful completion, the isunordered( ) macro shall return 1 if its arguments are 21346 unordered, and 0 otherwise. 21347 If x or y is NaN, 0 shall be returned. 21348 ERRORS 21349 No errors are defined. 21350 EXAMPLES 21351 None. 21352 APPLICATION USAGE 21353 The relational and equality operators support the usual mathematical relationships between 21354 numeric values. For any ordered pair of numeric values, exactly one of the relationships (less, 21355 greater, and equal) is true. Relational operators may raise the invalid floating-point exception 21356 when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the 21357 unordered relationship is true. This macro is a quiet (non-floating-point exception raising) 21358 version of a relational operator. It facilitates writing efficient code that accounts for NaNs 21359 without suffering the invalid floating-point exception. In the SYNOPSIS section, real-floating 21360 indicates that the argument shall be an expression of real-floating type. 21361 RATIONALE 21362 None. 21363 FUTURE DIRECTIONS 21364 None. 21365 SEE ALSO 21366 isgreater( ), isgreaterequal( ), isless( ), islessequal( ), islessgreater( ), the Base Definitions volume of 21367 IEEE Std 1003.1-200x, 21368 CHANGE HISTORY 21369 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1115 isupper( ) System Interfaces 21370 NAME 21371 isupper - test for an uppercase letter 21372 SYNOPSIS 21373 #include 21374 int isupper(int c); 21375 DESCRIPTION 21376 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21377 conflict between the requirements described here and the ISO C standard is unintentional. This 21378 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21379 The isupper( ) function shall test whether c is a character of class upper in the program's current 21380 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21381 The c argument is an int, the value of which the application shall ensure is a character | 21382 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21383 any other value, the behavior is undefined. 21384 RETURN VALUE 21385 The isupper( ) function shall return non-zero if c is an uppercase letter; otherwise, it shall return 0. 21386 ERRORS 21387 No errors are defined. 21388 EXAMPLES 21389 None. 21390 APPLICATION USAGE 21391 To ensure applications portability, especially across natural languages, only this function and 21392 those listed in the SEE ALSO section should be used for character classification. 21393 RATIONALE 21394 None. 21395 FUTURE DIRECTIONS 21396 None. 21397 SEE ALSO 21398 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isxdigit( ), 21399 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 21400 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 21401 CHANGE HISTORY 21402 First released in Issue 1. Derived from Issue 1 of the SVID. 21403 Issue 6 21404 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1116 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswalnum( ) 21405 NAME 21406 iswalnum - test for an alphanumeric wide-character code 21407 SYNOPSIS 21408 #include 21409 int iswalnum(wint_t wc); 21410 DESCRIPTION 21411 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21412 conflict between the requirements described here and the ISO C standard is unintentional. This 21413 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21414 The iswalnum( ) function shall test whether wc is a wide-character code representing a character 21415 of class alpha or digit in the program's current locale; see the Base Definitions volume of 21416 IEEE Std 1003.1-200x, Chapter 7, Locale. 21417 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21418 code corresponding to a valid character in the current locale, or equal to the value of the macro 21419 WEOF. If the argument has any other value, the behavior is undefined. 21420 RETURN VALUE 21421 The iswalnum( ) function shall return non-zero if wc is an alphanumeric wide-character code; 21422 otherwise, it shall return 0. 21423 ERRORS 21424 No errors are defined. 21425 EXAMPLES 21426 None. 21427 APPLICATION USAGE 21428 To ensure applications portability, especially across natural languages, only this function and 21429 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21430 RATIONALE 21431 None. 21432 FUTURE DIRECTIONS 21433 None. 21434 SEE ALSO 21435 iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21436 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21437 IEEE Std 1003.1-200x, , , , the Base Definitions volume of 21438 IEEE Std 1003.1-200x, Chapter 7, Locale 21439 CHANGE HISTORY 21440 First released as a World-wide Portability Interface in Issue 4. 21441 Issue 5 21442 The following change has been made in this issue for alignment with 21443 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21444 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21445 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1117 iswalnum( ) System Interfaces 21446 Issue 6 21447 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1118 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswalpha( ) 21448 NAME 21449 iswalpha - test for an alphabetic wide-character code 21450 SYNOPSIS 21451 #include 21452 int iswalpha(wint_t wc); 21453 DESCRIPTION 21454 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21455 conflict between the requirements described here and the ISO C standard is unintentional. This 21456 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21457 The iswalpha( ) function shall test whether wc is a wide-character code representing a character of 21458 class alpha in the program's current locale; see the Base Definitions volume of 21459 IEEE Std 1003.1-200x, Chapter 7, Locale. 21460 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21461 code corresponding to a valid character in the current locale, or equal to the value of the macro 21462 WEOF. If the argument has any other value, the behavior is undefined. 21463 RETURN VALUE 21464 The iswalpha( ) function shall return non-zero if wc is an alphabetic wide-character code; 21465 otherwise, it shall return 0. 21466 ERRORS 21467 No errors are defined. 21468 EXAMPLES 21469 None. 21470 APPLICATION USAGE 21471 To ensure applications portability, especially across natural languages, only this function and 21472 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21473 RATIONALE 21474 None. 21475 FUTURE DIRECTIONS 21476 None. 21477 SEE ALSO 21478 iswalnum( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21479 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21480 IEEE Std 1003.1-200x, , , , the Base Definitions volume of 21481 IEEE Std 1003.1-200x, Chapter 7, Locale 21482 CHANGE HISTORY 21483 First released in Issue 4. 21484 Issue 5 21485 The following change has been made in this issue for alignment with 21486 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21487 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21488 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1119 iswalpha( ) System Interfaces 21489 Issue 6 21490 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1120 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswblank( ) 21491 NAME 21492 iswblank - test for a blank wide-character code 21493 SYNOPSIS 21494 #include 21495 int iswblank(wint_t wc); 21496 DESCRIPTION 21497 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21498 conflict between the requirements described here and the ISO C standard is unintentional. This 21499 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21500 The iswblank( ) function shall test whether wc is a wide-character code representing a character of 21501 class blank in the program's current locale; see the Base Definitions volume of 21502 IEEE Std 1003.1-200x, Chapter 7, Locale. 21503 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21504 code corresponding to a valid character in the current locale, or equal to the value of the macro 21505 WEOF. If the argument has any other value, the behavior is undefined. 21506 RETURN VALUE 21507 The iswblank( ) function shall return non-zero if wc is a blank wide-character code; otherwise, it | 21508 shall return 0. | 21509 ERRORS 21510 No errors are defined. 21511 EXAMPLES 21512 None. 21513 APPLICATION USAGE 21514 To ensure applications portability, especially across natural languages, only this function and 21515 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21516 RATIONALE 21517 None. 21518 FUTURE DIRECTIONS 21519 None. 21520 SEE ALSO 21521 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 21522 iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21523 IEEE Std 1003.1-200x, , , 21524 CHANGE HISTORY 21525 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1121 iswcntrl( ) System Interfaces 21526 NAME 21527 iswcntrl - test for a control wide-character code 21528 SYNOPSIS 21529 #include 21530 int iswcntrl(wint_t wc); 21531 DESCRIPTION 21532 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21533 conflict between the requirements described here and the ISO C standard is unintentional. This 21534 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21535 The iswcntrl( ) function shall test whether wc is a wide-character code representing a character of 21536 class cntrl in the program's current locale; see the Base Definitions volume of | 21537 IEEE Std 1003.1-200x, Chapter 7, Locale. 21538 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21539 code corresponding to a valid character in the current locale, or equal to the value of the macro 21540 WEOF. If the argument has any other value, the behavior is undefined. 21541 RETURN VALUE 21542 The iswcntrl( ) function shall return non-zero if wc is a control wide-character code; otherwise, it 21543 shall return 0. 21544 ERRORS 21545 No errors are defined. 21546 EXAMPLES 21547 None. 21548 APPLICATION USAGE 21549 To ensure applications portability, especially across natural languages, only this function and 21550 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21551 RATIONALE 21552 None. 21553 FUTURE DIRECTIONS 21554 None. 21555 SEE ALSO 21556 iswalnum( ), iswalpha( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21557 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21558 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21559 IEEE Std 1003.1-200x, Chapter 7, Locale 21560 CHANGE HISTORY 21561 First released in Issue 4. 21562 Issue 5 21563 The following change has been made in this issue for alignment with 21564 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21565 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21566 now made visible by inclusion of the header rather than . 1122 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswcntrl( ) 21567 Issue 6 21568 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1123 iswctype( ) System Interfaces 21569 NAME 21570 iswctype - test character for a specified class 21571 SYNOPSIS 21572 #include 21573 int iswctype(wint_t wc, wctype_t charclass); 21574 DESCRIPTION 21575 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21576 conflict between the requirements described here and the ISO C standard is unintentional. This 21577 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21578 The iswctype( ) function shall determine whether the wide-character code wc has the character 21579 class charclass, returning true or false. The iswctype( ) function is defined on WEOF and wide- 21580 character codes corresponding to the valid character encodings in the current locale. If the wc 21581 argument is not in the domain of the function, the result is undefined. If the value of charclass is 21582 invalid (that is, not obtained by a call to wctype( ) or charclass is invalidated by a subsequent call 21583 to setlocale( ) that has affected category LC_CTYPE) the result is unspecified. 21584 RETURN VALUE 21585 The iswctype( ) function shall return non-zero (true) if and only if wc has the property described 21586 CX by charclass. If charclass is 0, iswctype( ) shall return 0. 21587 ERRORS 21588 No errors are defined. 21589 EXAMPLES 21590 Testing for a Valid Character 21591 #include 21592 ... 21593 int yes_or_no; 21594 wint_t wc; 21595 wctype_t valid_class; 21596 ... 21597 if ((valid_class=wctype("vowel")) == (wctype_t)0) 21598 /* Invalid character class. */ 21599 yes_or_no=iswctype(wc,valid_class); 21600 APPLICATION USAGE 21601 The twelve strings "alnum", "alpha", "blank", "cntrl", "digit", "graph", "lower", 21602 "print", "punct", "space", "upper", and "xdigit" are reserved for the standard 21603 character classes. In the table below, the functions in the left column are equivalent to the 21604 functions in the right column. 21605 iswalnum(wc) iswctype(wc, wctype("alnum")) 21606 iswalpha(wc) iswctype(wc, wctype("alpha")) 21607 iswblank(wc) iswctype(wc, wctype("blank")) 21608 iswcntrl(wc) iswctype(wc, wctype("cntrl")) 21609 iswdigit(wc) iswctype(wc, wctype("digit")) 21610 iswgraph(wc) iswctype(wc, wctype("graph")) 21611 iswlower(wc) iswctype(wc, wctype("lower")) 21612 iswprint(wc) iswctype(wc, wctype("print")) 21613 iswpunct(wc) iswctype(wc, wctype("punct")) 21614 iswspace(wc) iswctype(wc, wctype("space")) 1124 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswctype( ) 21615 iswupper(wc) iswctype(wc, wctype("upper")) 21616 iswxdigit(wc) iswctype(wc, wctype("xdigit")) 21617 RATIONALE 21618 None. 21619 FUTURE DIRECTIONS 21620 None. 21621 SEE ALSO 21622 iswalnum( ), iswalpha( ), iswcntrl( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21623 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), wctype( ), the Base Definitions volume of 21624 IEEE Std 1003.1-200x, , 21625 CHANGE HISTORY 21626 First released as World-wide Portability Interfaces in Issue 4. 21627 Issue 5 21628 The following change has been made in this issue for alignment with 21629 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21630 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21631 now made visible by inclusion of the header rather than . 21632 Issue 6 | 21633 The behavior of n=0 is now described. | 21634 An example is added. | 21635 A new function, iswblank( ), is added to the list in the APPLICATION USAGE. | System Interfaces, Issue 6 1125 iswdigit( ) System Interfaces 21636 NAME 21637 iswdigit - test for a decimal digit wide-character code 21638 SYNOPSIS 21639 #include 21640 int iswdigit(wint_t wc); 21641 DESCRIPTION 21642 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21643 conflict between the requirements described here and the ISO C standard is unintentional. This 21644 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21645 The iswdigit( ) function shall test whether wc is a wide-character code representing a character of 21646 class digit in the program's current locale; see the Base Definitions volume of 21647 IEEE Std 1003.1-200x, Chapter 7, Locale. 21648 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21649 code corresponding to a valid character in the current locale, or equal to the value of the macro 21650 WEOF. If the argument has any other value, the behavior is undefined. 21651 RETURN VALUE 21652 The iswdigit( ) function shall return non-zero if wc is a decimal digit wide-character code; 21653 otherwise, it shall return 0. 21654 ERRORS 21655 No errors are defined. 21656 EXAMPLES 21657 None. 21658 APPLICATION USAGE 21659 To ensure applications portability, especially across natural languages, only this function and 21660 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21661 RATIONALE 21662 None. 21663 FUTURE DIRECTIONS 21664 None. 21665 SEE ALSO 21666 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), 21667 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21668 IEEE Std 1003.1-200x, , 21669 CHANGE HISTORY 21670 First released in Issue 4. 21671 Issue 5 21672 The following change has been made in this issue for alignment with 21673 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21674 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21675 now made visible by inclusion of the header rather than . 21676 Issue 6 21677 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1126 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswgraph( ) 21678 NAME 21679 iswgraph - test for a visible wide-character code 21680 SYNOPSIS 21681 #include 21682 int iswgraph(wint_t wc); 21683 DESCRIPTION 21684 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21685 conflict between the requirements described here and the ISO C standard is unintentional. This 21686 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21687 The iswgraph( ) function shall test whether wc is a wide-character code representing a character 21688 of class graph in the program's current locale; see the Base Definitions volume of 21689 IEEE Std 1003.1-200x, Chapter 7, Locale. 21690 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21691 code corresponding to a valid character in the current locale, or equal to the value of the macro 21692 WEOF. If the argument has any other value, the behavior is undefined. 21693 RETURN VALUE 21694 The iswgraph( ) function shall return non-zero if wc is a wide-character code with a visible 21695 representation; otherwise, it shall return 0. 21696 ERRORS 21697 No errors are defined. 21698 EXAMPLES 21699 None. 21700 APPLICATION USAGE 21701 To ensure applications portability, especially across natural languages, only this function and 21702 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21703 RATIONALE 21704 None. 21705 FUTURE DIRECTIONS 21706 None. 21707 SEE ALSO 21708 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswlower( ), iswprint( ), iswpunct( ), 21709 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21710 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21711 IEEE Std 1003.1-200x, Chapter 7, Locale 21712 CHANGE HISTORY 21713 First released in Issue 4. 21714 Issue 5 21715 The following change has been made in this issue for alignment with 21716 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21717 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21718 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1127 iswgraph( ) System Interfaces 21719 Issue 6 21720 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1128 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswlower( ) 21721 NAME 21722 iswlower - test for a lowercase letter wide-character code 21723 SYNOPSIS 21724 #include 21725 int iswlower(wint_t wc); 21726 DESCRIPTION 21727 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21728 conflict between the requirements described here and the ISO C standard is unintentional. This 21729 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21730 The iswlower( ) function shall test whether wc is a wide-character code representing a character 21731 of class lower in the program's current locale; see the Base Definitions volume of 21732 IEEE Std 1003.1-200x, Chapter 7, Locale. 21733 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21734 code corresponding to a valid character in the current locale, or equal to the value of the macro 21735 WEOF. If the argument has any other value, the behavior is undefined. 21736 RETURN VALUE 21737 The iswlower( ) function shall return non-zero if wc is a lowercase letter wide-character code; 21738 otherwise, it shall return 0. 21739 ERRORS 21740 No errors are defined. 21741 EXAMPLES 21742 None. 21743 APPLICATION USAGE 21744 To ensure applications portability, especially across natural languages, only this function and 21745 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21746 RATIONALE 21747 None. 21748 FUTURE DIRECTIONS 21749 None. 21750 SEE ALSO 21751 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswprint( ), iswpunct( ), 21752 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21753 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21754 IEEE Std 1003.1-200x, Chapter 7, Locale 21755 CHANGE HISTORY 21756 First released in Issue 4. 21757 Issue 5 21758 The following change has been made in this issue for alignment with 21759 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21760 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21761 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1129 iswlower( ) System Interfaces 21762 Issue 6 21763 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1130 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswprint( ) 21764 NAME 21765 iswprint - test for a printable wide-character code | 21766 SYNOPSIS 21767 #include 21768 int iswprint(wint_t wc); 21769 DESCRIPTION 21770 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21771 conflict between the requirements described here and the ISO C standard is unintentional. This 21772 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21773 The iswprint( ) function shall test whether wc is a wide-character code representing a character of 21774 class print in the program's current locale; see the Base Definitions volume of 21775 IEEE Std 1003.1-200x, Chapter 7, Locale. 21776 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21777 code corresponding to a valid character in the current locale, or equal to the value of the macro 21778 WEOF. If the argument has any other value, the behavior is undefined. 21779 RETURN VALUE 21780 The iswprint( ) function shall return non-zero if wc is a printable wide-character code; otherwise, | 21781 it shall return 0. | 21782 ERRORS 21783 No errors are defined. 21784 EXAMPLES 21785 None. 21786 APPLICATION USAGE 21787 To ensure applications portability, especially across natural languages, only this function and 21788 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21789 RATIONALE 21790 None. 21791 FUTURE DIRECTIONS 21792 None. 21793 SEE ALSO 21794 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswpunct( ), 21795 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21796 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21797 IEEE Std 1003.1-200x, Chapter 7, Locale 21798 CHANGE HISTORY 21799 First released in Issue 4. 21800 Issue 5 21801 The following change has been made in this issue for alignment with 21802 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21803 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21804 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1131 iswprint( ) System Interfaces 21805 Issue 6 21806 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1132 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswpunct( ) 21807 NAME 21808 iswpunct - test for a punctuation wide-character code 21809 SYNOPSIS 21810 #include 21811 int iswpunct(wint_t wc); 21812 DESCRIPTION 21813 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21814 conflict between the requirements described here and the ISO C standard is unintentional. This 21815 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21816 The iswpunct( ) function shall test whether wc is a wide-character code representing a character 21817 of class punct in the program's current locale; see the Base Definitions volume of 21818 IEEE Std 1003.1-200x, Chapter 7, Locale. 21819 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21820 code corresponding to a valid character in the current locale, or equal to the value of the macro 21821 WEOF. If the argument has any other value, the behavior is undefined. 21822 RETURN VALUE 21823 The iswpunct( ) function shall return non-zero if wc is a punctuation wide-character code; 21824 otherwise, it shall return 0. 21825 ERRORS 21826 No errors are defined. 21827 EXAMPLES 21828 None. 21829 APPLICATION USAGE 21830 To ensure applications portability, especially across natural languages, only this function and 21831 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21832 RATIONALE 21833 None. 21834 FUTURE DIRECTIONS 21835 None. 21836 SEE ALSO 21837 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 21838 iswspace( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21839 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21840 IEEE Std 1003.1-200x, Chapter 7, Locale 21841 CHANGE HISTORY 21842 First released in Issue 4. 21843 Issue 5 21844 The following change has been made in this issue for alignment with 21845 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21846 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21847 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1133 iswpunct( ) System Interfaces 21848 Issue 6 21849 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1134 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswspace( ) 21850 NAME 21851 iswspace - test for a white-space wide-character code 21852 SYNOPSIS 21853 #include 21854 int iswspace(wint_t wc); 21855 DESCRIPTION 21856 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21857 conflict between the requirements described here and the ISO C standard is unintentional. This 21858 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21859 The iswspace( ) function shall test whether wc is a wide-character code representing a character of 21860 class space in the program's current locale; see the Base Definitions volume of 21861 IEEE Std 1003.1-200x, Chapter 7, Locale. 21862 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21863 code corresponding to a valid character in the current locale, or equal to the value of the macro 21864 WEOF. If the argument has any other value, the behavior is undefined. 21865 RETURN VALUE 21866 The iswspace( ) function shall return non-zero if wc is a white-space wide-character code; 21867 otherwise, it shall return 0. 21868 ERRORS 21869 No errors are defined. 21870 EXAMPLES 21871 None. 21872 APPLICATION USAGE 21873 To ensure applications portability, especially across natural languages, only this function and 21874 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21875 RATIONALE 21876 None. 21877 FUTURE DIRECTIONS 21878 None. 21879 SEE ALSO 21880 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 21881 iswpunct( ), iswupper( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21882 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21883 IEEE Std 1003.1-200x, Chapter 7, Locale 21884 CHANGE HISTORY 21885 First released in Issue 4. 21886 Issue 5 21887 The following change has been made in this issue for alignment with 21888 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21889 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21890 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1135 iswspace( ) System Interfaces 21891 Issue 6 21892 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1136 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswupper( ) 21893 NAME 21894 iswupper - test for an uppercase letter wide-character code 21895 SYNOPSIS 21896 #include 21897 int iswupper(wint_t wc); 21898 DESCRIPTION 21899 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21900 conflict between the requirements described here and the ISO C standard is unintentional. This 21901 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21902 The iswupper( ) function shall test whether wc is a wide-character code representing a character 21903 of class upper in the program's current locale; see the Base Definitions volume of 21904 IEEE Std 1003.1-200x, Chapter 7, Locale. 21905 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21906 code corresponding to a valid character in the current locale, or equal to the value of the macro 21907 WEOF. If the argument has any other value, the behavior is undefined. 21908 RETURN VALUE 21909 The iswupper( ) function shall return non-zero if wc is an uppercase letter wide-character code; 21910 otherwise, it shall return 0. 21911 ERRORS 21912 No errors are defined. 21913 EXAMPLES 21914 None. 21915 APPLICATION USAGE 21916 To ensure applications portability, especially across natural languages, only this function and 21917 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21918 RATIONALE 21919 None. 21920 FUTURE DIRECTIONS 21921 None. 21922 SEE ALSO 21923 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 21924 iswpunct( ), iswspace( ), iswxdigit( ), setlocale( ), the Base Definitions volume of 21925 IEEE Std 1003.1-200x, , , the Base Definitions volume of 21926 IEEE Std 1003.1-200x, Chapter 7, Locale 21927 CHANGE HISTORY 21928 First released in Issue 4. 21929 Issue 5 21930 The following change has been made in this issue for alignment with 21931 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21932 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21933 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 1137 iswupper( ) System Interfaces 21934 Issue 6 21935 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1138 Technical Standard (2001) (Draft April 16, 2001) System Interfaces iswxdigit( ) 21936 NAME 21937 iswxdigit - test for a hexadecimal digit wide-character code 21938 SYNOPSIS 21939 #include 21940 int iswxdigit(wint_t wc); 21941 DESCRIPTION 21942 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21943 conflict between the requirements described here and the ISO C standard is unintentional. This 21944 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21945 The iswxdigit( ) function shall test whether wc is a wide-character code representing a character 21946 of class xdigit in the program's current locale; see the Base Definitions volume of 21947 IEEE Std 1003.1-200x, Chapter 7, Locale. 21948 The wc argument is a wint_t, the value of which the application shall ensure is a wide-character | 21949 code corresponding to a valid character in the current locale, or equal to the value of the macro 21950 WEOF. If the argument has any other value, the behavior is undefined. 21951 RETURN VALUE 21952 The iswxdigit( ) function shall return non-zero if wc is a hexadecimal digit wide-character code; 21953 otherwise, it shall return 0. 21954 ERRORS 21955 No errors are defined. 21956 EXAMPLES 21957 None. 21958 APPLICATION USAGE 21959 To ensure applications portability, especially across natural languages, only this function and 21960 those listed in the SEE ALSO section should be used for classification of wide-character codes. 21961 RATIONALE 21962 None. 21963 FUTURE DIRECTIONS 21964 None. 21965 SEE ALSO 21966 iswalnum( ), iswalpha( ), iswcntrl( ), iswctype( ), iswdigit( ), iswgraph( ), iswlower( ), iswprint( ), 21967 iswpunct( ), iswspace( ), iswupper( ), setlocale( ), the Base Definitions volume of 21968 IEEE Std 1003.1-200x, , 21969 CHANGE HISTORY 21970 First released in Issue 4. 21971 Issue 5 21972 The following change has been made in this issue for alignment with 21973 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 21974 * The SYNOPSIS has been changed to indicate that this function and associated data types are 21975 now made visible by inclusion of the header rather than . 21976 Issue 6 21977 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1139 isxdigit( ) System Interfaces 21978 NAME 21979 isxdigit - test for a hexadecimal digit 21980 SYNOPSIS 21981 #include 21982 int isxdigit(int c); 21983 DESCRIPTION 21984 CX The functionality described on this reference page is aligned with the ISO C standard. Any 21985 conflict between the requirements described here and the ISO C standard is unintentional. This 21986 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 21987 The isxdigit( ) function shall test whether c is a character of class xdigit in the program's current 21988 locale; see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale. 21989 The c argument is an int, the value of which the application shall ensure is a character | 21990 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 21991 any other value, the behavior is undefined. 21992 RETURN VALUE 21993 The isxdigit( ) function shall return non-zero if c is a hexadecimal digit; otherwise, it shall return 21994 0. 21995 ERRORS 21996 No errors are defined. 21997 EXAMPLES 21998 None. 21999 APPLICATION USAGE 22000 To ensure applications portability, especially across natural languages, only this function and 22001 those listed in the SEE ALSO section should be used for character classification. 22002 RATIONALE 22003 None. 22004 FUTURE DIRECTIONS 22005 None. 22006 SEE ALSO 22007 isalnum( ), isalpha( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), isspace( ), isupper( ), 22008 the Base Definitions volume of IEEE Std 1003.1-200x, 22009 CHANGE HISTORY 22010 First released in Issue 1. Derived from Issue 1 of the SVID. 22011 Issue 6 22012 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1140 Technical Standard (2001) (Draft April 16, 2001) System Interfaces j0( ) 22013 NAME 22014 j0, j1, jn - Bessel functions of the first kind 22015 SYNOPSIS 22016 XSI #include 22017 double j0(double x); 22018 double j1(double x); 22019 double jn(int n, double x); 22020 22021 DESCRIPTION 22022 The j0( ), j1( ), and jn( ) functions shall compute Bessel functions of x of the first kind of orders 0, 22023 1, and n, respectively. 22024 An application wishing to check for error situations should set errno to zero and call 22025 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 22026 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 22027 zero, an error has occurred. 22028 RETURN VALUE 22029 Upon successful completion, these functions shall return the relevant Bessel value of x of the 22030 first kind. 22031 If the x argument is too large in magnitude, or the correct result would cause underflow, 0 shall 22032 be returned and a range error may occur. 22033 If x is NaN, a NaN shall be returned. 22034 ERRORS 22035 These functions may fail if: 22036 Range Error The value of x was too large in magnitude, or an underflow occurred. 22037 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22038 then errno shall be set to [ERANGE]. If the integer expression | 22039 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 22040 floating-point exception shall be raised. | 22041 No other errors shall occur. 22042 EXAMPLES 22043 None. 22044 APPLICATION USAGE 22045 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 22046 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 22047 RATIONALE 22048 None. 22049 FUTURE DIRECTIONS 22050 None. 22051 SEE ALSO 22052 feclearexcept( ), fetestexcept( ), isnan( ), y0( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 22053 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | System Interfaces, Issue 6 1141 j0( ) System Interfaces 22054 CHANGE HISTORY 22055 First released in Issue 1. Derived from Issue 1 of the SVID. 22056 Issue 5 22057 The DESCRIPTION is updated to indicate how an application should check for an error. This 22058 text was previously published in the APPLICATION USAGE section. 22059 Issue 6 22060 The may fail [EDOM] error is removed for the case for NaN. 22061 The RETURN VALUE and ERRORS sections are reworked for alignment of the error handling | 22062 with the ISO/IEC 9899: 1999 standard. 1142 Technical Standard (2001) (Draft April 16, 2001) System Interfaces jrand48( ) 22063 NAME 22064 jrand48 - generate a uniformly distributed pseudo-random long signed integer 22065 SYNOPSIS 22066 XSI #include 22067 long jrand48(unsigned short xsubi[3]); | 22068 | 22069 DESCRIPTION 22070 Refer to drand48( ). System Interfaces, Issue 6 1143 kill( ) System Interfaces 22071 NAME 22072 kill - send a signal to a process or a group of processes 22073 SYNOPSIS 22074 CX #include | 22075 int kill(pid_t pid, int sig); 22076 | 22077 DESCRIPTION 22078 The kill( ) function shall send a signal to a process or a group of processes specified by pid. The 22079 signal to be sent is specified by sig and is either one from the list given in or 0. If sig is 22080 0 (the null signal), error checking is performed but no signal is actually sent. The null signal can 22081 be used to check the validity of pid. 22082 For a process to have permission to send a signal to a process designated by pid, unless the | 22083 sending process has appropriate privileges, the real or effective user ID of the sending process | 22084 shall match the real or saved set-user-ID of the receiving process. | 22085 If pid is greater than 0, sig shall be sent to the process whose process ID is equal to pid. 22086 If pid is 0, sig shall be sent to all processes (excluding an unspecified set of system processes) 22087 whose process group ID is equal to the process group ID of the sender, and for which the 22088 process has permission to send a signal. 22089 If pid is -1, sig shall be sent to all processes (excluding an unspecified set of system processes) for 22090 which the process has permission to send that signal. 22091 If pid is negative, but not -1, sig shall be sent to all processes (excluding an unspecified set of 22092 system processes) whose process group ID is equal to the absolute value of pid, and for which 22093 the process has permission to send a signal. 22094 If the value of pid causes sig to be generated for the sending process, and if sig is not blocked for 22095 the calling thread and if no other thread has sig unblocked or is waiting in a sigwait( ) function 22096 for sig, either sig or at least one pending unblocked signal shall be delivered to the sending 22097 thread before kill( ) returns. 22098 The user ID tests described above shall not be applied when sending SIGCONT to a process that 22099 is a member of the same session as the sending process. 22100 An implementation that provides extended security controls may impose further 22101 implementation-defined restrictions on the sending of signals, including the null signal. In 22102 particular, the system may deny the existence of some or all of the processes specified by pid. 22103 The kill( ) function is successful if the process has permission to send sig to any of the processes 22104 specified by pid. If kill( ) fails, no signal shall be sent. 22105 RETURN VALUE 22106 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 22107 indicate the error. 22108 ERRORS 22109 The kill( ) function shall fail if: 22110 [EINVAL] The value of the sig argument is an invalid or unsupported signal number. 22111 [EPERM] The process does not have permission to send the signal to any receiving 22112 process. 22113 [ESRCH] No process or process group can be found corresponding to that specified by 22114 pid. 1144 Technical Standard (2001) (Draft April 16, 2001) System Interfaces kill( ) 22115 EXAMPLES 22116 None. 22117 APPLICATION USAGE 22118 None. 22119 RATIONALE 22120 The semantics for permission checking for kill( ) differed between System V and most other 22121 implementations, such as Version 7 or 4.3 BSD. The semantics chosen for this volume of 22122 IEEE Std 1003.1-200x agree with System V. Specifically, a set-user-ID process cannot protect 22123 itself against signals (or at least not against SIGKILL) unless it changes its real user ID. This 22124 choice allows the user who starts an application to send it signals even if it changes its effective 22125 user ID. The other semantics give more power to an application that wants to protect itself from 22126 the user who ran it. 22127 Some implementations provide semantic extensions to the kill( ) function when the absolute 22128 value of pid is greater than some maximum, or otherwise special, value. Negative values are a 22129 flag to kill( ). Since most implementations return [ESRCH] in this case, this behavior is not 22130 included in this volume of IEEE Std 1003.1-200x, although a conforming implementation could 22131 provide such an extension. 22132 The implementation-defined processes to which a signal cannot be sent may include the 22133 scheduler or init. 22134 There was initially strong sentiment to specify that, if pid specifies that a signal be sent to the 22135 calling process and that signal is not blocked, that signal would be delivered before kill( ) 22136 returns. This would permit a process to call kill( ) and be guaranteed that the call never return. 22137 However, historical implementations that provide only the signal( ) function make only the 22138 weaker guarantee in this volume of IEEE Std 1003.1-200x, because they only deliver one signal 22139 each time a process enters the kernel. Modifications to such implementations to support the 22140 sigaction( ) function generally require entry to the kernel following return from a signal-catching 22141 function, in order to restore the signal mask. Such modifications have the effect of satisfying the 22142 stronger requirement, at least when sigaction( ) is used, but not necessarily when signal( ) is used. 22143 The developers of this volume of IEEE Std 1003.1-200x considered making the stronger 22144 requirement except when signal( ) is used, but felt this would be unnecessarily complex. 22145 Implementors are encouraged to meet the stronger requirement whenever possible. In practice, 22146 the weaker requirement is the same, except in the rare case when two signals arrive during a 22147 very short window. This reasoning also applies to a similar requirement for sigprocmask( ). 22148 In 4.2 BSD, the SIGCONT signal can be sent to any descendant process regardless of user-ID 22149 security checks. This allows a job control shell to continue a job even if processes in the job have 22150 altered their user IDs (as in the su command). In keeping with the addition of the concept of 22151 sessions, similar functionality is provided by allowing the SIGCONT signal to be sent to any 22152 process in the same session regardless of user ID security checks. This is less restrictive than BSD 22153 in the sense that ancestor processes (in the same session) can now be the recipient. It is more 22154 restrictive than BSD in the sense that descendant processes that form new sessions are now 22155 subject to the user ID checks. A similar relaxation of security is not necessary for the other job 22156 control signals since those signals are typically sent by the terminal driver in recognition of 22157 special characters being typed; the terminal driver bypasses all security checks. 22158 In secure implementations, a process may be restricted from sending a signal to a process having 22159 a different security label. In order to prevent the existence or nonexistence of a process from 22160 being used as a covert channel, such processes should appear nonexistent to the sender; that is, 22161 [ESRCH] should be returned, rather than [EPERM], if pid refers only to such processes. System Interfaces, Issue 6 1145 kill( ) System Interfaces 22162 Existing implementations vary on the result of a kill( ) with pid indicating an inactive process (a 22163 terminated process that has not been waited for by its parent). Some indicate success on such a 22164 call (subject to permission checking), while others give an error of [ESRCH]. Since the definition 22165 of process lifetime in this volume of IEEE Std 1003.1-200x covers inactive processes, the 22166 [ESRCH] error as described is inappropriate in this case. In particular, this means that an 22167 application cannot have a parent process check for termination of a particular child with kill( ). 22168 (Usually this is done with the null signal; this can be done reliably with waitpid( ).) 22169 There is some belief that the name kill( ) is misleading, since the function is not always intended 22170 to cause process termination. However, the name is common to all historical implementations, 22171 and any change would be in conflict with the goal of minimal changes to existing application 22172 code. 22173 FUTURE DIRECTIONS 22174 None. 22175 SEE ALSO 22176 getpid( ), raise( ), setsid( ), sigaction( ), sigqueue( ), the Base Definitions volume of 22177 IEEE Std 1003.1-200x, , 22178 CHANGE HISTORY 22179 First released in Issue 1. Derived from Issue 1 of the SVID. 22180 Issue 5 22181 The DESCRIPTION is updated for alignment with POSIX Threads Extension. 22182 Issue 6 22183 In the SYNOPSIS, the optional include of the header is removed. 22184 The following new requirements on POSIX implementations derive from alignment with the 22185 Single UNIX Specification: 22186 * In the DESCRIPTION, the second paragraph is reworded to indicate that the saved set-user- 22187 ID of the calling process is checked in place of its effective user ID. This is a FIPS 22188 requirement. 22189 * The requirement to include has been removed. Although was 22190 required for conforming implementations of previous POSIX specifications, it was not 22191 required for UNIX applications. 22192 * The behavior when pid is -1 is now specified. It was previously explicitly unspecified in the 22193 POSIX.1-1988 standard. 22194 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1146 Technical Standard (2001) (Draft April 16, 2001) System Interfaces killpg( ) 22195 NAME 22196 killpg - send a signal to a process group 22197 SYNOPSIS 22198 XSI #include 22199 int killpg(pid_t pgrp, int sig); 22200 22201 DESCRIPTION 22202 The killpg( ) function shall send the signal specified by sig to the process group specified by pgrp. 22203 If pgrp is greater than 1, killpg(pgrp, sig) shall be equivalent to kill(-pgrp, sig). If pgrp is less than or 22204 equal to 1, the behavior of killpg( ) is undefined. 22205 RETURN VALUE 22206 Refer to kill( ). 22207 ERRORS 22208 Refer to kill( ). 22209 EXAMPLES 22210 None. 22211 APPLICATION USAGE 22212 None. 22213 RATIONALE 22214 None. 22215 FUTURE DIRECTIONS 22216 None. 22217 SEE ALSO 22218 getpgid( ), getpid( ), kill( ), raise( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22219 CHANGE HISTORY 22220 First released in Issue 4, Version 2. 22221 Issue 5 22222 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1147 l64a( ) System Interfaces 22223 NAME 22224 l64a - convert a 32-bit integer to a radix-64 ASCII string 22225 SYNOPSIS 22226 XSI #include 22227 char *l64a(long value); 22228 22229 DESCRIPTION 22230 Refer to a64l( ). 1148 Technical Standard (2001) (Draft April 16, 2001) System Interfaces labs( ) 22231 NAME 22232 labs, llabs - return a long integer absolute value 22233 SYNOPSIS 22234 #include 22235 long labs(long i); 22236 long long llabs(long long i); 22237 DESCRIPTION 22238 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22239 conflict between the requirements described here and the ISO C standard is unintentional. This 22240 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22241 The labs( ) function shall compute the absolute value of the long integer operand i. The llabs( ) 22242 function shall compute the absolute value of the long long integer operand i. If the result cannot 22243 be represented, the behavior is undefined. 22244 RETURN VALUE 22245 The labs( ) function shall return the absolute value of the long integer operand. The labs( ) 22246 function shall return the absolute value of the long long integer operand. 22247 ERRORS 22248 No errors are defined. 22249 EXAMPLES 22250 None. 22251 APPLICATION USAGE 22252 None. 22253 RATIONALE 22254 None. 22255 FUTURE DIRECTIONS 22256 None. 22257 SEE ALSO 22258 abs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22259 CHANGE HISTORY 22260 First released in Issue 4. Derived from the ISO C standard. 22261 Issue 6 22262 The llabs( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1149 lchown( ) System Interfaces 22263 NAME 22264 lchown - change the owner and group of a symbolic link 22265 SYNOPSIS 22266 XSI #include 22267 int lchown(const char *path, uid_t owner, gid_t group); 22268 22269 DESCRIPTION 22270 The lchown( ) function shall be equivalent to chown( ), except in the case where the named file is a | 22271 symbolic link. In this case, lchown( ) shall change the ownership of the symbolic link file itself, 22272 while chown( ) changes the ownership of the file or directory to which the symbolic link refers. 22273 RETURN VALUE 22274 Upon successful completion, lchown( ) shall return 0. Otherwise, it shall return -1 and set errno to 22275 indicate an error. 22276 ERRORS 22277 The lchown( ) function shall fail if: 22278 [EACCES] Search permission is denied on a component of the path prefix of path. 22279 [EINVAL] The owner or group ID is not a value supported by the implementation. 22280 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 22281 argument. 22282 [ENAMETOOLONG] 22283 The length of a pathname exceeds {PATH_MAX} or a pathname component is | 22284 longer than {NAME_MAX}. | 22285 [ENOENT] A component of path does not name an existing file or path is an empty string. 22286 [ENOTDIR] A component of the path prefix of path is not a directory. 22287 [EOPNOTSUPP] The path argument names a symbolic link and the implementation does not 22288 support setting the owner or group of a symbolic link. 22289 [EPERM] The effective user ID does not match the owner of the file and the process 22290 does not have appropriate privileges. 22291 [EROFS] The file resides on a read-only file system. 22292 The lchown( ) function may fail if: 22293 [EIO] An I/O error occurred while reading or writing to the file system. 22294 [EINTR] A signal was caught during execution of the function. 22295 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 22296 resolution of the path argument. 22297 [ENAMETOOLONG] 22298 Pathname resolution of a symbolic link produced an intermediate result | 22299 whose length exceeds {PATH_MAX}. 1150 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lchown( ) 22300 EXAMPLES 22301 Changing the Current Owner of a File 22302 The following example shows how to change the ownership of the symbolic link named 22303 /modules/pass1 to the user ID associated with ``jones'' and the group ID associated with ``cnd''. 22304 The numeric value for the user ID is obtained by using the getpwnam( ) function. The numeric 22305 value for the group ID is obtained by using the getgrnam( ) function. 22306 #include 22307 #include 22308 #include 22309 #include 22310 struct passwd *pwd; 22311 struct group *grp; 22312 char *path = "/modules/pass1"; 22313 ... 22314 pwd = getpwnam("jones"); 22315 grp = getgrnam("cnd"); 22316 lchown(path, pwd->pw_uid, grp->gr_gid); 22317 APPLICATION USAGE 22318 None. 22319 RATIONALE 22320 None. 22321 FUTURE DIRECTIONS 22322 None. 22323 SEE ALSO 22324 chown( ), symlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22325 CHANGE HISTORY 22326 First released in Issue 4, Version 2. 22327 Issue 5 22328 Moved from X/OPEN UNIX extension to BASE. 22329 Issue 6 22330 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 22331 [ELOOP] error condition is added. System Interfaces, Issue 6 1151 lcong48( ) System Interfaces 22332 NAME 22333 lcong48 - seed a uniformly distributed pseudo-random signed long integer generator 22334 SYNOPSIS 22335 XSI #include 22336 void lcong48(unsigned short param[7]); 22337 22338 DESCRIPTION 22339 Refer to drand48( ). 1152 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ldexp( ) 22340 NAME 22341 ldexp, ldexpf, ldexpl - load exponent of a floating-point number 22342 SYNOPSIS 22343 #include | 22344 double ldexp(double x, int exp); 22345 float ldexpf(float x, int exp); 22346 long double ldexpl(long double x, int exp); 22347 DESCRIPTION 22348 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22349 conflict between the requirements described here and the ISO C standard is unintentional. This 22350 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22351 These functions shall compute the quantity x * 2exp. 22352 An application wishing to check for error situations should set errno to zero and call 22353 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 22354 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 22355 zero, an error has occurred. 22356 RETURN VALUE 22357 Upon successful completion, these functions shall return x multiplied by 2, raised to the power 22358 exp. 22359 If these functions would cause overflow, a range error shall occur and ldexp( ), ldexpf( ), and 22360 ldexpl( ) shall return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (according to the sign of 22361 x), respectively. 22362 If the correct value would cause underflow, and is not representable, a range error may occur, 22363 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 22364 MX If x is NaN, a NaN shall be returned. 22365 If x is ±0 or ±Inf, x shall be returned. 22366 If exp is 0, x shall be returned. 22367 If the correct value would cause underflow, and is representable, a range error may occur and 22368 the correct value shall be returned. 22369 ERRORS 22370 These functions shall fail if: 22371 Range Error The result overflows. 22372 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22373 then errno shall be set to [ERANGE]. If the integer expression | 22374 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 22375 floating-point exception shall be raised. | 22376 These functions may fail if: 22377 Range Error The result underflows. 22378 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22379 then errno shall be set to [ERANGE]. If the integer expression | 22380 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 22381 floating-point exception shall be raised. | System Interfaces, Issue 6 1153 ldexp( ) System Interfaces 22382 EXAMPLES 22383 None. 22384 APPLICATION USAGE 22385 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 22386 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 22387 RATIONALE 22388 None. 22389 FUTURE DIRECTIONS 22390 None. 22391 SEE ALSO 22392 feclearexcept( ), fetestexcept( ), frexp( ), isnan( ), the Base Definitions volume of | 22393 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 22394 22395 CHANGE HISTORY 22396 First released in Issue 1. Derived from Issue 1 of the SVID. 22397 Issue 5 22398 The DESCRIPTION is updated to indicate how an application should check for an error. This 22399 text was previously published in the APPLICATION USAGE section. 22400 Issue 6 22401 The ldexpf( ) and ldexpl( ) functions are added for alignment with the ISO/IEC 9899: 1999 22402 standard. 22403 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 22404 revised to align with the ISO/IEC 9899: 1999 standard. 22405 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 22406 marked. 1154 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ldiv( ) 22407 NAME 22408 ldiv, lldiv - compute quotient and remainder of a long division 22409 SYNOPSIS 22410 #include 22411 ldiv_t ldiv(long numer, long denom); 22412 lldiv_t lldiv(long long numer, long long denom); 22413 DESCRIPTION 22414 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22415 conflict between the requirements described here and the ISO C standard is unintentional. This 22416 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22417 These functions shall compute the quotient and remainder of the division of the numerator 22418 numer by the denominator denom. If the division is inexact, the resulting quotient is the long 22419 integer (for the ldiv( ) function) or long long integer (for the lldiv( ) function) of lesser magnitude 22420 that is the nearest to the algebraic quotient. If the result cannot be represented, the behavior is 22421 undefined; otherwise, quot * denom+rem shall equal numer. 22422 RETURN VALUE 22423 The ldiv( ) function shall return a structure of type ldiv_t, comprising both the quotient and the | 22424 remainder. The structure shall include the following members, in any order: | 22425 long quot; /* Quotient */ 22426 long rem; /* Remainder */ 22427 The lldiv( ) function shall return a structure of type lldiv_t, comprising both the quotient and the | 22428 remainder. The structure shall include the following members, in any order: | 22429 long long quot; /* Quotient */ 22430 long long rem; /* Remainder */ 22431 ERRORS 22432 No errors are defined. 22433 EXAMPLES 22434 None. 22435 APPLICATION USAGE 22436 None. 22437 RATIONALE 22438 None. 22439 FUTURE DIRECTIONS 22440 None. 22441 SEE ALSO 22442 div( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22443 CHANGE HISTORY 22444 First released in Issue 4. Derived from the ISO C standard. 22445 Issue 6 22446 The lldiv( ) function is added for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1155 lfind( ) System Interfaces 22447 NAME 22448 lfind - find entry in a linear search table 22449 SYNOPSIS 22450 XSI #include 22451 void *lfind(const void *key, const void *base, size_t *nelp, 22452 size_t width, int (*compar)(const void *, const void *)); 22453 22454 DESCRIPTION 22455 Refer to lsearch( ). 1156 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lgamma( ) 22456 NAME 22457 lgamma, lgammaf, lgammal - log gamma function 22458 SYNOPSIS 22459 #include 22460 double lgamma(double x); 22461 float lgammaf(float x); 22462 long double lgammal(long double x); 22463 XSI extern int signgam; 22464 22465 DESCRIPTION 22466 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22467 conflict between the requirements described here and the ISO C standard is unintentional. This 22468 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22469 These functions shall compute loge ( x) where ( x) is defined as e-ttx-1dt. The argument x 22470 0 22471 need not be a non-positive integer ( ( x) is defined over the reals, except the non-positive 22472 integers). 22473 XSI The sign of ( x) is returned in the external integer signgam. 22474 CX These functions need not be reentrant. A function that is not required to be reentrant is not | 22475 required to be thread-safe. 22476 An application wishing to check for error situations should set errno to zero and call 22477 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 22478 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 22479 zero, an error has occurred. 22480 RETURN VALUE 22481 Upon successful completion, these functions shall return the logarithmic gamma of x. 22482 If x is a non-positive integer, a pole error shall occur and lgamma( ), lgammaf( ), and lgammal( ) 22483 shall return +HUGE_VAL, +HUGE_VALF, and +HUGE_VALL, respectively. 22484 If the correct value would cause overflow, a range error shall occur and lgamma( ), lgammaf( ), 22485 and lgammal( ) shall return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (having the same 22486 sign as the correct value), respectively. 22487 MX If x is NaN, a NaN shall be returned. 22488 If x is 1 or 2, +0 shall be returned. 22489 If x is ±Inf, +Inf shall be returned 22490 ERRORS 22491 These functions shall fail if: 22492 Pole Error The x argument is a negative integer or zero. 22493 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22494 then errno shall be set to [ERANGE]. If the integer expression | 22495 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 22496 zero floating-point exception shall be raised. | 22497 Range Error The result overflows System Interfaces, Issue 6 1157 lgamma( ) System Interfaces 22498 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22499 then errno shall be set to [ERANGE]. If the integer expression | 22500 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 22501 floating-point exception shall be raised. | 22502 EXAMPLES 22503 None. 22504 APPLICATION USAGE 22505 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 22506 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 22507 RATIONALE 22508 None. 22509 FUTURE DIRECTIONS 22510 None. 22511 SEE ALSO 22512 exp( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 22513 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 22514 CHANGE HISTORY 22515 First released in Issue 3. 22516 Issue 5 22517 The DESCRIPTION is updated to indicate how an application should check for an error. This 22518 text was previously published in the APPLICATION USAGE section. 22519 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 22520 Issue 6 22521 The lgamma( ) function is no longer marked as an extension. 22522 The lgammaf( ) and lgammal( ) functions are added for alignment with the ISO/IEC 9899: 1999 22523 standard. 22524 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 22525 revised to align with the ISO/IEC 9899: 1999 standard. 22526 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 22527 marked. 22528 XSI extensions are marked. 1158 Technical Standard (2001) (Draft April 16, 2001) System Interfaces link( ) 22529 NAME 22530 link - link to a file 22531 SYNOPSIS 22532 #include 22533 int link(const char *path1, const char *path2); 22534 DESCRIPTION 22535 The link( ) function shall create a new link (directory entry) for the existing file, path1. 22536 The path1 argument points to a pathname naming an existing file. The path2 argument points to | 22537 a pathname naming the new directory entry to be created. The link( ) function shall atomically | 22538 create a new link for the existing file and the link count of the file shall be incremented by one. 22539 If path1 names a directory, link( ) shall fail unless the process has appropriate privileges and the 22540 implementation supports using link( ) on directories. 22541 Upon successful completion, link( ) shall mark for update the st_ctime field of the file. Also, the 22542 st_ctime and st_mtime fields of the directory that contains the new entry shall be marked for 22543 update. 22544 If link( ) fails, no link shall be created and the link count of the file shall remain unchanged. 22545 The implementation may require that the calling process has permission to access the existing 22546 file. 22547 RETURN VALUE 22548 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 22549 indicate the error. 22550 ERRORS 22551 The link( ) function shall fail if: 22552 [EACCES] A component of either path prefix denies search permission, or the requested 22553 link requires writing in a directory that denies write permission, or the calling 22554 process does not have permission to access the existing file and this is 22555 required by the implementation. 22556 [EEXIST] The path2 argument resolves to an existing file or refers to a symbolic link. 22557 [ELOOP] A loop exists in symbolic links encountered during resolution of the path1 or 22558 path2 argument. 22559 [EMLINK] The number of links to the file named by path1 would exceed {LINK_MAX}. 22560 [ENAMETOOLONG] 22561 The length of the path1 or path2 argument exceeds {PATH_MAX} or a | 22562 pathname component is longer than {NAME_MAX}. | 22563 [ENOENT] A component of either path prefix does not exist; the file named by path1 does 22564 not exist; or path1 or path2 points to an empty string. 22565 [ENOSPC] The directory to contain the link cannot be extended. 22566 [ENOTDIR] A component of either path prefix is not a directory. 22567 [EPERM] The file named by path1 is a directory and either the calling process does not 22568 have appropriate privileges or the implementation prohibits using link( ) on 22569 directories. System Interfaces, Issue 6 1159 link( ) System Interfaces 22570 [EROFS] The requested link requires writing in a directory on a read-only file system. 22571 [EXDEV] The link named by path2 and the file named by path1 are on different file 22572 XSR systems and the implementation does not support links between file systems, 22573 or path1 refers to a named STREAM. 22574 The link( ) function may fail if: 22575 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 22576 resolution of the path1 or path2 argument. 22577 [ENAMETOOLONG] 22578 As a result of encountering a symbolic link in resolution of the path1 or path2 | 22579 argument, the length of the substituted pathname string exceeded | 22580 {PATH_MAX}. 22581 EXAMPLES 22582 Creating a Link to a File 22583 The following example shows how to create a link to a file named /home/cnd/mod1 by creating a 22584 new directory entry named /modules/pass1. 22585 #include 22586 char *path1 = "/home/cnd/mod1"; 22587 char *path2 = "/modules/pass1"; 22588 int status; 22589 ... 22590 status = link (path1, path2); 22591 Creating a Link to a File Within a Program 22592 In the following program example, the link( ) function links the /etc/passwd file (defined as | 22593 PASSWDFILE) to a file named /etc/opasswd (defined as SAVEFILE), which is used to save the 22594 current password file. Then, after removing the current password file (defined as 22595 PASSWDFILE), the new password file is saved as the current password file using the link( ) 22596 function again. 22597 #include 22598 #define LOCKFILE "/etc/ptmp" 22599 #define PASSWDFILE "/etc/passwd" 22600 #define SAVEFILE "/etc/opasswd" 22601 ... 22602 /* Save current password file */ 22603 link (PASSWDFILE, SAVEFILE); 22604 /* Remove current password file. */ 22605 unlink (PASSWDFILE); 22606 /* Save new password file as current password file. */ 22607 link (LOCKFILE,PASSWDFILE); 22608 APPLICATION USAGE 22609 Some implementations do allow links between file systems. 1160 Technical Standard (2001) (Draft April 16, 2001) System Interfaces link( ) 22610 RATIONALE 22611 Linking to a directory is restricted to the superuser in most historical implementations because 22612 this capability may produce loops in the file hierarchy or otherwise corrupt the file system. This 22613 volume of IEEE Std 1003.1-200x continues that philosophy by prohibiting link( ) and unlink( ) 22614 from doing this. Other functions could do it if the implementor designed such an extension. 22615 Some historical implementations allow linking of files on different file systems. Wording was 22616 added to explicitly allow this optional behavior. | 22617 The exception for cross-file system links is intended to apply only to links that are 22618 programmatically indistinguishable from ``hard'' links. 22619 FUTURE DIRECTIONS 22620 None. 22621 SEE ALSO 22622 symlink( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22623 CHANGE HISTORY 22624 First released in Issue 1. Derived from Issue 1 of the SVID. 22625 Issue 6 22626 The following new requirements on POSIX implementations derive from alignment with the | 22627 Single UNIX Specification: 22628 * The [ELOOP] mandatory error condition is added. 22629 * A second [ENAMETOOLONG] is added as an optional error condition. 22630 The following changes were made to align with the IEEE P1003.1a draft standard: 22631 * An explanation is added of action when path2 refers to a symbolic link. 22632 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1161 lio_listio( ) System Interfaces 22633 NAME 22634 lio_listio - list directed I/O (REALTIME) 22635 SYNOPSIS 22636 AIO #include 22637 int lio_listio(int mode, struct aiocb *restrict const list[restrict], 22638 int nent, struct sigevent *restrict sig); 22639 22640 DESCRIPTION 22641 The lio_listio ( ) function shall initiate a list of I/O requests with a single function call. | 22642 The mode argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in and 22643 determines whether the function returns when the I/O operations have been completed, or as 22644 soon as the operations have been queued. If the mode argument is LIO_WAIT, the function shall 22645 wait until all I/O is complete and the sig argument shall be ignored. 22646 If the mode argument is LIO_NOWAIT, the function shall return immediately, and asynchronous 22647 notification shall occur, according to the sig argument, when all the I/O operations complete. If 22648 sig is NULL, then no asynchronous notification shall occur. If sig is not NULL, asynchronous 22649 notification occurs as specified in Section 2.4.1 (on page 478) when all the requests in list have 22650 completed. 22651 The I/O requests enumerated by list are submitted in an unspecified order. 22652 The list argument is an array of pointers to aiocb structures. The array contains nent elements. 22653 The array may contain NULL elements, which shall be ignored. 22654 The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The 22655 supported operations are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in 22656 . The LIO_NOP operation causes the list entry to be ignored. If the aio_lio_opcode 22657 element is equal to LIO_READ, then an I/O operation is submitted as if by a call to aio_read( ) 22658 with the aiocbp equal to the address of the aiocb structure. If the aio_lio_opcode element is equal 22659 to LIO_WRITE, then an I/O operation is submitted as if by a call to aio_write( ) with the aiocbp 22660 equal to the address of the aiocb structure. 22661 The aio_fildes member specifies the file descriptor on which the operation is to be performed. 22662 The aio_buf member specifies the address of the buffer to or from which the data is transferred. 22663 The aio_nbytes member specifies the number of bytes of data to be transferred. 22664 The members of the aiocb structure further describe the I/O operation to be performed, in a 22665 manner identical to that of the corresponding aiocb structure when used by the aio_read( ) and 22666 aio_write( ) functions. 22667 The nent argument specifies how many elements are members of the list; that is, the length of the 22668 array. 22669 The behavior of this function is altered according to the definitions of synchronized I/O data 22670 integrity completion and synchronized I/O file integrity completion if synchronized I/O is 22671 enabled on the file associated with aio_fildes . 22672 For regular files, no data transfer shall occur past the offset maximum established in the open 22673 file description associated with aiocbp->aio_fildes. 1162 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lio_listio( ) 22674 RETURN VALUE 22675 If the mode argument has the value LIO_NOWAIT, the lio_listio ( ) function shall return the value 22676 zero if the I/O operations are successfully queued; otherwise, the function shall return the value 22677 -1 and set errno to indicate the error. 22678 If the mode argument has the value LIO_WAIT, the lio_listio ( ) function shall return the value 22679 zero when all the indicated I/O has completed successfully. Otherwise, lio_listio ( ) shall return a 22680 value of -1 and set errno to indicate the error. 22681 In either case, the return value only indicates the success or failure of the lio_listio ( ) call itself, 22682 not the status of the individual I/O requests. In some cases one or more of the I/O requests 22683 contained in the list may fail. Failure of an individual request does not prevent completion of 22684 any other individual request. To determine the outcome of each I/O request, the application 22685 shall examine the error status associated with each aiocb control block. The error statuses so 22686 returned are identical to those returned as the result of an aio_read( ) or aio_write( ) function. 22687 ERRORS 22688 The lio_listio ( ) function shall fail if: 22689 [EAGAIN] The resources necessary to queue all the I/O requests were not available. The 22690 application may check the error status for each aiocb to determine the 22691 individual request(s) that failed. 22692 [EAGAIN] The number of entries indicated by nent would cause the system-wide limit 22693 {AIO_MAX} to be exceeded. 22694 [EINVAL] The mode argument is not a proper value, or the value of nent was greater than 22695 {AIO_LISTIO_MAX}. 22696 [EINTR] A signal was delivered while waiting for all I/O requests to complete during 22697 an LIO_WAIT operation. Note that, since each I/O operation invoked by 22698 lio_listio ( ) may possibly provoke a signal when it completes, this error return 22699 may be caused by the completion of one (or more) of the very I/O operations 22700 being awaited. Outstanding I/O requests are not canceled, and the application 22701 shall examine each list element to determine whether the request was 22702 initiated, canceled, or completed. 22703 [EIO] One or more of the individual I/O operations failed. The application may 22704 check the error status for each aiocb structure to determine the individual 22705 request(s) that failed. 22706 In addition to the errors returned by the lio_listio ( ) function, if the lio_listio ( ) function succeeds 22707 or fails with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified by the list 22708 may have been initiated. If the lio_listio ( ) function fails with an error code other than [EAGAIN], 22709 [EINTR], or [EIO], no operations from the list shall have been initiated. The I/O operation 22710 indicated by each list element can encounter errors specific to the individual read or write 22711 function being performed. In this event, the error status for each aiocb control block contains the 22712 associated error code. The error codes that can be set are the same as would be set by a read( ) or 22713 write( ) function, with the following additional error codes possible: 22714 [EAGAIN] The requested I/O operation was not queued due to resource limitations. 22715 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit 22716 aio_cancel( ) request. 22717 [EFBIG] The aiocbp->aio_lio_opcode is LIO_WRITE, the file is a regular file, aiocbp- 22718 >aio_nbytes is greater than 0, and the aiocbp->aio_offset is greater than or equal 22719 to the offset maximum in the open file description associated with aiocbp- System Interfaces, Issue 6 1163 lio_listio( ) System Interfaces 22720 >aio_fildes. 22721 [EINPROGRESS] The requested I/O is in progress. 22722 [EOVERFLOW] The aiocbp->aio_lio_opcode is LIO_READ, the file is a regular file, aiocbp- 22723 >aio_nbytes is greater than 0, and the aiocbp->aio_offset is before the end-of-file 22724 and is greater than or equal to the offset maximum in the open file description 22725 associated with aiocbp->aio_fildes. 22726 EXAMPLES 22727 None. 22728 APPLICATION USAGE 22729 None. 22730 RATIONALE 22731 Although it may appear that there are inconsistencies in the specified circumstances for error 22732 codes, the [EIO] error condition applies when any circumstance relating to an individual 22733 operation makes that operation fail. This might be due to a badly formulated request (for 22734 example, the aio_lio_opcode field is invalid, and aio_error( ) returns [EINVAL]) or might arise from 22735 application behavior (for example, the file descriptor is closed before the operation is initiated, 22736 and aio_error( ) returns [EBADF]). 22737 The limitation on the set of error codes returned when operations from the list shall have been 22738 initiated enables applications to know when operations have been started and whether 22739 aio_error( ) is valid for a specific operation. 22740 FUTURE DIRECTIONS 22741 None. 22742 SEE ALSO 22743 aio_read( ), aio_write( ), aio_error( ), aio_return( ), aio_cancel( ), close( ), exec, exit( ), fork( ), lseek( ), 22744 read( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22745 CHANGE HISTORY 22746 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 22747 Large File Summit extensions are added. 22748 Issue 6 22749 The [ENOSYS] error condition has been removed as stubs need not be provided if an 22750 implementation does not support the Asynchronous Input and Output option. 22751 The lio_listio ( ) function is marked as part of the Asynchronous Input and Output option. 22752 The following new requirements on POSIX implementations derive from alignment with the 22753 Single UNIX Specification: 22754 * In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 22755 past the offset maximum established in the open file description associated with aiocbp- 22756 >aio_fildes. This change is to support large files. 22757 * The [EBIG] and [EOVERFLOW] error conditions are defined. This change is to support large 22758 files. 22759 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 22760 The restrict keyword is added to the lio_listio ( ) prototype for alignment with the 22761 ISO/IEC 9899: 1999 standard. 1164 Technical Standard (2001) (Draft April 16, 2001) System Interfaces listen( ) 22762 NAME 22763 listen - listen for socket connections and limit the queue of incoming connections 22764 SYNOPSIS 22765 #include 22766 int listen(int socket, int backlog); 22767 DESCRIPTION 22768 The listen( ) function shall mark a connection-mode socket, specified by the socket argument, as 22769 accepting connections. 22770 The backlog argument provides a hint to the implementation which the implementation shall use 22771 to limit the number of outstanding connections in the socket's listen queue. Implementations 22772 may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog 22773 argument value shall result in a larger or equal length of the listen queue. Implementations shall 22774 support values of backlog up to SOMAXCONN, defined in . 22775 The implementation may include incomplete connections in its listen queue. The limits on the 22776 number of incomplete connections and completed connections queued may be different. 22777 The implementation may have an upper limit on the length of the listen queue-either global or 22778 per accepting socket. If backlog exceeds this limit, the length of the listen queue is set to the limit. 22779 If listen( ) is called with a backlog argument value that is less than 0, the function behaves as if it 22780 had been called with a backlog argument value of 0. 22781 A backlog argument of 0 may allow the socket to accept connections, in which case the length of 22782 the listen queue may be set to an implementation-defined minimum value. 22783 The socket in use may require the process to have appropriate privileges to use the listen( ) 22784 function. 22785 RETURN VALUE 22786 Upon successful completions, listen( ) shall return 0; otherwise, -1 shall be returned and errno set 22787 to indicate the error. 22788 ERRORS 22789 The listen( ) function shall fail if: 22790 [EBADF] The socket argument is not a valid file descriptor. 22791 [EDESTADDRREQ] 22792 The socket is not bound to a local address, and the protocol does not support 22793 listening on an unbound socket. 22794 [EINVAL] The socket is already connected. 22795 [ENOTSOCK] The socket argument does not refer to a socket. 22796 [EOPNOTSUPP] The socket protocol does not support listen( ). 22797 The listen( ) function may fail if: 22798 [EACCES] The calling process does not have the appropriate privileges. 22799 [EINVAL] The socket has been shut down. 22800 [ENOBUFS] Insufficient resources are available in the system to complete the call. System Interfaces, Issue 6 1165 listen( ) System Interfaces 22801 EXAMPLES 22802 None. 22803 APPLICATION USAGE 22804 None. 22805 RATIONALE 22806 None. 22807 FUTURE DIRECTIONS 22808 None. 22809 SEE ALSO 22810 accept( ), connect( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 22811 CHANGE HISTORY 22812 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 22813 The DESCRIPTION is updated to describe the relationship of SOMAXCONN and the backlog 22814 argument. 1166 Technical Standard (2001) (Draft April 16, 2001) System Interfaces llabs( ) 22815 NAME 22816 llabs - return a long integer absolute value 22817 SYNOPSIS 22818 #include 22819 long long llabs(long long i); 22820 DESCRIPTION 22821 Refer to labs( ). System Interfaces, Issue 6 1167 lldiv( ) System Interfaces 22822 NAME 22823 lldiv - compute quotient and remainder of a long division 22824 SYNOPSIS 22825 #include 22826 lldiv_t lldiv(long long numer, long long denom); 22827 DESCRIPTION 22828 Refer to ldiv( ). 1168 Technical Standard (2001) (Draft April 16, 2001) System Interfaces llrint( ) 22829 NAME 22830 llrint, llrintf, llrintl, - round to nearest integer value using current rounding direction 22831 SYNOPSIS 22832 #include 22833 long long llrint(double x); 22834 long long llrintf(float x); 22835 long long llrintl(long double x); 22836 DESCRIPTION 22837 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22838 conflict between the requirements described here and the ISO C standard is unintentional. This 22839 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22840 These functions shall round their argument to the nearest integer value, rounding according to 22841 the current rounding direction. 22842 An application wishing to check for error situations should set errno to zero and call 22843 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 22844 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 22845 zero, an error has occurred. 22846 RETURN VALUE 22847 Upon successful completion, these functions shall return the rounded integer value. 22848 MX If x is NaN, a domain error shall occur, and an unspecified value is returned. 22849 If x is +Inf, a domain error shall occur and an unspecified value is returned. 22850 If x is -Inf, a domain error shall occur and an unspecified value is returned. 22851 If the correct value is positive and too large to represent as a long long, a domain error shall | 22852 occur and an unspecified value is returned. | 22853 If the correct value is negative and too large to represent as a long long, a domain error shall | 22854 occur and an unspecified value is returned. | 22855 ERRORS 22856 These functions shall fail if: 22857 MX Domain Error The x argument is NaN or ±Inf, or the correct value is not representable as an 22858 integer. 22859 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22860 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 22861 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 22862 shall be raised. | 22863 EXAMPLES 22864 None. 22865 APPLICATION USAGE 22866 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 22867 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 22868 RATIONALE 22869 These functions provide floating-to-integer conversions. They round according to the current 22870 rounding direction. If the rounded value is outside the range of the return type, the numeric 22871 result is unspecified and the invalid floating-point exception is raised. When they raise no other 22872 floating-point exception and the result differs from the argument, they raise the inexact System Interfaces, Issue 6 1169 llrint( ) System Interfaces 22873 floating-point exception. 22874 FUTURE DIRECTIONS 22875 None. 22876 SEE ALSO 22877 feclearexcept( ), fetestexcept( ), lrint( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 22878 4.18, Treatment of Error Conditions for Mathematical Functions, | 22879 CHANGE HISTORY 22880 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1170 Technical Standard (2001) (Draft April 16, 2001) System Interfaces llround( ) 22881 NAME 22882 llround, llroundf, llroundl, - round to nearest integer value 22883 SYNOPSIS 22884 #include 22885 long long llround(double x); 22886 long long llroundf(float x); 22887 long long llroundl(long double x); 22888 DESCRIPTION 22889 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22890 conflict between the requirements described here and the ISO C standard is unintentional. This 22891 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22892 These functions shall round their argument to the nearest integer value, rounding halfway cases 22893 away from zero, regardless of the current rounding direction. 22894 An application wishing to check for error situations should set errno to zero and call 22895 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 22896 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 22897 zero, an error has occurred. 22898 RETURN VALUE 22899 Upon successful completion, these functions shall return the rounded integer value. 22900 MX If x is NaN, a domain error shall occur, and an unspecified value is returned. 22901 If x is +Inf, a domain error shall occur and an unspecified value is returned. 22902 If x is -Inf, a domain error shall occur and an unspecified value is returned. 22903 If the correct value is positive and too large to represent as a long long, a domain error shall | 22904 occur and an unspecified value is returned. 22905 If the correct value is negative and too large to represent as a long long, a domain error shall | 22906 occur and an unspecified value is returned. 22907 ERRORS 22908 These functions shall fail if: 22909 MX Domain Error The x argument is NaN or ±Inf, or the correct value is not representable as an 22910 integer. 22911 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 22912 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 22913 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 22914 shall be raised. | 22915 EXAMPLES 22916 None. 22917 APPLICATION USAGE 22918 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 22919 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 22920 RATIONALE 22921 These functions provide floating-to-integer conversions. They round according to the current 22922 rounding direction. If the rounded value is outside the range of the return type, the numeric 22923 result is unspecified and the invalid floating-point exception is raised. When they raise no other 22924 floating-point exception and the result differs from the argument, they raise the inexact System Interfaces, Issue 6 1171 llround( ) System Interfaces 22925 floating-point exception. 22926 These functions differ from the llrint( ) functions in that the default rounding direction for the 22927 llround( ) functions round halfway cases away from zero and need not raise the inexact floating- 22928 point exception for non-integer arguments that round to within the range of the return type. 22929 FUTURE DIRECTIONS 22930 None. 22931 SEE ALSO 22932 feclearexcept( ), fetestexcept( ), lround( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 22933 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 22934 CHANGE HISTORY 22935 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1172 Technical Standard (2001) (Draft April 16, 2001) System Interfaces localeconv( ) 22936 NAME 22937 localeconv - return locale-specific information 22938 SYNOPSIS 22939 #include 22940 struct lconv *localeconv(void); 22941 DESCRIPTION 22942 CX The functionality described on this reference page is aligned with the ISO C standard. Any 22943 conflict between the requirements described here and the ISO C standard is unintentional. This 22944 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 22945 The localeconv( ) function shall set the components of an object with the type struct lconv with 22946 the values appropriate for the formatting of numeric quantities (monetary and otherwise) 22947 according to the rules of the current locale. 22948 The members of the structure with type char * are pointers to strings, any of which (except 22949 decimal_point) can point to " ", to indicate that the value is not available in the current locale or 22950 is of zero length. The members with type char are non-negative numbers, any of which can be 22951 {CHAR_MAX} to indicate that the value is not available in the current locale. 22952 The members include the following: 22953 char *decimal_point 22954 The radix character used to format non-monetary quantities. 22955 char *thousands_sep 22956 The character used to separate groups of digits before the decimal-point character in 22957 formatted non-monetary quantities. 22958 char *grouping 22959 A string whose elements taken as one-byte integer values indicate the size of each group of 22960 digits in formatted non-monetary quantities. 22961 char *int_curr_symbol 22962 The international currency symbol applicable to the current locale. The first three 22963 characters contain the alphabetic international currency symbol in accordance with those 22964 specified in the ISO 4217: 1995 standard. The fourth character (immediately preceding the 22965 null byte) is the character used to separate the international currency symbol from the 22966 monetary quantity. 22967 char *currency_symbol 22968 The local currency symbol applicable to the current locale. 22969 char *mon_decimal_point 22970 The radix character used to format monetary quantities. 22971 char *mon_thousands_sep 22972 The separator for groups of digits before the decimal-point in formatted monetary 22973 quantities. 22974 char *mon_grouping 22975 A string whose elements taken as one-byte integer values indicate the size of each group of 22976 digits in formatted monetary quantities. 22977 char *positive_sign 22978 The string used to indicate a non-negative valued formatted monetary quantity. System Interfaces, Issue 6 1173 localeconv( ) System Interfaces 22979 char *negative_sign 22980 The string used to indicate a negative valued formatted monetary quantity. 22981 char int_frac_digits 22982 The number of fractional digits (those after the decimal-point) to be displayed in an 22983 internationally formatted monetary quantity. 22984 char frac_digits 22985 The number of fractional digits (those after the decimal-point) to be displayed in a 22986 formatted monetary quantity. 22987 char p_cs_precedes 22988 Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a non-negative 22989 formatted monetary quantity. Set to 0 if the symbol succeeds the value. 22990 char p_sep_by_space 22991 Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a 22992 non-negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 22993 XSI value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 22994 char n_cs_precedes 22995 Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a negative 22996 formatted monetary quantity. Set to 0 if the symbol succeeds the value. 22997 char n_sep_by_space 22998 Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a 22999 negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 23000 XSI value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 23001 char p_sign_posn 23002 Set to a value indicating the positioning of the positive_sign for a non-negative formatted 23003 monetary quantity. 23004 char n_sign_posn 23005 Set to a value indicating the positioning of the negative_sign for a negative formatted 23006 monetary quantity. 23007 char int_p_cs_precedes 23008 Set to 1 or 0 if the int_curr_symbol respectively precedes or succeeds the value for a non- | 23009 negative internationally formatted monetary quantity. 23010 char int_n_cs_precedes 23011 Set to 1 or 0 if the int_curr_symbol respectively precedes or succeeds the value for a | 23012 negative internationally formatted monetary quantity. 23013 char int_p_sep_by_space 23014 Set to a value indicating the separation of the int_curr_symbol, the sign string, and the | 23015 value for a non-negative internationally formatted monetary quantity. 23016 char int_n_sep_by_space 23017 Set to a value indicating the separation of the int_curr_symbol, the sign string, and the | 23018 value for a negative internationally formatted monetary quantity. 23019 char int_p_sign_posn 23020 Set to a value indicating the positioning of the positive_sign for a non-negative 23021 internationally formatted monetary quantity. 23022 char int_n_sign_posn 23023 Set to a value indicating the positioning of the negative_sign for a negative internationally 1174 Technical Standard (2001) (Draft April 16, 2001) System Interfaces localeconv( ) 23024 formatted monetary quantity. 23025 The elements of grouping and mon_grouping are interpreted according to the following: 23026 {CHAR_MAX} No further grouping is to be performed. 23027 0 The previous element is to be repeatedly used for the remainder of the digits. 23028 other The integer value is the number of digits that comprise the current group. The 23029 next element is examined to determine the size of the next group of digits 23030 before the current group. 23031 The values of p_sep_by_space, n_sep_by_space, int_p_sep_by_space, and int_n_sep_by_space 23032 are interpreted according to the following: 23033 0 No space separates the currency symbol and value. 23034 1 If the currency symbol and sign string are adjacent, a space separates them from the value; 23035 otherwise, a space separates the currency symbol from the value. 23036 2 If the currency symbol and sign string are adjacent, a space separates them; otherwise, a 23037 space separates the sign string from the value. 23038 For int_p_sep_by_space and int_n_sep_by_space, the fourth character of int_curr_symbol is | 23039 used instead of a space. | 23040 The values of p_sign_posn, n_sign_posn, int_p_sign_posn, and int_n_sign_posn are | 23041 interpreted according to the following: 23042 0 Parentheses surround the quantity and currency_symbol or int_curr_symbol. 23043 1 The sign string precedes the quantity and currency_symbol or int_curr_symbol. 23044 2 The sign string succeeds the quantity and currency_symbol or int_curr_symbol. 23045 3 The sign string immediately precedes the currency_symbol or int_curr_symbol. 23046 4 The sign string immediately succeeds the currency_symbol or int_curr_symbol. 23047 The implementation shall behave as if no function in this volume of IEEE Std 1003.1-200x calls 23048 localeconv( ). 23049 CX The localeconv( ) function need not be reentrant. A function that is not required to be reentrant is 23050 not required to be thread-safe. 23051 RETURN VALUE 23052 The localeconv( ) function shall return a pointer to the filled-in object. The application shall not 23053 modify the structure pointed to by the return value which may be overwritten by a subsequent 23054 call to localeconv( ). In addition, calls to setlocale( ) with the categories LC_ALL, LC_MONETARY, 23055 or LC_NUMERIC may overwrite the contents of the structure. 23056 ERRORS 23057 No errors are defined. System Interfaces, Issue 6 1175 localeconv( ) System Interfaces 23058 EXAMPLES 23059 None. 23060 APPLICATION USAGE 23061 The following table illustrates the rules which may be used by four countries to format monetary 23062 quantities. ______________________________________________________________________ | 23063 _ Country Positive Format Negative Format International Format _____________________________________________________________________ || 23064 Italy L.1.230 -L.1.230 ITL.1.230 | 23065 Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56 | 23066 Norway kr1.234,56 kr1.234,56- NOK 1.234,56 | 23067 _ Switzerland SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 _____________________________________________________________________ ||||||| 23068 For these four countries, the respective values for the monetary members of the structure 23069 returned by localeconv( ) are: ______________________________________________________________________ | 23070 _ Italy Netherlands Norway Switzerland _____________________________________________________________________ || 23071 int_curr_symbol "ITL." "NLG " "NOK " "CHF " | 23072 currency_symbol "L." "F" "kr" "SFrs." | 23073 mon_decimal_point "" "," "," "." | 23074 mon_thousands_sep "." "." "." "," | 23075 mon_grouping "\3" "\3" "\3" "\3" | 23076 positive_sign "" "" "" "" | 23077 negative_sign "-" "-" "-" "C" | 23078 int_frac_digits 0 2 2 2 | 23079 frac_digits 0 2 2 2 | 23080 p_cs_precedes 1 1 1 1 | 23081 p_sep_by_space 0 1 0 0 | 23082 n_cs_precedes 1 1 1 1 | 23083 n_sep_by_space 0 1 0 0 | 23084 p_sign_posn 1 1 1 1 | 23085 n_sign_posn 1 4 2 2 | 23086 int_p_cs_precedes 1 1 1 1 | 23087 int_n_cs_precedes 1 1 1 1 | 23088 int_p_sep_by_space 0 0 0 0 | 23089 int_n_sep_by_space 0 0 0 0 | 23090 int_p_sign_posn 1 1 1 1 | 23091 _ int_n_sign_posn 1 4 4 2 _____________________________________________________________________ |||||||| 23092 RATIONALE 23093 None. 23094 FUTURE DIRECTIONS 23095 None. 23096 SEE ALSO 23097 isalpha( ), isascii( ), nl_langinfo ( ), printf( ), scanf( ), setlocale( ), strcat( ), strchr( ), strcmp( ), strcoll( ), 23098 strcpy( ), strftime( ), strlen( ), strpbrk( ), strspn( ), strtok( ), strxfrm( ), strtod( ), the Base Definitions 23099 volume of IEEE Std 1003.1-200x, , 23100 CHANGE HISTORY 23101 First released in Issue 4. Derived from the ANSI C standard. 1176 Technical Standard (2001) (Draft April 16, 2001) System Interfaces localeconv( ) 23102 Issue 6 23103 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 23104 The RETURN VALUE section is rewritten to avoid use of the term ``must''. 23105 This reference page is updated for alignment with the ISO/IEC 9899: 1999 standard. | 23106 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 1177 localtime( ) System Interfaces 23107 NAME 23108 localtime, localtime_r - convert a time value to a broken-down local time 23109 SYNOPSIS 23110 #include 23111 struct tm *localtime(const time_t *timer); 23112 TSF struct tm *localtime_r(const time_t *restrict timer, 23113 struct tm *restrict result); 23114 23115 DESCRIPTION 23116 CX For localtime( ): The functionality described on this reference page is aligned with the ISO C 23117 standard. Any conflict between the requirements described here and the ISO C standard is 23118 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23119 The localtime( ) function shall convert the time in seconds since the Epoch pointed to by timer 23120 into a broken-down time, expressed as a local time. The function corrects for the timezone and 23121 CX any seasonal time adjustments. Local timezone information is used as though localtime( ) calls 23122 tzset( ). 23123 The relationship between a time in seconds since the Epoch used as an argument to localtime( ) | 23124 and the tm structure (defined in the header) is that the result shall be as specified in the | 23125 expression given in the definition of seconds since the Epoch (see the Base Definitions volume of | 23126 IEEE Std 1003.1-200x, Section 4.14, Seconds Since the Epoch) corrected for timezone and any | 23127 seasonal time adjustments, where the names in the structure and in the expression correspond. | 23128 TSF The same relationship shall apply for localtime_r( ). | 23129 CX The localtime( ) function need not be reentrant. A function that is not required to be reentrant is | 23130 not required to be thread-safe. | 23131 The asctime( ), ctime( ), gmtime( ), and localtime( ) functions shall return values in one of two static | 23132 objects: a broken-down time structure and an array of type char. Execution of any of the | 23133 functions may overwrite the information returned in either of these objects by any of the other | 23134 functions. | 23135 TSF The localtime_r( ) function shall convert the time in seconds since the Epoch pointed to by timer 23136 into a broken-down time stored in the structure to which result points. The localtime_r( ) function 23137 shall also return a pointer to that same structure. 23138 Unlike localtime( ), the reentrant version is not required to set tzname. 23139 RETURN VALUE 23140 The localtime( ) function shall return a pointer to the broken-down time structure. 23141 TSF Upon successful completion, localtime_r( ) shall return a pointer to the structure pointed to by 23142 the argument result. 23143 ERRORS 23144 No errors are defined. 1178 Technical Standard (2001) (Draft April 16, 2001) System Interfaces localtime( ) 23145 EXAMPLES 23146 Getting the Local Date and Time 23147 The following example uses the time( ) function to calculate the time elapsed, in seconds, since 23148 January 1, 1970 0:00 UTC (the Epoch), localtime( ) to convert that value to a broken-down time, 23149 and asctime( ) to convert the broken-down time values into a printable string. 23150 #include 23151 #include 23152 main() 23153 { 23154 time_t result; 23155 result = time(NULL); 23156 printf("%s%ld secs since the Epoch\n", 23157 asctime(localtime(&result)), 23158 (long)result); 23159 return(0); 23160 } 23161 This example writes the current time to stdout in a form like this: 23162 Wed Jun 26 10:32:15 1996 23163 835810335 secs since the Epoch 23164 Getting the Modification Time for a File 23165 The following example gets the modification time for a file. The localtime( ) function converts the 23166 time_t value of the last modification date, obtained by a previous call to stat( ), into a tm 23167 structure that contains the year, month, day, and so on. 23168 #include 23169 ... 23170 struct stat statbuf; 23171 ... 23172 tm = localtime(&statbuf.st_mtime); 23173 ... 23174 Timing an Event 23175 The following example gets the current time, converts it to a string using localtime( ) and 23176 asctime( ), and prints it to standard output using fputs( ). It then prints the number of minutes to 23177 an event being timed. 23178 #include 23179 #include 23180 ... 23181 time_t now; 23182 int minutes_to_event; 23183 ... 23184 time(&now); 23185 printf("The time is "); 23186 fputs(asctime(localtime(&now)), stdout); 23187 printf("There are still %d minutes to the event.\n", System Interfaces, Issue 6 1179 localtime( ) System Interfaces 23188 minutes_to_event); 23189 ... 23190 APPLICATION USAGE 23191 The localtime_r( ) function is thread-safe and returns values in a user-supplied buffer instead of | 23192 possibly using a static data area that may be overwritten by each call. 23193 RATIONALE 23194 None. 23195 FUTURE DIRECTIONS 23196 None. 23197 SEE ALSO 23198 asctime( ), clock( ), ctime( ), difftime( ), getdate( ), gmtime( ), mktime( ), strftime( ), strptime( ), time( ), 23199 utime( ), the Base Definitions volume of IEEE Std 1003.1-200x, 23200 CHANGE HISTORY 23201 First released in Issue 1. Derived from Issue 1 of the SVID. 23202 Issue 5 23203 A note indicating that the localtime( ) function need not be reentrant is added to the 23204 DESCRIPTION. 23205 The localtime_r( ) function is included for alignment with the POSIX Threads Extension. 23206 Issue 6 23207 The localtime_r( ) function is marked as part of the Thread-Safe Functions option. 23208 Extensions beyond the ISO C standard are now marked. 23209 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 23210 its avoidance of possibly using a static data area. 23211 The restrict keyword is added to the localtime_r( ) prototype for alignment with the 23212 ISO/IEC 9899: 1999 standard. | 23213 Examples are added. | 1180 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lockf( ) 23214 NAME 23215 lockf - record locking on files 23216 SYNOPSIS 23217 XSI #include 23218 int lockf(int fildes, int function, off_t size); 23219 23220 DESCRIPTION 23221 The lockf( ) function shall lock sections of a file with advisory-mode locks. Calls to lockf( ) from | 23222 other threads which attempt to lock the locked file section shall either return an error value or 23223 block until the section becomes unlocked. All the locks for a process are removed when the 23224 process terminates. Record locking with lockf( ) shall be supported for regular files and may be | 23225 supported for other files. | 23226 The fildes argument is an open file descriptor. To establish a lock with this function, the file | 23227 descriptor shall be opened with write-only permission (O_WRONLY) or with read/write | 23228 permission (O_RDWR). | 23229 The function argument is a control value which specifies the action to be taken. The permissible 23230 values for function are defined in as follows: 23231 ____________________________________________________ 23232 _ Function Description ___________________________________________________ 23233 F_ULOCK Unlock locked sections. 23234 F_LOCK Lock a section for exclusive use. 23235 F_TLOCK Test and lock a section for exclusive use. 23236 _ F_TEST Test a section for locks by other processes. ___________________________________________________ 23237 F_TEST shall detect if a lock by another process is present on the specified section. | 23238 F_LOCK and F_TLOCK shall both lock a section of a file if the section is available. | 23239 F_ULOCK shall remove locks from a section of the file. | 23240 The size argument is the number of contiguous bytes to be locked or unlocked. The section to be 23241 locked or unlocked starts at the current offset in the file and extends forward for a positive size 23242 or backward for a negative size (the preceding bytes up to but not including the current offset). 23243 If size is 0, the section from the current offset through the largest possible file offset shall be | 23244 locked (that is, from the current offset through the present or any future end-of-file). An area | 23245 need not be allocated to the file to be locked because locks may exist past the end-of-file. | 23246 The sections locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be contained 23247 by a previously locked section for the same process. When this occurs, or if adjacent locked 23248 sections would occur, the sections shall be combined into a single locked section. If the request | 23249 would cause the number of locks to exceed a system-imposed limit, the request shall fail. | 23250 F_LOCK and F_TLOCK requests differ only by the action taken if the section is not available. | 23251 F_LOCK shall block the calling thread until the section is available. F_TLOCK shall cause the | 23252 function to fail if the section is already locked by another process. | 23253 File locks shall be released on first close by the locking process of any file descriptor for the file. | 23254 F_ULOCK requests may release (wholly or in part) one or more locked sections controlled by the 23255 process. Locked sections shall be unlocked starting at the current file offset through size bytes or 23256 to the end-of-file if size is (off_t)0. When all of a locked section is not released (that is, when the 23257 beginning or end of the area to be unlocked falls within a locked section), the remaining portions | 23258 of that section shall remain locked by the process. Releasing the center portion of a locked | System Interfaces, Issue 6 1181 lockf( ) System Interfaces 23259 section shall cause the remaining locked beginning and end portions to become two separate 23260 locked sections. If the request would cause the number of locks in the system to exceed a 23261 system-imposed limit, the request shall fail. 23262 A potential for deadlock occurs if the threads of a process controlling a locked section are 23263 blocked by accessing another process' locked section. If the system detects that deadlock would 23264 occur, lockf( ) shall fail with an [EDEADLK] error. 23265 The interaction between fcntl( ) and lockf( ) locks is unspecified. 23266 Blocking on a section shall be interrupted by any signal. | 23267 An F_ULOCK request in which size is non-zero and the offset of the last byte of the requested 23268 section is the maximum value for an object of type off_t, when the process has an existing lock 23269 in which size is 0 and which includes the last byte of the requested section, shall be treated as a 23270 request to unlock from the start of the requested section with a size equal to 0. Otherwise, an 23271 F_ULOCK request shall attempt to unlock only the requested section. 23272 Attempting to lock a section of a file that is associated with a buffered stream produces 23273 unspecified results. 23274 RETURN VALUE 23275 Upon successful completion, lockf( ) shall return 0. Otherwise, it shall return -1, set errno to 23276 indicate an error, and existing locks shall not be changed. 23277 ERRORS 23278 The lockf( ) function shall fail if: 23279 [EBADF] The fildes argument is not a valid open file descriptor; or function is F_LOCK 23280 or F_TLOCK and fildes is not a valid file descriptor open for writing. 23281 [EACCES] or [EAGAIN] 23282 The function argument is F_TLOCK or F_TEST and the section is already 23283 locked by another process. 23284 [EDEADLK] The function argument is F_LOCK and a deadlock is detected. 23285 [EINTR] A signal was caught during execution of the function. 23286 [EINVAL] The function argument is not one of F_LOCK, F_TLOCK, F_TEST, or 23287 F_ULOCK; or size plus the current file offset is less than 0. 23288 [EOVERFLOW] The offset of the first, or if size is not 0 then the last, byte in the requested 23289 section cannot be represented correctly in an object of type off_t. 23290 The lockf( ) function may fail if: 23291 [EAGAIN] The function argument is F_LOCK or F_TLOCK and the file is mapped with 23292 mmap( ). 23293 [EDEADLK] or [ENOLCK] 23294 The function argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request 23295 would cause the number of locks to exceed a system-imposed limit. 23296 [EOPNOTSUPP] or [EINVAL] 23297 The implementation does not support the locking of files of the type indicated 23298 by the fildes argument. 1182 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lockf( ) 23299 EXAMPLES 23300 Locking a Portion of a File 23301 In the following example, a file named /home/cnd/mod1 is being modified. Other processes that 23302 use locking are prevented from changing it during this process. Only the first 10,000 bytes are 23303 locked, and the lock call fails if another process has any part of this area locked already. 23304 #include 23305 #include 23306 int fildes; 23307 int status; 23308 ... 23309 fildes = open("/home/cnd/mod1", O_RDWR); 23310 status = lockf(fildes, F_TLOCK, (off_t)10000); 23311 APPLICATION USAGE 23312 Record-locking should not be used in combination with the fopen( ), fread( ), fwrite( ), and other 23313 stdio functions. Instead, the more primitive, non-buffered functions (such as open( )) should be 23314 used. Unexpected results may occur in processes that do buffering in the user address space. The 23315 process may later read/write data which is/was locked. The stdio functions are the most 23316 common source of unexpected buffering. 23317 The alarm( ) function may be used to provide a timeout facility in applications requiring it. 23318 RATIONALE 23319 None. 23320 FUTURE DIRECTIONS 23321 None. 23322 SEE ALSO 23323 alarm( ), chmod( ), close( ), creat( ), fcntl( ), fopen( ), mmap( ), open( ), read( ), write( ), the Base 23324 Definitions volume of IEEE Std 1003.1-200x, 23325 CHANGE HISTORY 23326 First released in Issue 4, Version 2. 23327 Issue 5 23328 Moved from X/OPEN UNIX extension to BASE. 23329 Large File Summit extensions are added. In particular, the description of [EINVAL] is clarified 23330 and moved from optional to mandatory status. 23331 A note is added to the DESCRIPTION indicating the effects of attempting to lock a section of a 23332 file that is associated with a buffered stream. 23333 Issue 6 23334 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1183 log( ) System Interfaces 23335 NAME 23336 log, logf, logl - natural logarithm function 23337 SYNOPSIS 23338 #include 23339 double log(double x); 23340 float logf(float x); 23341 long double logl(long double x); 23342 DESCRIPTION 23343 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23344 conflict between the requirements described here and the ISO C standard is unintentional. This 23345 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23346 These functions shall compute the natural logarithm of their argument x, log (x). | e 23347 An application wishing to check for error situations should set errno to zero and call 23348 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23349 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23350 zero, an error has occurred. 23351 RETURN VALUE 23352 Upon successful completion, these functions shall return the natural logarithm of x. 23353 If x is ±0, a pole error shall occur and log( ), logf( ), and logl( ) shall return -HUGE_VAL, 23354 -HUGE_VALF, and -HUGE_VALL, respectively. 23355 MX MX For finite values of x that are less than 0, or if x is -Inf, a domain error shall occur, and either a 23356 NaN (if supported), or an implementation-defined value shall be returned. 23357 MX If x is NaN, a NaN shall be returned. 23358 If x is 1, +0 shall be returned. 23359 If x is +Inf, x shall be returned. 23360 ERRORS 23361 These functions shall fail if: 23362 MX Domain Error The finite value of x is negative, or x is -Inf. 23363 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23364 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23365 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23366 shall be raised. | 23367 Pole Error The value of x is zero. 23368 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23369 then errno shall be set to [ERANGE]. If the integer expression | 23370 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 23371 zero floating-point exception shall be raised. | 1184 Technical Standard (2001) (Draft April 16, 2001) System Interfaces log( ) 23372 EXAMPLES 23373 None. 23374 APPLICATION USAGE 23375 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23376 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23377 RATIONALE 23378 None. 23379 FUTURE DIRECTIONS 23380 None. 23381 SEE ALSO 23382 exp( ), feclearexcept( ), fetestexcept( ), isnan( ), log10( ), log1p( ), the Base Definitions volume of | 23383 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 23384 23385 CHANGE HISTORY 23386 First released in Issue 1. Derived from Issue 1 of the SVID. 23387 Issue 5 23388 The DESCRIPTION is updated to indicate how an application should check for an error. This 23389 text was previously published in the APPLICATION USAGE section. 23390 Issue 6 23391 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 23392 The logf( ) and logl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 23393 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 23394 revised to align with the ISO/IEC 9899: 1999 standard. 23395 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 23396 marked. System Interfaces, Issue 6 1185 log10( ) System Interfaces 23397 NAME 23398 log10, log10f, log10l - base 10 logarithm function 23399 SYNOPSIS 23400 #include 23401 double log10(double x); 23402 float log10f(float x); 23403 long double log10l(long double x); 23404 DESCRIPTION 23405 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23406 conflict between the requirements described here and the ISO C standard is unintentional. This 23407 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23408 These functions shall compute the base 10 logarithm of their argument x, log (x). | 10 23409 An application wishing to check for error situations should set errno to zero and call 23410 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23411 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23412 zero, an error has occurred. 23413 RETURN VALUE 23414 Upon successful completion, these functions shall return the base 10 logarithm of x. 23415 If x is ±0, a pole error shall occur and log10( ), log10f( ), and log10l( ) shall return -HUGE_VAL, 23416 -HUGE_VALF, and -HUGE_VALL, respectively. 23417 MX MX For finite values of x that are less than 0, or if x is -Inf, a domain error shall occur, and either a 23418 NaN (if supported), or an implementation-defined value shall be returned. 23419 MX If x is NaN, a NaN shall be returned. 23420 If x is 1, +0 shall be returned. 23421 If x is +Inf, +Inf shall be returned. 23422 ERRORS 23423 These functions shall fail if: 23424 MX Domain Error The finite value of x is negative, or x is -Inf. 23425 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23426 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23427 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23428 shall be raised. | 23429 Pole Error The value of x is zero. 23430 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23431 then errno shall be set to [ERANGE]. If the integer expression | 23432 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 23433 zero floating-point exception shall be raised. | 1186 Technical Standard (2001) (Draft April 16, 2001) System Interfaces log10( ) 23434 EXAMPLES 23435 None. 23436 APPLICATION USAGE 23437 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23438 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23439 RATIONALE 23440 None. 23441 FUTURE DIRECTIONS 23442 None. 23443 SEE ALSO 23444 feclearexcept( ), fetestexcept( ), isnan( ), log( ), pow( ), the Base Definitions volume of | 23445 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 23446 23447 CHANGE HISTORY 23448 First released in Issue 1. Derived from Issue 1 of the SVID. 23449 Issue 5 23450 The DESCRIPTION is updated to indicate how an application should check for an error. This 23451 text was previously published in the APPLICATION USAGE section. 23452 Issue 6 23453 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 23454 The log10f( ) and log10l( ) functions are added for alignment with the ISO/IEC 9899: 1999 23455 standard. 23456 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 23457 revised to align with the ISO/IEC 9899: 1999 standard. 23458 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 23459 marked. System Interfaces, Issue 6 1187 log1p( ) System Interfaces 23460 NAME 23461 log1p, log1pf, log1pl - compute a natural logarithm 23462 SYNOPSIS 23463 #include 23464 double log1p(double x); 23465 float log1pf(float x); 23466 long double log1pl(long double x); 23467 DESCRIPTION 23468 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23469 conflict between the requirements described here and the ISO C standard is unintentional. This 23470 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23471 These functions shall compute log (1.0 + x). | e 23472 An application wishing to check for error situations should set errno to zero and call 23473 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23474 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23475 zero, an error has occurred. 23476 RETURN VALUE 23477 Upon successful completion, these functions shall return the natural logarithm of 1.0 + x. 23478 If x is -1, a pole error shall occur and log1p( ), log1pf( ), and log1pl( ) shall return -HUGE_VAL, 23479 -HUGE_VALF, and -HUGE_VALL, respectively. 23480 MX MX For finite values of x that are less than -1, or if x is -Inf,a domain error shall occur, and either a 23481 NaN (if supported), or an implementation-defined value shall be returned. 23482 MX If x is NaN, a NaN shall be returned. 23483 If x is ±0, or +Inf, x shall be returned. 23484 If x is subnormal, a range error may occur and x should be returned. 23485 ERRORS 23486 These functions shall fail if: 23487 MX Domain Error The finite value of x is less than -1, or x is -Inf. 23488 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23489 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23490 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23491 shall be raised. | 23492 Pole Error The value of x is -1. 23493 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23494 then errno shall be set to [ERANGE]. If the integer expression | 23495 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 23496 zero floating-point exception shall be raised. | 23497 These functions may fail if: 23498 MX Range Error The value of x is subnormal. 23499 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23500 then errno shall be set to [ERANGE]. If the integer expression | 23501 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 23502 floating-point exception shall be raised. | 1188 Technical Standard (2001) (Draft April 16, 2001) System Interfaces log1p( ) 23503 EXAMPLES 23504 None. 23505 APPLICATION USAGE 23506 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23507 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23508 RATIONALE 23509 None. 23510 FUTURE DIRECTIONS 23511 None. 23512 SEE ALSO 23513 feclearexcept( ), fetestexcept( ), log( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 23514 4.18, Treatment of Error Conditions for Mathematical Functions, | 23515 CHANGE HISTORY 23516 First released in Issue 4, Version 2. 23517 Issue 5 23518 Moved from X/OPEN UNIX extension to BASE. 23519 Issue 6 23520 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 23521 The log1p( ) function is no longer marked as an extension. 23522 The log1pf( ) and log1pl( ) functions are added for alignment with the ISO/IEC 9899: 1999 23523 standard. 23524 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 23525 revised to align with the ISO/IEC 9899: 1999 standard. 23526 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 23527 marked. System Interfaces, Issue 6 1189 log2( ) System Interfaces 23528 NAME 23529 log2, log2f, log2l - compute base 2 logarithm functions 23530 SYNOPSIS 23531 #include 23532 double log2(double x); 23533 float log2f(float x); 23534 long double log2l(long double x); 23535 DESCRIPTION 23536 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23537 conflict between the requirements described here and the ISO C standard is unintentional. This 23538 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23539 These functions shall compute the base 2 logarithm of their argument x, log2(x). | 23540 An application wishing to check for error situations should set errno to zero and call 23541 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23542 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23543 zero, an error has occurred. 23544 RETURN VALUE 23545 Upon successful completion, these functions shall return the base 2 logarithm of x. 23546 If x is ±0, a pole error shall occur and log2( ), log2f( ), and log2l( ) shall return -HUGE_VAL, 23547 -HUGE_VALF, and -HUGE_VALL, respectively. 23548 MX MX For finite values of x that are less than 0, or if x is -Inf a domain error shall occur, and either a 23549 NaN (if supported), or an implementation-defined value shall be returned. 23550 MX If x is NaN, a NaN shall be returned. 23551 If x is 1, +0 shall be returned. 23552 If x is +Inf, x shall be returned. 23553 ERRORS 23554 These functions shall fail if: 23555 MX Domain Error The finite value of x is less than zero, or x is -Inf. 23556 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23557 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23558 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23559 shall be raised. | 23560 Pole Error The value of x is zero. 23561 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23562 then errno shall be set to [ERANGE]. If the integer expression | 23563 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 23564 zero floating-point exception shall be raised. | 1190 Technical Standard (2001) (Draft April 16, 2001) System Interfaces log2( ) 23565 EXAMPLES 23566 None. 23567 APPLICATION USAGE 23568 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23569 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23570 RATIONALE 23571 None. 23572 FUTURE DIRECTIONS 23573 None. 23574 SEE ALSO 23575 feclearexcept( ), fetestexcept( ), log( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 23576 4.18, Treatment of Error Conditions for Mathematical Functions, | 23577 CHANGE HISTORY 23578 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1191 logb( ) System Interfaces 23579 NAME 23580 logb, logbf, logbl - radix-independent exponent 23581 SYNOPSIS 23582 #include 23583 double logb(double x); 23584 float logbf(float x); 23585 long double logbl(long double x); 23586 DESCRIPTION 23587 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23588 conflict between the requirements described here and the ISO C standard is unintentional. This 23589 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23590 These functions shall compute the exponent of x, which is the integral part of log | x |, as a r 23591 signed floating-point value, for non-zero x, where r is the radix of the machine's floating-point 23592 arithmetic, which is the value of FLT_RADIX defined in the header. 23593 If x is subnormal it is treated a though it were normalized; thus for finite positive x: 23594 1 <= x * FLT_RADIX-logb(x) < FLT_RADIX 23595 An application wishing to check for error situations should set errno to zero and call 23596 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23597 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23598 zero, an error has occurred. 23599 RETURN VALUE 23600 Upon successful completion, these functions shall return the exponent of x. 23601 If x is ±0, a pole error shall occur and logb( ), logbf( ), and logbl( ) shall return -HUGE_VAL, 23602 -HUGE_VALF, and -HUGE_VALL, respectively. 23603 MX If x is NaN, a NaN shall be returned. 23604 If x is ±Inf, +Inf shall be returned. 23605 ERRORS 23606 These functions shall fail if: 23607 Pole Error The value of x is ±0. 23608 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23609 then errno shall be set to [ERANGE]. If the integer expression | 23610 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 23611 zero floating-point exception shall be raised. | 23612 EXAMPLES 23613 None. 23614 APPLICATION USAGE 23615 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23616 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23617 RATIONALE 23618 None. 1192 Technical Standard (2001) (Draft April 16, 2001) System Interfaces logb( ) 23619 FUTURE DIRECTIONS 23620 None. 23621 SEE ALSO 23622 feclearexcept( ), fetestexcept( ), ilogb( ), scalb( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 23623 Section 4.18, Treatment of Error Conditions for Mathematical Functions, , | 23624 CHANGE HISTORY 23625 First released in Issue 4, Version 2. 23626 Issue 5 23627 Moved from X/OPEN UNIX extension to BASE. 23628 Issue 6 23629 The logb( ) function is no longer marked as an extension. 23630 The logbf( ) and logbl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 23631 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 23632 revised to align with the ISO/IEC 9899: 1999 standard. 23633 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 23634 marked. System Interfaces, Issue 6 1193 logf( ) System Interfaces 23635 NAME 23636 logf - natural logarithm function 23637 SYNOPSIS 23638 #include 23639 float logf(float x); 23640 DESCRIPTION 23641 Refer to log( ). 1194 Technical Standard (2001) (Draft April 16, 2001) System Interfaces logl( ) 23642 NAME 23643 logl - natural logarithm function 23644 SYNOPSIS 23645 #include 23646 long double logl(long double x); 23647 DESCRIPTION 23648 Refer to log( ). System Interfaces, Issue 6 1195 longjmp( ) System Interfaces 23649 NAME 23650 longjmp - non-local goto 23651 SYNOPSIS 23652 #include | 23653 void longjmp(jmp_buf env, int val); 23654 DESCRIPTION 23655 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23656 conflict between the requirements described here and the ISO C standard is unintentional. This 23657 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23658 The longjmp( ) function shall restore the environment saved by the most recent invocation of 23659 setjmp( ) in the same thread, with the corresponding jmp_buf argument. If there is no such 23660 invocation, or if the function containing the invocation of setjmp( ) has terminated execution in 23661 the interim, or if the invocation of setjmp( ) was within the scope of an identifier with variably 23662 CX modified type and execution has left that scope in the interim, the behavior is undefined. It is 23663 unspecified whether longjmp( ) restores the signal mask, leaves the signal mask unchanged, or 23664 restores it to its value at the time setjmp( ) was called. 23665 All accessible objects have values, and all other components of the abstract machine have state 23666 (for example, floating-point status flags and open files), as of the time longjmp( ) was called, 23667 except that the values of objects of automatic storage duration are unspecified if they meet all | 23668 the following conditions: | 23669 * They are local to the function containing the corresponding setjmp( ) invocation. 23670 * They do not have volatile-qualified type. 23671 * They are changed between the setjmp( ) invocation and longjmp( ) call. 23672 CX As it bypasses the usual function call and return mechanisms, longjmp( ) shall execute correctly 23673 in contexts of interrupts, signals, and any of their associated functions. However, if longjmp( ) is 23674 invoked from a nested signal handler (that is, from a function invoked as a result of a signal 23675 raised during the handling of another signal), the behavior is undefined. 23676 The effect of a call to longjmp( ) where initialization of the jmp_buf structure was not performed 23677 in the calling thread is undefined. 23678 RETURN VALUE 23679 After longjmp( ) is completed, program execution continues as if the corresponding invocation of 23680 setjmp( ) had just returned the value specified by val. The longjmp( ) function shall not cause 23681 setjmp( ) to return 0; if val is 0, setjmp( ) shall return 1. 23682 ERRORS 23683 No errors are defined. 23684 EXAMPLES 23685 None. 23686 APPLICATION USAGE 23687 Applications whose behavior depends on the value of the signal mask should not use longjmp( ) 23688 and setjmp( ), since their effect on the signal mask is unspecified, but should instead use the 23689 siglongjmp( ) and sigsetjmp( ) functions (which can save and restore the signal mask under 23690 application control). 1196 Technical Standard (2001) (Draft April 16, 2001) System Interfaces longjmp( ) 23691 RATIONALE 23692 None. 23693 FUTURE DIRECTIONS 23694 None. 23695 SEE ALSO 23696 setjmp( ), sigaction( ), siglongjmp( ), sigsetjmp( ), the Base Definitions volume of 23697 IEEE Std 1003.1-200x, 23698 CHANGE HISTORY 23699 First released in Issue 1. Derived from Issue 1 of the SVID. 23700 Issue 5 23701 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 23702 Issue 6 23703 Extensions beyond the ISO C standard are now marked. 23704 The following new requirements on POSIX implementations derive from alignment with the 23705 Single UNIX Specification: 23706 * The DESCRIPTION now explicitly makes longjmp( )'s effect on the signal mask unspecified. 23707 The DESCRIPTION is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1197 lrand48( ) System Interfaces 23708 NAME 23709 lrand48 - generate uniformly distributed pseudo-random non-negative long integers 23710 SYNOPSIS 23711 XSI #include 23712 long lrand48(void); 23713 23714 DESCRIPTION 23715 Refer to drand48( ). 1198 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lrint( ) 23716 NAME 23717 lrint, lrintf, lrintl - round to nearest integer value using current rounding direction 23718 SYNOPSIS 23719 #include 23720 long lrint(double x); 23721 long lrintf(float x); 23722 long lrintl(long double x); 23723 DESCRIPTION 23724 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23725 conflict between the requirements described here and the ISO C standard is unintentional. This 23726 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23727 These functions shall round their argument to the nearest integer value, rounding according to 23728 the current rounding direction. 23729 An application wishing to check for error situations should set errno to zero and call 23730 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23731 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23732 zero, an error has occurred. 23733 RETURN VALUE 23734 Upon successful completion, these functions shall return the rounded integer value. 23735 MX If x is NaN, a domain error shall occur, and an unspecified value is returned. 23736 If x is +Inf, a domain error shall occur and an unspecified value is returned. 23737 If x is -Inf, a domain error shall occur and an unspecified value is returned. 23738 If the correct value is positive and too large to represent as a long, a domain error shall occur | 23739 and an unspecified value is returned. 23740 If the correct value is negative and too large to represent as a long, a domain error shall occur | 23741 and an unspecified value is returned. 23742 ERRORS 23743 These functions shall fail if: 23744 MX Domain Error The x argument is NaN or ±Inf, or the correct value is not representable as an 23745 integer. 23746 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23747 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23748 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23749 shall be raised. | 23750 EXAMPLES 23751 None. 23752 APPLICATION USAGE 23753 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23754 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23755 RATIONALE 23756 These functions provide floating-to-integer conversions. They round according to the current 23757 rounding direction. If the rounded value is outside the range of the return type, the numeric 23758 result is unspecified and the invalid floating-point exception is raised. When they raise no other 23759 floating-point exception and the result differs from the argument, they raise the inexact System Interfaces, Issue 6 1199 lrint( ) System Interfaces 23760 floating-point exception. 23761 FUTURE DIRECTIONS 23762 None. 23763 SEE ALSO 23764 feclearexcept( ), fetestexcept( ), llrint( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 23765 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 23766 CHANGE HISTORY 23767 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1200 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lround( ) 23768 NAME 23769 lround, lroundf, lroundl - round to nearest integer value 23770 SYNOPSIS 23771 #include 23772 long lround(double x); 23773 long lroundf(float x); 23774 long lroundl(long double x); 23775 DESCRIPTION 23776 CX The functionality described on this reference page is aligned with the ISO C standard. Any 23777 conflict between the requirements described here and the ISO C standard is unintentional. This 23778 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 23779 These functions shall round their argument to the nearest integer value, rounding halfway cases 23780 away from zero, regardless of the current rounding direction. 23781 An application wishing to check for error situations should set errno to zero and call 23782 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 23783 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 23784 zero, an error has occurred. 23785 RETURN VALUE 23786 Upon successful completion, these functions shall return the rounded integer value. 23787 MX If x is NaN, a domain error shall occur, and an unspecified value is returned. 23788 If x is +Inf, a domain error shall occur and an unspecified value is returned. 23789 If x is -Inf, a domain error shall occur and an unspecified value is returned. 23790 If the correct value is positive and too large to represent as a long, a domain error shall occur | 23791 and an unspecified value is returned. 23792 If the correct value is negative and too large to represent as a long, a domain error shall occur | 23793 and an unspecified value is returned. 23794 ERRORS 23795 These functions shall fail if: 23796 MX Domain Error The x argument is NaN or ±Inf, or the correct value is not representable as an 23797 integer. 23798 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 23799 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 23800 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 23801 shall be raised. | 23802 EXAMPLES 23803 None. 23804 APPLICATION USAGE 23805 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 23806 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 23807 RATIONALE 23808 These functions provide floating-to-integer conversions. They round according to the current 23809 rounding direction. If the rounded value is outside the range of the return type, the numeric 23810 result is unspecified and the invalid floating-point exception is raised. When they raise no other 23811 floating-point exception and the result differs from the argument, they raise the inexact System Interfaces, Issue 6 1201 lround( ) System Interfaces 23812 floating-point exception. 23813 These functions differ from the lrint( ) functions in the default rounding direction, with the 23814 lround( ) functions rounding halfway cases away from zero and needing not to raise the inexact 23815 floating-point exception for non-integer arguments that round to within the range of the return 23816 type. 23817 FUTURE DIRECTIONS 23818 None. 23819 SEE ALSO 23820 feclearexcept( ), fetestexcept( ), llround( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 23821 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 23822 CHANGE HISTORY 23823 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1202 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lsearch( ) 23824 NAME 23825 lsearch, lfind - linear search and update 23826 SYNOPSIS 23827 XSI #include 23828 void *lsearch(const void *key, void *base, size_t *nelp, size_t width, 23829 int (*compar)(const void *, const void *)); 23830 void *lfind(const void *key, const void *base, size_t *nelp, 23831 size_t width, int (*compar)(const void *, const void *)); 23832 23833 DESCRIPTION 23834 The lsearch( ) function shall linearly search the table and return a pointer into the table for the | 23835 matching entry. If the entry does not occur, it shall be added at the end of the table. The key 23836 argument points to the entry to be sought in the table. The base argument points to the first 23837 element in the table. The width argument is the size of an element in bytes. The nelp argument 23838 points to an integer containing the current number of elements in the table. The integer to which 23839 nelp points shall be incremented if the entry is added to the table. The compar argument points to | 23840 a comparison function which the application shall supply (for example, strcmp( )). It is called 23841 with two arguments that point to the elements being compared. The application shall ensure 23842 that the function returns 0 if the elements are equal, and non-zero otherwise. 23843 The lfind( ) function shall be equivalent to lsearch( ), except that if the entry is not found, it is not | 23844 added to the table. Instead, a null pointer is returned. 23845 RETURN VALUE 23846 If the searched for entry is found, both lsearch( ) and lfind( ) shall return a pointer to it. Otherwise, 23847 lfind( ) shall return a null pointer and lsearch( ) shall return a pointer to the newly added element. 23848 Both functions shall return a null pointer in case of error. 23849 ERRORS 23850 No errors are defined. 23851 EXAMPLES 23852 Storing Strings in a Table 23853 This fragment reads in less than or equal to TABSIZE strings of length less than or equal to 23854 ELSIZE and stores them in a table, eliminating duplicates. 23855 #include 23856 #include 23857 #include 23858 #define TABSIZE 50 23859 #define ELSIZE 120 23860 ... 23861 char line[ELSIZE], tab[TABSIZE][ELSIZE]; 23862 size_t nel = 0; 23863 ... 23864 while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) 23865 (void) lsearch(line, tab, &nel, 23866 ELSIZE, (int (*)(const void *, const void *)) strcmp); 23867 ... System Interfaces, Issue 6 1203 lsearch( ) System Interfaces 23868 Finding a Matching Entry 23869 The following example finds any line that reads "This is a test.". 23870 #include 23871 #include 23872 ... 23873 char line[ELSIZE], tab[TABSIZE][ELSIZE]; 23874 size_t nel = 0; 23875 char *findline; 23876 void *entry; 23877 findline = "This is a test.\n"; 23878 entry = lfind(findline, tab, &nel, ELSIZE, ( 23879 int (*)(const void *, const void *)) strcmp); 23880 APPLICATION USAGE 23881 The comparison function need not compare every byte, so arbitrary data may be contained in 23882 the elements in addition to the values being compared. 23883 Undefined results can occur if there is not enough room in the table to add a new item. 23884 RATIONALE 23885 None. 23886 FUTURE DIRECTIONS 23887 None. 23888 SEE ALSO 23889 hcreate( ), tsearch( ), the Base Definitions volume of IEEE Std 1003.1-200x, 23890 CHANGE HISTORY 23891 First released in Issue 1. Derived from Issue 1 of the SVID. 23892 Issue 6 23893 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1204 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lseek( ) 23894 NAME 23895 lseek - move the read/write file offset 23896 SYNOPSIS 23897 #include 23898 off_t lseek(int fildes, off_t offset, int whence); 23899 DESCRIPTION 23900 The lseek( ) function shall set the file offset for the open file description associated with the file 23901 descriptor fildes, as follows: 23902 * If whence is SEEK_SET, the file offset shall be set to offset bytes. | 23903 * If whence is SEEK_CUR, the file offset shall be set to its current location plus offset. | 23904 * If whence is SEEK_END, the file offset shall be set to the size of the file plus offset. | 23905 The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END are defined in . 23906 The behavior of lseek( ) on devices which are incapable of seeking is implementation-defined. 23907 The value of the file offset associated with such a device is undefined. 23908 The lseek( ) function shall allow the file offset to be set beyond the end of the existing data in the 23909 file. If data is later written at this point, subsequent reads of data in the gap shall return bytes 23910 with the value 0 until data is actually written into the gap. 23911 The lseek( ) function shall not, by itself, extend the size of a file. 23912 SHM If fildes refers to a shared memory object, the result of the lseek( ) function is unspecified. 23913 TYM If fildes refers to a typed memory object, the result of the lseek( ) function is unspecified. 23914 RETURN VALUE 23915 Upon successful completion, the resulting offset, as measured in bytes from the beginning of the 23916 file, shall be returned. Otherwise, (off_t)-1 shall be returned, errno shall be set to indicate the 23917 error, and the file offset shall remain unchanged. 23918 ERRORS 23919 The lseek( ) function shall fail if: 23920 [EBADF] The fildes argument is not an open file descriptor. 23921 [EINVAL] The whence argument is not a proper value, or the resulting file offset would 23922 be negative for a regular file, block special file, or directory. 23923 [EOVERFLOW] The resulting file offset would be a value which cannot be represented 23924 correctly in an object of type off_t. 23925 [ESPIPE] The fildes argument is associated with a pipe, FIFO, or socket. 23926 EXAMPLES 23927 None. 23928 APPLICATION USAGE 23929 None. 23930 RATIONALE 23931 The ISO C standard includes the functions fgetpos( ) and fsetpos( ), which work on very large files 23932 by use of a special positioning type. 23933 Although lseek( ) may position the file offset beyond the end of the file, this function does not 23934 itself extend the size of the file. While the only function in IEEE Std 1003.1-200x that may directly | System Interfaces, Issue 6 1205 lseek( ) System Interfaces 23935 extend the size of the file is write( ), truncate( ), and ftruncate( ), several functions originally | 23936 derived from the ISO C standard, such as fwrite( ), fprintf( ), and so on, may do so (by causing 23937 calls on write( )). 23938 An invalid file offset that would cause [EINVAL] to be returned may be both implementation- 23939 defined and device-dependent (for example, memory may have few invalid values). A negative 23940 file offset may be valid for some devices in some implementations. 23941 The POSIX.1-1990 standard did not specifically prohibit lseek( ) from returning a negative offset. 23942 Therefore, an application was required to clear errno prior to the call and check errno upon return 23943 to determine whether a return value of (off_t)-1 is a negative offset or an indication of an error 23944 condition. The standard developers did not wish to require this action on the part of a | 23945 conforming application, and chose to require that errno be set to [EINVAL] when the resulting | 23946 file offset would be negative for a regular file, block special file, or directory. 23947 FUTURE DIRECTIONS 23948 None. 23949 SEE ALSO 23950 open( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 23951 CHANGE HISTORY 23952 First released in Issue 1. Derived from Issue 1 of the SVID. 23953 Issue 5 23954 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 23955 Large File Summit extensions are added. 23956 Issue 6 23957 In the SYNOPSIS, the optional include of the header is removed. 23958 The following new requirements on POSIX implementations derive from alignment with the 23959 Single UNIX Specification: 23960 * The requirement to include has been removed. Although was 23961 required for conforming implementations of previous POSIX specifications, it was not 23962 required for UNIX applications. 23963 * The [EOVERFLOW] error condition is added. This change is to support large files. 23964 An additional [ESPIPE] error condition is added for sockets. 23965 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 23966 lseek( ) results are unspecified for typed memory objects. 1206 Technical Standard (2001) (Draft April 16, 2001) System Interfaces lstat( ) 23967 NAME 23968 lstat - get symbolic link status 23969 SYNOPSIS 23970 #include 23971 int lstat(const char *restrict path, struct stat *restrict buf); 23972 DESCRIPTION 23973 The lstat( ) function shall be equivalent to stat( ), except when path refers to a symbolic link. In | 23974 that case lstat( ) shall return information about the link, while stat( ) shall return information 23975 about the file the link references. 23976 For symbolic links, the st_mode member shall contain meaningful information when used with 23977 the file type macros, and the st_size member shall contain the length of the pathname contained | 23978 in the symbolic link. File mode bits and the contents of the remaining members of the stat | 23979 structure are unspecified. The value returned in the st_size member is the length of the contents 23980 of the symbolic link, and does not count any trailing null. 23981 RETURN VALUE 23982 Upon successful completion, lstat( ) shall return 0. Otherwise, it shall return -1 and set errno to 23983 indicate the error. 23984 ERRORS 23985 The lstat( ) function shall fail if: 23986 [EACCES] A component of the path prefix denies search permission. 23987 [EIO] An error occurred while reading from the file system. 23988 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 23989 argument. 23990 [ENAMETOOLONG] 23991 The length of a pathname exceeds {PATH_MAX} or a pathname component is | 23992 longer than {NAME_MAX}. | 23993 [ENOTDIR] A component of the path prefix is not a directory. 23994 [ENOENT] A component of path does not name an existing file or path is an empty string. 23995 [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 23996 serial number cannot be represented correctly in the structure pointed to by 23997 buf. 23998 The lstat( ) function may fail if: 23999 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24000 resolution of the path argument. 24001 [ENAMETOOLONG] 24002 As a result of encountering a symbolic link in resolution of the path argument, | 24003 the length of the substituted pathname string exceeded {PATH_MAX}. | 24004 [EOVERFLOW] One of the members is too large to store into the structure pointed to by the 24005 buf argument. System Interfaces, Issue 6 1207 lstat( ) System Interfaces 24006 EXAMPLES 24007 Obtaining Symbolic Link Status Information 24008 The following example shows how to obtain status information for a symbolic link named 24009 /modules/pass1. The structure variable buffer is defined for the stat structure. If the path 24010 argument specified the filename for the file pointed to by the symbolic link (/home/cnd/mod1), 24011 the results of calling the function would be the same as those returned by a call to the stat( ) 24012 function. 24013 #include 24014 struct stat buffer; 24015 int status; 24016 ... 24017 status = lstat("/modules/pass1", &buffer); 24018 APPLICATION USAGE 24019 None. 24020 RATIONALE 24021 The lstat( ) function is not required to update the time-related fields if the named file is not a 24022 symbolic link. While the st_uid, st_gid, st_atime, st_mtime, and st_ctime members of the stat 24023 structure may apply to a symbolic link, they are not required to do so. No functions in 24024 IEEE Std 1003.1-200x are required to maintain any of these time fields. 24025 FUTURE DIRECTIONS 24026 None. 24027 SEE ALSO 24028 fstat( ), readlink( ), stat( ), symlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24029 24030 CHANGE HISTORY 24031 First released in Issue 4, Version 2. 24032 Issue 5 24033 Moved from X/OPEN UNIX extension to BASE. 24034 Large File Summit extensions are added. 24035 Issue 6 24036 The following changes were made to align with the IEEE P1003.1a draft standard: 24037 * This function is now mandatory. 24038 * The [ELOOP] optional error condition is added. 24039 The restrict keyword is added to the lstat( ) prototype for alignment with the ISO/IEC 9899: 1999 24040 standard. 1208 Technical Standard (2001) (Draft April 16, 2001) System Interfaces makecontext( ) 24041 NAME 24042 makecontext, swapcontext - manipulate user contexts 24043 SYNOPSIS 24044 XSI #include 24045 void makecontext(ucontext_t *ucp, void (*func)(void), 24046 int argc, ...); 24047 int swapcontext(ucontext_t *restrict oucp, 24048 const ucontext_t *restrict ucp); 24049 24050 DESCRIPTION 24051 The makecontext( ) function shall modify the context specified by ucp, which has been initialized 24052 using getcontext( ). When this context is resumed using swapcontext( ) or setcontext( ), program 24053 execution shall continue by calling func, passing it the arguments that follow argc in the 24054 makecontext( ) call. 24055 Before a call is made to makecontext( ), the application shall ensure that the context being 24056 modified has a stack allocated for it. The application shall ensure that the value of argc matches 24057 the number of integer arguments passed to func; otherwise, the behavior is undefined. 24058 The uc_link member is used to determine the context that shall be resumed when the context 24059 being modified by makecontext( ) returns. The application shall ensure that the uc_link member is 24060 initialized prior to the call to makecontext( ). 24061 The swapcontext( ) function shall save the current context in the context structure pointed to by 24062 oucp and shall set the context to the context structure pointed to by ucp. 24063 RETURN VALUE 24064 Upon successful completion, swapcontext( ) shall return 0. Otherwise, -1 shall be returned and 24065 errno set to indicate the error. 24066 ERRORS 24067 The swapcontext( ) function shall fail if: 24068 [ENOMEM] The ucp argument does not have enough stack left to complete the operation. 24069 EXAMPLES 24070 The following example illustrates the use of makecontext( ): | 24071 #include | 24072 #include | 24073 static ucontext_t ctx[3]; | 24074 static void | 24075 f1 (void) | 24076 { | 24077 puts("start f1"); | 24078 swapcontext(&ctx[1], &ctx[2]); | 24079 puts("finish f1"); | 24080 } | 24081 static void | 24082 f2 (void) | 24083 { | 24084 puts("start f2"); | 24085 swapcontext(&ctx[2], &ctx[1]); | System Interfaces, Issue 6 1209 makecontext( ) System Interfaces 24086 puts("finish f2"); | 24087 } | 24088 int | 24089 main (void) | 24090 { | 24091 char st1[8192]; | 24092 char st2[8192]; | 24093 getcontext(&ctx[1]); | 24094 ctx[1].uc_stack.ss_sp = st1; | 24095 ctx[1].uc_stack.ss_size = sizeof st1; | 24096 ctx[1].uc_link = &ctx[0]; | 24097 makecontext(&ctx[1], f1, 0); | 24098 getcontext(&ctx[2]); | 24099 ctx[2].uc_stack.ss_sp = st2; | 24100 ctx[2].uc_stack.ss_size = sizeof st2; | 24101 ctx[2].uc_link = &ctx[1]; | 24102 makecontext(&ctx[2], f2, 0); | 24103 swapcontext(&ctx[0], &ctx[2]); | 24104 return 0; | 24105 } | 24106 APPLICATION USAGE | 24107 None. 24108 RATIONALE 24109 None. 24110 FUTURE DIRECTIONS 24111 None. 24112 SEE ALSO 24113 exit( ), getcontext( ), sigaction( ), sigprocmask( ), the Base Definitions volume of 24114 IEEE Std 1003.1-200x, 24115 CHANGE HISTORY 24116 First released in Issue 4, Version 2. 24117 Issue 5 24118 Moved from X/OPEN UNIX extension to BASE. 24119 In the ERRORS section, the description of [ENOMEM] is changed to apply to swapcontext( ) only. 24120 Issue 6 24121 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 24122 The restrict keyword is added to the swapcontext( ) prototype for alignment with the 24123 ISO/IEC 9899: 1999 standard. 1210 Technical Standard (2001) (Draft April 16, 2001) System Interfaces malloc( ) 24124 NAME 24125 malloc - a memory allocator 24126 SYNOPSIS 24127 #include 24128 void *malloc(size_t size); 24129 DESCRIPTION 24130 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24131 conflict between the requirements described here and the ISO C standard is unintentional. This 24132 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24133 The malloc( ) function shall allocate unused space for an object whose size in bytes is specified by 24134 size and whose value is unspecified. | 24135 The order and contiguity of storage allocated by successive calls to malloc( ) is unspecified. The 24136 pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to 24137 a pointer to any type of object and then used to access such an object in the space allocated (until 24138 the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object 24139 disjoint from any other object. The pointer returned points to the start (lowest byte address) of 24140 the allocated space. If the space cannot be allocated, a null pointer shall be returned. If the size of 24141 the space requested is 0, the behavior is implementation-defined: the value returned shall be 24142 either a null pointer or a unique pointer. 24143 RETURN VALUE 24144 Upon successful completion with size not equal to 0, malloc( ) shall return a pointer to the 24145 allocated space. If size is 0, either a null pointer or a unique pointer that can be successfully 24146 CX passed to free( ) shall be returned. Otherwise, it shall return a null pointer and set errno to 24147 indicate the error. 24148 ERRORS 24149 The malloc( ) function shall fail if: 24150 CX [ENOMEM] Insufficient storage space is available. 24151 EXAMPLES 24152 None. 24153 APPLICATION USAGE 24154 None. 24155 RATIONALE 24156 None. 24157 FUTURE DIRECTIONS 24158 None. 24159 SEE ALSO 24160 calloc( ), free( ), realloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24161 CHANGE HISTORY 24162 First released in Issue 1. Derived from Issue 1 of the SVID. 24163 Issue 6 24164 Extensions beyond the ISO C standard are now marked. 24165 The following new requirements on POSIX implementations derive from alignment with the 24166 Single UNIX Specification: System Interfaces, Issue 6 1211 malloc( ) System Interfaces 24167 * In the RETURN VALUE section, the requirement to set errno to indicate an error is added. 24168 * The [ENOMEM] error condition is added. 1212 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mblen( ) 24169 NAME 24170 mblen - get number of bytes in a character 24171 SYNOPSIS 24172 #include 24173 int mblen(const char *s, size_t n); 24174 DESCRIPTION 24175 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24176 conflict between the requirements described here and the ISO C standard is unintentional. This 24177 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24178 If s is not a null pointer, mblen( ) shall determine the number of bytes constituting the character | 24179 pointed to by s. Except that the shift state of mbtowc( ) is not affected, it shall be equivalent to: | 24180 mbtowc((wchar_t *)0, s, n); 24181 The implementation shall behave as if no function defined in this volume of 24182 IEEE Std 1003.1-200x calls mblen( ). 24183 The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 24184 state-dependent encoding, this function shall be placed into its initial state by a call for which its | 24185 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null | 24186 pointer shall cause the internal state of the function to be altered as necessary. A call with s as a | 24187 null pointer shall cause this function to return a non-zero value if encodings have state | 24188 dependency, and 0 otherwise. If the implementation employs special bytes to change the shift | 24189 state, these bytes shall not produce separate wide-character codes, but shall be grouped with an | 24190 adjacent character. Changing the LC_CTYPE category causes the shift state of this function to be | 24191 unspecified. | 24192 RETURN VALUE 24193 If s is a null pointer, mblen( ) shall return a non-zero or 0 value, if character encodings, 24194 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mblen( ) shall 24195 either return 0 (if s points to the null byte), or return the number of bytes that constitute the 24196 character (if the next n or fewer bytes form a valid character), or return -1 (if they do not form a 24197 CX valid character) and may set errno to indicate the error. In no case shall the value returned be 24198 greater than n or the value of the {MB_CUR_MAX} macro. 24199 ERRORS 24200 The mblen( ) function may fail if: 24201 XSI [EILSEQ] Invalid character sequence is detected. 24202 EXAMPLES 24203 None. 24204 APPLICATION USAGE 24205 None. 24206 RATIONALE 24207 None. 24208 FUTURE DIRECTIONS 24209 None. System Interfaces, Issue 6 1213 mblen( ) System Interfaces 24210 SEE ALSO 24211 mbtowc( ), mbstowcs( ), wctomb( ), wcstombs( ), the Base Definitions volume of 24212 IEEE Std 1003.1-200x, 24213 CHANGE HISTORY 24214 First released in Issue 4. Aligned with the ISO C standard. 1214 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbrlen( ) 24215 NAME 24216 mbrlen - get number of bytes in a character (restartable) 24217 SYNOPSIS 24218 #include 24219 size_t mbrlen(const char *restrict s, size_t n, 24220 mbstate_t *restrict ps); 24221 DESCRIPTION 24222 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24223 conflict between the requirements described here and the ISO C standard is unintentional. This 24224 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24225 If s is not a null pointer, mbrlen( ) shall determine the number of bytes constituting the character 24226 pointed to by s. It shall be equivalent to: | 24227 mbstate_t internal; 24228 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); 24229 If ps is a null pointer, the mbrlen( ) function shall use its own internal mbstate_t object, which is | 24230 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 24231 pointed to by ps shall be used to completely describe the current conversion state of the | 24232 associated character sequence. The implementation shall behave as if no function defined in this | 24233 volume of IEEE Std 1003.1-200x calls mbrlen( ). | 24234 The behavior of this function is affected by the LC_CTYPE category of the current locale. | 24235 RETURN VALUE 24236 The mbrlen( ) function shall return the first of the following that applies: 24237 0 If the next n or fewer bytes complete the character that corresponds to the null 24238 wide character. 24239 positive If the next n or fewer bytes complete a valid character; the value returned shall 24240 be the number of bytes that complete the character. 24241 (size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 24242 and all n bytes have been processed. When n has at least the value of the 24243 {MB_CUR_MAX} macro, this case can only occur if s points at a sequence of 24244 redundant shift sequences (for implementations with state-dependent 24245 encodings). 24246 (size_t)-1 If an encoding error occurs, in which case the next n or fewer bytes do not 24247 contribute to a complete and valid character. In this case, [EILSEQ] shall be 24248 stored in errno and the conversion state is undefined. 24249 ERRORS 24250 The mbrlen( ) function may fail if: 24251 [EINVAL] ps points to an object that contains an invalid conversion state. 24252 [EILSEQ] Invalid character sequence is detected. System Interfaces, Issue 6 1215 mbrlen( ) System Interfaces 24253 EXAMPLES 24254 None. 24255 APPLICATION USAGE 24256 None. 24257 RATIONALE 24258 None. 24259 FUTURE DIRECTIONS 24260 None. 24261 SEE ALSO 24262 mbsinit( ), mbrtowc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24263 CHANGE HISTORY 24264 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24265 (E). 24266 Issue 6 24267 The mbrlen( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 1216 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbrtowc( ) 24268 NAME 24269 mbrtowc - convert a character to a wide-character code (restartable) 24270 SYNOPSIS 24271 #include 24272 size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s, 24273 size_t n, mbstate_t *restrict ps); 24274 DESCRIPTION 24275 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24276 conflict between the requirements described here and the ISO C standard is unintentional. This 24277 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24278 If s is a null pointer, the mbrtowc( ) function shall be equivalent to the call: 24279 mbrtowc(NULL, "", 1, ps) 24280 In this case, the values of the arguments pwc and n are ignored. 24281 If s is not a null pointer, the mbrtowc( ) function shall inspect at most n bytes beginning at the | 24282 byte pointed to by s to determine the number of bytes needed to complete the next character 24283 (including any shift sequences). If the function determines that the next character is completed, it | 24284 shall determine the value of the corresponding wide character and then, if pwc is not a null | 24285 pointer, shall store that value in the object pointed to by pwc. If the corresponding wide | 24286 character is the null wide character, the resulting state described shall be the initial conversion | 24287 state. | 24288 If ps is a null pointer, the mbrtowc( ) function shall use its own internal mbstate_t object, which | 24289 shall be initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t | 24290 object pointed to by ps shall be used to completely describe the current conversion state of the | 24291 associated character sequence. The implementation shall behave as if no function defined in this | 24292 volume of IEEE Std 1003.1-200x calls mbrtowc( ). | 24293 The behavior of this function is affected by the LC_CTYPE category of the current locale. | 24294 RETURN VALUE 24295 The mbrtowc( ) function shall return the first of the following that applies: 24296 0 If the next n or fewer bytes complete the character that corresponds to the null 24297 wide character (which is the value stored). | 24298 between 1 and n inclusive | 24299 If the next n or fewer bytes complete a valid character (which is the value | 24300 stored); the value returned shall be the number of bytes that complete the 24301 character. 24302 (size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 24303 and all n bytes have been processed (no value is stored). When n has at least 24304 the value of the {MB_CUR_MAX} macro, this case can only occur if s points at 24305 a sequence of redundant shift sequences (for implementations with state- 24306 dependent encodings). 24307 (size_t)-1 If an encoding error occurs, in which case the next n or fewer bytes do not 24308 contribute to a complete and valid character (no value is stored). In this case, 24309 [EILSEQ] shall be stored in errno and the conversion state is undefined. System Interfaces, Issue 6 1217 mbrtowc( ) System Interfaces 24310 ERRORS 24311 The mbrtowc( ) function may fail if: 24312 CX [EINVAL] ps points to an object that contains an invalid conversion state. 24313 [EILSEQ] Invalid character sequence is detected. 24314 EXAMPLES 24315 None. 24316 APPLICATION USAGE 24317 None. 24318 RATIONALE 24319 None. 24320 FUTURE DIRECTIONS 24321 None. 24322 SEE ALSO 24323 mbsinit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24324 CHANGE HISTORY 24325 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24326 (E). 24327 Issue 6 24328 The mbrtowc( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 24329 The following new requirements on POSIX implementations derive from alignment with the | 24330 Single UNIX Specification: | 24331 * The [EINVAL] error condition is added. | 24332 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 1218 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbsinit( ) 24333 NAME 24334 mbsinit - determine conversion object status 24335 SYNOPSIS 24336 #include 24337 int mbsinit(const mbstate_t *ps); 24338 DESCRIPTION 24339 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24340 conflict between the requirements described here and the ISO C standard is unintentional. This 24341 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24342 If ps is not a null pointer, the mbsinit( ) function shall determine whether the object pointed to by 24343 ps describes an initial conversion state. 24344 RETURN VALUE 24345 The mbsinit( ) function shall return non-zero if ps is a null pointer, or if the pointed-to object 24346 describes an initial conversion state; otherwise, it shall return zero. 24347 If an mbstate_t object is altered by any of the functions described as ``restartable'', and is then 24348 used with a different character sequence, or in the other conversion direction, or with a different 24349 LC_CTYPE category setting than on earlier function calls, the behavior is undefined. 24350 ERRORS 24351 No errors are defined. 24352 EXAMPLES 24353 None. 24354 APPLICATION USAGE 24355 The mbstate_t object is used to describe the current conversion state from a particular character 24356 sequence to a wide-character sequence (or vice versa) under the rules of a particular setting of the 24357 LC_CTYPE category of the current locale. 24358 The initial conversion state corresponds, for a conversion in either direction, to the beginning of 24359 a new character sequence in the initial shift state. A zero valued mbstate_t object is at least one 24360 way to describe an initial conversion state. A zero valued mbstate_t object can be used to initiate 24361 conversion involving any character sequence, in any LC_CTYPE category setting. 24362 RATIONALE 24363 None. 24364 FUTURE DIRECTIONS 24365 None. 24366 SEE ALSO 24367 mbrlen( ), mbrtowc( ), wcrtomb( ), mbsrtowcs( ), wcsrtombs( ), the Base Definitions volume of 24368 IEEE Std 1003.1-200x, 24369 CHANGE HISTORY 24370 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24371 (E). System Interfaces, Issue 6 1219 mbsrtowcs( ) System Interfaces 24372 NAME 24373 mbsrtowcs - convert a character string to a wide-character string (restartable) 24374 SYNOPSIS 24375 #include 24376 size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src, 24377 size_t len, mbstate_t *restrict ps); 24378 DESCRIPTION 24379 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24380 conflict between the requirements described here and the ISO C standard is unintentional. This 24381 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24382 The mbsrtowcs( ) function shall convert a sequence of characters, beginning in the conversion 24383 state described by the object pointed to by ps, from the array indirectly pointed to by src into a 24384 sequence of corresponding wide characters. If dst is not a null pointer, the converted characters | 24385 shall be stored into the array pointed to by dst. Conversion continues up to and including a | 24386 terminating null character, which shall also be stored. Conversion shall stop early in either of the | 24387 following cases: | 24388 * A sequence of bytes is encountered that does not form a valid character. 24389 * len codes have been stored into the array pointed to by dst (and dst is not a null pointer). 24390 Each conversion shall take place as if by a call to the mbrtowc( ) function. | 24391 If dst is not a null pointer, the pointer object pointed to by src shall be assigned either a null | 24392 pointer (if conversion stopped due to reaching a terminating null character) or the address just | 24393 past the last character converted (if any). If conversion stopped due to reaching a terminating 24394 null character, and if dst is not a null pointer, the resulting state described shall be the initial | 24395 conversion state. | 24396 If ps is a null pointer, the mbsrtowcs( ) function shall use its own internal mbstate_t object, which | 24397 is initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 24398 pointed to by ps shall be used to completely describe the current conversion state of the | 24399 associated character sequence. The implementation behaves as if no function defined in this | 24400 volume of IEEE Std 1003.1-200x calls mbsrtowcs( ). 24401 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. | 24402 RETURN VALUE 24403 If the input conversion encounters a sequence of bytes that do not form a valid character, an 24404 encoding error occurs. In this case, the mbsrtowcs( ) function stores the value of the macro 24405 [EILSEQ] in errno and shall return (size_t)-1; the conversion state is undefined. Otherwise, it 24406 shall return the number of characters successfully converted, not including the terminating null 24407 (if any). 24408 ERRORS 24409 The mbsrtowcs( ) function may fail if: 24410 CX [EINVAL] ps points to an object that contains an invalid conversion state. | 24411 [EILSEQ] Invalid character sequence is detected. 1220 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbsrtowcs( ) 24412 EXAMPLES 24413 None. 24414 APPLICATION USAGE 24415 None. 24416 RATIONALE 24417 None. 24418 FUTURE DIRECTIONS 24419 None. 24420 SEE ALSO 24421 mbsinit( ), mbrtowc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24422 CHANGE HISTORY 24423 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 24424 (E). 24425 Issue 6 24426 The mbsrtowcs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 24427 The [EINVAL] error condition is marked CX. | System Interfaces, Issue 6 1221 mbstowcs( ) System Interfaces 24428 NAME 24429 mbstowcs - convert a character string to a wide-character string 24430 SYNOPSIS 24431 #include 24432 size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, 24433 size_t n); 24434 DESCRIPTION 24435 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24436 conflict between the requirements described here and the ISO C standard is unintentional. This 24437 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24438 The mbstowcs( ) function shall convert a sequence of characters that begins in the initial shift 24439 state from the array pointed to by s into a sequence of corresponding wide-character codes and | 24440 shall store not more than n wide-character codes into the array pointed to by pwcs. No | 24441 characters that follow a null byte (which is converted into a wide-character code with value 0) 24442 shall be examined or converted. Each character shall be converted as if by a call to mbtowc( ), | 24443 except that the shift state of mbtowc( ) is not affected. 24444 No more than n elements shall be modified in the array pointed to by pwcs. If copying takes 24445 place between objects that overlap, the behavior is undefined. 24446 XSI The behavior of this function shall be affected by the LC_CTYPE category of the current locale. If 24447 pwcs is a null pointer, mbstowcs( ) shall return the length required to convert the entire array 24448 regardless of the value of n, but no values are stored. 24449 RETURN VALUE 24450 CX If an invalid character is encountered, mbstowcs( ) shall return (size_t)-1 and may set errno to 24451 XSI indicate the error. Otherwise, mbstowcs( ) shall return the number of the array elements modified | 24452 (or required if pwcs is null), not including a terminating 0 code, if any. The array shall not be | 24453 zero-terminated if the value returned is n. 24454 ERRORS 24455 The mbstowcs( ) function may fail if: 24456 XSI [EILSEQ] Invalid byte sequence is detected. 24457 EXAMPLES 24458 None. 24459 APPLICATION USAGE 24460 None. 24461 RATIONALE 24462 None. 24463 FUTURE DIRECTIONS 24464 None. 24465 SEE ALSO 24466 mblen( ), mbtowc( ), wctomb( ), wcstombs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24467 24468 CHANGE HISTORY 24469 First released in Issue 4. Aligned with the ISO C standard. 1222 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbstowcs( ) 24470 Issue 6 24471 The mbstowcs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 24472 Extensions beyond the ISO C standard are now marked. | System Interfaces, Issue 6 1223 mbtowc( ) System Interfaces 24473 NAME 24474 mbtowc - convert a character to a wide-character code 24475 SYNOPSIS 24476 #include 24477 int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n); 24478 DESCRIPTION 24479 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24480 conflict between the requirements described here and the ISO C standard is unintentional. This 24481 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24482 If s is not a null pointer, mbtowc( ) shall determine the number of the bytes that constitute the 24483 character pointed to by s. It shall then determine the wide-character code for the value of type | 24484 wchar_t that corresponds to that character. (The value of the wide-character code corresponding 24485 to the null byte is 0.) If the character is valid and pwc is not a null pointer, mbtowc( ) shall store | 24486 the wide-character code in the object pointed to by pwc. | 24487 The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 24488 state-dependent encoding, this function is placed into its initial state by a call for which its 24489 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null | 24490 pointer shall cause the internal state of the function to be altered as necessary. A call with s as a | 24491 null pointer shall cause this function to return a non-zero value if encodings have state | 24492 dependency, and 0 otherwise. If the implementation employs special bytes to change the shift | 24493 state, these bytes shall not produce separate wide-character codes, but shall be grouped with an | 24494 adjacent character. Changing the LC_CTYPE category causes the shift state of this function to be | 24495 unspecified. At most n bytes of the array pointed to by s shall be examined. | 24496 The implementation shall behave as if no function defined in this volume of 24497 IEEE Std 1003.1-200x calls mbtowc( ). 24498 RETURN VALUE 24499 If s is a null pointer, mbtowc( ) shall return a non-zero or 0 value, if character encodings, 24500 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mbtowc( ) 24501 shall either return 0 (if s points to the null byte), or return the number of bytes that constitute the 24502 CX converted character (if the next n or fewer bytes form a valid character), or return -1 and may 24503 set errno to indicate the error(if they do not form a valid character). 24504 In no case shall the value returned be greater than n or the value of the {MB_CUR_MAX} macro. 24505 ERRORS 24506 The mbtowc( ) function may fail if: 24507 XSI [EILSEQ] Invalid character sequence is detected. 24508 EXAMPLES 24509 None. 24510 APPLICATION USAGE 24511 None. 24512 RATIONALE 24513 None. 24514 FUTURE DIRECTIONS 24515 None. 1224 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mbtowc( ) 24516 SEE ALSO 24517 mblen( ), mbstowcs( ), wctomb( ), wcstombs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 24518 24519 CHANGE HISTORY 24520 First released in Issue 4. Aligned with the ISO C standard. 24521 Issue 6 24522 The mbtowc( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. | 24523 Extensions beyond the ISO C standard are now marked. | System Interfaces, Issue 6 1225 memccpy( ) System Interfaces 24524 NAME 24525 memccpy - copy bytes in memory 24526 SYNOPSIS 24527 XSI #include 24528 void *memccpy(void *restrict s1, const void *restrict s2, 24529 int c, size_t n); 24530 24531 DESCRIPTION 24532 The memccpy( ) function shall copy bytes from memory area s2 into s1, stopping after the first 24533 occurrence of byte c (converted to an unsigned char) is copied, or after n bytes are copied, 24534 whichever comes first. If copying takes place between objects that overlap, the behavior is 24535 undefined. 24536 RETURN VALUE 24537 The memccpy( ) function shall return a pointer to the byte after the copy of c in s1, or a null 24538 pointer if c was not found in the first n bytes of s2. 24539 ERRORS 24540 No errors are defined. 24541 EXAMPLES 24542 None. 24543 APPLICATION USAGE 24544 The memccpy( ) function does not check for the overflow of the receiving memory area. 24545 RATIONALE 24546 None. 24547 FUTURE DIRECTIONS 24548 None. 24549 SEE ALSO 24550 The Base Definitions volume of IEEE Std 1003.1-200x, 24551 CHANGE HISTORY 24552 First released in Issue 1. Derived from Issue 1 of the SVID. 24553 Issue 6 24554 The restrict keyword is added to the memccpy( ) prototype for alignment with the 24555 ISO/IEC 9899: 1999 standard. 1226 Technical Standard (2001) (Draft April 16, 2001) System Interfaces memchr( ) 24556 NAME 24557 memchr - find byte in memory 24558 SYNOPSIS 24559 #include 24560 void *memchr(const void *s, int c, size_t n); 24561 DESCRIPTION 24562 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24563 conflict between the requirements described here and the ISO C standard is unintentional. This 24564 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24565 The memchr( ) function shall locate the first occurrence of c (converted to an unsigned char) in 24566 the initial n bytes (each interpreted as unsigned char) of the object pointed to by s. 24567 RETURN VALUE 24568 The memchr( ) function shall return a pointer to the located byte, or a null pointer if the byte does 24569 not occur in the object. 24570 ERRORS 24571 No errors are defined. 24572 EXAMPLES 24573 None. 24574 APPLICATION USAGE 24575 None. 24576 RATIONALE 24577 None. 24578 FUTURE DIRECTIONS 24579 None. 24580 SEE ALSO 24581 The Base Definitions volume of IEEE Std 1003.1-200x, 24582 CHANGE HISTORY 24583 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 1227 memcmp( ) System Interfaces 24584 NAME 24585 memcmp - compare bytes in memory 24586 SYNOPSIS 24587 #include 24588 int memcmp(const void *s1, const void *s2, size_t n); 24589 DESCRIPTION 24590 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24591 conflict between the requirements described here and the ISO C standard is unintentional. This 24592 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24593 The memcmp( ) function shall compare the first n bytes (each interpreted as unsigned char) of the 24594 object pointed to by s1 to the first n bytes of the object pointed to by s2. 24595 The sign of a non-zero return value shall be determined by the sign of the difference between the 24596 values of the first pair of bytes (both interpreted as type unsigned char) that differ in the objects 24597 being compared. 24598 RETURN VALUE 24599 The memcmp( ) function shall return an integer greater than, equal to, or less than 0, if the object 24600 pointed to by s1 is greater than, equal to, or less than the object pointed to by s2, respectively. 24601 ERRORS 24602 No errors are defined. 24603 EXAMPLES 24604 None. 24605 APPLICATION USAGE 24606 None. 24607 RATIONALE 24608 None. 24609 FUTURE DIRECTIONS 24610 None. 24611 SEE ALSO 24612 The Base Definitions volume of IEEE Std 1003.1-200x, 24613 CHANGE HISTORY 24614 First released in Issue 1. Derived from Issue 1 of the SVID. 1228 Technical Standard (2001) (Draft April 16, 2001) System Interfaces memcpy( ) 24615 NAME 24616 memcpy - copy bytes in memory 24617 SYNOPSIS 24618 #include 24619 void *memcpy(void *restrict s1, const void *restrict s2, size_t n); 24620 DESCRIPTION 24621 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24622 conflict between the requirements described here and the ISO C standard is unintentional. This 24623 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24624 The memcpy( ) function shall copy n bytes from the object pointed to by s2 into the object pointed 24625 to by s1. If copying takes place between objects that overlap, the behavior is undefined. 24626 RETURN VALUE 24627 The memcpy( ) function shall return s1; no return value is reserved to indicate an error. 24628 ERRORS 24629 No errors are defined. 24630 EXAMPLES 24631 None. 24632 APPLICATION USAGE 24633 The memcpy( ) function does not check for the overflowing of the receiving memory area. 24634 RATIONALE 24635 None. 24636 FUTURE DIRECTIONS 24637 None. 24638 SEE ALSO 24639 The Base Definitions volume of IEEE Std 1003.1-200x, 24640 CHANGE HISTORY 24641 First released in Issue 1. Derived from Issue 1 of the SVID. 24642 Issue 6 24643 The memcpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1229 memmove( ) System Interfaces 24644 NAME 24645 memmove - copy bytes in memory with overlapping areas 24646 SYNOPSIS 24647 #include 24648 void *memmove(void *s1, const void *s2, size_t n); 24649 DESCRIPTION 24650 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24651 conflict between the requirements described here and the ISO C standard is unintentional. This 24652 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24653 The memmove( ) function shall copy n bytes from the object pointed to by s2 into the object 24654 pointed to by s1. Copying takes place as if the n bytes from the object pointed to by s2 are first 24655 copied into a temporary array of n bytes that does not overlap the objects pointed to by s1 and 24656 s2, and then the n bytes from the temporary array are copied into the object pointed to by s1. 24657 RETURN VALUE 24658 The memmove( ) function shall return s1; no return value is reserved to indicate an error. 24659 ERRORS 24660 No errors are defined. 24661 EXAMPLES 24662 None. 24663 APPLICATION USAGE 24664 None. 24665 RATIONALE 24666 None. 24667 FUTURE DIRECTIONS 24668 None. 24669 SEE ALSO 24670 The Base Definitions volume of IEEE Std 1003.1-200x, 24671 CHANGE HISTORY 24672 First released in Issue 4. Derived from the ANSI C standard. 1230 Technical Standard (2001) (Draft April 16, 2001) System Interfaces memset( ) 24673 NAME 24674 memset - set bytes in memory 24675 SYNOPSIS 24676 #include 24677 void *memset(void *s, int c, size_t n); 24678 DESCRIPTION 24679 CX The functionality described on this reference page is aligned with the ISO C standard. Any 24680 conflict between the requirements described here and the ISO C standard is unintentional. This 24681 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 24682 The memset( ) function shall copy c (converted to an unsigned char) into each of the first n bytes 24683 of the object pointed to by s. 24684 RETURN VALUE 24685 The memset( ) function shall return s; no return value is reserved to indicate an error. 24686 ERRORS 24687 No errors are defined. 24688 EXAMPLES 24689 None. 24690 APPLICATION USAGE 24691 None. 24692 RATIONALE 24693 None. 24694 FUTURE DIRECTIONS 24695 None. 24696 SEE ALSO 24697 The Base Definitions volume of IEEE Std 1003.1-200x, 24698 CHANGE HISTORY 24699 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 1231 mkdir( ) System Interfaces 24700 NAME 24701 mkdir - make a directory 24702 SYNOPSIS 24703 #include 24704 int mkdir(const char *path, mode_t mode); 24705 DESCRIPTION 24706 The mkdir( ) function shall create a new directory with name path. The file permission bits of the | 24707 new directory shall be initialized from mode. These file permission bits of the mode argument | 24708 shall be modified by the process' file creation mask. | 24709 When bits in mode other than the file permission bits are set, the meaning of these additional bits 24710 is implementation-defined. 24711 The directory's user ID shall be set to the process' effective user ID. The directory's group ID | 24712 shall be set to the group ID of the parent directory or to the effective group ID of the process. | 24713 Implementations shall provide a way to initialize the directory's group ID to the group ID of the | 24714 parent directory. Implementations may, but need not, provide an implementation-defined way | 24715 to initialize the directory's group ID to the effective group ID of the calling process. | 24716 The newly created directory shall be an empty directory. 24717 If path names a symbolic link, mkdir( ) shall fail and set errno to [EEXIST]. 24718 Upon successful completion, mkdir( ) shall mark for update the st_atime, st_ctime, and st_mtime 24719 fields of the directory. Also, the st_ctime and st_mtime fields of the directory that contains the 24720 new entry shall be marked for update. 24721 RETURN VALUE 24722 Upon successful completion, mkdir( ) shall return 0. Otherwise, -1 shall be returned, no directory 24723 shall be created, and errno shall be set to indicate the error. 24724 ERRORS 24725 The mkdir( ) function shall fail if: 24726 [EACCES] Search permission is denied on a component of the path prefix, or write 24727 permission is denied on the parent directory of the directory to be created. 24728 [EEXIST] The named file exists. 24729 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 24730 argument. 24731 [EMLINK] The link count of the parent directory would exceed {LINK_MAX}. 24732 [ENAMETOOLONG] 24733 The length of the path argument exceeds {PATH_MAX} or a pathname | 24734 component is longer than {NAME_MAX}. | 24735 [ENOENT] A component of the path prefix specified by path does not name an existing 24736 directory or path is an empty string. 24737 [ENOSPC] The file system does not contain enough space to hold the contents of the new 24738 directory or to extend the parent directory of the new directory. 24739 [ENOTDIR] A component of the path prefix is not a directory. 24740 [EROFS] The parent directory resides on a read-only file system. 1232 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mkdir( ) 24741 The mkdir( ) function may fail if: 24742 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24743 resolution of the path argument. 24744 [ENAMETOOLONG] 24745 As a result of encountering a symbolic link in resolution of the path argument, | 24746 the length of the substituted pathname string exceeded {PATH_MAX}. | 24747 EXAMPLES 24748 Creating a Directory 24749 The following example shows how to create a directory named /home/cnd/mod1, with 24750 read/write/search permissions for owner and group, and with read/search permissions for 24751 others. 24752 #include 24753 #include 24754 int status; 24755 ... 24756 status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); 24757 APPLICATION USAGE 24758 None. 24759 RATIONALE 24760 The mkdir( ) function originated in 4.2 BSD and was added to System V in Release 3.0. 24761 4.3 BSD detects [ENAMETOOLONG]. 24762 The POSIX.1-1990 standard required that the group ID of a newly created directory be set to the | 24763 group ID of its parent directory or to the effective group ID of the creating process. FIPS 151-2 | 24764 required that implementations provide a way to have the group ID be set to the group ID of the | 24765 containing directory, but did not prohibit implementations also supporting a way to set the | 24766 group ID to the effective group ID of the creating process. Conforming applications should not | 24767 assume which group ID will be used. If it matters, an application can use chown( ) to set the | 24768 group ID after the directory is created, or determine under what conditions the implementation | 24769 will set the desired group ID. | 24770 FUTURE DIRECTIONS 24771 None. 24772 SEE ALSO 24773 umask( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 24774 CHANGE HISTORY 24775 First released in Issue 3. 24776 Entry included for alignment with the POSIX.1-1988 standard. 24777 Issue 6 24778 In the SYNOPSIS, the optional include of the header is removed. 24779 The following new requirements on POSIX implementations derive from alignment with the | 24780 Single UNIX Specification: 24781 * The requirement to include has been removed. Although was 24782 required for conforming implementations of previous POSIX specifications, it was not 24783 required for UNIX applications. System Interfaces, Issue 6 1233 mkdir( ) System Interfaces 24784 * The [ELOOP] mandatory error condition is added. 24785 * A second [ENAMETOOLONG] is added as an optional error condition. 24786 The following changes were made to align with the IEEE P1003.1a draft standard: 24787 * The [ELOOP] optional error condition is added. 1234 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mkfifo( ) 24788 NAME 24789 mkfifo - make a FIFO special file 24790 SYNOPSIS 24791 #include 24792 int mkfifo(const char *path, mode_t mode); 24793 DESCRIPTION 24794 The mkfifo( ) function shall create a new FIFO special file named by the pathname pointed to by | 24795 path. The file permission bits of the new FIFO shall be initialized from mode. The file permission | 24796 bits of the mode argument shall be modified by the process' file creation mask. | 24797 When bits in mode other than the file permission bits are set, the effect is implementation- 24798 defined. 24799 If path names a symbolic link, mkfifo( ) shall fail and set errno to [EEXIST]. 24800 The FIFO's user ID shall be set to the process' effective user ID. The FIFO's group ID shall be set 24801 to the group ID of the parent directory or to the effective group ID of the process. | 24802 Implementation shall provide a way to initialize the FIFO's group ID to the group ID of the | 24803 parent directory. Implementations may, but need not, provide an implementation-defined way | 24804 to initialize the FIFO's group ID to the effective group ID of the calling process. | 24805 Upon successful completion, mkfifo( ) shall mark for update the st_atime, st_ctime, and st_mtime 24806 fields of the file. Also, the st_ctime and st_mtime fields of the directory that contains the new 24807 entry shall be marked for update. 24808 RETURN VALUE 24809 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, no FIFO shall 24810 be created, and errno shall be set to indicate the error. 24811 ERRORS 24812 The mkfifo( ) function shall fail if: 24813 [EACCES] A component of the path prefix denies search permission, or write permission 24814 is denied on the parent directory of the FIFO to be created. 24815 [EEXIST] The named file already exists. 24816 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 24817 argument. 24818 [ENAMETOOLONG] 24819 The length of the path argument exceeds {PATH_MAX} or a pathname | 24820 component is longer than {NAME_MAX}. | 24821 [ENOENT] A component of the path prefix specified by path does not name an existing 24822 directory or path is an empty string. 24823 [ENOSPC] The directory that would contain the new file cannot be extended or the file 24824 system is out of file-allocation resources. 24825 [ENOTDIR] A component of the path prefix is not a directory. 24826 [EROFS] The named file resides on a read-only file system. 24827 The mkfifo( ) function may fail if: 24828 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24829 resolution of the path argument. System Interfaces, Issue 6 1235 mkfifo( ) System Interfaces 24830 [ENAMETOOLONG] 24831 As a result of encountering a symbolic link in resolution of the path argument, | 24832 the length of the substituted pathname string exceeded {PATH_MAX}. | 24833 EXAMPLES 24834 Creating a FIFO File 24835 The following example shows how to create a FIFO file named /home/cnd/mod_done, with 24836 read/write permissions for owner, and with read permissions for group and others. 24837 #include 24838 #include 24839 int status; 24840 ... 24841 status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | 24842 S_IRGRP | S_IROTH); 24843 APPLICATION USAGE 24844 None. 24845 RATIONALE 24846 The syntax of this function is intended to maintain compatibility with historical 24847 implementations of mknod( ). The latter function was included in the 1984 /usr/group standard 24848 but only for use in creating FIFO special files. The mknod( ) function was originally excluded 24849 from the POSIX.1-1988 standard as implementation-defined and replaced by mkdir( ) and 24850 mkfifo( ). The mknod( ) function is now included for alignment with the Single UNIX 24851 Specification. 24852 The POSIX.1-1990 standard required that the group ID of a newly created FIFO be set to the | 24853 group ID of its parent directory or to the effective group ID of the creating process. FIPS 151-2 | 24854 required that implementations provide a way to have the group ID be set to the group ID of the | 24855 containing directory, but did not prohibit implementations also supporting a way to set the | 24856 group ID to the effective group ID of the creating process. Conforming applications should not | 24857 assume which group ID will be used. If it matters, an application can use chown( ) to set the | 24858 group ID after the FIFO is created, or determine under what conditions the implementation will | 24859 set the desired group ID. | 24860 FUTURE DIRECTIONS 24861 None. 24862 SEE ALSO 24863 umask( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 24864 CHANGE HISTORY 24865 First released in Issue 3. 24866 Entry included for alignment with the POSIX.1-1988 standard. 24867 Issue 6 24868 In the SYNOPSIS, the optional include of the header is removed. 24869 The following new requirements on POSIX implementations derive from alignment with the | 24870 Single UNIX Specification: 24871 * The requirement to include has been removed. Although was 24872 required for conforming implementations of previous POSIX specifications, it was not 24873 required for UNIX applications. 1236 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mkfifo( ) 24874 * The [ELOOP] mandatory error condition is added. 24875 * A second [ENAMETOOLONG] is added as an optional error condition. 24876 The following changes were made to align with the IEEE P1003.1a draft standard: 24877 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1237 mknod( ) System Interfaces 24878 NAME 24879 mknod - make a directory, a special or regular file 24880 SYNOPSIS 24881 XSI #include 24882 int mknod(const char *path, mode_t mode, dev_t dev); 24883 24884 DESCRIPTION 24885 The mknod( ) function shall create a new file named by the pathname to which the argument path | 24886 points. 24887 The file type for path is OR'ed into the mode argument, and the application shall select one of the 24888 following symbolic constants: 24889 __________________________________________ 24890 _ Name Description _________________________________________ 24891 S_IFIFO FIFO-special 24892 S_IFCHR Character-special (non-portable) 24893 S_IFDIR Directory (non-portable) 24894 S_IFBLK Block-special (non-portable) 24895 _ S_IFREG Regular (non-portable) _________________________________________ 24896 The only portable use of mknod( ) is to create a FIFO-special file. If mode is not S_IFIFO or dev is 24897 not 0, the behavior of mknod( ) is unspecified. 24898 The permissions for the new file are OR'ed into the mode argument, and may be selected from 24899 any combination of the following symbolic constants: 24900 ___________________________________________________ 24901 _ Name Description __________________________________________________ 24902 S_ISUID Set user ID on execution. 24903 S_ISGID Set group ID on execution. 24904 S_IRWXU Read, write, or execute (search) by owner. 24905 S_IRUSR Read by owner. 24906 S_IWUSR Write by owner. 24907 S_IXUSR Execute (search) by owner. 24908 S_IRWXG Read, write, or execute (search) by group. 24909 S_IRGRP Read by group. 24910 S_IWGRP Write by group. 24911 S_IXGRP Execute (search) by group. 24912 S_IRWXO Read, write, or execute (search) by others. 24913 S_IROTH Read by others. 24914 S_IWOTH Write by others. 24915 S_IXOTH Execute (search) by others. 24916 _ S_ISVTX On directories, restricted deletion flag. __________________________________________________ 24917 The user ID of the file shall be initialized to the effective user ID of the process. The group ID of | 24918 the file shall be initialized to either the effective group ID of the process or the group ID of the | 24919 parent directory. Implementations shall provide a way to initialize the file's group ID to the | 24920 group ID of the parent directory. Implementations may, but need not, provide an | 24921 implementation-defined way to initialize the file's gorup ID to the effective group ID of the | 24922 calling proces. | 1238 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mknod( ) 24923 The owner, group, and other permission bits of mode shall be modified by the file mode creation | 24924 mask of the process. The mknod( ) function shall clear each bit whose corresponding bit in the file | 24925 mode creation mask of the process is set. | 24926 If path names a symbolic link, mknod( ) shall fail and set errno to [EEXIST]. 24927 Upon successful completion, mknod( ) shall mark for update the st_atime, st_ctime, and st_mtime 24928 fields of the file. Also, the st_ctime and st_mtime fields of the directory that contains the new 24929 entry shall be marked for update. 24930 Only a process with appropriate privileges may invoke mknod( ) for file types other than FIFO- 24931 special. 24932 RETURN VALUE 24933 Upon successful completion, mknod( ) shall return 0. Otherwise, it shall return -1, the new file 24934 shall not be created, and errno shall be set to indicate the error. 24935 ERRORS 24936 The mknod( ) function shall fail if: 24937 [EACCES] A component of the path prefix denies search permission, or write permission 24938 is denied on the parent directory. 24939 [EEXIST] The named file exists. 24940 [EINVAL] An invalid argument exists. 24941 [EIO] An I/O error occurred while accessing the file system. 24942 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 24943 argument. 24944 [ENAMETOOLONG] 24945 The length of a pathname exceeds {PATH_MAX} or a pathname component is | 24946 longer than {NAME_MAX}. | 24947 [ENOENT] A component of the path prefix specified by path does not name an existing 24948 directory or path is an empty string. 24949 [ENOSPC] The directory that would contain the new file cannot be extended or the file 24950 system is out of file allocation resources. 24951 [ENOTDIR] A component of the path prefix is not a directory. 24952 [EPERM] The invoking process does not have appropriate privileges and the file type is 24953 not FIFO-special. 24954 [EROFS] The directory in which the file is to be created is located on a read-only file 24955 system. 24956 The mknod( ) function may fail if: 24957 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 24958 resolution of the path argument. 24959 [ENAMETOOLONG] 24960 Pathname resolution of a symbolic link produced an intermediate result | 24961 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 1239 mknod( ) System Interfaces 24962 EXAMPLES 24963 Creating a FIFO Special File 24964 The following example shows how to create a FIFO special file named /home/cnd/mod_done, 24965 with read/write permissions for owner, and with read permissions for group and others. 24966 #include 24967 #include 24968 dev_t dev; 24969 int status; 24970 ... 24971 status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | 24972 S_IRUSR | S_IRGRP | S_IROTH, dev); 24973 APPLICATION USAGE 24974 mkfifo( ) is preferred over this function for making FIFO special files. 24975 RATIONALE 24976 The POSIX.1-1990 standard required that the group ID of a newly created file be set to the group | 24977 ID of its parent directory or to the effective group ID of the creating process. FIPS 151-2 required | 24978 that implementations provide a way to have the group ID be set to the group ID of the | 24979 containing directory, but did not prohibit implementations also supporting a way to set the | 24980 group ID to the effective group ID of the creating process. Conforming applications should not | 24981 assume which group ID will be used. If it matters, an application can use chown( ) to set the | 24982 group ID after the file is created, or determine under what conditions the implementation will | 24983 set the desired group ID. | 24984 FUTURE DIRECTIONS 24985 None. 24986 SEE ALSO 24987 chmod( ), creat( ), exec, mkdir( ), mkfifo( ), open( ), stat( ), umask( ), the Base Definitions volume of 24988 IEEE Std 1003.1-200x, 24989 CHANGE HISTORY 24990 First released in Issue 4, Version 2. 24991 Issue 5 24992 Moved from X/OPEN UNIX extension to BASE. 24993 Issue 6 24994 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 24995 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 24996 [ELOOP] error condition is added. 1240 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mkstemp( ) 24997 NAME 24998 mkstemp - make a unique filename 24999 SYNOPSIS 25000 XSI #include 25001 int mkstemp(char *template); 25002 25003 DESCRIPTION 25004 The mkstemp( ) function shall replace the contents of the string pointed to by template by a unique 25005 filename, and return a file descriptor for the file open for reading and writing. The function thus 25006 prevents any possible race condition between testing whether the file exists and opening it for 25007 use. The string in template should look like a filename with six trailing Xs; mkstemp( ) replaces 25008 each X with a character from the portable filename character set. The characters are chosen such 25009 that the resulting name does not duplicate the name of an existing file at the time of a call to 25010 mkstemp( ). 25011 RETURN VALUE 25012 Upon successful completion, mkstemp( ) shall return an open file descriptor. Otherwise, -1 shall 25013 be returned if no suitable file could be created. 25014 ERRORS 25015 No errors are defined. 25016 EXAMPLES 25017 Generating a Filename 25018 The following example creates a file with a 10-character name beginning with the characters 25019 "file" and opens the file for reading and writing. The value returned as the value of fd is a file 25020 descriptor that identifies the file. 25021 #include 25022 ... 25023 char template[] = "/tmp/fileXXXXXX"; | 25024 int fd; | 25025 fd = mkstemp(template); 25026 APPLICATION USAGE 25027 It is possible to run out of letters. 25028 The mkstemp( ) function need not check to determine whether the filename part of template 25029 exceeds the maximum allowable filename length. 25030 RATIONALE 25031 None. 25032 FUTURE DIRECTIONS 25033 None. 25034 SEE ALSO 25035 getpid( ), open( ), tmpfile( ), tmpnam( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25036 System Interfaces, Issue 6 1241 mkstemp( ) System Interfaces 25037 CHANGE HISTORY 25038 First released in Issue 4, Version 2. 25039 Issue 5 25040 Moved from X/OPEN UNIX extension to BASE. 1242 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mktemp( ) 25041 NAME 25042 mktemp - make a unique filename (LEGACY) 25043 SYNOPSIS 25044 XSI #include 25045 char *mktemp(char *template); 25046 25047 DESCRIPTION 25048 The mktemp( ) function shall replace the contents of the string pointed to by template by a unique 25049 filename and return template. The application shall initialize template to be a filename with six 25050 trailing Xs; mktemp( ) shall replace each X with a single byte character from the portable filename 25051 character set. 25052 RETURN VALUE 25053 The mktemp( ) function shall return the pointer template. If a unique name cannot be created, 25054 template shall point to a null string. 25055 ERRORS 25056 No errors are defined. 25057 EXAMPLES 25058 Generating a Filename 25059 The following example replaces the contents of the "template" string with a 10-character 25060 filename beginning with the characters "file" and returns a pointer to the "template" string 25061 that contains the new filename. 25062 #include 25063 ... 25064 char *template = "/tmp/fileXXXXXX"; 25065 char *ptr; 25066 ptr = mktemp(template); 25067 APPLICATION USAGE 25068 Between the time a pathname is created and the file opened, it is possible for some other process | 25069 to create a file with the same name. The mkstemp( ) function avoids this problem and is preferred 25070 over this function. 25071 RATIONALE 25072 None. 25073 FUTURE DIRECTIONS 25074 This function may be withdrawn in a future version. 25075 SEE ALSO 25076 mkstemp( ), tmpfile( ), tmpnam( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25077 CHANGE HISTORY 25078 First released in Issue 4, Version 2. 25079 Issue 5 25080 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1243 mktemp( ) System Interfaces 25081 Issue 6 25082 This function is marked LEGACY. 25083 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1244 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mktime( ) 25084 NAME 25085 mktime - convert broken-down time into time since the Epoch 25086 SYNOPSIS 25087 #include 25088 time_t mktime(struct tm *timeptr); 25089 DESCRIPTION 25090 CX The functionality described on this reference page is aligned with the ISO C standard. Any 25091 conflict between the requirements described here and the ISO C standard is unintentional. This 25092 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 25093 The mktime( ) function shall convert the broken-down time, expressed as local time, in the 25094 structure pointed to by timeptr, into a time since the Epoch value with the same encoding as that 25095 of the values returned by time( ). The original values of the tm_wday and tm_yday components of 25096 the structure are ignored, and the original values of the other components are not restricted to 25097 the ranges described in . 25098 CX A positive or 0 value for tm_isdst shall cause mktime( ) to presume initially that Daylight Savings 25099 Time, respectively, is or is not in effect for the specified time. A negative value for tm_isdst shall 25100 cause mktime( ) to attempt to determine whether Daylight Saving Time is in effect for the 25101 specified time. 25102 Local timezone information shall be set as though mktime( ) called tzset( ). | 25103 The relationship between the tm structure (defined in the header) and the time in | 25104 seconds since the Epoch is that the result shall be as specified in the expression given in the | 25105 definition of seconds since the Epoch (see the Base Definitions volume of IEEE Std 1003.1-200x, | 25106 Section 4.14, Seconds Since the Epoch) corrected for timezone and any seasonal time | 25107 adjustments, where the names in the structure and in the expression correspond. | 25108 Upon successful completion, the values of the tm_wday and tm_yday components of the structure 25109 shall be set appropriately, and the other components are set to represent the specified time since 25110 the Epoch, but with their values forced to the ranges indicated in the entry; the final 25111 value of tm_mday shall not be set until tm_mon and tm_year are determined. 25112 RETURN VALUE 25113 The mktime( ) function shall return the specified time since the Epoch encoded as a value of type 25114 time_t. If the time since the Epoch cannot be represented, the function shall return the value 25115 (time_t)-1. 25116 ERRORS 25117 No errors are defined. 25118 EXAMPLES 25119 What day of the week is July 4, 2001? 25120 #include 25121 #include 25122 struct tm time_str; 25123 char daybuf[20]; 25124 int main(void) 25125 { 25126 time_str.tm_year = 2001 - 1900; 25127 time_str.tm_mon = 7 - 1; 25128 time_str.tm_mday = 4; System Interfaces, Issue 6 1245 mktime( ) System Interfaces 25129 time_str.tm_hour = 0; 25130 time_str.tm_min = 0; 25131 time_str.tm_sec = 1; 25132 time_str.tm_isdst = -1; 25133 if (mktime(&time_str) == -1) 25134 (void)puts("-unknown-"); 25135 else { 25136 (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); 25137 (void)puts(daybuf); 25138 } 25139 return 0; 25140 } 25141 APPLICATION USAGE 25142 None. 25143 RATIONALE 25144 None. 25145 FUTURE DIRECTIONS 25146 None. 25147 SEE ALSO 25148 asctime( ), clock( ), ctime( ), difftime( ), gmtime( ), localtime( ), strftime( ), strptime( ), time( ), utime( ), 25149 the Base Definitions volume of IEEE Std 1003.1-200x, 25150 CHANGE HISTORY 25151 First released in Issue 3. 25152 Entry included for alignment with the POSIX.1-1988 standard and the ANSI C standard. 25153 Issue 6 25154 Extensions beyond the ISO C standard are now marked. 1246 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mlock( ) 25155 NAME 25156 mlock, munlock - lock or unlock a range of process address space (REALTIME) 25157 SYNOPSIS 25158 MLR #include 25159 int mlock(const void *addr, size_t len); 25160 int munlock(const void *addr, size_t len); 25161 25162 DESCRIPTION 25163 The mlock( ) function shall cause those whole pages containing any part of the address space of 25164 the process starting at address addr and continuing for len bytes to be memory-resident until 25165 unlocked or until the process exits or execs another process image. The implementation may 25166 require that addr be a multiple of {PAGESIZE}. 25167 The munlock( ) function shall unlock those whole pages containing any part of the address space 25168 of the process starting at address addr and continuing for len bytes, regardless of how many 25169 times mlock( ) has been called by the process for any of the pages in the specified range. The 25170 implementation may require that addr be a multiple of {PAGESIZE}. | 25171 If any of the pages in the range specified to a call to munlock( ) are also mapped into the address 25172 spaces of other processes, any locks established on those pages by another process are 25173 unaffected by the call of this process to munlock( ). If any of the pages in the range specified by a 25174 call to munlock( ) are also mapped into other portions of the address space of the calling process 25175 outside the range specified, any locks established on those pages via the other mappings are also 25176 unaffected by this call. 25177 Upon successful return from mlock( ), pages in the specified range shall be locked and memory- 25178 resident. Upon successful return from munlock( ), pages in the specified range shall be unlocked 25179 with respect to the address space of the process. Memory residency of unlocked pages is 25180 unspecified. 25181 The appropriate privilege is required to lock process memory with mlock( ). 25182 RETURN VALUE 25183 Upon successful completion, the mlock( ) and munlock( ) functions shall return a value of zero. 25184 Otherwise, no change is made to any locks in the address space of the process, and the function 25185 shall return a value of -1 and set errno to indicate the error. 25186 ERRORS 25187 The mlock( ) and munlock( ) functions shall fail if: 25188 [ENOMEM] Some or all of the address range specified by the addr and len arguments does 25189 not correspond to valid mapped pages in the address space of the process. 25190 The mlock( ) function shall fail if: 25191 [EAGAIN] Some or all of the memory identified by the operation could not be locked 25192 when the call was made. 25193 The mlock( ) and munlock( ) functions may fail if: 25194 [EINVAL] The addr argument is not a multiple of {PAGESIZE}. 25195 The mlock( ) function may fail if: 25196 [ENOMEM] Locking the pages mapped by the specified range would exceed an 25197 implementation-defined limit on the amount of memory that the process may 25198 lock. System Interfaces, Issue 6 1247 mlock( ) System Interfaces 25199 [EPERM] The calling process does not have the appropriate privilege to perform the 25200 requested operation. 25201 EXAMPLES 25202 None. 25203 APPLICATION USAGE 25204 None. 25205 RATIONALE 25206 None. 25207 FUTURE DIRECTIONS 25208 None. 25209 SEE ALSO 25210 exec, exit( ), fork( ), mlockall( ), munmap( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25211 25212 CHANGE HISTORY 25213 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25214 Issue 6 25215 The mlock( ) and munlock( ) functions are marked as part of the Range Memory Locking option. 25216 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25217 implementation does not support the Range Memory Locking option. 1248 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mlockall( ) 25218 NAME 25219 mlockall, munlockall - lock/unlock the address space of a process (REALTIME) 25220 SYNOPSIS 25221 ML #include 25222 int mlockall(int flags); 25223 int munlockall(void); 25224 25225 DESCRIPTION 25226 The mlockall( ) function shall cause all of the pages mapped by the address space of a process to 25227 be memory-resident until unlocked or until the process exits or execs another process image. The 25228 flags argument determines whether the pages to be locked are those currently mapped by the 25229 address space of the process, those that are mapped in the future, or both. The flags argument is 25230 constructed from the bitwise-inclusive OR of one or more of the following symbolic constants, 25231 defined in : 25232 MCL_CURRENT Lock all of the pages currently mapped into the address space of the process. 25233 MCL_FUTURE Lock all of the pages that become mapped into the address space of the 25234 process in the future, when those mappings are established. 25235 If MCL_FUTURE is specified, and the automatic locking of future mappings eventually causes 25236 the amount of locked memory to exceed the amount of available physical memory or any other 25237 implementation-defined limit, the behavior is implementation-defined. The manner in which the 25238 implementation informs the application of these situations is also implementation-defined. 25239 The munlockall( ) function shall unlock all currently mapped pages of the address space of the | 25240 process. Any pages that become mapped into the address space of the process after a call to | 25241 munlockall( ) shall not be locked, unless there is an intervening call to mlockall( ) specifying 25242 MCL_FUTURE or a subsequent call to mlockall( ) specifying MCL_CURRENT. If pages mapped 25243 into the address space of the process are also mapped into the address spaces of other processes 25244 and are locked by those processes, the locks established by the other processes shall be | 25245 unaffected by a call by this process to munlockall( ). | 25246 Upon successful return from the mlockall( ) function that specifies MCL_CURRENT, all currently 25247 mapped pages of the process' address space shall be memory-resident and locked. Upon return 25248 from the munlockall( ) function, all currently mapped pages of the process' address space shall be 25249 unlocked with respect to the process' address space. The memory residency of unlocked pages is 25250 unspecified. 25251 The appropriate privilege is required to lock process memory with mlockall( ). 25252 RETURN VALUE 25253 Upon successful completion, the mlockall( ) function shall return a value of zero. Otherwise, no 25254 additional memory shall be locked, and the function shall return a value of -1 and set errno to 25255 indicate the error. The effect of failure of mlockall( ) on previously existing locks in the address 25256 space is unspecified. 25257 If it is supported by the implementation, the munlockall( ) function shall always return a value of 25258 zero. Otherwise, the function shall return a value of -1 and set errno to indicate the error. 25259 ERRORS 25260 The mlockall( ) function shall fail if: 25261 [EAGAIN] Some or all of the memory identified by the operation could not be locked 25262 when the call was made. System Interfaces, Issue 6 1249 mlockall( ) System Interfaces 25263 [EINVAL] The flags argument is zero, or includes unimplemented flags. 25264 The mlockall( ) function may fail if: 25265 [ENOMEM] Locking all of the pages currently mapped into the address space of the 25266 process would exceed an implementation-defined limit on the amount of 25267 memory that the process may lock. 25268 [EPERM] The calling process does not have the appropriate privilege to perform the 25269 requested operation. 25270 EXAMPLES 25271 None. 25272 APPLICATION USAGE 25273 None. 25274 RATIONALE 25275 None. 25276 FUTURE DIRECTIONS 25277 None. 25278 SEE ALSO 25279 exec, exit( ), fork( ), mlock( ), munmap( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25280 25281 CHANGE HISTORY 25282 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25283 Issue 6 25284 The mlockall( ) and munlockall( ) functions are marked as part of the Process Memory Locking 25285 option. 25286 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25287 implementation does not support the Process Memory Locking option. 1250 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mmap( ) 25288 NAME 25289 mmap - map pages of memory 25290 SYNOPSIS 25291 MF|SHM #include 25292 void *mmap(void *addr, size_t len, int prot, int flags, 25293 int fildes, off_t off); 25294 25295 DESCRIPTION 25296 The mmap( ) function shall establish a mapping between a process' address space and a file, 25297 TYM shared memory object, or typed memory object. The format of the call is as follows: 25298 pa=mmap(addr, len, prot, flags, fildes, off); 25299 The mmap( ) function shall establish a mapping between the address space of the process at an | 25300 address pa for len bytes to the memory object represented by the file descriptor fildes at offset off | 25301 for len bytes. The value of pa is an implementation-defined function of the parameter addr and 25302 the values of flags, further described below. A successful mmap( ) call shall return pa as its result. 25303 The address range starting at pa and continuing for len bytes shall be legitimate for the possible 25304 (not necessarily current) address space of the process. The range of bytes starting at off and 25305 continuing for len bytes shall be legitimate for the possible (not necessarily current) offsets in the 25306 TYM file, shared memory object, or typed memory objectrepresented by fildes. 25307 TYM If fildes represents a typed memory object opened with either the 25308 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG 25309 flag, the memory object to be mapped shall be that portion of the typed memory object allocated 25310 by the implementation as specified below. In this case, if off is non-zero, the behavior of mmap( ) 25311 is undefined. If fildes refers to a valid typed memory object that is not accessible from the calling 25312 process, mmap( ) shall fail. 25313 The mapping established by mmap( ) shall replace any previous mappings for those whole pages | 25314 containing any part of the address space of the process starting at pa and continuing for len | 25315 bytes. 25316 If the size of the mapped file changes after the call to mmap( ) as a result of some other operation 25317 on the mapped file, the effect of references to portions of the mapped region that correspond to 25318 added or removed portions of the file is unspecified. 25319 TYM The mmap( ) function shall be supported for regular files, shared memory objects, and typed | 25320 memory objects. Support for any other type of file is unspecified. 25321 The parameter prot determines whether read, write, execute, or some combination of accesses 25322 are permitted to the data being mapped. The prot shall be either PROT_NONE or the bitwise- | 25323 inclusive OR of one or more of the other flags in the following table, defined in the 25324 header. 25325 ____________________________________________ 25326 _ Symbolic Constant Description ___________________________________________ 25327 PROT_READ Data can be read. 25328 PROT_WRITE Data can be written. 25329 PROT_EXEC Data can be executed. 25330 _ PROT_NONE Data cannot be accessed. ___________________________________________ 25331 If an implementation cannot support the combination of access types specified by prot, the call 25332 MPR to mmap( ) shall fail. An implementation may permit accesses other than those specified by prot; | 25333 however, if the Memory Protection option is supported, the implementation shall not permit a System Interfaces, Issue 6 1251 mmap( ) System Interfaces 25334 write to succeed where PROT_WRITE has not been set or shall not permit any access where 25335 PROT_NONE alone has been set. The implementation shall support at least the following values 25336 of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of 25337 PROT_READ and PROT_WRITE. If the Memory Protection option is not supported, the result of 25338 any access that conflicts with the specified protection is undefined. The file descriptor fildes shall 25339 have been opened with read permission, regardless of the protection options specified. If 25340 PROT_WRITE is specified, the application shall ensure that it has opened the file descriptor 25341 fildes with write permission unless MAP_PRIVATE is specified in the flags parameter as 25342 described below. 25343 The parameter flags provides other information about the handling of the mapped data. The 25344 value of flags is the bitwise-inclusive OR of these options, defined in : 25345 __________________________________________ 25346 _ Symbolic Constant Description _________________________________________ 25347 MAP_SHARED Changes are shared. 25348 MAP_PRIVATE Changes are private. 25349 _ MAP_FIXED Interpret addr exactly. _________________________________________ 25350 Implementations that do not support the Memory Mapped Files option are not required to 25351 support MAP_PRIVATE. 25352 XSI It is implementation-defined whether MAP_FIXED shall be supported. MAP_FIXED shall be 25353 supported on XSI-conformant systems. 25354 MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory 25355 object. If MAP_SHARED is specified, write references shall change the underlying object. If | 25356 MAP_PRIVATE is specified, modifications to the mapped data by the calling process shall be | 25357 visible only to the calling process and shall not change the underlying object. It is unspecified 25358 whether modifications to the underlying object done after the MAP_PRIVATE mapping is 25359 established are visible through the MAP_PRIVATE mapping. Either MAP_SHARED or 25360 MAP_PRIVATE can be specified, but not both. The mapping type is retained across fork( ). 25361 TYM When fildes represents a typed memory object opened with either the 25362 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG 25363 flag, mmap( ) shall, if there are enough resources available, map len bytes allocated from the 25364 corresponding typed memory object which were not previously allocated to any process in any 25365 processor that may access that typed memory object. If there are not enough resources available, 25366 the function shall fail. If fildes represents a typed memory object opened with the 25367 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be contiguous 25368 within the typed memory object. If fildes represents a typed memory object opened with the 25369 POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of non- 25370 contiguous fragments within the typed memory object. If fildes represents a typed memory 25371 object opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the 25372 POSIX_TYPED_MEM_ALLOCATE flag, len bytes starting at offset off within the typed memory 25373 object are mapped, exactly as when mapping a file or shared memory object. In this case, if two 25374 processes map an area of typed memory using the same off and len values and using file 25375 descriptors that refer to the same memory pool (either from the same port or from a different 25376 port), both processes shall map the same region of storage. 25377 When MAP_FIXED is set in the flags argument, the implementation is informed that the value of 25378 pa shall be addr, exactly. If MAP_FIXED is set, mmap( ) may return MAP_FAILED and set errno to 25379 [EINVAL]. If a MAP_FIXED request is successful, the mapping established by mmap( ) replaces 25380 any previous mappings for the process' pages in the range [pa,pa+len). 1252 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mmap( ) 25381 When MAP_FIXED is not set, the implementation uses addr in an implementation-defined 25382 manner to arrive at pa. The pa so chosen shall be an area of the address space that the 25383 implementation deems suitable for a mapping of len bytes to the file. All implementations 25384 interpret an addr value of 0 as granting the implementation complete freedom in selecting pa, 25385 subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a 25386 process address near which the mapping should be placed. When the implementation selects a 25387 value for pa, it never places a mapping at address 0, nor does it replace any extant mapping. 25388 The off argument is constrained to be aligned and sized according to the value returned by 25389 sysconf( ) when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the 25390 application shall ensure that the argument addr also meets these constraints. The 25391 implementation performs mapping operations over whole pages. Thus, while the argument len 25392 need not meet a size or alignment constraint, the implementation shall include, in any mapping 25393 operation, any partial page specified by the range [pa,pa+len). 25394 The system shall always zero-fill any partial page at the end of an object. Further, the system 25395 shall never write out any modified portions of the last page of an object which are beyond its 25396 MPR end. References within the address range starting at pa and continuing for len bytes to whole 25397 pages following the end of an object shall result in delivery of a SIGBUS signal. 25398 An implementation may generate SIGBUS signals when a reference would cause an error in the 25399 mapped object, such as out-of-space condition. 25400 The mmap( ) function shall add an extra reference to the file associated with the file descriptor | 25401 fildes which is not removed by a subsequent close( ) on that file descriptor. This reference shall be | 25402 removed when there are no more mappings to the file. | 25403 The st_atime field of the mapped file may be marked for update at any time between the mmap( ) 25404 call and the corresponding munmap( ) call. The initial read or write reference to a mapped region 25405 shall cause the file's st_atime field to be marked for update if it has not already been marked for 25406 update. 25407 The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE 25408 shall be marked for update at some point in the interval between a write reference to the 25409 mapped region and the next call to msync( ) with MS_ASYNC or MS_SYNC for that portion of 25410 the file by any process. If there is no such call and if the underlying file is modified as a result of 25411 a write reference, then these fields shall be marked for update at some time after the write 25412 reference. 25413 There may be implementation-defined limits on the number of memory regions that can be 25414 mapped (per process or per system). 25415 XSI If such a limit is imposed, whether the number of memory regions that can be mapped by a 25416 process is decreased by the use of shmat( ) is implementation-defined. 25417 If mmap( ) fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP], some of the 25418 mappings in the address range starting at addr and continuing for len bytes may have been 25419 unmapped. 25420 RETURN VALUE 25421 Upon successful completion, the mmap( ) function shall return the address at which the mapping 25422 was placed (pa); otherwise, it shall return a value of MAP_FAILED and set errno to indicate the | 25423 error. The symbol MAP_FAILED is defined in the header. No successful return | 25424 from mmap( ) shall return the value MAP_FAILED. | System Interfaces, Issue 6 1253 mmap( ) System Interfaces 25425 ERRORS 25426 The mmap( ) function shall fail if: 25427 [EACCES] The fildes argument is not open for read, regardless of the protection specified, 25428 or fildes is not open for write and PROT_WRITE was specified for a 25429 MAP_SHARED type mapping. 25430 ML [EAGAIN] The mapping could not be locked in memory, if required by mlockall( ), due to 25431 a lack of resources. 25432 [EBADF] The fildes argument is not a valid open file descriptor. 25433 [EINVAL] The addr argument (if MAP_FIXED was specified) or off is not a multiple of 25434 the page size as returned by sysconf( ), or are considered invalid by the 25435 implementation. 25436 [EINVAL] The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is 25437 set). 25438 [EMFILE] The number of mapped regions would exceed an implementation-defined 25439 limit (per process or per system). 25440 [ENODEV] The fildes argument refers to a file whose type is not supported by mmap( ). 25441 [ENOMEM] MAP_FIXED was specified, and the range [addr,addr+len) exceeds that allowed 25442 for the address space of a process; or, if MAP_FIXED was not specified and 25443 there is insufficient room in the address space to effect the mapping. 25444 ML [ENOMEM] The mapping could not be locked in memory, if required by mlockall( ), 25445 because it would require more space than the system is able to supply. 25446 MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the 25447 implementation does not support this functionality. 25448 TYM [ENOMEM] Not enough unallocated memory resources remain in the typed memory 25449 object designated by fildes to allocate len bytes. 25450 [ENOTSUP] The implementation does not support the combination of accesses requested 25451 in the prot argument. 25452 [ENXIO] Addresses in the range [off,off+len) are invalid for the object specified by fildes. 25453 [ENXIO] MAP_FIXED was specified in flags and the combination of addr, len, and off is 25454 invalid for the object specified by fildes. 25455 TYM [ENXIO] The fildes argument refers to a typed memory object that is not accessible from 25456 the calling process. 25457 [EOVERFLOW] The file is a regular file and the value of off plus len exceeds the offset 25458 maximum established in the open file description associated with fildes. 25459 EXAMPLES 25460 None. 25461 APPLICATION USAGE 25462 Use of mmap( ) may reduce the amount of memory available to other memory allocation 25463 functions. 25464 Use of MAP_FIXED may result in unspecified behavior in further use of malloc( ) and shmat( ). 25465 The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the 25466 most effective use of resources. 1254 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mmap( ) 25467 The application must ensure correct synchronization when using mmap( ) in conjunction with 25468 any other file access method, such as read( ) and write( ), standard input/output, and shmat( ). 25469 The mmap( ) function allows access to resources via address space manipulations, instead of 25470 read( )/write( ). Once a file is mapped, all a process has to do to access it is use the data at the 25471 address to which the file was mapped. So, using pseudo-code to illustrate the way in which an 25472 existing program might be changed to use mmap( ), the following: 25473 fildes = open(...) 25474 lseek(fildes, some_offset) 25475 read(fildes, buf, len) 25476 /* Use data in buf. */ 25477 becomes: 25478 fildes = open(...) 25479 address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) 25480 /* Use data at address. */ 25481 The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 25482 Realtime Extension. 25483 RATIONALE 25484 After considering several other alternatives, it was decided to adopt the mmap( ) definition found 25485 in SVR4 for mapping memory objects into process address spaces. The SVR4 definition is 25486 minimal, in that it describes only what has been built, and what appears to be necessary for a 25487 general and portable mapping facility. 25488 Note that while mmap( ) was first designed for mapping files, it is actually a general-purpose 25489 mapping facility. It can be used to map any appropriate object, such as memory, files, devices, 25490 and so on, into the address space of a process. 25491 When a mapping is established, it is possible that the implementation may need to map more 25492 than is requested into the address space of the process because of hardware requirements. An 25493 application, however, cannot count on this behavior. Implementations that do not use a paged 25494 architecture may simply allocate a common memory region and return the address of it; such 25495 implementations probably do not allocate any more than is necessary. References past the end of 25496 the requested area are unspecified. 25497 If an application requests a mapping that would overlay existing mappings in the process, it 25498 might be desirable that an implementation detect this and inform the application. However, the 25499 default, portable (not MAP_FIXED) operation does not overlay existing mappings. On the other 25500 hand, if the program specifies a fixed address mapping (which requires some implementation 25501 knowledge to determine a suitable address, if the function is supported at all), then the program 25502 is presumed to be successfully managing its own address space and should be trusted when it 25503 asks to map over existing data structures. Furthermore, it is also desirable to make as few system 25504 calls as possible, and it might be considered onerous to require an munmap( ) before an mmap( ) 25505 to the same address range. This volume of IEEE Std 1003.1-200x specifies that the new mappings 25506 replace any existing mappings, following existing practice in this regard. 25507 It is not expected, when the Memory Protection option is supported, that all hardware 25508 implementations are able to support all combinations of permissions at all addresses. When this 25509 option is supported, implementations are required to disallow write access to mappings without 25510 write permission and to disallow access to mappings without any access permission. Other than 25511 these restrictions, implementations may allow access types other than those requested by the 25512 application. For example, if the application requests only PROT_WRITE, the implementation 25513 may also allow read access. A call to mmap( ) fails if the implementation cannot support allowing System Interfaces, Issue 6 1255 mmap( ) System Interfaces 25514 all the access requested by the application. For example, some implementations cannot support 25515 a request for both write access and execute access simultaneously. All implementations 25516 supporting the Memory Protection option must support requests for no access, read access, 25517 write access, and both read and write access. Strictly conforming code must only rely on the 25518 required checks. These restrictions allow for portability across a wide range of hardware. 25519 The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for certain 25520 architecture-dependent address ranges. Conforming implementations cannot count on being 25521 able to choose address values for MAP_FIXED without utilizing non-portable, implementation- 25522 defined knowledge. Nonetheless, MAP_FIXED is provided as a standard interface conforming to 25523 existing practice for utilizing such knowledge when it is available. 25524 Similarly, in order to allow implementations that do not support virtual addresses, support for 25525 directly specifying any mapping addresses via MAP_FIXED is not required and thus a 25526 conforming application may not count on it. 25527 The MAP_PRIVATE function can be implemented efficiently when memory protection hardware 25528 is available. When such hardware is not available, implementations can implement such 25529 ``mappings'' by simply making a real copy of the relevant data into process private memory, 25530 though this tends to behave similarly to read( ). 25531 The function has been defined to allow for many different models of using shared memory. 25532 However, all uses are not equally portable across all machine architectures. In particular, the 25533 mmap( ) function allows the system as well as the application to specify the address at which to 25534 map a specific region of a memory object. The most portable way to use the function is always to 25535 let the system choose the address, specifying NULL as the value for the argument addr and not 25536 to specify MAP_FIXED. 25537 If it is intended that a particular region of a memory object be mapped at the same address in a 25538 group of processes (on machines where this is even possible), then MAP_FIXED can be used to 25539 pass in the desired mapping address. The system can still be used to choose the desired address 25540 if the first such mapping is made without specifying MAP_FIXED, and then the resulting 25541 mapping address can be passed to subsequent processes for them to pass in via MAP_FIXED. 25542 The availability of a specific address range cannot be guaranteed, in general. 25543 The mmap( ) function can be used to map a region of memory that is larger than the current size 25544 of the object. Memory access within the mapping but beyond the current end of the underlying 25545 objects may result in SIGBUS signals being sent to the process. The reason for this is that the size 25546 of the object can be manipulated by other processes and can change at any moment. The 25547 implementation should tell the application that a memory reference is outside the object where 25548 this can be detected; otherwise, written data may be lost and read data may not reflect actual 25549 data in the object. 25550 Note that references beyond the end of the object do not extend the object as the new end cannot 25551 be determined precisely by most virtual memory hardware. Instead, the size can be directly 25552 manipulated by ftruncate( ). 25553 Process memory locking does apply to shared memory regions, and the MEMLOCK_FUTURE 25554 argument to memlockall( ) can be relied upon to cause new shared memory regions to be 25555 automatically locked. 25556 Existing implementations of mmap( ) return the value -1 when unsuccessful. Since the casting of 25557 this value to type void * cannot be guaranteed by the ISO C standard to be distinct from a 25558 successful value, this volume of IEEE Std 1003.1-200x defines the symbol MAP_FAILED, which a 25559 conforming implementation does not return as the result of a successful call. 1256 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mmap( ) 25560 FUTURE DIRECTIONS 25561 None. 25562 SEE ALSO 25563 exec, fcntl( ), fork( ), lockf( ), msync( ), munmap( ), mprotect( ), posix_typed_mem_open( ), shmat( ), 25564 sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25565 CHANGE HISTORY 25566 First released in Issue 4, Version 2. 25567 Issue 5 25568 Moved from X/OPEN UNIX extension to BASE. 25569 Aligned with mmap( ) in the POSIX Realtime Extension as follows: 25570 * The DESCRIPTION is extensively reworded. 25571 * The [EAGAIN] and [ENOTSUP] mandatory error conditions are added. 25572 * New cases of [ENOMEM] and [ENXIO] are added as mandatory error conditions. 25573 * The value returned on failure is the value of the constant MAP_FAILED; this was previously 25574 defined as -1. 25575 Large File Summit extensions are added. 25576 Issue 6 25577 The mmap( ) function is marked as part of the Memory Mapped Files option. 25578 The Open Group Corrigendum U028/6 is applied, changing (void *)-1 to MAP_FAILED. 25579 The following new requirements on POSIX implementations derive from alignment with the 25580 Single UNIX Specification: 25581 * The DESCRIPTION is updated to described the use of MAP_FIXED. 25582 * The DESCRIPTION is updated to describe the addition of an extra reference to the file 25583 associated with the file descriptor passed to mmap( ). 25584 * The DESCRIPTION is updated to state that there may be implementation-defined limits on 25585 the number of memory regions that can be mapped. 25586 * The DESCRIPTION is updated to describe constraints on the alignment and size of the off 25587 argument. 25588 * The [EINVAL] and [EMFILE] error conditions are added. 25589 * The [EOVERFLOW] error condition is added. This change is to support large files. 25590 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 25591 * The DESCRIPTION is updated to describe the cases when MAP_PRIVATE and MAP_FIXED 25592 need not be supported. 25593 The following changes are made for alignment with IEEE Std 1003.1j-2000: 25594 * Semantics for typed memory objects are added to the DESCRIPTION. 25595 * New [ENOMEM] and [ENXIO] errors are added to the ERRORS section. 25596 * The posix_typed_mem_open( ) function is added to the SEE ALSO section. 25597 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1257 modf( ) System Interfaces 25598 NAME 25599 modf, modff, modfl - decompose a floating-point number 25600 SYNOPSIS 25601 #include 25602 double modf(double x, double *iptr); 25603 float modff(float value, float *iptr); 25604 long double modfl(long double value, long double *iptr); 25605 DESCRIPTION 25606 CX The functionality described on this reference page is aligned with the ISO C standard. Any 25607 conflict between the requirements described here and the ISO C standard is unintentional. This 25608 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 25609 These functions shall break the argument x into integral and fractional parts, each of which has 25610 the same sign as the argument. It stores the integral part as a double (for the modf( ) function), a 25611 float (for the modff( ) function), or a long double (for the modfl( ) function), in the object pointed 25612 to by iptr. 25613 RETURN VALUE 25614 Upon successful completion, these functions shall return the signed fractional part of x. 25615 MX If x is NaN, a NaN shall be returned, and *iptr shall be set to a NaN. 25616 If x is ±Inf, ±0 shall be returned, and *iptr shall be set to ±Inf. 25617 ERRORS 25618 No errors are defined. 25619 EXAMPLES 25620 None. 25621 APPLICATION USAGE 25622 The modf( ) function computes the function result and *iptr such that: 25623 a = modf(x, &iptr) ; 25624 x == a+*iptr ; 25625 allowing for the usual floating-point inaccuracies. 25626 RATIONALE 25627 None. 25628 FUTURE DIRECTIONS 25629 None. 25630 SEE ALSO 25631 frexp( ), isnan( ), ldexp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25632 CHANGE HISTORY 25633 First released in Issue 1. Derived from Issue 1 of the SVID. 25634 Issue 5 25635 The DESCRIPTION is updated to indicate how an application should check for an error. This 25636 text was previously published in the APPLICATION USAGE section. 25637 Issue 6 25638 The modff( ) and modfl( ) functions are added for alignment with the ISO/IEC 9899: 1999 25639 standard. 1258 Technical Standard (2001) (Draft April 16, 2001) System Interfaces modf( ) 25640 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 25641 revised to align with the ISO/IEC 9899: 1999 standard. 25642 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 25643 marked. System Interfaces, Issue 6 1259 mprotect( ) System Interfaces 25644 NAME 25645 mprotect - set protection of memory mapping 25646 SYNOPSIS 25647 MPR #include 25648 int mprotect(void *addr, size_t len, int prot); 25649 25650 DESCRIPTION 25651 The mprotect( ) function shall change the access protections to be that specified by prot for those 25652 whole pages containing any part of the address space of the process starting at address addr and 25653 continuing for len bytes. The parameter prot determines whether read, write, execute, or some 25654 combination of accesses are permitted to the data being mapped. The prot argument should be 25655 either PROT_NONE or the bitwise-inclusive OR of one or more of PROT_READ, PROT_WRITE, 25656 and PROT_EXEC. 25657 If an implementation cannot support the combination of access types specified by prot, the call 25658 to mprotect( ) shall fail. 25659 An implementation may permit accesses other than those specified by prot; however, no 25660 implementation shall permit a write to succeed where PROT_WRITE has not been set or shall 25661 permit any access where PROT_NONE alone has been set. Implementations shall support at 25662 least the following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise- 25663 inclusive OR of PROT_READ and PROT_WRITE. If PROT_WRITE is specified, the application 25664 shall ensure that it has opened the mapped objects in the specified address range with write 25665 permission, unless MAP_PRIVATE was specified in the original mapping, regardless of whether 25666 the file descriptors used to map the objects have since been closed. 25667 The implementation shall require that addr be a multiple of the page size as returned by 25668 sysconf( ). 25669 The behavior of this function is unspecified if the mapping was not established by a call to 25670 mmap( ). 25671 When mprotect( ) fails for reasons other than [EINVAL], the protections on some of the pages in 25672 the range [addr,addr+len) may have been changed. 25673 RETURN VALUE 25674 Upon successful completion, mprotect( ) shall return 0; otherwise, it shall return -1 and set errno 25675 to indicate the error. 25676 ERRORS 25677 The mprotect( ) function shall fail if: 25678 [EACCES] The prot argument specifies a protection that violates the access permission 25679 the process has to the underlying memory object. 25680 [EAGAIN] The prot argument specifies PROT_WRITE over a MAP_PRIVATE mapping 25681 and there are insufficient memory resources to reserve for locking the private 25682 page. 25683 [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). 25684 [ENOMEM] Addresses in the range [addr,addr+len) are invalid for the address space of a 25685 process, or specify one or more pages which are not mapped. 25686 [ENOMEM] The prot argument specifies PROT_WRITE on a MAP_PRIVATE mapping, and 25687 it would require more space than the system is able to supply for locking the 25688 private pages, if required. 1260 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mprotect( ) 25689 [ENOTSUP] The implementation does not support the combination of accesses requested 25690 in the prot argument. 25691 EXAMPLES 25692 None. 25693 APPLICATION USAGE 25694 The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 25695 Realtime Extension. 25696 RATIONALE 25697 None. 25698 FUTURE DIRECTIONS 25699 None. 25700 SEE ALSO 25701 mmap( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 25702 CHANGE HISTORY 25703 First released in Issue 4, Version 2. 25704 Issue 5 25705 Moved from X/OPEN UNIX extension to BASE. 25706 Aligned with mprotect( ) in the POSIX Realtime Extension as follows: 25707 * The DESCRIPTION is largely reworded. 25708 * [ENOTSUP] and a second form of [ENOMEM] are added as mandatory error conditions. 25709 * [EAGAIN] is moved from the optional to the mandatory error conditions. 25710 Issue 6 25711 The mprotect( ) function is marked as part of the Memory Protection option. 25712 The following new requirements on POSIX implementations derive from alignment with the 25713 Single UNIX Specification: 25714 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 25715 the page size as returned by sysconf( ). 25716 * The [EINVAL] error condition is added. 25717 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1261 mq_close( ) System Interfaces 25718 NAME 25719 mq_close - close a message queue (REALTIME) 25720 SYNOPSIS 25721 MSG #include 25722 int mq_close(mqd_t mqdes); 25723 25724 DESCRIPTION 25725 The mq_close( ) function shall remove the association between the message queue descriptor, 25726 mqdes, and its message queue. The results of using this message queue descriptor after 25727 successful return from this mq_close( ), and until the return of this message queue descriptor 25728 from a subsequent mq_open( ), are undefined. 25729 If the process has successfully attached a notification request to the message queue via this 25730 mqdes, this attachment shall be removed, and the message queue is available for another process 25731 to attach for notification. 25732 RETURN VALUE 25733 Upon successful completion, the mq_close( ) function shall return a value of zero; otherwise, the 25734 function shall return a value of -1 and set errno to indicate the error. 25735 ERRORS 25736 The mq_close( ) function shall fail if: 25737 [EBADF] The mqdes argument is not a valid message queue descriptor. 25738 EXAMPLES 25739 None. 25740 APPLICATION USAGE 25741 None. 25742 RATIONALE 25743 None. 25744 FUTURE DIRECTIONS 25745 None. 25746 SEE ALSO 25747 mq_open( ), mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of 25748 IEEE Std 1003.1-200x, 25749 CHANGE HISTORY 25750 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25751 Issue 6 25752 The mq_close( ) function is marked as part of the Message Passing option. 25753 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25754 implementation does not support the Message Passing option. 1262 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_getattr( ) 25755 NAME 25756 mq_getattr - get message queue attributes (REALTIME) 25757 SYNOPSIS 25758 MSG #include 25759 int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat); 25760 25761 DESCRIPTION 25762 The mqdes argument specifies a message queue descriptor. 25763 The mq_getattr( ) function shall obtain status information and attributes of the message queue | 25764 and the open message queue description associated with the message queue descriptor. | 25765 The results shall be returned in the mq_attr structure referenced by the mqstat argument. | 25766 Upon return, the following members shall have the values associated with the open message | 25767 queue description as set when the message queue was opened and as modified by subsequent | 25768 mq_setattr( ) calls: mq_flags. 25769 The following attributes of the message queue shall be returned as set at message queue 25770 creation: mq_maxmsg, mq_msgsize. 25771 Upon return, the following members within the mq_attr structure referenced by the mqstat | 25772 argument shall be set to the current state of the message queue: | 25773 mq_curmsgs The number of messages currently on the queue. 25774 RETURN VALUE 25775 Upon successful completion, the mq_getattr( ) function shall return zero. Otherwise, the function 25776 shall return -1 and set errno to indicate the error. 25777 ERRORS 25778 The mq_getattr( ) function shall fail if: 25779 [EBADF] The mqdes argument is not a valid message queue descriptor. 25780 EXAMPLES 25781 None. 25782 APPLICATION USAGE 25783 None. 25784 RATIONALE 25785 None. 25786 FUTURE DIRECTIONS 25787 None. 25788 SEE ALSO 25789 mq_open( ), mq_send( ), mq_setattr( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the 25790 Base Definitions volume of IEEE Std 1003.1-200x, 25791 CHANGE HISTORY 25792 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25793 Issue 6 25794 The mq_getattr( ) function is marked as part of the Message Passing option. 25795 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25796 implementation does not support the Message Passing option. System Interfaces, Issue 6 1263 mq_getattr( ) System Interfaces 25797 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 25798 IEEE Std 1003.1d-1999. 1264 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_notify( ) 25799 NAME 25800 mq_notify - notify process that a message is available (REALTIME) 25801 SYNOPSIS 25802 MSG #include 25803 int mq_notify(mqd_t mqdes, const struct sigevent *notification); 25804 25805 DESCRIPTION 25806 If the argument notification is not NULL, this function shall register the calling process to be | 25807 notified of message arrival at an empty message queue associated with the specified message | 25808 queue descriptor, mqdes. The notification specified by the notification argument shall be sent to | 25809 the process when the message queue transitions from empty to non-empty. At any time, only 25810 one process may be registered for notification by a message queue. If the calling process or any 25811 other process has already registered for notification of message arrival at the specified message 25812 queue, subsequent attempts to register for that message queue shall fail. | 25813 If notification is NULL and the process is currently registered for notification by the specified | 25814 message queue, the existing registration shall be removed. | 25815 When the notification is sent to the registered process, its registration shall be removed. The 25816 message queue shall then be available for registration. 25817 If a process has registered for notification of message arrival at a message queue and some 25818 thread is blocked in mq_receive( ) waiting to receive a message when a message arrives at the 25819 queue, the arriving message shall satisfy the appropriate mq_receive( ). The resulting behavior is | 25820 as if the message queue remains empty, and no notification shall be sent. | 25821 RETURN VALUE 25822 Upon successful completion, the mq_notify( ) function shall return a value of zero; otherwise, the 25823 function shall return a value of -1 and set errno to indicate the error. 25824 ERRORS 25825 The mq_notify( ) function shall fail if: 25826 [EBADF] The mqdes argument is not a valid message queue descriptor. 25827 [EBUSY] A process is already registered for notification by the message queue. 25828 EXAMPLES 25829 None. 25830 APPLICATION USAGE 25831 None. 25832 RATIONALE 25833 None. 25834 FUTURE DIRECTIONS 25835 None. 25836 SEE ALSO 25837 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base 25838 Definitions volume of IEEE Std 1003.1-200x, 25839 CHANGE HISTORY 25840 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. System Interfaces, Issue 6 1265 mq_notify( ) System Interfaces 25841 Issue 6 25842 The mq_notify( ) function is marked as part of the Message Passing option. 25843 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25844 implementation does not support the Message Passing option. 25845 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 25846 IEEE Std 1003.1d-1999. 1266 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_open( ) 25847 NAME 25848 mq_open - open a message queue (REALTIME) 25849 SYNOPSIS 25850 MSG #include 25851 mqd_t mq_open(const char *name, int oflag, ...); 25852 25853 DESCRIPTION 25854 The mq_open( ) function shall establish the connection between a process and a message queue 25855 with a message queue descriptor. It shall create an open message queue description that refers to 25856 the message queue, and a message queue descriptor that refers to that open message queue 25857 description. The message queue descriptor is used by other functions to refer to that message 25858 queue. The name argument points to a string naming a message queue. It is unspecified whether 25859 the name appears in the file system and is visible to other functions that take pathnames as | 25860 arguments. The name argument shall conform to the construction rules for a pathname. If name | 25861 begins with the slash character, then processes calling mq_open( ) with the same value of name | 25862 shall refer to the same message queue object, as long as that name has not been removed. If name | 25863 does not begin with the slash character, the effect is implementation-defined. The interpretation 25864 of slash characters other than the leading slash character in name is implementation-defined. If 25865 the name argument is not the name of an existing message queue and creation is not requested, 25866 mq_open( ) shall fail and return an error. 25867 A message queue descriptor may be implemented using a file descriptor, in which case 25868 applications can open up to at least {OPEN_MAX} file and message queues. 25869 The oflag argument requests the desired receive and/or send access to the message queue. The 25870 requested access permission to receive messages or send messages shall be granted if the calling | 25871 process would be granted read or write access, respectively, to an equivalently protected file. | 25872 The value of oflag is the bitwise-inclusive OR of values from the following list. Applications | 25873 shall specify exactly one of the first three values (access modes) below in the value of oflag: | 25874 O_RDONLY Open the message queue for receiving messages. The process can use the 25875 returned message queue descriptor with mq_receive( ), but not mq_send( ). A 25876 message queue may be open multiple times in the same or different processes 25877 for receiving messages. 25878 O_WRONLY Open the queue for sending messages. The process can use the returned 25879 message queue descriptor with mq_send( ) but not mq_receive( ). A message 25880 queue may be open multiple times in the same or different processes for 25881 sending messages. 25882 O_RDWR Open the queue for both receiving and sending messages. The process can use 25883 any of the functions allowed for O_RDONLY and O_WRONLY. A message 25884 queue may be open multiple times in the same or different processes for 25885 sending messages. 25886 Any combination of the remaining flags may be specified in the value of oflag: 25887 O_CREAT Create a message queue. It requires two additional arguments: mode, which | 25888 shall be of type mode_t, and attr, which shall be a pointer to a mq_attr | 25889 structure. If the pathname name has already been used to create a message | 25890 queue that still exists, then this flag shall have no effect, except as noted under | 25891 O_EXCL. Otherwise, a message queue shall be created without any messages | 25892 in it. The user ID of the message queue shall be set to the effective user ID of | 25893 the process, and the group ID of the message queue shall be set to the effective | System Interfaces, Issue 6 1267 mq_open( ) System Interfaces 25894 group ID of the process. The file permission bits shall be set to the value of | 25895 mode. When bits in mode other than file permission bits are set, the effect is 25896 implementation-defined. If attr is NULL, the message queue shall be created | 25897 with implementation-defined default message queue attributes. If attr is non- | 25898 NULL and the calling process has the appropriate privilege on name, the 25899 message queue mq_maxmsg and mq_msgsize attributes shall be set to the values | 25900 of the corresponding members in the mq_attr structure referred to by attr. If | 25901 attr is non-NULL, but the calling process does not have the appropriate 25902 privilege on name, the mq_open( ) function shall fail and return an error 25903 without creating the message queue. 25904 O_EXCL If O_EXCL and O_CREAT are set, mq_open( ) shall fail if the message queue | 25905 name exists. The check for the existence of the message queue and the creation 25906 of the message queue if it does not exist shall be atomic with respect to other 25907 threads executing mq_open( ) naming the same name with O_EXCL and 25908 O_CREAT set. If O_EXCL is set and O_CREAT is not set, the result is 25909 undefined. 25910 O_NONBLOCK Determines whether a mq_send( ) or mq_receive( ) waits for resources or | 25911 messages that are not currently available, or fails with errno set to [EAGAIN]; 25912 see mq_send( ) and mq_receive( ) for details. 25913 The mq_open( ) function does not add or remove messages from the queue. 25914 RETURN VALUE 25915 Upon successful completion, the function shall return a message queue descriptor; otherwise, 25916 the function shall return (mqd_t)-1 and set errno to indicate the error. 25917 ERRORS 25918 The mq_open( ) function shall fail if: 25919 [EACCES] The message queue exists and the permissions specified by oflag are denied, or 25920 the message queue does not exist and permission to create the message queue 25921 is denied. 25922 [EEXIST] O_CREAT and O_EXCL are set and the named message queue already exists. 25923 [EINTR] The mq_open( ) function was interrupted by a signal. 25924 [EINVAL] The mq_open( ) function is not supported for the given name. 25925 [EINVAL] O_CREAT was specified in oflag, the value of attr is not NULL, and either 25926 mq_maxmsg or mq_msgsize was less than or equal to zero. 25927 [EMFILE] Too many message queue descriptors or file descriptors are currently in use by 25928 this process. 25929 [ENAMETOOLONG] 25930 The length of the name argument exceeds {PATH_MAX} or a pathname | 25931 component is longer than {NAME_MAX}. | 25932 [ENFILE] Too many message queues are currently open in the system. 25933 [ENOENT] O_CREAT is not set and the named message queue does not exist. 25934 [ENOSPC] There is insufficient space for the creation of the new message queue. 1268 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_open( ) 25935 EXAMPLES 25936 None. 25937 APPLICATION USAGE 25938 None. 25939 RATIONALE 25940 None. 25941 FUTURE DIRECTIONS 25942 None. 25943 SEE ALSO 25944 mq_close( ), mq_getattr( ), mq_receive( ), mq_send( ), mq_setattr( ), mq_timedreceive( ), mq_timedsend( ), 25945 mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of 25946 IEEE Std 1003.1-200x, 25947 CHANGE HISTORY 25948 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 25949 Issue 6 25950 The mq_open( ) function is marked as part of the Message Passing option. 25951 The [ENOSYS] error condition has been removed as stubs need not be provided if an 25952 implementation does not support the Message Passing option. 25953 The mq_timedreceive( ) and mq_timedsend( ) functions are added to the SEE ALSO section for 25954 alignment with IEEE Std 1003.1d-1999. 25955 The DESCRIPTION of O_EXCL is updated in response to IEEE PASC Interpretation 1003.1c #48. System Interfaces, Issue 6 1269 mq_receive( ) System Interfaces 25956 NAME 25957 mq_receive, mq_timedreceive - receive a message from a message queue (REALTIME) 25958 SYNOPSIS 25959 MSG #include 25960 ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, 25961 unsigned *msg_prio); 25962 25963 MSG TMO #include 25964 #include 25965 ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr, 25966 size_t msg_len, unsigned *restrict msg_prio, 25967 const struct timespec *restrict abs_timeout); 25968 25969 DESCRIPTION 25970 The mq_receive( ) function shall receive the oldest of the highest priority message(s) from the | 25971 message queue specified by mqdes. If the size of the buffer in bytes, specified by the msg_len 25972 argument, is less than the mq_msgsize attribute of the message queue, the function shall fail and 25973 return an error. Otherwise, the selected message shall be removed from the queue and copied to | 25974 the buffer pointed to by the msg_ptr argument. | 25975 If the value of msg_len is greater than {SSIZE_MAX}, the result is implementation-defined. 25976 If the argument msg_prio is not NULL, the priority of the selected message shall be stored in the | 25977 location referenced by msg_prio. 25978 If the specified message queue is empty and O_NONBLOCK is not set in the message queue 25979 description associated with mqdes, mq_receive( ) shall block until a message is enqueued on the | 25980 message queue or until mq_receive( ) is interrupted by a signal. If more than one thread is waiting | 25981 to receive a message when a message arrives at an empty queue and the Priority Scheduling 25982 option is supported, then the thread of highest priority that has been waiting the longest shall be 25983 selected to receive the message. Otherwise, it is unspecified which waiting thread receives the 25984 message. If the specified message queue is empty and O_NONBLOCK is set in the message 25985 queue description associated with mqdes, no message shall be removed from the queue, and | 25986 mq_receive( ) shall return an error. 25987 TMO The mq_timedreceive( ) function shall receive the oldest of the highest priority messages from the | 25988 message queue specified by mqdes as described for the mq_receive( ) function. However, if | 25989 O_NONBLOCK was not specified when the message queue was opened via the mq_open( ) 25990 function, and no message exists on the queue to satisfy the receive, the wait for such a message | 25991 shall be terminated when the specified timeout expires. If O_NONBLOCK is set, this function is | 25992 equivalent to mq_receive( ). | 25993 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the 25994 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 25995 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 25996 of the call. 25997 TMO TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; if | 25998 the Timers option is not supported, the timeout shall be based on the system clock as returned | 25999 by the time( ) function. | 26000 TMO The resolution of the timeout shall be the resolution of the clock on which it is based. The | 26001 timespec argument is defined in the header. | 1270 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_receive( ) 26002 Under no circumstance shall the operation fail with a timeout if a message can be removed from 26003 the message queue immediately. The validity of the abs_timeout parameter need not be checked 26004 if a message can be removed from the message queue immediately. 26005 RETURN VALUE 26006 TMO Upon successful completion, the mq_receive( ) and mq_timedreceive( ) functions shall return the 26007 length of the selected message in bytes and the message shall be removed from the queue. 26008 Otherwise, no message shall be removed from the queue, the functions shall return a value of -1, 26009 and set errno to indicate the error. 26010 ERRORS 26011 TMO The mq_receive( ) and mq_timedreceive( )functions shall fail if: 26012 [EAGAIN] O_NONBLOCK was set in the message description associated with mqdes, 26013 and the specified message queue is empty. 26014 [EBADF] The mqdes argument is not a valid message queue descriptor open for reading. 26015 [EMSGSIZE] The specified message buffer size, msg_len, is less than the message size 26016 attribute of the message queue. 26017 TMO [EINTR] The mq_receive( ) or mq_timedreceive( )operation was interrupted by a signal. 26018 TMO [EINVAL] The process or thread would have blocked, and the abs_timeout parameter 26019 specified a nanoseconds field value less than zero or greater than or equal to 26020 1 000 million. 26021 TMO [ETIMEDOUT] The O_NONBLOCK flag was not set when the message queue was opened, 26022 but no message arrived on the queue before the specified timeout expired. 26023 TMO The mq_receive( ) and mq_timedreceive( )functions may fail if: 26024 [EBADMSG] The implementation has detected a data corruption problem with the 26025 message. 26026 EXAMPLES 26027 None. 26028 APPLICATION USAGE 26029 None. 26030 RATIONALE 26031 None. 26032 FUTURE DIRECTIONS 26033 None. 26034 SEE ALSO 26035 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), time( ), the Base 26036 Definitions volume of IEEE Std 1003.1-200x, , 26037 CHANGE HISTORY 26038 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26039 Issue 6 26040 The mq_receive( ) function is marked as part of the Message Passing option. 26041 The Open Group Corrigendum U021/4 is applied. The DESCRIPTION is changed to refer to 26042 msg_len rather than maxsize. 26043 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26044 implementation does not support the Message Passing option. System Interfaces, Issue 6 1271 mq_receive( ) System Interfaces 26045 The following new requirements on POSIX implementations derive from alignment with the 26046 Single UNIX Specification: 26047 * In this function it is possible for the return value to exceed the range of the type ssize_t (since 26048 size_t has a larger range of positive values than ssize_t). A sentence restricting the size of 26049 the size_t object is added to the description to resolve this conflict. 26050 The mq_timedreceive( ) function is added for alignment with IEEE Std 1003.1d-1999. 26051 The restrict keyword is added to the mq_timedreceive( ) prototype for alignment with the 26052 ISO/IEC 9899: 1999 standard. 26053 IEEE PASC Interpretation 1003.1 #109 is applied, correcting the return type for mq_timedreceive( ) 26054 from int to ssize_t. 1272 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_send( ) 26055 NAME 26056 mq_send, mq_timedsend - send a message to a message queue (REALTIME) 26057 SYNOPSIS 26058 MSG #include 26059 int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26060 unsigned msg_prio); 26061 26062 MSG TMO #include 26063 #include 26064 int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26065 unsigned msg_prio, const struct timespec *abs_timeout); 26066 26067 DESCRIPTION 26068 The mq_send( ) function shall add the message pointed to by the argument msg_ptr to the 26069 message queue specified by mqdes. The msg_len argument specifies the length of the message, in | 26070 bytes, pointed to by msg_ptr. The value of msg_len shall be less than or equal to the mq_msgsize | 26071 attribute of the message queue, or mq_send( ) shall fail. 26072 If the specified message queue is not full, mq_send( ) shall behave as if the message is inserted | 26073 into the message queue at the position indicated by the msg_prio argument. A message with a | 26074 larger numeric value of msg_prio shall be inserted before messages with lower values of 26075 msg_prio. A message shall be inserted after other messages in the queue, if any, with equal 26076 msg_prio. The value of msg_prio shall be less than {MQ_PRIO_MAX}. 26077 If the specified message queue is full and O_NONBLOCK is not set in the message queue 26078 description associated with mqdes, mq_send( ) shall block until space becomes available to 26079 enqueue the message, or until mq_send( ) is interrupted by a signal. If more than one thread is 26080 waiting to send when space becomes available in the message queue and the Priority Scheduling 26081 option is supported, then the thread of the highest priority that has been waiting the longest 26082 shall be unblocked to send its message. Otherwise, it is unspecified which waiting thread is 26083 unblocked. If the specified message queue is full and O_NONBLOCK is set in the message 26084 queue description associated with mqdes, the message shall not be queued and mq_send( ) shall 26085 return an error. 26086 TMO The mq_timedsend( ) function shall add a message to the message queue specified by mqdes in the | 26087 manner defined for the mq_send( ) function. However, if the specified message queue is full and 26088 O_NONBLOCK is not set in the message queue description associated with mqdes, the wait for 26089 sufficient room in the queue shall be terminated when the specified timeout expires. If 26090 O_NONBLOCK is set in the message queue description, this function shall be equivalent to | 26091 mq_send( ). 26092 The timeout shall expire when the absolute time specified by abs_timeout passes, as measured by | 26093 the clock on which timeouts are based (that is, when the value of that clock equals or exceeds 26094 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 26095 of the call. 26096 TMO TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; if | 26097 the Timers option is not supported, the timeout shall be based on the system clock as returned | 26098 by the time( ) function. | 26099 TMO The resolution of the timeout shall be the resolution of the clock on which it is based. The | 26100 timespec argument is defined in the header. | System Interfaces, Issue 6 1273 mq_send( ) System Interfaces 26101 Under no circumstance shall the operation fail with a timeout if there is sufficient room in the 26102 queue to add the message immediately. The validity of the abs_timeout parameter need not be 26103 checked when there is sufficient room in the queue. 26104 RETURN VALUE 26105 TMO Upon successful completion, the mq_send( ) and mq_timedsend( ) functions shall return a value of 26106 zero. Otherwise, no message shall be enqueued, the functions shall return -1, and errno shall be 26107 set to indicate the error. 26108 ERRORS 26109 TMO The mq_send( ) and mq_timedsend( )functions shall fail if: 26110 [EAGAIN] The O_NONBLOCK flag is set in the message queue description associated 26111 with mqdes, and the specified message queue is full. 26112 [EBADF] The mqdes argument is not a valid message queue descriptor open for writing. 26113 TMO [EINTR] A signal interrupted the call to mq_send( ) or mq_timedsend( ). 26114 [EINVAL] The value of msg_prio was outside the valid range. 26115 TMO [EINVAL] The process or thread would have blocked, and the abs_timeout parameter 26116 specified a nanoseconds field value less than zero or greater than or equal to 26117 1 000 million. 26118 [EMSGSIZE] The specified message length, msg_len, exceeds the message size attribute of 26119 the message queue. 26120 TMO [ETIMEDOUT] The O_NONBLOCK flag was not set when the message queue was opened, 26121 but the timeout expired before the message could be added to the queue. 26122 EXAMPLES 26123 None. 26124 APPLICATION USAGE 26125 The value of the symbol {MQ_PRIO_MAX} limits the number of priority levels supported by the 26126 application. Message priorities range from 0 to {MQ_PRIO_MAX}-1. 26127 RATIONALE 26128 None. 26129 FUTURE DIRECTIONS 26130 None. 26131 SEE ALSO 26132 mq_open( ), mq_receive( ), mq_setattr( ), mq_timedreceive( ), time( ), the Base Definitions volume of 26133 IEEE Std 1003.1-200x, , 26134 CHANGE HISTORY 26135 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26136 Issue 6 26137 The mq_send( ) function is marked as part of the Message Passing option. 26138 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26139 implementation does not support the Message Passing option. 26140 The mq_timedsend( ) function is added for alignment with IEEE Std 1003.1d-1999. 1274 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_setattr( ) 26141 NAME 26142 mq_setattr - set message queue attributes (REALTIME) 26143 SYNOPSIS 26144 MSG #include 26145 int mq_setattr(mqd_t mqdes, const struct mq_attr *restrict mqstat, 26146 struct mq_attr *restrict omqstat); 26147 26148 DESCRIPTION 26149 The mq_setattr( ) function shall set attributes associated with the open message queue | 26150 description referenced by the message queue descriptor specified by mqdes. | 26151 The message queue attributes corresponding to the following members defined in the mq_attr | 26152 structure shall be set to the specified values upon successful completion of mq_setattr( ): | 26153 mq_flags The value of this member is the bitwise-logical OR of zero or more of 26154 O_NONBLOCK and any implementation-defined flags. 26155 The values of the mq_maxmsg, mq_msgsize, and mq_curmsgs members of the mq_attr structure | 26156 shall be ignored by mq_setattr( ). | 26157 If omqstat is non-NULL, the mq_setattr( ) function shall store, in the location referenced by | 26158 omqstat, the previous message queue attributes and the current queue status. These values shall | 26159 be the same as would be returned by a call to mq_getattr( ) at that point. | 26160 RETURN VALUE 26161 Upon successful completion, the function shall return a value of zero and the attributes of the 26162 message queue shall have been changed as specified. 26163 Otherwise, the message queue attributes shall be unchanged, and the function shall return a 26164 value of -1 and set errno to indicate the error. 26165 ERRORS 26166 The mq_setattr( ) function shall fail if: 26167 [EBADF] The mqdes argument is not a valid message queue descriptor. 26168 EXAMPLES 26169 None. 26170 APPLICATION USAGE 26171 None. 26172 RATIONALE 26173 None. 26174 FUTURE DIRECTIONS 26175 None. 26176 SEE ALSO 26177 mq_open( ), mq_send( ), mq_timedsend( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base 26178 Definitions volume of IEEE Std 1003.1-200x, 26179 CHANGE HISTORY 26180 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. System Interfaces, Issue 6 1275 mq_setattr( ) System Interfaces 26181 Issue 6 26182 The mq_setattr( ) function is marked as part of the Message Passing option. 26183 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26184 implementation does not support the Message Passing option. 26185 The mq_timedsend( ) function is added to the SEE ALSO section for alignment with 26186 IEEE Std 1003.1d-1999. 26187 The restrict keyword is added to the mq_setattr( ) prototype for alignment with the 26188 ISO/IEC 9899: 1999 standard. 1276 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_timedreceive( ) 26189 NAME 26190 mq_timedreceive - receive a message from a message queue (ADVANCED REALTIME) 26191 SYNOPSIS 26192 MSG TMO #include 26193 #include 26194 ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr, 26195 size_t msg_len, unsigned *restrict msg_prio, 26196 const struct timespec *restrict abs_timeout); 26197 26198 DESCRIPTION 26199 Refer to mq_receive( ). System Interfaces, Issue 6 1277 mq_timedsend( ) System Interfaces 26200 NAME 26201 mq_timedsend - send a message to a message queue (ADVANCED REALTIME) 26202 SYNOPSIS 26203 MSG TMO #include 26204 #include 26205 int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 26206 unsigned msg_prio, const struct timespec *abs_timeout); 26207 26208 DESCRIPTION 26209 Refer to mq_send( ). 1278 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mq_unlink( ) 26210 NAME 26211 mq_unlink - remove a message queue (REALTIME) 26212 SYNOPSIS 26213 MSG #include 26214 int mq_unlink(const char *name); 26215 26216 DESCRIPTION 26217 The mq_unlink( ) function shall remove the message queue named by the pathname name. After | 26218 a successful call to mq_unlink( ) with name, a call to mq_open( ) with name shall fail if the flag | 26219 O_CREAT is not set in flags. If one or more processes have the message queue open when | 26220 mq_unlink( ) is called, destruction of the message queue shall be postponed until all references to | 26221 the message queue have been closed. 26222 Calls to mq_open( ) to recreate the message queue may fail until the message queue is actually 26223 removed. However, the mq_unlink( ) call need not block until all references have been closed; it 26224 may return immediately. 26225 RETURN VALUE 26226 Upon successful completion, the function shall return a value of zero. Otherwise, the named 26227 message queue shall be unchanged by this function call, and the function shall return a value of 26228 -1 and set errno to indicate the error. 26229 ERRORS 26230 The mq_unlink( ) function shall fail if: 26231 [EACCES] Permission is denied to unlink the named message queue. 26232 [ENAMETOOLONG] 26233 The length of the name argument exceeds {PATH_MAX} or a pathname | 26234 component is longer than {NAME_MAX}. | 26235 [ENOENT] The named message queue does not exist. 26236 EXAMPLES 26237 None. 26238 APPLICATION USAGE 26239 None. 26240 RATIONALE 26241 None. 26242 FUTURE DIRECTIONS 26243 None. 26244 SEE ALSO 26245 mq_close( ), mq_open( ), msgctl( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of 26246 IEEE Std 1003.1-200x, 26247 CHANGE HISTORY 26248 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26249 Issue 6 26250 The mq_unlink( ) function is marked as part of the Message Passing option. 26251 The Open Group Corrigendum U021/5 is applied, clarifying that upon unsuccessful completion, 26252 the named message queue is unchanged by this function. System Interfaces, Issue 6 1279 mq_unlink( ) System Interfaces 26253 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26254 implementation does not support the Message Passing option. 1280 Technical Standard (2001) (Draft April 16, 2001) System Interfaces mrand48( ) 26255 NAME 26256 mrand48 - generate uniformly distributed pseudo-random signed long integers 26257 SYNOPSIS 26258 XSI #include 26259 long mrand48(void); 26260 26261 DESCRIPTION 26262 Refer to drand48( ). System Interfaces, Issue 6 1281 msgctl( ) System Interfaces 26263 NAME 26264 msgctl - XSI message control operations 26265 SYNOPSIS 26266 XSI #include 26267 int msgctl(int msqid, int cmd, struct msqid_ds *buf); 26268 26269 DESCRIPTION 26270 The msgctl( ) function operates on XSI message queues (see the Base Definitions volume of 26271 IEEE Std 1003.1-200x, Section 3.224, Message Queue). It is unspecified whether this function 26272 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26273 page 491). 26274 The msgctl( ) function shall provide message control operations as specified by cmd. The 26275 following values for cmd, and the message control operations they specify, are: 26276 IPC_STAT Place the current value of each member of the msqid_ds data structure 26277 associated with msqid into the structure pointed to by buf. The contents of this 26278 structure are defined in . 26279 IPC_SET Set the value of the following members of the msqid_ds data structure 26280 associated with msqid to the corresponding value found in the structure 26281 pointed to by buf: 26282 msg_perm.uid 26283 msg_perm.gid 26284 msg_perm.mode 26285 msg_qbytes 26286 IPC_SET can only be executed by a process with appropriate privileges or that 26287 has an effective user ID equal to the value of msg_perm.cuid or 26288 msg_perm.uid in the msqid_ds data structure associated with msqid. Only a 26289 process with appropriate privileges can raise the value of msg_qbytes. | 26290 IPC_RMID Remove the message queue identifier specified by msqid from the system and 26291 destroy the message queue and msqid_ds data structure associated with it. 26292 IPC_RMD can only be executed by a process with appropriate privileges or 26293 one that has an effective user ID equal to the value of msg_perm.cuid or 26294 msg_perm.uid in the msqid_ds data structure associated with msqid. 26295 RETURN VALUE 26296 Upon successful completion, msgctl( ) shall return 0; otherwise, it shall return -1 and set errno to 26297 indicate the error. 26298 ERRORS 26299 The msgctl( ) function shall fail if: 26300 [EACCES] The argument cmd is IPC_STAT and the calling process does not have read 26301 permission; see Section 2.7 (on page 489). 26302 [EINVAL] The value of msqid is not a valid message queue identifier; or the value of cmd 26303 is not a valid command. 26304 [EPERM] The argument cmd is IPC_RMID or IPC_SET and the effective user ID of the 26305 calling process is not equal to that of a process with appropriate privileges 26306 and it is not equal to the value of msg_perm.cuid or msg_perm.uid in the data 26307 structure associated with msqid. 1282 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msgctl( ) 26308 [EPERM] The argument cmd is IPC_SET, an attempt is being made to increase to the 26309 value of msg_qbytes, and the effective user ID of the calling process does not | 26310 have appropriate privileges. 26311 EXAMPLES 26312 None. 26313 APPLICATION USAGE 26314 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26315 (IPC). Application developers who need to use IPC should design their applications so that 26316 modules using the IPC routines described in Section 2.7 (on page 489) can be easily modified to 26317 use the alternative interfaces. 26318 RATIONALE 26319 None. 26320 FUTURE DIRECTIONS 26321 None. 26322 SEE ALSO 26323 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26324 mq_unlink( ), msgget( ), msgrcv( ), msgsnd( ), the Base Definitions volume of IEEE Std 1003.1-200x, 26325 , Section 2.7 (on page 489) 26326 CHANGE HISTORY 26327 First released in Issue 2. Derived from Issue 2 of the SVID. 26328 Issue 5 26329 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26330 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1283 msgget( ) System Interfaces 26331 NAME 26332 msgget - get the XSI message queue identifier 26333 SYNOPSIS 26334 XSI #include 26335 int msgget(key_t key, int msgflg); 26336 26337 DESCRIPTION 26338 The msgget( ) function operates on XSI message queues (see the Base Definitions volume of 26339 IEEE Std 1003.1-200x, Section 3.224, Message Queue). It is unspecified whether this function 26340 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26341 page 491). 26342 The msgget( ) function shall return the message queue identifier associated with the argument 26343 key. 26344 A message queue identifier, associated message queue, and data structure (see ), | 26345 shall be created for the argument key if one of the following is true: | 26346 * The argument key is equal to IPC_PRIVATE. 26347 * The argument key does not already have a message queue identifier associated with it, and 26348 (msgflg & IPC_CREAT) is non-zero. 26349 Upon creation, the data structure associated with the new message queue identifier shall be | 26350 initialized as follows: | 26351 * msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid shall be set equal to the | 26352 effective user ID and effective group ID, respectively, of the calling process. | 26353 * The low-order 9 bits of msg_perm.mode shall be set equal to the low-order 9 bits of msgflg. | 26354 * msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime shall be set equal to 0. | 26355 * msg_ctime shall be set equal to the current time. | 26356 * msg_qbytes shall be set equal to the system limit. | 26357 RETURN VALUE 26358 Upon successful completion, msgget( ) shall return a non-negative integer, namely a message 26359 queue identifier. Otherwise, it shall return -1 and set errno to indicate the error. 26360 ERRORS 26361 The msgget( ) function shall fail if: 26362 [EACCES] A message queue identifier exists for the argument key, but operation 26363 permission as specified by the low-order 9 bits of msgflg would not be granted; 26364 see Section 2.7 (on page 489). 26365 [EEXIST] A message queue identifier exists for the argument key but ((msgflg & 26366 IPC_CREAT) && (msgflg & IPC_EXCL)) is non-zero. 26367 [ENOENT] A message queue identifier does not exist for the argument key and (msgflg & 26368 IPC_CREAT) is 0. 26369 [ENOSPC] A message queue identifier is to be created but the system-imposed limit on 26370 the maximum number of allowed message queue identifiers system-wide 26371 would be exceeded. 1284 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msgget( ) 26372 EXAMPLES 26373 None. 26374 APPLICATION USAGE 26375 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26376 (IPC). Application developers who need to use IPC should design their applications so that 26377 modules using the IPC routines described in Section 2.7 (on page 489) can be easily modified to 26378 use the alternative interfaces. 26379 RATIONALE 26380 None. 26381 FUTURE DIRECTIONS 26382 None. 26383 SEE ALSO 26384 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26385 mq_unlink( ), msgctl( ), msgrcv( ), msgsnd( ), the Base Definitions volume of IEEE Std 1003.1-200x, 26386 , Section 2.7 (on page 489) 26387 CHANGE HISTORY 26388 First released in Issue 2. Derived from Issue 2 of the SVID. 26389 Issue 5 26390 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26391 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1285 msgrcv( ) System Interfaces 26392 NAME 26393 msgrcv - XSI message receive operation 26394 SYNOPSIS 26395 XSI #include 26396 ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, 26397 int msgflg); 26398 26399 DESCRIPTION 26400 The msgrcv( ) function operates on XSI message queues (see the Base Definitions volume of 26401 IEEE Std 1003.1-200x, Section 3.224, Message Queue). It is unspecified whether this function 26402 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26403 page 491). 26404 The msgrcv( ) function shall read a message from the queue associated with the message queue 26405 identifier specified by msqid and place it in the user-defined buffer pointed to by msgp. 26406 The application shall ensure that the argument msgp points to a user-defined buffer that contains 26407 first a field of type long specifying the type of the message, and then a data portion that holds 26408 the data bytes of the message. The structure below is an example of what this user-defined 26409 buffer might look like: 26410 struct mymsg { 26411 long mtype; /* Message type. */ 26412 char mtext[1]; /* Message text. */ 26413 } 26414 The structure member mtype is the received message's type as specified by the sending process. 26415 The structure member mtext is the text of the message. 26416 The argument msgsz specifies the size in bytes of mtext. The received message shall be truncated | 26417 to msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The | 26418 truncated part of the message shall be lost and no indication of the truncation shall be given to | 26419 the calling process. | 26420 If the value of msgsz is greater than {SSIZE_MAX}, the result is implementation-defined. 26421 The argument msgtyp specifies the type of message requested as follows: 26422 * If msgtyp is 0, the first message on the queue shall be received. | 26423 * If msgtyp is greater than 0, the first message of type msgtyp shall be received. | 26424 * If msgtyp is less than 0, the first message of the lowest type that is less than or equal to the 26425 absolute value of msgtyp shall be received. | 26426 The argument msgflg specifies the action to be taken if a message of the desired type is not on the 26427 queue. These are as follows: 26428 * If (msgflg & IPC_NOWAIT) is non-zero, the calling thread shall return immediately with a 26429 return value of -1 and errno set to [ENOMSG]. 26430 * If (msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 26431 following occurs: 26432 - A message of the desired type is placed on the queue. 26433 - The message queue identifier msqid is removed from the system; when this occurs, errno 26434 shall be set equal to [EIDRM] and -1 shall be returned. 1286 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msgrcv( ) 26435 - The calling thread receives a signal that is to be caught; in this case a message is not 26436 received and the calling thread resumes execution in the manner prescribed in sigaction( ). 26437 Upon successful completion, the following actions are taken with respect to the data structure 26438 associated with msqid: 26439 * msg_qnum shall be decremented by 1. | 26440 * msg_lrpid shall be set equal to the process ID of the calling process. | 26441 * msg_rtime shall be set equal to the current time. | 26442 RETURN VALUE 26443 Upon successful completion, msgrcv( ) shall return a value equal to the number of bytes actually 26444 placed into the buffer mtext. Otherwise, no message shall be received, msgrcv( ) shall return 26445 (ssize_t)-1, and errno shall be set to indicate the error. 26446 ERRORS 26447 The msgrcv( ) function shall fail if: 26448 [E2BIG] The value of mtext is greater than msgsz and (msgflg & MSG_NOERROR) is 0. 26449 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page 26450 489). 26451 [EIDRM] The message queue identifier msqid is removed from the system. 26452 [EINTR] The msgrcv( ) function was interrupted by a signal. 26453 [EINVAL] msqid is not a valid message queue identifier. 26454 [ENOMSG] The queue does not contain a message of the desired type and (msgflg & 26455 IPC_NOWAIT) is non-zero. 26456 EXAMPLES 26457 Receiving a Message 26458 The following example receives the first message on the queue (based on the value of the msgtyp 26459 argument, 0). The queue is identified by the msqid argument (assuming that the value has 26460 previously been set). This call specifies that an error should be reported if no message is 26461 available, but not if the message is too large. The message size is calculated directly using the 26462 sizeof operator. 26463 #include 26464 ... 26465 int result; 26466 int msqid; 26467 struct message { 26468 long type; 26469 char text[20]; 26470 } msg; 26471 long msgtyp = 0; 26472 ... 26473 result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), 26474 msgtyp, MSG_NOERROR | IPC_NOWAIT); System Interfaces, Issue 6 1287 msgrcv( ) System Interfaces 26475 APPLICATION USAGE 26476 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26477 (IPC). Application developers who need to use IPC should design their applications so that 26478 modules using the IPC routines described in Section 2.7 (on page 489) can be easily modified to 26479 use the alternative interfaces. 26480 RATIONALE 26481 None. 26482 FUTURE DIRECTIONS 26483 None. 26484 SEE ALSO 26485 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26486 mq_unlink( ), msgctl( ), msgget( ), msgsnd( ), sigaction( ), the Base Definitions volume of 26487 IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 26488 CHANGE HISTORY 26489 First released in Issue 2. Derived from Issue 2 of the SVID. 26490 Issue 5 26491 The type of the return value is changed from int to ssize_t, and a warning is added to the 26492 DESCRIPTION about values of msgsz larger the {SSIZE_MAX}. 26493 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26494 DIRECTIONS to the APPLICATION USAGE section. 26495 Issue 6 26496 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1288 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msgsnd( ) 26497 NAME 26498 msgsnd - XSI message send operation 26499 SYNOPSIS 26500 XSI #include 26501 int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg); 26502 26503 DESCRIPTION 26504 The msgsnd( ) function operates on XSI message queues (see the Base Definitions volume of 26505 IEEE Std 1003.1-200x, Section 3.224, Message Queue). It is unspecified whether this function 26506 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 26507 page 491). 26508 The msgsnd( ) function shall send a message to the queue associated with the message queue | 26509 identifier specified by msqid. 26510 The application shall ensure that the argument msgp points to a user-defined buffer that contains 26511 first a field of type long specifying the type of the message, and then a data portion that holds 26512 the data bytes of the message. The structure below is an example of what this user-defined 26513 buffer might look like: 26514 struct mymsg { 26515 long mtype; /* Message type. */ 26516 char mtext[1]; /* Message text. */ 26517 } 26518 The structure member mtype is a non-zero positive type long that can be used by the receiving 26519 process for message selection. 26520 The structure member mtext is any text of length msgsz bytes. The argument msgsz can range 26521 from 0 to a system-imposed maximum. 26522 The argument msgflg specifies the action to be taken if one or more of the following are true: 26523 * The number of bytes already on the queue is equal to msg_qbytes; see . | 26524 * The total number of messages on all queues system-wide is equal to the system-imposed 26525 limit. 26526 These actions are as follows: 26527 * If (msgflg & IPC_NOWAIT) is non-zero, the message shall not be sent and the calling thread 26528 shall return immediately. 26529 * If (msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 26530 following occurs: 26531 - The condition responsible for the suspension no longer exists, in which case the message 26532 is sent. 26533 - The message queue identifier msqid is removed from the system; when this occurs, errno 26534 shall be set equal to [EIDRM] and -1 shall be returned. 26535 - The calling thread receives a signal that is to be caught; in this case the message is not 26536 sent and the calling thread resumes execution in the manner prescribed in sigaction( ). 26537 Upon successful completion, the following actions are taken with respect to the data structure 26538 associated with msqid; see : System Interfaces, Issue 6 1289 msgsnd( ) System Interfaces 26539 * msg_qnum shall be incremented by 1. | 26540 * msg_lspid shall be set equal to the process ID of the calling process. | 26541 * msg_stime shall be set equal to the current time. | 26542 RETURN VALUE 26543 Upon successful completion, msgsnd( ) shall return 0; otherwise, no message shall be sent, 26544 msgsnd( ) shall return -1, and errno shall be set to indicate the error. 26545 ERRORS 26546 The msgsnd( ) function shall fail if: 26547 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page 26548 489). 26549 [EAGAIN] The message cannot be sent for one of the reasons cited above and (msgflg & 26550 IPC_NOWAIT) is non-zero. 26551 [EIDRM] The message queue identifier msgid is removed from the system. 26552 [EINTR] The msgsnd( ) function was interrupted by a signal. 26553 [EINVAL] The value of msqid is not a valid message queue identifier, or the value of 26554 mtype is less than 1; or the value of msgsz is less than 0 or greater than the 26555 system-imposed limit. 26556 EXAMPLES 26557 Sending a Message 26558 The following example sends a message to the queue identified by the msqid argument 26559 (assuming that value has previously been set). This call specifies that an error should be 26560 reported if no message is available. The message size is calculated directly using the sizeof 26561 operator. 26562 #include 26563 ... 26564 int result; 26565 int msqid; 26566 struct message { 26567 long type; 26568 char text[20]; 26569 } msg; 26570 msg.type = 1; 26571 strcpy(msg.text, "This is message 1"); 26572 ... 26573 result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT); 26574 APPLICATION USAGE 26575 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 26576 (IPC). Application developers who need to use IPC should design their applications so that 26577 modules using the IPC routines described in Section 2.7 (on page 489) can be easily modified to 26578 use the alternative interfaces. 1290 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msgsnd( ) 26579 RATIONALE 26580 None. 26581 FUTURE DIRECTIONS 26582 None. 26583 SEE ALSO 26584 mq_close( ), mq_getattr( ), mq_notify( ), mq_open( ), mq_receive( ), mq_send( ), mq_setattr( ), 26585 mq_unlink( ), msgctl( ), msgget( ), msgrcv( ), sigaction( ), the Base Definitions volume of 26586 IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 26587 CHANGE HISTORY 26588 First released in Issue 2. Derived from Issue 2 of the SVID. 26589 Issue 5 26590 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 26591 DIRECTIONS to a new APPLICATION USAGE section. 26592 Issue 6 26593 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1291 msync( ) System Interfaces 26594 NAME 26595 msync - synchronize memory with physical storage 26596 SYNOPSIS 26597 MF SIO #include 26598 int msync(void *addr, size_t len, int flags); 26599 26600 DESCRIPTION 26601 The msync( ) function shall write all modified data to permanent storage locations, if any, in 26602 those whole pages containing any part of the address space of the process starting at address 26603 addr and continuing for len bytes. If no such storage exists, msync( ) need not have any effect. If 26604 requested, the msync( ) function shall then invalidate cached copies of data. | 26605 The implementation shall require that addr be a multiple of the page size as returned by 26606 sysconf( ). 26607 For mappings to files, the msync( ) function shall ensure that all write operations are completed | 26608 as defined for synchronized I/O data integrity completion. It is unspecified whether the | 26609 implementation also writes out other file attributes. When the msync( ) function is called on | 26610 MAP_PRIVATE mappings, any modified data shall not be written to the underlying object and 26611 shall not cause such data to be made visible to other processes. It is unspecified whether data in 26612 SHM|TYM MAP_PRIVATE mappings has any permanent storage locations. The effect of msync( ) on a 26613 shared memory object or a typed memory object is unspecified. The behavior of this function is 26614 unspecified if the mapping was not established by a call to mmap( ). 26615 The flags argument is constructed from the bitwise-inclusive OR of one or more of the following 26616 flags defined in the header: 26617 _________________________________________________ 26618 _ Symbolic Constant Description ________________________________________________ 26619 MS_ASYNC Perform asynchronous writes. 26620 MS_SYNC Perform synchronous writes. 26621 _ MS_INVALIDATE Invalidate cached data. ________________________________________________ 26622 When MS_ASYNC is specified, msync( ) shall return immediately once all the write operations 26623 are initiated or queued for servicing; when MS_SYNC is specified, msync( ) shall not return until 26624 all write operations are completed as defined for synchronized I/O data integrity completion. 26625 Either MS_ASYNC or MS_SYNC is specified, but not both. 26626 When MS_INVALIDATE is specified, msync( ) shall invalidate all cached copies of mapped data | 26627 that are inconsistent with the permanent storage locations such that subsequent references shall | 26628 obtain data that was consistent with the permanent storage locations sometime between the call | 26629 to msync( ) and the first subsequent memory reference to the data. | 26630 If msync( ) causes any write to a file, the file's st_ctime and st_mtime fields shall be marked for 26631 update. 26632 RETURN VALUE 26633 Upon successful completion, msync( ) shall return 0; otherwise, it shall return -1 and set errno to 26634 indicate the error. 26635 ERRORS 26636 The msync( ) function shall fail if: 26637 [EBUSY] Some or all of the addresses in the range starting at addr and continuing for len 26638 bytes are locked, and MS_INVALIDATE is specified. 1292 Technical Standard (2001) (Draft April 16, 2001) System Interfaces msync( ) 26639 [EINVAL] The value of flags is invalid. 26640 [EINVAL] The value of addr is not a multiple of the page size, {PAGESIZE}. 26641 [ENOMEM] The addresses in the range starting at addr and continuing for len bytes are 26642 outside the range allowed for the address space of a process or specify one or 26643 more pages that are not mapped. 26644 EXAMPLES 26645 None. 26646 APPLICATION USAGE 26647 The msync( ) function is only supported if the Memory Mapped Files option and the 26648 Synchronized Input and Output option are supported, and thus need not be available on all 26649 implementations. 26650 The msync( ) function should be used by programs that require a memory object to be in a 26651 known state; for example, in building transaction facilities. 26652 Normal system activity can cause pages to be written to disk. Therefore, there are no guarantees 26653 that msync( ) is the only control over when pages are or are not written to disk. 26654 RATIONALE 26655 The msync( ) function writes out data in a mapped region to the permanent storage for the | 26656 underlying object. The call to msync( ) ensures data integrity of the file. 26657 After the data is written out, any cached data may be invalidated if the MS_INVALIDATE flag 26658 was specified. This is useful on systems that do not support read/write consistency. 26659 FUTURE DIRECTIONS 26660 None. 26661 SEE ALSO 26662 mmap( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 26663 CHANGE HISTORY 26664 First released in Issue 4, Version 2. 26665 Issue 5 26666 Moved from X/OPEN UNIX extension to BASE. 26667 Aligned with msync( ) in the POSIX Realtime Extension as follows: 26668 * The DESCRIPTION is extensively reworded. 26669 * [EBUSY] and a new form of [EINVAL] are added as mandatory error conditions. 26670 Issue 6 26671 The msync( ) function is marked as part of the Memory Mapped Files and Synchronized Input 26672 and Output options. 26673 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 26674 * The [EBUSY] mandatory error condition is added. 26675 The following new requirements on POSIX implementations derive from alignment with the 26676 Single UNIX Specification: 26677 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 26678 the page size. 26679 * The second [EINVAL] error condition is made mandatory. System Interfaces, Issue 6 1293 msync( ) System Interfaces 26680 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding reference to 26681 typed memory objects. 1294 Technical Standard (2001) (Draft April 16, 2001) System Interfaces munlock( ) 26682 NAME 26683 munlock - unlock a range of process address space 26684 SYNOPSIS 26685 MLR #include 26686 int munlock(const void *addr, size_t len); 26687 26688 DESCRIPTION 26689 Refer to mlock( ). System Interfaces, Issue 6 1295 munlockall( ) System Interfaces 26690 NAME 26691 munlockall - unlock the address space of a process 26692 SYNOPSIS 26693 ML #include 26694 int munlockall(void); 26695 26696 DESCRIPTION 26697 Refer to mlockall( ). 1296 Technical Standard (2001) (Draft April 16, 2001) System Interfaces munmap( ) 26698 NAME 26699 munmap - unmap pages of memory 26700 SYNOPSIS 26701 MF|SHM #include 26702 int munmap(void *addr, size_t len); 26703 26704 DESCRIPTION 26705 The munmap( ) function shall remove any mappings for those entire pages containing any part of 26706 the address space of the process starting at addr and continuing for len bytes. Further references | 26707 to these pages shall result in the generation of a SIGSEGV signal to the process. If there are no | 26708 mappings in the specified address range, then munmap( ) has no effect. 26709 The implementation shall require that addr be a multiple of the page size {PAGESIZE}. 26710 If a mapping to be removed was private, any modifications made in this address range shall be 26711 discarded. 26712 ML|MLR Any memory locks (see mlock( ) and mlockall ( )) associated with this address range shall be 26713 removed, as if by an appropriate call to munlock( ). 26714 TYM If a mapping removed from a typed memory object causes the corresponding address range of 26715 the memory pool to be inaccessible by any process in the system except through allocatable 26716 mappings (that is, mappings of typed memory objects opened with the 26717 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory pool shall 26718 become deallocated and may become available to satisfy future typed memory allocation 26719 requests. 26720 A mapping removed from a typed memory object opened with the 26721 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag shall not affect in any way the availability of 26722 that typed memory for allocation. 26723 The behavior of this function is unspecified if the mapping was not established by a call to 26724 mmap( ). 26725 RETURN VALUE 26726 Upon successful completion, munmap( ) shall return 0; otherwise, it shall return -1 and set errno 26727 to indicate the error. 26728 ERRORS 26729 The munmap( ) function shall fail if: 26730 [EINVAL] Addresses in the range [addr,addr+len) are outside the valid range for the 26731 address space of a process. 26732 [EINVAL] The len argument is 0. 26733 [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). System Interfaces, Issue 6 1297 munmap( ) System Interfaces 26734 EXAMPLES 26735 None. 26736 APPLICATION USAGE 26737 The munmap( ) function is only supported if the Memory Mapped Files option or the Shared 26738 Memory Objects option is supported. 26739 RATIONALE 26740 The munmap( ) function corresponds to SVR4, just as the mmap( ) function does. 26741 It is possible that an application has applied process memory locking to a region that contains 26742 shared memory. If this has occurred, the munmap( ) call ignores those locks and, if necessary, 26743 causes those locks to be removed. 26744 FUTURE DIRECTIONS 26745 None. 26746 SEE ALSO 26747 mlock( ), mlockall( ), mmap( ), posix_typed_mem_open( ), sysconf( ), the Base Definitions volume of 26748 IEEE Std 1003.1-200x, , 26749 CHANGE HISTORY 26750 First released in Issue 4, Version 2. 26751 Issue 5 26752 Moved from X/OPEN UNIX extension to BASE. 26753 Aligned with munmap( ) in the POSIX Realtime Extension as follows: 26754 * The DESCRIPTION is extensively reworded. 26755 * The SIGBUS error is no longer permitted to be generated. 26756 Issue 6 26757 The munmap( ) function is marked as part of the Memory Mapped Files and Shared Memory 26758 Objects option. 26759 The following new requirements on POSIX implementations derive from alignment with the 26760 Single UNIX Specification: 26761 * The DESCRIPTION is updated to state that implementations require addr to be a multiple of 26762 the page size. 26763 * The [EINVAL] error conditions are added. 26764 The following changes are made for alignment with IEEE Std 1003.1j-2000: 26765 * Semantics for typed memory objects are added to the DESCRIPTION. 26766 * The posix_typed_mem_open( ) function is added to the SEE ALSO section. 1298 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nan( ) 26767 NAME 26768 nan, nanf, nanl - return quiet NaN 26769 SYNOPSIS 26770 #include 26771 double nan(const char *tagp); 26772 float nanf(const char *tagp); 26773 long double nanl(const char *tagp); 26774 DESCRIPTION 26775 CX The functionality described on this reference page is aligned with the ISO C standard. Any 26776 conflict between the requirements described here and the ISO C standard is unintentional. This 26777 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 26778 The function call nan("n-char-sequence") shall be equivalent to: 26779 strtod("NAN(n-char-sequence)", (char **) NULL); 26780 The function call nan(" ") shall be equivalent to: 26781 strtod("NAN()", (char **) NULL) 26782 If tagp does not point to an n-char sequence or an empty string, the function call shall be 26783 equivalent to: 26784 strtod("NAN", (char **) NULL) 26785 Function calls to nanf( ) and nanl( ) are equivalent to the corresponding function calls to strtof( ) 26786 and strtold( ). 26787 RETURN VALUE 26788 These functions shall return a quiet NaN, if available, with content indicated through tagp. 26789 If the implementation does not support quiet NaNs, these functions shall return zero. 26790 ERRORS 26791 No errors are defined. 26792 EXAMPLES 26793 None. 26794 APPLICATION USAGE 26795 None. 26796 RATIONALE 26797 None. 26798 FUTURE DIRECTIONS 26799 None. 26800 SEE ALSO 26801 strtod( ), strtold( ), the Base Definitions volume of IEEE Std 1003.1-200x, 26802 CHANGE HISTORY 26803 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1299 nanosleep( ) System Interfaces 26804 NAME 26805 nanosleep - high resolution sleep (REALTIME) 26806 SYNOPSIS 26807 TMR #include 26808 int nanosleep(const struct timespec *rqtp, struct timespec *rmtp); 26809 26810 DESCRIPTION 26811 The nanosleep( ) function shall cause the current thread to be suspended from execution until 26812 either the time interval specified by the rqtp argument has elapsed or a signal is delivered to the 26813 calling thread, and its action is to invoke a signal-catching function or to terminate the process. 26814 The suspension time may be longer than requested because the argument value is rounded up to 26815 an integer multiple of the sleep resolution or because of the scheduling of other activity by the 26816 system. But, except for the case of being interrupted by a signal, the suspension time shall not be 26817 less than the time specified by rqtp, as measured by the system clock, CLOCK_REALTIME. 26818 The use of the nanosleep( ) function has no effect on the action or blockage of any signal. 26819 RETURN VALUE 26820 If the nanosleep( ) function returns because the requested time has elapsed, its return value shall 26821 be zero. 26822 If the nanosleep( ) function returns because it has been interrupted by a signal, it shall return a 26823 value of -1 and set errno to indicate the interruption. If the rmtp argument is non-NULL, the 26824 timespec structure referenced by it is updated to contain the amount of time remaining in the 26825 interval (the requested time minus the time actually slept). If the rmtp argument is NULL, the 26826 remaining time is not returned. 26827 If nanosleep( ) fails, it shall return a value of -1 and set errno to indicate the error. 26828 ERRORS 26829 The nanosleep( ) function shall fail if: 26830 [EINTR] The nanosleep( ) function was interrupted by a signal. 26831 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than 26832 or equal to 1000 million. 26833 EXAMPLES 26834 None. 26835 APPLICATION USAGE 26836 None. 26837 RATIONALE 26838 It is common to suspend execution of a process for an interval in order to poll the status of a 26839 non-interrupting function. A large number of actual needs can be met with a simple extension to 26840 sleep( ) that provides finer resolution. 26841 In the POSIX.1-1990 standard and SVR4, it is possible to implement such a routine, but the 26842 frequency of wakeup is limited by the resolution of the alarm( ) and sleep( ) functions. In 4.3 BSD, 26843 it is possible to write such a routine using no static storage and reserving no system facilities. 26844 Although it is possible to write a function with similar functionality to sleep( ) using the 26845 remainder of the timers function, such a function requires the use of signals and the reservation 26846 of some signal number. This volume of IEEE Std 1003.1-200x requires that nanosleep( ) be non- 26847 intrusive of the signals function. 1300 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nanosleep( ) 26848 The nanosleep( ) function shall return a value of 0 on success and -1 on failure or if interrupted. 26849 This latter case is different from sleep( ). This was done because the remaining time is returned 26850 via an argument structure pointer, rmtp, instead of as the return value. 26851 FUTURE DIRECTIONS 26852 None. 26853 SEE ALSO 26854 sleep( ), the Base Definitions volume of IEEE Std 1003.1-200x, 26855 CHANGE HISTORY 26856 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 26857 Issue 6 26858 The nanosleep( ) function is marked as part of the Timers option. 26859 The [ENOSYS] error condition has been removed as stubs need not be provided if an 26860 implementation does not support the Timers option. System Interfaces, Issue 6 1301 nearbyint( ) System Interfaces 26861 NAME 26862 nearbyint, nearbyintf, nearbyintl - floating-point rounding functions 26863 SYNOPSIS 26864 #include 26865 double nearbyint(double x); 26866 float nearbyintf(float x); 26867 long double nearbyintl(long double x); 26868 DESCRIPTION 26869 CX The functionality described on this reference page is aligned with the ISO C standard. Any 26870 conflict between the requirements described here and the ISO C standard is unintentional. This 26871 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 26872 These functions shall round their argument to an integer value in floating-point format, using 26873 the current rounding direction and without raising the inexact floating-point exception. 26874 An application wishing to check for error situations should set errno to zero and call 26875 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 26876 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 26877 zero, an error has occurred. 26878 RETURN VALUE 26879 Upon successful completion, these functions shall return the rounded integer value. 26880 MX If x is NaN, a NaN shall be returned. 26881 If x is ±0, ±0 shall be returned. 26882 If x is ±Inf, x shall be returned. 26883 XSI If the correct value would cause overflow, a range error shall occur and nearbyint( ), nearbyintf( ), 26884 and nearbyintl( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and 26885 HUGE_VALL, respectively. 26886 ERRORS 26887 These functions shall fail if: 26888 XSI Range Error The result would cause an overflow. 26889 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 26890 then errno shall be set to [ERANGE]. If the integer expression | 26891 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 26892 floating-point exception shall be raised. | 26893 EXAMPLES 26894 None. 26895 APPLICATION USAGE 26896 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 26897 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 26898 RATIONALE 26899 None. 26900 FUTURE DIRECTIONS 26901 None. 1302 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nearbyint( ) 26902 SEE ALSO 26903 feclearexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section 4.18, | 26904 Treatment of Error Conditions for Mathematical Functions, | 26905 CHANGE HISTORY 26906 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1303 nextafter( ) System Interfaces 26907 NAME 26908 nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl - next representable 26909 floating-point number 26910 SYNOPSIS 26911 #include 26912 double nextafter(double x, double y); 26913 float nextafterf(float x, float y); 26914 long double nextafterl(long double x, long double y); 26915 double nexttoward(double x, long double y); 26916 float nexttowardf(float x, long double y); 26917 long double nexttowardl(long double x, long double y); 26918 DESCRIPTION 26919 CX The functionality described on this reference page is aligned with the ISO C standard. Any 26920 conflict between the requirements described here and the ISO C standard is unintentional. This 26921 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 26922 The nextafter( ), nextafterf( ), and nextafterl( ) functions shall compute the next representable 26923 floating-point value following x in the direction of y. Thus, if y is less than x, nextafter( ) shall 26924 return the largest representable floating-point number less than x. The nextafter( ), nextafterf( ), 26925 and nextafterl( ) functions shall return y if x equals y. 26926 The nexttoward( ), nexttowardf( ), and nexttowardl( ) functions shall be equivalent to the | 26927 corresponding nextafter( ) functions, except that the second parameter shall have type long | 26928 double and the functions shall return y converted to the type of the function if x equals y. | 26929 An application wishing to check for error situations should set errno to zero and call 26930 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 26931 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 26932 zero, an error has occurred. 26933 RETURN VALUE 26934 Upon successful completion, these functions shall return the next representable floating-point 26935 value following x in the direction of y. 26936 If x==y, y (of the type x) shall be returned. 26937 If x is finite and the correct function value would overflow, a range error shall occur and 26938 ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (with the same sign as x) shall be returned as 26939 appropriate for the return type of the function. 26940 MX If x or y is NaN, a NaN shall be returned. 26941 If x!=y and the correct function value is subnormal, zero, or underflows, a range error shall 26942 occur, and either the correct function value (if representable) or 0.0 shall be returned. 26943 ERRORS 26944 These functions shall fail if: 26945 Range Error The correct value overflows 26946 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 26947 then errno shall be set to [ERANGE]. If the integer expression | 26948 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 26949 floating-point exception shall be raised. | 26950 MX Range Error The correct value is subnormal or underflows 1304 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nextafter( ) 26951 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 26952 then errno shall be set to [ERANGE]. If the integer expression | 26953 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 26954 floating-point exception shall be raised. | 26955 EXAMPLES 26956 None. 26957 APPLICATION USAGE 26958 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 26959 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 26960 RATIONALE 26961 None. 26962 FUTURE DIRECTIONS 26963 None. 26964 SEE ALSO 26965 feclearexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section 4.18, | 26966 Treatment of Error Conditions for Mathematical Functions, | 26967 CHANGE HISTORY 26968 First released in Issue 4, Version 2. 26969 Issue 5 26970 Moved from X/OPEN UNIX extension to BASE. 26971 Issue 6 26972 The nextafter( ) function is no longer marked as an extension. 26973 The nextafterf( ), nextafterl( ), nexttoward( ), nexttowardf( ), nexttowardl( ) functions are added for 26974 alignment with the ISO/IEC 9899: 1999 standard. 26975 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 26976 revised to align with the ISO/IEC 9899: 1999 standard. 26977 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 26978 marked. System Interfaces, Issue 6 1305 nexttoward( ) System Interfaces 26979 NAME 26980 nexttoward, nexttowardf, nexttowardl - next representable floating-point number 26981 SYNOPSIS 26982 #include 26983 double nexttoward(double x, long double y); 26984 float nexttowardf(float x, long double y); 26985 long double nexttowardl(long double x, long double y); 26986 DESCRIPTION 26987 Refer to nextafter( ). 1306 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nftw( ) 26988 NAME 26989 nftw - walk a file tree 26990 SYNOPSIS 26991 XSI #include 26992 int nftw(const char *path, int (*fn)(const char *, 26993 const struct stat *, int, struct FTW *), int depth, int flags); 26994 26995 DESCRIPTION 26996 The nftw( ) function shall recursively descend the directory hierarchy rooted in path. The nftw( ) 26997 function has a similar effect to ftw( ) except that it takes an additional argument flags, which is a 26998 bitwise-inclusive OR of zero or more of the following flags: 26999 FTW_CHDIR If set, nftw( ) shall change the current working directory to each directory as it 27000 reports files in that directory. If clear, nftw( ) shall not change the current 27001 working directory. 27002 FTW_DEPTH If set, nftw( ) shall report all files in a directory before reporting the directory 27003 itself. If clear, nftw( ) shall report any directory before reporting the files in that 27004 directory. 27005 FTW_MOUNT If set, nftw( ) shall only report files in the same file system as path. If clear, 27006 nftw( ) shall report all files encountered during the walk. 27007 FTW_PHYS If set, nftw( ) shall perform a physical walk and shall not follow symbolic links. 27008 If FTW_PHYS is clear and FTW_DEPTH is set, nftw( ) shall follow links instead of reporting 27009 them, but shall not report any directory that would be a descendant of itself. If FTW_PHYS is 27010 clear and FTW_DEPTH is clear, nftw( ) shall follow links instead of reporting them, but shall not 27011 report the contents of any directory that would be a descendant of itself. 27012 At each file it encounters, nftw( ) shall call the user-supplied function fn with four arguments: 27013 * The first argument is the pathname of the object. | 27014 * The second argument is a pointer to the stat buffer containing information on the object. 27015 * The third argument is an integer giving additional information. Its value is one of the 27016 following: 27017 FTW_F The object is a file. 27018 FTW_D The object is a directory. 27019 FTW_DP The object is a directory and subdirectories have been visited. (This condition 27020 shall only occur if the FTW_DEPTH flag is included in flags.) 27021 FTW_SL The object is a symbolic link. (This condition shall only occur if the FTW_PHYS 27022 flag is included in flags.) 27023 FTW_SLN The object is a symbolic link that does not name an existing file. (This 27024 condition shall only occur if the FTW_PHYS flag is not included in flags.) 27025 FTW_DNR The object is a directory that cannot be read. The fn function shall not be called 27026 for any of its descendants. 27027 FTW_NS The stat( ) function failed on the object because of lack of appropriate 27028 permission. The stat buffer passed to fn is undefined. Failure of stat( ) for any 27029 other reason is considered an error and nftw( ) shall return -1. System Interfaces, Issue 6 1307 nftw( ) System Interfaces 27030 * The fourth argument is a pointer to an FTW structure. The value of base is the offset of the | 27031 object's filename in the pathname passed as the first argument to fn. The value of level | 27032 indicates depth relative to the root of the walk, where the root level is 0. 27033 The results are unspecified if the application-supplied fn function does not preserve the current | 27034 working directory. | 27035 The argument depth sets the maximum number of file descriptors that are shall be used by nftw( ) | 27036 while traversing the file tree. At most one file descriptor shall be used for each directory level. | 27037 The nftw( ) function need not be reentrant. A function that is not required to be reentrant is not | 27038 required to be thread-safe. | 27039 RETURN VALUE 27040 The nftw( ) function shall continue until the first of the following conditions occurs: 27041 * An invocation of fn shall return a non-zero value, in which case nftw( ) shall return that value. 27042 * The nftw( ) function detects an error other than [EACCES] (see FTW_DNR and FTW_NS 27043 above), in which case nftw( ) shall return -1 and set errno to indicate the error. 27044 * The tree is exhausted, in which case nftw( ) shall return 0. 27045 ERRORS 27046 The nftw( ) function shall fail if: 27047 [EACCES] Search permission is denied for any component of path or read permission is 27048 denied for path, or fn returns -1 and does not reset errno. 27049 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 27050 argument. 27051 [ENAMETOOLONG] 27052 The length of the path argument exceeds {PATH_MAX} or a pathname | 27053 component is longer than {NAME_MAX}. | 27054 [ENOENT] A component of path does not name an existing file or path is an empty string. 27055 [ENOTDIR] A component of path is not a directory. | 27056 [EOVERFLOW] A field in the stat structure cannot be represented correctly in the current | 27057 programming environment for one or more files found in the file hierarchy. | 27058 The nftw( ) function may fail if: 27059 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 27060 resolution of the path argument. 27061 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 27062 [ENAMETOOLONG] 27063 Pathname resolution of a symbolic link produced an intermediate result | 27064 whose length exceeds {PATH_MAX}. 27065 [ENFILE] Too many files are currently open in the system. 27066 In addition, errno may be set if the function pointed by fn causes errno to be set. 1308 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nftw( ) 27067 EXAMPLES 27068 The following example walks the /tmp directory and its subdirectories, calling the nftw( ) 27069 function for every directory entry, to a maximum of 5 levels deep. 27070 #include 27071 ... 27072 int nftwfunc(const char *, const struct stat *, int, struct FTW *); 27073 int nftwfunc(const char *filename, const struct stat *statptr, 27074 int fileflags, struct FTW *pfwt) 27075 { 27076 return 0; 27077 } 27078 ... 27079 char *startpath = "/tmp"; 27080 int depth = 5; 27081 int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT; 27082 int ret; 27083 ret = nftw(startpath, nftwfunc, depth, flags); 27084 APPLICATION USAGE 27085 None. 27086 RATIONALE 27087 None. 27088 FUTURE DIRECTIONS 27089 None. 27090 SEE ALSO 27091 lstat( ), opendir( ), readdir( ), stat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 27092 CHANGE HISTORY 27093 First released in Issue 4, Version 2. 27094 Issue 5 27095 Moved from X/OPEN UNIX extension to BASE. 27096 In the DESCRIPTION, the definition of the depth argument is clarified. 27097 Issue 6 27098 The Open Group Base Resolution bwg97-003 is applied. 27099 The ERRORS section is updated as follows: | 27100 * The wording of the mandatory [ELOOP] error condition is updated. | 27101 * A second optional [ELOOP] error condition is added. | 27102 * The [EOVERFLOW] mandatory error condition is added. | 27103 Text is added to the DESCRIPTION to say that the nftw( ) function need not be reentrant and | 27104 that the results are unspecified if the application-supplied fn function does not preserve the | 27105 current working directory. | System Interfaces, Issue 6 1309 nice( ) System Interfaces 27106 NAME 27107 nice - change the nice value of a process 27108 SYNOPSIS 27109 XSI #include 27110 int nice(int incr); 27111 27112 DESCRIPTION 27113 The nice( ) function shall add the value of incr to the nice value of the calling process. A process' 27114 nice value is a non-negative number for which a more positive value shall result in less favorable 27115 scheduling. 27116 A maximum nice value of 2*{NZERO}-1 and a minimum nice value of 0 shall be imposed by the | 27117 system. Requests for values above or below these limits shall result in the nice value being set to | 27118 the corresponding limit. Only a process with appropriate privileges can lower the nice value. | 27119 PS|TPS Calling the nice( ) function has no effect on the priority of processes or threads with policy 27120 SCHED_FIFO or SCHED_RR. The effect on processes or threads with other scheduling policies 27121 is implementation-defined. 27122 The nice value set with nice( ) shall be applied to the process. If the process is multi-threaded, the 27123 nice value shall affect all system scope threads in the process. 27124 As -1 is a permissible return value in a successful situation, an application wishing to check for 27125 error situations should set errno to 0, then call nice( ), and if it returns -1, check to see whether | 27126 errno is non-zero. 27127 RETURN VALUE 27128 Upon successful completion, nice( ) shall return the new nice value -{NZERO}. Otherwise, -1 27129 shall be returned, the process' nice value shall not be changed, and errno shall be set to indicate 27130 the error. 27131 ERRORS 27132 The nice( ) function shall fail if: 27133 [EPERM] The incr argument is negative and the calling process does not have 27134 appropriate privileges. 27135 EXAMPLES 27136 Changing the Nice Value 27137 The following example adds the value of the incr argument, -20, to the nice value of the calling 27138 process. 27139 #include 27140 ... 27141 int incr = -20; 27142 int ret; 27143 ret = nice(incr); 27144 APPLICATION USAGE 27145 None. 1310 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nice( ) 27146 RATIONALE 27147 None. 27148 FUTURE DIRECTIONS 27149 None. 27150 SEE ALSO 27151 getpriority( ), setpriority( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 27152 27153 CHANGE HISTORY 27154 First released in Issue 1. Derived from Issue 1 of the SVID. 27155 Issue 5 27156 A statement is added to the description indicating the effects of this function on the different 27157 scheduling policies and multi-threaded processes. System Interfaces, Issue 6 1311 nl_langinfo( ) System Interfaces 27158 NAME 27159 nl_langinfo - language information 27160 SYNOPSIS 27161 XSI #include 27162 char *nl_langinfo(nl_item item); 27163 27164 DESCRIPTION 27165 The nl_langinfo ( ) function shall return a pointer to a string containing information relevant to 27166 the particular language or cultural area defined in the program's locale (see ). The 27167 manifest constant names and values of item are defined in . For example: 27168 nl_langinfo(ABDAY_1) 27169 would return a pointer to the string "Dom" if the identified language was Portuguese, and 27170 "Sun" if the identified language was English. 27171 Calls to setlocale( ) with a category corresponding to the category of item (see ), or to 27172 the category LC_ALL, may overwrite the array pointed to by the return value. 27173 The nl_langinfo ( ) function need not be reentrant. A function that is not required to be reentrant is 27174 not required to be thread-safe. 27175 RETURN VALUE 27176 In a locale where langinfo data is not defined, nl_langinfo ( ) shall return a pointer to the 27177 corresponding string in the POSIX locale. In all locales, nl_langinfo ( ) shall return a pointer to an 27178 empty string if item contains an invalid setting. 27179 This pointer may point to static data that may be overwritten on the next call. 27180 ERRORS 27181 No errors are defined. 27182 EXAMPLES 27183 Getting Date and Time Formatting Information 27184 The following example returns a pointer to a string containing date and time formatting 27185 information, as defined in the LC_TIME category of the current locale. 27186 #include 27187 #include 27188 ... 27189 strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); 27190 ... 27191 APPLICATION USAGE 27192 The array pointed to by the return value should not be modified by the program, but may be 27193 modified by further calls to nl_langinfo ( ). 27194 RATIONALE 27195 None. 27196 FUTURE DIRECTIONS 27197 None. 1312 Technical Standard (2001) (Draft April 16, 2001) System Interfaces nl_langinfo( ) 27198 SEE ALSO 27199 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the 27200 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 27201 CHANGE HISTORY 27202 First released in Issue 2. 27203 Issue 5 27204 The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section. 27205 A note indicating that this function need not be reentrant is added to the DESCRIPTION. System Interfaces, Issue 6 1313 nrand48( ) System Interfaces 27206 NAME 27207 nrand48 - generate uniformly distributed pseudo-random non-negative long integers 27208 SYNOPSIS 27209 XSI #include 27210 long nrand48(unsigned short xsubi[3]); 27211 27212 DESCRIPTION 27213 Refer to drand48( ). 1314 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ntohl( ) 27214 NAME 27215 ntohl - convert values between host and network byte order 27216 SYNOPSIS 27217 #include 27218 uint32_t ntohl(uint32_t netlong); 27219 DESCRIPTION 27220 Refer to htonl( ). System Interfaces, Issue 6 1315 ntohs( ) System Interfaces 27221 NAME 27222 ntohs - convert values between host and network byte order 27223 SYNOPSIS 27224 #include 27225 uint16_t ntohs(uint16_t netshort); 27226 DESCRIPTION 27227 Refer to htonl( ). 1316 Technical Standard (2001) (Draft April 16, 2001) System Interfaces open( ) 27228 NAME 27229 open - open a file 27230 SYNOPSIS 27231 OH #include 27232 #include 27233 int open(const char *path, int oflag, ... ); 27234 DESCRIPTION 27235 The open( ) function shall establish the connection between a file and a file descriptor. It shall 27236 create an open file description that refers to a file and a file descriptor that refers to that open file 27237 description. The file descriptor is used by other I/O functions to refer to that file. The path | 27238 argument points to a pathname naming the file. | 27239 The open( ) function shall return a file descriptor for the named file that is the lowest file 27240 descriptor not currently open for that process. The open file description is new, and therefore the | 27241 file descriptor shall not share it with any other process in the system. The FD_CLOEXEC file | 27242 descriptor flag associated with the new file descriptor shall be cleared. 27243 The file offset used to mark the current position within the file shall be set to the beginning of the 27244 file. 27245 The file status flags and file access modes of the open file description shall be set according to 27246 the value of oflag. 27247 Values for oflag are constructed by a bitwise-inclusive OR of flags from the following list, 27248 defined in . Applications shall specify exactly one of the first three values (file access 27249 modes) below in the value of oflag: 27250 O_RDONLY Open for reading only. 27251 O_WRONLY Open for writing only. 27252 O_RDWR Open for reading and writing. The result is undefined if this flag is applied to 27253 a FIFO. 27254 Any combination of the following may be used: 27255 O_APPEND If set, the file offset shall be set to the end of the file prior to each write. 27256 O_CREAT If the file exists, this flag has no effect except as noted under O_EXCL below. | 27257 Otherwise, the file shall be created; the user ID of the file shall be set to the | 27258 effective user ID of the process; the group ID of the file shall be set to the | 27259 group ID of the file's parent directory or to the effective group ID of the | 27260 process; and the access permission bits (see ) of the file mode shall | 27261 be set to the value of the third argument taken as type mode_t modified as 27262 follows: a bitwise AND is performed on the file-mode bits and the 27263 corresponding bits in the complement of the process' file mode creation mask. 27264 Thus, all bits in the file mode whose corresponding bit in the file mode | 27265 creation mask is set are cleared. When bits other than the file permission bits | 27266 are set, the effect is unspecified. The third argument does not affect whether | 27267 the file is open for reading, writing, or for both. Implementations shall provide | 27268 a way to initialize the file's group ID to the group ID of the parent directory. | 27269 Implementations may, but need not, provide an implementation-defined way | 27270 to initialize the file's group ID to the effective group ID of the calling process. | 27271 SIO O_DSYNC Write I/O operations on the file descriptor shall complete as defined by | 27272 synchronized I/O data integrity completion. | System Interfaces, Issue 6 1317 open( ) System Interfaces 27273 O_EXCL If O_CREAT and O_EXCL are set, open( ) shall fail if the file exists. The check 27274 for the existence of the file and the creation of the file if it does not exist shall 27275 be atomic with respect to other threads executing open( ) naming the same 27276 filename in the same directory with O_EXCL and O_CREAT set. If O_EXCL 27277 and O_CREAT are set, and path names a symbolic link, open( ) shall fail and set 27278 errno to [EEXIST], regardless of the contents of the symbolic link. If O_EXCL is 27279 set and O_CREAT is not set, the result is undefined. 27280 O_NOCTTY If set and path identifies a terminal device, open( ) shall not cause the terminal | 27281 device to become the controlling terminal for the process. 27282 O_NONBLOCK When opening a FIFO with O_RDONLY or O_WRONLY set: 27283 * If O_NONBLOCK is set, an open( ) for reading-only shall return without 27284 delay. An open( ) for writing-only shall return an error if no process 27285 currently has the file open for reading. 27286 * If O_NONBLOCK is clear, an open( ) for reading-only shall block the 27287 calling thread until a thread opens the file for writing. An open( ) for 27288 writing-only shall block the calling thread until a thread opens the file for 27289 reading. 27290 When opening a block special or character special file that supports non- 27291 blocking opens: 27292 * If O_NONBLOCK is set, the open( ) function shall return without blocking 27293 for the device to be ready or available. Subsequent behavior of the device 27294 is device-specific. 27295 * If O_NONBLOCK is clear, the open( ) function shall block the calling 27296 thread until the device is ready or available before returning. 27297 Otherwise, the behavior of O_NONBLOCK is unspecified. 27298 SIO O_RSYNC Read I/O operations on the file descriptor shall complete at the same level of | 27299 integrity as specified by the O_DSYNC and O_SYNC flags. If both O_DSYNC | 27300 and O_RSYNC are set in oflag, all I/O operations on the file descriptor shall | 27301 complete as defined by synchronized I/O data integrity completion. If both | 27302 O_SYNC and O_RSYNC are set in flags, all I/O operations on the file | 27303 descriptor shall complete as defined by synchronized I/O file integrity | 27304 completion. | 27305 SIO O_SYNC Write I/O operations on the file descriptor shall complete as defined by | 27306 synchronized I/O file integrity completion. | 27307 O_TRUNC If the file exists and is a regular file, and the file is successfully opened 27308 O_RDWR or O_WRONLY, its length shall be truncated to 0, and the mode and | 27309 owner shall be unchanged. It shall have no effect on FIFO special files or | 27310 terminal device files. Its effect on other file types is implementation-defined. | 27311 The result of using O_TRUNC with O_RDONLY is undefined. | 27312 If O_CREAT is set and the file did not previously exist, upon successful completion, open( ) shall 27313 mark for update the st_atime, st_ctime, and st_mtime fields of the file and the st_ctime and 27314 st_mtime fields of the parent directory. 27315 If O_TRUNC is set and the file did previously exist, upon successful completion, open( ) shall 27316 mark for update the st_ctime and st_mtime fields of the file. 1318 Technical Standard (2001) (Draft April 16, 2001) System Interfaces open( ) 27317 SIO If both the O_SYNC and O_DSYNC flags are set, the effect is as if only the O_SYNC flag was set. 27318 27319 XSR If path refers to a STREAMS file, oflag may be constructed from O_NONBLOCK OR'ed with 27320 either O_RDONLY, O_WRONLY, or O_RDWR. Other flag values are not applicable to | 27321 STREAMS devices and shall have no effect on them. The value O_NONBLOCK affects the | 27322 operation of STREAMS drivers and certain functions applied to file descriptors associated with | 27323 STREAMS files. For STREAMS drivers, the implementation of O_NONBLOCK is device-specific. | 27324 27325 XSI If path names the master side of a pseudo-terminal device, then it is unspecified whether open( ) | 27326 locks the slave side so that it cannot be opened. Conforming applications shall call unlockpt( ) | 27327 before opening the slave side. 27328 The largest value that can be represented correctly in an object of type off_t shall be established 27329 as the offset maximum in the open file description. 27330 RETURN VALUE 27331 Upon successful completion, the function shall open the file and return a non-negative integer 27332 representing the lowest numbered unused file descriptor. Otherwise, -1 shall be returned and 27333 errno set to indicate the error. No files shall be created or modified if the function returns -1. 27334 ERRORS 27335 The open( ) function shall fail if: 27336 [EACCES] Search permission is denied on a component of the path prefix, or the file 27337 exists and the permissions specified by oflag are denied, or the file does not 27338 exist and write permission is denied for the parent directory of the file to be 27339 created, or O_TRUNC is specified and write permission is denied. 27340 [EEXIST] O_CREAT and O_EXCL are set, and the named file exists. 27341 [EINTR] A signal was caught during open( ). 27342 SIO [EINVAL] The implementation does not support synchronized I/O for this file. 27343 XSR [EIO] The path argument names a STREAMS file and a hangup or error occurred 27344 during the open( ). 27345 [EISDIR] The named file is a directory and oflag includes O_WRONLY or O_RDWR. 27346 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 27347 argument. 27348 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 27349 [ENAMETOOLONG] 27350 The length of the path argument exceeds {PATH_MAX} or a pathname | 27351 component is longer than {NAME_MAX}. | 27352 [ENFILE] The maximum allowable number of files is currently open in the system. 27353 [ENOENT] O_CREAT is not set and the named file does not exist; or O_CREAT is set and 27354 either the path prefix does not exist or the path argument points to an empty 27355 string. 27356 XSR [ENOSR] The path argument names a STREAMS-based file and the system is unable to 27357 allocate a STREAM. 27358 [ENOSPC] The directory or file system that would contain the new file cannot be 27359 expanded, the file does not exist, and O_CREAT is specified. System Interfaces, Issue 6 1319 open( ) System Interfaces 27360 [ENOTDIR] A component of the path prefix is not a directory. 27361 [ENXIO] O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and no 27362 process has the file open for reading. 27363 [ENXIO] The named file is a character special or block special file, and the device 27364 associated with this special file does not exist. 27365 [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented 27366 correctly in an object of type off_t. 27367 [EROFS] The named file resides on a read-only file system and either O_WRONLY, 27368 O_RDWR, O_CREAT (if file does not exist), or O_TRUNC is set in the oflag 27369 argument. 27370 The open( ) function may fail if: 27371 XSI [EAGAIN] The path argument names the slave side of a pseudo-terminal device that is 27372 locked. 27373 [EINVAL] The value of the oflag argument is not valid. 27374 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 27375 resolution of the path argument. 27376 [ENAMETOOLONG] 27377 As a result of encountering a symbolic link in resolution of the path argument, | 27378 the length of the substituted pathname string exceeded {PATH_MAX}. | 27379 XSR [ENOMEM] The path argument names a STREAMS file and the system is unable to allocate 27380 resources. 27381 [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and oflag is 27382 O_WRONLY or O_RDWR. 27383 EXAMPLES 27384 Opening a File for Writing by the Owner 27385 The following example opens the file /tmp/file, either by creating it (if it does not already exist), 27386 or by truncating its length to 0 (if it does exist). In the former case, if the call creates a new file, 27387 the access permission bits in the file mode of the file are set to permit reading and writing by the 27388 owner, and to permit reading only by group members and others. 27389 If the call to open( ) is successful, the file is opened for writing. 27390 #include 27391 ... 27392 int fd; 27393 mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; 27394 char *filename = "/tmp/file"; 27395 ... 27396 fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode); 27397 ... 1320 Technical Standard (2001) (Draft April 16, 2001) System Interfaces open( ) 27398 Opening a File Using an Existence Check 27399 The following example uses the open( ) function to try to create the LOCKFILE file and open it | 27400 for writing. Since the open( ) function specifies the O_EXCL flag, the call fails if the file already | 27401 exists. In that case, the program assumes that someone else is updating the password file and 27402 exits. 27403 #include 27404 #include 27405 #include 27406 #define LOCKFILE "/etc/ptmp" 27407 ... 27408 int pfd; /* Integer for file descriptor returned by open() call. */ 27409 ... 27410 if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, 27411 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 27412 { 27413 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n"); 27414 exit(1); 27415 } 27416 ... 27417 Opening a File for Writing 27418 The following example opens a file for writing, creating the file if it does not already exist. If the 27419 file does exist, the system truncates the file to zero bytes. 27420 #include 27421 #include 27422 #include 27423 #define LOCKFILE "/etc/ptmp" 27424 ... 27425 int pfd; 27426 char filename[PATH_MAX+1]; 27427 ... 27428 if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, 27429 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 27430 { 27431 perror("Cannot open output file\n"); exit(1); 27432 } 27433 ... 27434 APPLICATION USAGE 27435 None. 27436 RATIONALE 27437 Except as specified in this volume of IEEE Std 1003.1-200x, the flags allowed in oflag are not 27438 mutually-exclusive and any number of them may be used simultaneously. 27439 Some implementations permit opening FIFOs with O_RDWR. Since FIFOs could be 27440 implemented in other ways, and since two file descriptors can be used to the same effect, this 27441 possibility is left as undefined. 27442 See getgroups( ) about the group of a newly created file. System Interfaces, Issue 6 1321 open( ) System Interfaces 27443 The use of open( ) to create a regular file is preferable to the use of creat( ), because the latter is 27444 redundant and included only for historical reasons. 27445 The use of the O_TRUNC flag on FIFOs and directories (pipes cannot be open( )-ed) must be 27446 permissible without unexpected side effects (for example, creat( ) on a FIFO must not remove | 27447 data). Since terminal special files might have type-ahead data stored in the buffer, O_TRUNC | 27448 should not affect their content, particularly if a program that normally opens a regular file 27449 should open the current controlling terminal instead. Other file types, particularly 27450 implementation-defined ones, are left implementation-defined. 27451 IEEE Std 1003.1-200x permits [EACCES] to be returned for conditions other than those explicitly 27452 listed. 27453 The O_NOCTTY flag was added to allow applications to avoid unintentionally acquiring a 27454 controlling terminal as a side effect of opening a terminal file. This volume of 27455 IEEE Std 1003.1-200x does not specify how a controlling terminal is acquired, but it allows an 27456 implementation to provide this on open( ) if the O_NOCTTY flag is not set and other conditions 27457 specified in the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal 27458 Interface are met. The O_NOCTTY flag is an effective no-op if the file being opened is not a 27459 terminal device. 27460 In historical implementations the value of O_RDONLY is zero. Because of that, it is not possible 27461 to detect the presence of O_RDONLY and another option. Future implementations should 27462 encode O_RDONLY and O_WRONLY as bit flags so that: 27463 O_RDONLY | O_WRONLY == O_RDWR 27464 In general, the open( ) function follows the symbolic link if path names a symbolic link. However, 27465 the open( ) function, when called with O_CREAT and O_EXCL, is required to fail with [EEXIST] 27466 if path names an existing symbolic link, even if the symbolic link refers to a nonexistent file. This 27467 behavior is required so that privileged applications can create a new file in a known location 27468 without the possibility that a symbolic link might cause the file to be created in a different 27469 location. 27470 For example, a privileged application that must create a file with a predictable name in a user- 27471 writable directory, such as the user's home directory, could be compromised if the user creates a 27472 symbolic link with that name that refers to a nonexistent file in a system directory. If the user can 27473 influence the contents of a file, the user could compromise the system by creating a new system 27474 configuration or spool file that would then be interpreted by the system. The test for a symbolic 27475 link which refers to a nonexisting file must be atomic with the creation of a new file. | 27476 The POSIX.1-1990 standard required that the group ID of a newly created file be set to the group | 27477 ID of its parent directory or to the effective group ID of the creating process. FIPS 151-2 required | 27478 that implementations provide a way to have the group ID be set to the group ID of the | 27479 containing directory, but did not prohibit implementations also supporting a way to set the | 27480 group ID to the effective group ID of the creating process. Conforming applications should not | 27481 assume which group ID will be used. If it matters, an application can use chown( ) to set the | 27482 group ID after the file is created, or determine under what conditions the implementation will | 27483 set the desired group ID. | 27484 FUTURE DIRECTIONS 27485 None. 27486 SEE ALSO 27487 chmod( ), close( ), creat( ), dup( ), fcntl( ), lseek( ), read( ), umask( ), unlockpt( ), write( ), the Base 27488 Definitions volume of IEEE Std 1003.1-200x, , , 1322 Technical Standard (2001) (Draft April 16, 2001) System Interfaces open( ) 27489 CHANGE HISTORY 27490 First released in Issue 1. Derived from Issue 1 of the SVID. 27491 Issue 5 27492 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 27493 Threads Extension. 27494 Large File Summit extensions are added. 27495 Issue 6 27496 In the SYNOPSIS, the optional include of the header is removed. 27497 The following new requirements on POSIX implementations derive from alignment with the | 27498 Single UNIX Specification: 27499 * The requirement to include has been removed. Although was 27500 required for conforming implementations of previous POSIX specifications, it was not 27501 required for UNIX applications. 27502 * In the DESCRIPTION, O_CREAT is amended to state that the group ID of the file is set to the 27503 group ID of the file's parent directory or to the effective group ID of the process. This is a 27504 FIPS requirement. 27505 * In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 27506 description. This change is to support large files. 27507 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 27508 large files. 27509 * The [ENXIO] mandatory error condition is added. 27510 * The [EINVAL], [ENAMETOOLONG], and [ETXTBSY] optional error conditions are added. 27511 The DESCRIPTION and ERRORS sections are updated so that items related to the optional XSI 27512 STREAMS Option Group are marked. 27513 The following changes were made to align with the IEEE P1003.1a draft standard: 27514 * An explanation is added of the effect of the O_CREAT and O_EXCL flags when the path 27515 refers to a symbolic link. 27516 * The [ELOOP] optional error condition is added. 27517 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 27518 The DESCRIPTION of O_EXCL is updated in response to IEEE PASC Interpretation 1003.1c #48. System Interfaces, Issue 6 1323 opendir( ) System Interfaces 27519 NAME 27520 opendir - open a directory 27521 SYNOPSIS 27522 #include 27523 DIR *opendir(const char *dirname); 27524 DESCRIPTION 27525 The opendir( ) function shall open a directory stream corresponding to the directory named by 27526 the dirname argument. The directory stream is positioned at the first entry. If the type DIR is 27527 implemented using a file descriptor, applications shall only be able to open up to a total of 27528 {OPEN_MAX} files and directories. 27529 RETURN VALUE 27530 Upon successful completion, opendir( ) shall return a pointer to an object of type DIR. 27531 Otherwise, a null pointer shall be returned and errno set to indicate the error. 27532 ERRORS 27533 The opendir( ) function shall fail if: 27534 [EACCES] Search permission is denied for the component of the path prefix of dirname or 27535 read permission is denied for dirname. 27536 [ELOOP] A loop exists in symbolic links encountered during resolution of the dirname 27537 argument. 27538 [ENAMETOOLONG] 27539 The length of the dirname argument exceeds {PATH_MAX} or a pathname | 27540 component is longer than {NAME_MAX}. | 27541 [ENOENT] A component of dirname does not name an existing directory or dirname is an 27542 empty string. 27543 [ENOTDIR] A component of dirname is not a directory. 27544 The opendir( ) function may fail if: 27545 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 27546 resolution of the dirname argument. 27547 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 27548 [ENAMETOOLONG] 27549 As a result of encountering a symbolic link in resolution of the dirname | 27550 argument, the length of the substituted pathname string exceeded | 27551 {PATH_MAX}. 27552 [ENFILE] Too many files are currently open in the system. 1324 Technical Standard (2001) (Draft April 16, 2001) System Interfaces opendir( ) 27553 EXAMPLES | 27554 Open a Directory Stream 27555 The following program fragment demonstrates how the opendir( ) function is used. 27556 #include 27557 #include 27558 #include 27559 ... 27560 DIR *dir; 27561 struct dirent *dp; 27562 ... 27563 if ((dir = opendir (".")) == NULL) { 27564 perror ("Cannot open ."); 27565 exit (1); 27566 } 27567 while ((dp = readdir (dir)) != NULL) { 27568 ... 27569 APPLICATION USAGE 27570 The opendir( ) function should be used in conjunction with readdir( ), closedir( ), and rewinddir( ) to 27571 examine the contents of the directory (see the EXAMPLES section in readdir( )). This method is 27572 recommended for portability. 27573 RATIONALE 27574 Based on historical implementations, the rules about file descriptors apply to directory streams 27575 as well. However, this volume of IEEE Std 1003.1-200x does not mandate that the directory 27576 stream be implemented using file descriptors. The description of closedir( ) clarifies that if a file 27577 descriptor is used for the directory stream, it is mandatory that closedir( ) deallocate the file 27578 descriptor. When a file descriptor is used to implement the directory stream, it behaves as if the 27579 FD_CLOEXEC had been set for the file descriptor. 27580 The directory entries for dot and dot-dot are optional. This volume of IEEE Std 1003.1-200x does 27581 not provide a way to test a priori for their existence because an application that is portable must 27582 be written to look for (and usually ignore) those entries. Writing code that presumes that they 27583 are the first two entries does not always work, as many implementations permit them to be 27584 other than the first two entries, with a ``normal'' entry preceding them. There is negligible value 27585 in providing a way to determine what the implementation does because the code to deal with 27586 dot and dot-dot must be written in any case and because such a flag would add to the list of 27587 those flags (which has proven in itself to be objectionable) and might be abused. 27588 Since the structure and buffer allocation, if any, for directory operations are defined by the 27589 implementation, this volume of IEEE Std 1003.1-200x imposes no portability requirements for 27590 erroneous program constructs, erroneous data, or the use of unspecified values such as the use | 27591 or referencing of a dirp value or a dirent structure value after a directory stream has been closed | 27592 or after a fork( ) or one of the exec function calls. 27593 FUTURE DIRECTIONS 27594 None. 27595 SEE ALSO 27596 closedir( ), lstat( ), readdir( ), rewinddir( ), symlink( ), the Base Definitions volume of 27597 IEEE Std 1003.1-200x, , , System Interfaces, Issue 6 1325 opendir( ) System Interfaces 27598 CHANGE HISTORY 27599 First released in Issue 2. 27600 Issue 6 27601 In the SYNOPSIS, the optional include of the header is removed. 27602 The following new requirements on POSIX implementations derive from alignment with the | 27603 Single UNIX Specification: 27604 * The requirement to include has been removed. Although was 27605 required for conforming implementations of previous POSIX specifications, it was not 27606 required for UNIX applications. 27607 * The [ELOOP] mandatory error condition is added. 27608 * A second [ENAMETOOLONG] is added as an optional error condition. 27609 The following changes were made to align with the IEEE P1003.1a draft standard: 27610 * The [ELOOP] optional error condition is added. 1326 Technical Standard (2001) (Draft April 16, 2001) System Interfaces openlog( ) 27611 NAME 27612 openlog - open a connection to the logging facility 27613 SYNOPSIS 27614 XSI #include 27615 void openlog(const char *ident, int logopt, int facility); 27616 27617 DESCRIPTION 27618 Refer to closelog( ). System Interfaces, Issue 6 1327 optarg System Interfaces 27619 NAME 27620 optarg, opterr, optind, optopt - options parsing variables 27621 SYNOPSIS 27622 #include 27623 extern char *optarg; 27624 extern int opterr, optind, optopt; 27625 DESCRIPTION 27626 Refer to getopt( ). 1328 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pathconf( ) 27627 NAME 27628 pathconf - get configurable pathname variables | 27629 SYNOPSIS 27630 #include 27631 long pathconf(const char *path, int name); 27632 DESCRIPTION 27633 Refer to fpathconf( ). System Interfaces, Issue 6 1329 pause( ) System Interfaces 27634 NAME 27635 pause - suspend the thread until a signal is received 27636 SYNOPSIS 27637 #include 27638 int pause(void); 27639 DESCRIPTION 27640 The pause( ) function shall suspend the calling thread until delivery of a signal whose action is 27641 either to execute a signal-catching function or to terminate the process. 27642 If the action is to terminate the process, pause( ) shall not return. 27643 If the action is to execute a signal-catching function, pause( ) shall return after the signal-catching 27644 function returns. 27645 RETURN VALUE 27646 Since pause( ) suspends thread execution indefinitely unless interrupted by a signal, there is no 27647 successful completion return value. A value of -1 shall be returned and errno set to indicate the 27648 error. 27649 ERRORS 27650 The pause( ) function shall fail if: 27651 [EINTR] A signal is caught by the calling process and control is returned from the 27652 signal-catching function. 27653 EXAMPLES 27654 None. 27655 APPLICATION USAGE 27656 Many common uses of pause( ) have timing windows. The scenario involves checking a 27657 condition related to a signal and, if the signal has not occurred, calling pause( ). When the signal 27658 occurs between the check and the call to pause( ), the process often blocks indefinitely. The 27659 sigprocmask( ) and sigsuspend( ) functions can be used to avoid this type of problem. 27660 RATIONALE 27661 None. 27662 FUTURE DIRECTIONS 27663 None. 27664 SEE ALSO 27665 sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 27666 CHANGE HISTORY 27667 First released in Issue 1. Derived from Issue 1 of the SVID. 27668 Issue 5 27669 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 27670 Issue 6 27671 The APPLICATION USAGE section is added. 1330 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pclose( ) 27672 NAME 27673 pclose - close a pipe stream to or from a process 27674 SYNOPSIS 27675 CX #include | 27676 int pclose(FILE *stream); 27677 | 27678 DESCRIPTION 27679 The pclose( ) function shall close a stream that was opened by popen( ), wait for the command to 27680 terminate, and return the termination status of the process that was running the command 27681 language interpreter. However, if a call caused the termination status to be unavailable to 27682 pclose( ), then pclose( ) shall return -1 with errno set to [ECHILD] to report this situation. This can 27683 happen if the application calls one of the following functions: 27684 * wait( ) 27685 * waitpid ( ) with a pid argument less than or equal to 0 or equal to the process ID of the 27686 command line interpreter 27687 * Any other function not defined in this volume of IEEE Std 1003.1-200x that could do one of 27688 the above 27689 In any case, pclose( ) shall not return before the child process created by popen( ) has terminated. 27690 If the command language interpreter cannot be executed, the child termination status returned 27691 by pclose( ) shall be as if the command language interpreter terminated using exit(127) or | 27692 _exit(127). 27693 The pclose( ) function shall not affect the termination status of any child of the calling process 27694 other than the one created by popen( ) for the associated stream. 27695 If the argument stream to pclose( ) is not a pointer to a stream created by popen( ), the result of 27696 pclose( ) is undefined. 27697 RETURN VALUE 27698 Upon successful return, pclose( ) shall return the termination status of the command language 27699 interpreter. Otherwise, pclose( ) shall return -1 and set errno to indicate the error. 27700 ERRORS 27701 The pclose( ) function shall fail if: 27702 [ECHILD] The status of the child process could not be obtained, as described above. 27703 EXAMPLES 27704 None. 27705 APPLICATION USAGE 27706 None. 27707 RATIONALE 27708 There is a requirement that pclose( ) not return before the child process terminates. This is 27709 intended to disallow implementations that return [EINTR] if a signal is received while waiting. 27710 If pclose( ) returned before the child terminated, there would be no way for the application to 27711 discover which child used to be associated with the stream, and it could not do the cleanup 27712 itself. 27713 If the stream pointed to by stream was not created by popen( ), historical implementations of 27714 pclose( ) return -1 without setting errno. To avoid requiring pclose( ) to set errno in this case, 27715 IEEE Std 1003.1-200x makes the behavior unspecified. An application should not use pclose( ) to System Interfaces, Issue 6 1331 pclose( ) System Interfaces 27716 close any stream that was not created by popen( ). 27717 Some historical implementations of pclose( ) either block or ignore the signals SIGINT, SIGQUIT, 27718 and SIGHUP while waiting for the child process to terminate. Since this behavior is not 27719 described for the pclose( ) function in IEEE Std 1003.1-200x, such implementations are not 27720 conforming. Also, some historical implementations return [EINTR] if a signal is received, even 27721 though the child process has not terminated. Such implementations are also considered non- 27722 conforming. 27723 Consider, for example, an application that uses: 27724 popen("command", "r") 27725 to start command, which is part of the same application. The parent writes a prompt to its 27726 standard output (presumably the terminal) and then reads from the stream. The child reads the 27727 response from the user, does some transformation on the response (pathname expansion, | 27728 perhaps) and writes the result to its standard output. The parent process reads the result from | 27729 the pipe, does something with it, and prints another prompt. The cycle repeats. Assuming that 27730 both processes do appropriate buffer flushing, this would be expected to work. 27731 To conform to IEEE Std 1003.1-200x, pclose( ) must use waitpid( ), or some similar function, 27732 instead of wait( ). 27733 The code sample below illustrates how the pclose( ) function might be implemented on a system 27734 conforming to IEEE Std 1003.1-200x. 27735 int pclose(FILE *stream) 27736 { 27737 int stat; 27738 pid_t pid; 27739 pid = 27740 (void) fclose(stream); 27741 while (waitpid(pid, &stat, 0) == -1) { 27742 if (errno != EINTR){ 27743 stat = -1; 27744 break; 27745 } 27746 } 27747 return(stat); 27748 } 27749 FUTURE DIRECTIONS 27750 None. 27751 SEE ALSO 27752 fork( ), popen( ), waitpid( ), the Base Definitions volume of IEEE Std 1003.1-200x, 27753 CHANGE HISTORY 27754 First released in Issue 1. Derived from Issue 1 of the SVID. 1332 Technical Standard (2001) (Draft April 16, 2001) System Interfaces perror( ) 27755 NAME 27756 perror - write error messages to standard error 27757 SYNOPSIS 27758 #include 27759 void perror(const char *s); 27760 DESCRIPTION 27761 CX The functionality described on this reference page is aligned with the ISO C standard. Any 27762 conflict between the requirements described here and the ISO C standard is unintentional. This 27763 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 27764 The perror( ) function shall map the error number accessed through the symbol errno to a | 27765 language-dependent error message, which shall be written to the standard error stream as 27766 follows: 27767 * First (if s is not a null pointer and the character pointed to by s is not the null byte), the string 27768 pointed to by s followed by a colon and a . 27769 * Then an error message string followed by a . 27770 The contents of the error message strings shall be the same as those returned by strerror( ) with | 27771 argument errno. 27772 CX The perror( ) function shall mark the file associated with the standard error stream as having 27773 been written (st_ctime, st_mtime marked for update) at some time between its successful 27774 completion and exit( ), abort( ), or the completion of fflush( ) or fclose( ) on stderr. 27775 The perror( ) function shall not change the orientation of the standard error stream. 27776 RETURN VALUE 27777 The perror( ) function shall not return a value. 27778 ERRORS 27779 No errors are defined. 27780 EXAMPLES 27781 Printing an Error Message for a Function 27782 The following example replaces bufptr with a buffer that is the necessary size. If an error occurs, 27783 the perror( ) function prints a message and the program exits. 27784 #include 27785 #include 27786 ... 27787 char *bufptr; 27788 size_t szbuf; 27789 ... 27790 if ((bufptr = malloc(szbuf)) == NULL) { 27791 perror("malloc"); exit(2); 27792 } 27793 ... 27794 APPLICATION USAGE 27795 None. System Interfaces, Issue 6 1333 perror( ) System Interfaces 27796 RATIONALE 27797 None. 27798 FUTURE DIRECTIONS 27799 None. 27800 SEE ALSO 27801 strerror( ), the Base Definitions volume of IEEE Std 1003.1-200x, 27802 CHANGE HISTORY 27803 First released in Issue 1. Derived from Issue 1 of the SVID. 27804 Issue 5 27805 A paragraph is added to the DESCRIPTION indicating that perror( ) does not change the 27806 orientation of the standard error stream. 27807 Issue 6 27808 Extensions beyond the ISO C standard are now marked. 1334 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pipe( ) 27809 NAME 27810 pipe - create an interprocess channel 27811 SYNOPSIS 27812 #include 27813 int pipe(int fildes[2]); 27814 DESCRIPTION 27815 The pipe( ) function shall create a pipe and place two file descriptors, one each into the 27816 arguments fildes[0] and fildes[1], that refer to the open file descriptions for the read and write 27817 ends of the pipe. Their integer values shall be the two lowest available at the time of the pipe( ) 27818 call. The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file descriptors. (The 27819 fcntl( ) function can be used to set both these flags.) 27820 Data can be written to the file descriptor fildes[1] and read from the file descriptor fildes[0]. A 27821 read on the file descriptor fildes[0] shall access data written to the file descriptor fildes[1] on a 27822 first-in-first-out basis. It is unspecified whether fildes[0] is also open for writing and whether 27823 fildes[1] is also open for reading. 27824 A process has the pipe open for reading (correspondingly writing) if it has a file descriptor open 27825 that refers to the read end, fildes[0] (write end, fildes[1]). 27826 Upon successful completion, pipe( ) shall mark for update the st_atime, st_ctime, and st_mtime 27827 fields of the pipe. 27828 RETURN VALUE 27829 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 27830 indicate the error. 27831 ERRORS 27832 The pipe( ) function shall fail if: 27833 [EMFILE] More than {OPEN_MAX} minus two file descriptors are already in use by this 27834 process. 27835 [ENFILE] The number of simultaneously open files in the system would exceed a 27836 system-imposed limit. 27837 EXAMPLES 27838 None. 27839 APPLICATION USAGE 27840 None. 27841 RATIONALE 27842 The wording carefully avoids using the verb ``to open'' in order to avoid any implication of use 27843 of open( ); see also write( ). 27844 FUTURE DIRECTIONS 27845 None. 27846 SEE ALSO 27847 fcntl( ), read( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 27848 27849 CHANGE HISTORY 27850 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 1335 pipe( ) System Interfaces 27851 Issue 6 27852 The following new requirements on POSIX implementations derive from alignment with the 27853 Single UNIX Specification: 27854 * The DESCRIPTION is updated to indicate that certain dispositions of fildes[0] and fildes[1] 27855 are unspecified. 1336 Technical Standard (2001) (Draft April 16, 2001) System Interfaces poll( ) 27856 NAME 27857 poll - input/output multiplexing 27858 SYNOPSIS 27859 XSI #include 27860 int poll(struct pollfd fds[], nfds_t nfds, int timeout); 27861 27862 DESCRIPTION 27863 The poll( ) function provides applications with a mechanism for multiplexing input/output over 27864 a set of file descriptors. For each member of the array pointed to by fds, poll( ) shall examine the | 27865 given file descriptor for the event(s) specified in events. The number of pollfd structures in the | 27866 fds array is specified by nfds. The poll( ) function shall identify those file descriptors on which an | 27867 application can read or write data, or on which certain events have occurred. | 27868 The fds argument specifies the file descriptors to be examined and the events of interest for each 27869 file descriptor. It is a pointer to an array with one member for each open file descriptor of 27870 interest. The array's members are pollfd structures within which fd specifies an open file 27871 descriptor and events and revents are bitmasks constructed by OR'ing a combination of the 27872 following event flags: 27873 POLLIN Data other than high-priority data may be read without blocking. 27874 XSR For STREAMS, this flag is set in revents even if the message is of zero length. | 27875 This flag shall be equivalent to POLLRDNORM | POLLRDBAND. | 27876 POLLRDNORM Normal data may be read without blocking. 27877 XSR For STREAMS, data on priority band 0 may be read without blocking. This 27878 flag is set in revents even if the message is of zero length. 27879 POLLRDBAND Priority data may be read without blocking. 27880 XSR For STREAMS, data on priority bands greater than 0 may be read without 27881 blocking. This flag is set in revents even if the message is of zero length. 27882 POLLPRI High-priority data may be read without blocking. 27883 XSR For STREAMS, this flag is set in revents even if the message is of zero length. 27884 POLLOUT Normal data may be written without blocking. 27885 XSR For STREAMS, data on priority band 0 may be written without blocking. 27886 POLLWRNORM Equivalent to POLLOUT. | 27887 POLLWRBAND Priority data may be written. 27888 XSR For STREAMS, data on priority bands greater than 0 may be written without | 27889 blocking. If any priority band has been written to on this STREAM, this event | 27890 only examines bands that have been written to at least once. | 27891 POLLERR An error has occurred on the device or stream. This flag is only valid in the 27892 revents bitmask; it shall be ignored in the events member. 27893 POLLHUP The device has been disconnected. This event and POLLOUT are mutually- 27894 exclusive; a stream can never be writable if a hangup has occurred. However, 27895 this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not 27896 mutually-exclusive. This flag is only valid in the revents bitmask; it shall be 27897 ignored in the events member. System Interfaces, Issue 6 1337 poll( ) System Interfaces 27898 POLLNVAL The specified fd value is invalid. This flag is only valid in the revents member; 27899 it shall ignored in the events member. 27900 The significance and semantics of normal, priority, and high-priority data are file and device- 27901 specific. 27902 If the value of fd is less than 0, events shall be ignored, and revents shall be set to 0 in that entry on 27903 return from poll( ). 27904 In each pollfd structure, poll( ) shall clear the revents member, except that where the application | 27905 requested a report on a condition by setting one of the bits of events listed above, poll( ) shall set 27906 the corresponding bit in revents if the requested condition is true. In addition, poll( ) shall set the 27907 POLLHUP, POLLERR, and POLLNVAL flag in revents if the condition is true, even if the 27908 application did not set the corresponding bit in events. 27909 If none of the defined events have occurred on any selected file descriptor, poll( ) shall wait at 27910 least timeout milliseconds for an event to occur on any of the selected file descriptors. If the value 27911 of timeout is 0, poll( ) shall return immediately. If the value of timeout is -1, poll( ) shall block until 27912 a requested event occurs or until the call is interrupted. 27913 Implementations may place limitations on the granularity of timeout intervals. If the requested 27914 timeout interval requires a finer granularity than the implementation supports, the actual 27915 timeout interval shall be rounded up to the next supported value. 27916 The poll( ) function shall not be affected by the O_NONBLOCK flag. 27917 XSR The poll( ) function shall support regular files, terminal and pseudo-terminal devices, 27918 STREAMS-based files, FIFOs, pipes, and sockets. The behavior of poll( ) on elements of fds that 27919 refer to other types of file is unspecified. 27920 Regular files shall always poll TRUE for reading and writing. 27921 A file descriptor for a socket that is listening for connections shall indicate that it is ready for 27922 reading, once connections are available. A file descriptor for a socket that is connecting 27923 asynchronously shall indicate that it is ready for writing, once a connection has been established. 27924 RETURN VALUE 27925 Upon successful completion, poll( ) shall return a non-negative value. A positive value indicates 27926 the total number of file descriptors that have been selected (that is, file descriptors for which the 27927 revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors 27928 have been selected. Upon failure, poll( ) shall return -1 and set errno to indicate the error. 27929 ERRORS 27930 The poll( ) function shall fail if: 27931 [EAGAIN] The allocation of internal data structures failed but a subsequent request may 27932 succeed. 27933 [EINTR] A signal was caught during poll( ). 27934 XSR [EINVAL] The nfds argument is greater than {OPEN_MAX}, or one of the fd members 27935 refers to a STREAM or multiplexer that is linked (directly or indirectly) 27936 downstream from a multiplexer. 1338 Technical Standard (2001) (Draft April 16, 2001) System Interfaces poll( ) 27937 EXAMPLES 27938 Checking for Events on a Stream 27939 The following example opens a pair of STREAMS devices and then waits for either one to 27940 become writable. This example proceeds as follows: 27941 1. Sets the timeout parameter to 500 milliseconds. 27942 2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and then polls them, specifying 27943 POLLOUT and POLLWRBAND as the events of interest. 27944 The STREAMS device names /dev/dev0 and /dev/dev1 are only examples of how 27945 STREAMS devices can be named; STREAMS naming conventions may vary among 27946 systems conforming to the IEEE Std 1003.1-200x. 27947 3. Uses the ret variable to determine whether an event has occurred on either of the two 27948 STREAMS. The poll( ) function is given 500 milliseconds to wait for an event to occur (if it 27949 has not occurred prior to the poll( ) call). 27950 4. Checks the returned value of ret. If a positive value is returned, one of the following can 27951 be done: 27952 a. Priority data can be written to the open STREAM on priority bands greater than 0, 27953 because the POLLWRBAND event occurred on the open STREAM (fds[0] or fds[1]). 27954 b. Data can be written to the open STREAM on priority-band 0, because the POLLOUT 27955 event occurred on the open STREAM (fds[0] or fds[1]). 27956 5. If the returned value is not a positive value, permission to write data to the open STREAM 27957 (on any priority band) is denied. 27958 6. If the POLLHUP event occurs on the open STREAM (fds[0] or fds[1]), the device on the 27959 open STREAM has disconnected. 27960 #include 27961 #include 27962 ... 27963 struct pollfd fds[2]; 27964 int timeout_msecs = 500; 27965 int ret; 27966 int i; 27967 /* Open STREAMS device. */ 27968 fds[0].fd = open("/dev/dev0", ...); 27969 fds[1].fd = open("/dev/dev1", ...); 27970 fds[0].events = POLLOUT | POLLWRBAND; 27971 fds[1].events = POLLOUT | POLLWRBAND; 27972 ret = poll(fds, 2, timeout_msecs); 27973 if (ret > 0) { 27974 /* An event on one of the fds has occurred. */ 27975 for (i=0; i<2; i++) { 27976 if (fds[i].revents & POLLWRBAND) { 27977 /* Priority data may be written on device number i. */ 27978 ... 27979 } 27980 if (fds[i].revents & POLLOUT) { System Interfaces, Issue 6 1339 poll( ) System Interfaces 27981 /* Data may be written on device number i. */ 27982 ... 27983 } 27984 if (fds[i].revents & POLLHUP) { 27985 /* A hangup has occurred on device number i. */ 27986 ... 27987 } 27988 } 27989 } 27990 APPLICATION USAGE 27991 None. 27992 RATIONALE 27993 None. 27994 FUTURE DIRECTIONS 27995 None. 27996 SEE ALSO 27997 getmsg( ), putmsg( ), read( ), select( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 27998 , , Section 2.6 (on page 488) 27999 CHANGE HISTORY 28000 First released in Issue 4, Version 2. 28001 Issue 5 28002 Moved from X/OPEN UNIX extension to BASE. 28003 The description of POLLWRBAND is updated. 28004 Issue 6 28005 Text referring to sockets is added to the DESCRIPTION. 28006 Text relating to the XSI STREAMS Option Group is marked. | 28007 The Open Group Corrigendum Unnn/nn is applied, updating the DESCRIPTION of | 28008 POLLWRBAND. | 1340 Technical Standard (2001) (Draft April 16, 2001) System Interfaces popen( ) 28009 NAME 28010 popen - initiate pipe streams to or from a process 28011 SYNOPSIS 28012 CX #include | 28013 FILE *popen(const char *command, const char *mode); 28014 | 28015 DESCRIPTION 28016 The popen( ) function shall execute the command specified by the string command. It shall create a 28017 pipe between the calling program and the executed command, and shall return a pointer to a 28018 stream that can be used to either read from or write to the pipe. 28019 The environment of the executed command shall be as if a child process were created within the 28020 popen( ) call using the fork( ) function, and the child invoked the sh utility using the call: | 28021 execl(shell path, "sh", "-c", command, (char *)0); 28022 where shell path is an unspecified pathname for the sh utility. | 28023 The popen( ) function shall ensure that any streams from previous popen( ) calls that remain open | 28024 in the parent process are closed in the new child process. 28025 The mode argument to popen( ) is a string that specifies I/O mode: 28026 1. If mode is r, when the child process is started, its file descriptor STDOUT_FILENO shall be 28027 the writable end of the pipe, and the file descriptor fileno(stream) in the calling process, 28028 where stream is the stream pointer returned by popen( ), shall be the readable end of the 28029 pipe. 28030 2. If mode is w, when the child process is started its file descriptor STDIN_FILENO shall be 28031 the readable end of the pipe, and the file descriptor fileno(stream) in the calling process, 28032 where stream is the stream pointer returned by popen( ), shall be the writable end of the 28033 pipe. 28034 3. If mode is any other value, the result is undefined. 28035 After popen( ), both the parent and the child process shall be capable of executing independently 28036 before either terminates. 28037 Pipe streams are byte-oriented. 28038 RETURN VALUE 28039 Upon successful completion, popen( ) shall return a pointer to an open stream that can be used to 28040 read or write to the pipe. Otherwise, it shall return a null pointer and may set errno to indicate 28041 the error. 28042 ERRORS 28043 The popen( ) function may fail if: 28044 [EMFILE] {FOPEN_MAX} or {STREAM_MAX} streams are currently open in the calling 28045 process. 28046 [EINVAL] The mode argument is invalid. 28047 The popen( ) function may also set errno values as described by fork( ) or pipe( ). System Interfaces, Issue 6 1341 popen( ) System Interfaces 28048 EXAMPLES 28049 None. 28050 APPLICATION USAGE 28051 Since open files are shared, a mode r command can be used as an input filter and a mode w | 28052 command as an output filter. 28053 Buffered reading before opening an input filter may leave the standard input of that filter 28054 mispositioned. Similar problems with an output filter may be prevented by careful buffer 28055 flushing; for example, with fflush( ). 28056 A stream opened by popen( ) should be closed by pclose( ). 28057 The behavior of popen( ) is specified for values of mode of r and w. Other modes such as rb and 28058 wb might be supported by specific implementations, but these would not be portable features. 28059 Note that historical implementations of popen( ) only check to see if the first character of mode is 28060 r. Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else would be 28061 treated as mode w. 28062 If the application calls waitpid( ) or waitid( ) with a pid argument greater than 0, and it still has a 28063 stream that was called with popen( ) open, it must ensure that pid does not refer to the process 28064 started by popen( ). 28065 To determine whether or not the environment specified in the Shell and Utilities volume of 28066 IEEE Std 1003.1-200x is present, use the function call: 28067 sysconf(_SC_2_VERSION) 28068 (See sysconf( )). 28069 RATIONALE 28070 The popen( ) function should not be used by programs that have set user (or group) ID privileges. 28071 The fork( ) and exec family of functions (except execlp( ) and execvp( )), should be used instead. 28072 This prevents any unforeseen manipulation of the environment of the user that could cause 28073 execution of commands not anticipated by the calling program. 28074 If the original and popen( )ed processes both intend to read or write or read and write a common 28075 file, and either will be using FILE-type C functions (fread( ), fwrite( ), and so on), the rules for 28076 sharing file handles must be observed (see Section 2.5.1 (on page 485)). 28077 Since open files are shared, a mode r argument can be used as an input filter and a mode w | 28078 argument as an output filter. 28079 The behavior of popen( ) is specified for modes of r and w. Other modes such as rb and wb might 28080 be supported by specific implementations, but these would not be portable features. Note that 28081 historical implementations of popen( ) only check to see if the first character of mode is 'r'. 28082 Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else would be 28083 treated as mode w. 28084 If the application calls waitpid( ) with a pid argument greater than zero, and it still has a 28085 popen( )ed stream open, it must ensure that pid does not refer to the process started by popen( ). 28086 FUTURE DIRECTIONS 28087 None. 28088 SEE ALSO 28089 pclose( ), pipe( ), sysconf( ), system( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28090 , the Shell and Utilities volume of IEEE Std 1003.1-200x, sh | 1342 Technical Standard (2001) (Draft April 16, 2001) System Interfaces popen( ) 28091 CHANGE HISTORY 28092 First released in Issue 1. Derived from Issue 1 of the SVID. 28093 Issue 5 28094 A statement is added to the DESCRIPTION indicating that pipe streams are byte-oriented. 28095 Issue 6 28096 The following new requirements on POSIX implementations derive from alignment with the 28097 Single UNIX Specification: | 28098 * The optional [EMFILE] error condition is added. System Interfaces, Issue 6 1343 posix_fadvise( ) System Interfaces 28099 NAME 28100 posix_fadvise - file advisory information (ADVANCED REALTIME) 28101 SYNOPSIS 28102 ADV #include 28103 int posix_fadvise(int fd, off_t offset, size_t len, int advice); 28104 28105 DESCRIPTION 28106 The posix_fadvise( ) function shall advise the implementation on the expected behavior of the | 28107 application with respect to the data in the file associated with the open file descriptor, fd, 28108 starting at offset and continuing for len bytes. The specified range need not currently exist in the 28109 file. If len is zero, all data following offset is specified. The implementation may use this 28110 information to optimize handling of the specified data. The posix_fadvise( ) function shall have no | 28111 effect on the semantics of other operations on the specified data, although it may affect the | 28112 performance of other operations. | 28113 The advice to be applied to the data is specified by the advice parameter and may be one of the 28114 following values: 28115 POSIX_FADV_NORMAL 28116 Specifies that the application has no advice to give on its behavior with respect to the 28117 specified data. It is the default characteristic if no advice is given for an open file. 28118 POSIX_FADV_SEQUENTIAL 28119 Specifies that the application expects to access the specified data sequentially from lower 28120 offsets to higher offsets. 28121 POSIX_FADV_RANDOM 28122 Specifies that the application expects to access the specified data in a random order. 28123 POSIX_FADV_WILLNEED 28124 Specifies that the application expects to access the specified data in the near future. 28125 POSIX_FADV_DONTNEED 28126 Specifies that the application expects that it will not access the specified data in the near 28127 future. 28128 POSIX_FADV_NOREUSE 28129 Specifies that the application expects to access the specified data once and then not reuse it 28130 thereafter. 28131 These values are defined in . | 28132 RETURN VALUE 28133 Upon successful completion, posix_fadvise( ) shall return zero; otherwise, an error number shall 28134 be returned to indicate the error. 28135 ERRORS 28136 The posix_fadvise( ) function shall fail if: 28137 [EBADF] The fd argument is not a valid file descriptor. 28138 [EINVAL] The value of advice is invalid. 28139 [ESPIPE] The fd argument is associated with a pipe or FIFO. 1344 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_fadvise( ) 28140 EXAMPLES 28141 None. 28142 APPLICATION USAGE 28143 The posix_fadvise( ) function is part of the Advisory Information option and need not be provided 28144 on all implementations. 28145 RATIONALE 28146 None. 28147 FUTURE DIRECTIONS 28148 None. 28149 SEE ALSO 28150 posix_madvise( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28151 CHANGE HISTORY 28152 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28153 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1345 posix_fallocate( ) System Interfaces 28154 NAME 28155 posix_fallocate - file space control (ADVANCED REALTIME) 28156 SYNOPSIS 28157 ADV #include 28158 int posix_fallocate(int fd, off_t offset, size_t len); 28159 28160 DESCRIPTION 28161 The posix_fallocate( ) function shall ensure that any required storage for regular file data starting | 28162 at offset and continuing for len bytes is allocated on the file system storage media. If 28163 posix_fallocate( ) returns successfully, subsequent writes to the specified file data shall not fail 28164 due to the lack of free space on the file system storage media. 28165 If the offset+len is beyond the current file size, then posix_fallocate( ) shall adjust the file size to 28166 offset+len. Otherwise, the file size shall not be changed. 28167 It is implementation-defined whether a previous posix_fadvise( ) call influences allocation 28168 strategy. 28169 Space allocated via posix_fallocate( ) shall be freed by a successful call to creat( ) or open( ) that 28170 truncates the size of the file. Space allocated via posix_fallocate( ) may be freed by a successful call 28171 to ftruncate( ) that reduces the file size to a size smaller than offset+len. 28172 RETURN VALUE 28173 Upon successful completion, posix_fallocate( ) shall return zero; otherwise, an error number shall 28174 be returned to indicate the error. 28175 ERRORS 28176 The posix_fallocate( ) function shall fail if: 28177 [EBADF] The fd argument is not a valid file descriptor. 28178 [EBADF] The fd argument references a file that was opened without write permission. 28179 [EFBIG] The value of offset+len is greater than the maximum file size. 28180 [EINTR] A signal was caught during execution. 28181 [EINVAL] The len argument was zero or the offset argument was less than zero. 28182 [EIO] An I/O error occurred while reading from or writing to a file system. 28183 [ENODEV] The fd argument does not refer to a regular file. 28184 [ENOSPC] There is insufficient free space remaining on the file system storage media. 28185 [ESPIPE] The fd argument is associated with a pipe or FIFO. 28186 EXAMPLES 28187 None. 28188 APPLICATION USAGE 28189 The posix_fallocate( ) function is part of the Advisory Information option and need not be 28190 provided on all implementations. 28191 RATIONALE 28192 None. 1346 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_fallocate( ) 28193 FUTURE DIRECTIONS 28194 None. 28195 SEE ALSO 28196 creat( ), ftruncate( ), open( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28197 28198 CHANGE HISTORY 28199 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28200 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1347 posix_madvise( ) System Interfaces 28201 NAME 28202 posix_madvise - memory advisory information and alignment control (ADVANCED 28203 REALTIME) 28204 SYNOPSIS 28205 ADV #include 28206 int posix_madvise(void *addr, size_t len, int advice); 28207 28208 DESCRIPTION 28209 MF|SHM The posix_madvise( ) function need only be supported if either the Memory Mapped Files or the 28210 Shared Memory Objects options are supported. 28211 The posix_madvise( ) function shall advise the implementation on the expected behavior of the | 28212 application with respect to the data in the memory starting at address addr, and continuing for | 28213 len bytes. The implementation may use this information to optimize handling of the specified 28214 data. The posix_madvise( ) function shall have no effect on the semantics of access to memory in | 28215 the specified range, although it may affect the performance of access. | 28216 The implementation may require that addr be a multiple of the page size, which is the value 28217 returned by sysconf( ) when the name value _SC_PAGESIZE is used. 28218 The advice to be applied to the memory range is specified by the advice parameter and may be 28219 one of the following values: 28220 POSIX_MADV_NORMAL 28221 Specifies that the application has no advice to give on its behavior with respect to the 28222 specified range. It is the default characteristic if no advice is given for a range of memory. 28223 POSIX_MADV_SEQUENTIAL 28224 Specifies that the application expects to access the specified range sequentially from lower 28225 addresses to higher addresses. 28226 POSIX_MADV_RANDOM 28227 Specifies that the application expects to access the specified range in a random order. 28228 POSIX_MADV_WILLNEED 28229 Specifies that the application expects to access the specified range in the near future. 28230 POSIX_MADV_DONTNEED 28231 Specifies that the application expects that it will not access the specified range in the near 28232 future. 28233 These values are defined in the header. | 28234 RETURN VALUE 28235 Upon successful completion, posix_madvise( ) shall return zero; otherwise, an error number shall 28236 be returned to indicate the error. 28237 ERRORS 28238 The posix_madvise( ) function shall fail if: 28239 [EINVAL] The value of advice is invalid. 28240 [ENOMEM] Addresses in the range starting at addr and continuing for len bytes are partly 28241 or completely outside the range allowed for the address space of the calling 28242 process. 28243 The posix_madvise( ) function may fail if: 1348 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_madvise( ) 28244 [EINVAL] The value of addr is not a multiple of the value returned by sysconf( ) when the 28245 name value _SC_PAGESIZE is used. 28246 [EINVAL] The value of len is zero. 28247 EXAMPLES 28248 None. 28249 APPLICATION USAGE 28250 The posix_madvise( ) function is part of the Advisory Information option and need not be 28251 provided on all implementations. 28252 RATIONALE 28253 None. 28254 FUTURE DIRECTIONS 28255 None. 28256 SEE ALSO 28257 mmap( ), posix_fadvise( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 28258 | 28259 CHANGE HISTORY 28260 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28261 IEEE PASC Interpretation 1003.1 #102 is applied. | System Interfaces, Issue 6 1349 posix_mem_offset( ) System Interfaces 28262 NAME 28263 posix_mem_offset - find offset and length of a mapped typed memory block (ADVANCED 28264 REALTIME) 28265 SYNOPSIS 28266 TYM #include 28267 int posix_mem_offset(const void *restrict addr, size_t len, 28268 off_t *restrict off, size_t *restrict contig_len, 28269 int *restrict fildes); 28270 28271 DESCRIPTION 28272 The posix_mem_offset( ) function shall return in the variable pointed to by off a value that 28273 identifies the offset (or location), within a memory object, of the memory block currently 28274 mapped at addr. The function shall return in the variable pointed to by fildes, the descriptor used 28275 (via mmap( )) to establish the mapping which contains addr. If that descriptor was closed since 28276 the mapping was established, the returned value of fildes shall be -1. The len argument specifies 28277 the length of the block of the memory object the user wishes the offset for; upon return, the value 28278 pointed to by contig_len shall equal either len, or the length of the largest contiguous block of the 28279 memory object that is currently mapped to the calling process starting at addr, whichever is 28280 smaller. 28281 If the memory object mapped at addr is a typed memory object, then if the off and contig_len 28282 values obtained by calling posix_mem_offset( ) are used in a call to mmap( ) with a file descriptor 28283 that refers to the same memory pool as fildes (either through the same port or through a different 28284 port), and that was opened with neither the POSIX_TYPED_MEM_ALLOCATE nor the 28285 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the typed memory area that is mapped shall 28286 be exactly the same area that was mapped at addr in the address space of the process that called 28287 posix_mem_offset( ). 28288 If the memory object specified by fildes is not a typed memory object, then the behavior of this 28289 function is implementation-defined. 28290 RETURN VALUE 28291 Upon successful completion, the posix_mem_offset( ) function shall return zero; otherwise, the 28292 corresponding error status value shall be returned. 28293 ERRORS 28294 The posix_mem_offset( ) function shall fail if: 28295 [EACCES] The process has not mapped a memory object supported by this function at 28296 the given address addr. 28297 This function shall not return an error code of [EINTR]. 28298 EXAMPLES 28299 None. 28300 APPLICATION USAGE 28301 None. 28302 RATIONALE 28303 None. 1350 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_mem_offset( ) 28304 FUTURE DIRECTIONS 28305 None. 28306 SEE ALSO 28307 mmap( ), posix_typed_mem_open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28308 28309 CHANGE HISTORY 28310 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. System Interfaces, Issue 6 1351 posix_memalign( ) System Interfaces 28311 NAME 28312 posix_memalign - aligned memory allocation (ADVANCED REALTIME) 28313 SYNOPSIS 28314 ADV #include 28315 int posix_memalign(void **memptr, size_t alignment, size_t size); 28316 28317 DESCRIPTION 28318 The posix_memalign( ) function shall allocate size bytes aligned on a boundary specified by 28319 alignment, and shall return a pointer to the allocated memory in memptr. The value of alignment 28320 shall be a multiple of sizeof(void *), that is also a power of two. Upon successful completion, the 28321 value pointed to by memptr shall be a multiple of alignment. 28322 CX The free( ) function shall deallocate memory that has previously been allocated by 28323 posix_memalign( ). 28324 RETURN VALUE 28325 Upon successful completion, posix_memalign( ) shall return zero; otherwise, an error number 28326 shall be returned to indicate the error. 28327 ERRORS 28328 The posix_memalign( ) function shall fail if: 28329 [EINVAL] The value of the alignment parameter is not a power of two multiple of 28330 sizeof(void *). 28331 [ENOMEM] There is insufficient memory available with the requested alignment. 28332 EXAMPLES 28333 None. 28334 APPLICATION USAGE 28335 The posix_memalign( ) function is part of the Advisory Information option and need not be 28336 provided on all implementations. 28337 RATIONALE 28338 None. 28339 FUTURE DIRECTIONS 28340 None. 28341 SEE ALSO 28342 free( ), malloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28343 CHANGE HISTORY 28344 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28345 In the SYNOPSIS, the inclusion of is no longer required. 1352 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_openpt( ) 28346 NAME 28347 posix_openpt - open a pseudo terminal device 28348 SYNOPSIS 28349 XSI #include 28350 #include 28351 int posix_openpt(int oflag); 28352 28353 DESCRIPTION 28354 The posix_openpt( ) function shall establish a connection between a master device for a pseudo- 28355 terminal and a file descriptor. The file descriptor is used by other I/O functions that refer to that 28356 pseudo-terminal. 28357 The file status flags and file access modes of the open file description shall be set according to 28358 the value of oflag. 28359 Values for oflag are constructed by a bitwise-inclusive OR of flags from the following list, 28360 defined in : 28361 O_RDWR Open for reading and writing. 28362 O_NOCTTY If set posix_openpt( ) shall not cause the terminal device to become the 28363 controlling terminal for the process. 28364 The behavior of other values for the oflag argument is unspecified. 28365 RETURN VALUE 28366 Upon successful completion, the posix_openpt( ) function shall open a master pseudo-terminal 28367 device and return a non-negative integer representing the lowest numbered unused file 28368 descriptor. Otherwise, -1 shall be returned and errno set to indicate the error. 28369 ERRORS 28370 The posix_openpt( ) function shall fail if: 28371 [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 28372 [ENFILE] The maximum allowable number of files is currently open in the system. 28373 The posix_openpt( ) function may fail if: 28374 [EINVAL] The value of oflag is not valid. 28375 [EAGAIN] Out of pseudo-terminal resources. 28376 XSR [ENOSR] Out of STREAMS resources. 28377 EXAMPLES 28378 Opening a Pseudo-Terminal and Returning the Name of the Slave Device and a File 28379 Descriptor 28380 #include 28381 #include 28382 int masterfd, slavefd; 28383 char *slavedevice; 28384 masterfd = posix_openpt(O_RDWR|O_NOCTTY); 28385 if (masterfd == -1 28386 || grantpt (masterfd) == -1 System Interfaces, Issue 6 1353 posix_openpt( ) System Interfaces 28387 || unlockpt (masterfd) == -1 28388 || (slavedevice = ptsname (masterfd)) == NULL) 28389 return -1; 28390 printf("slave device is: %s\n", slavedevice); 28391 slavefd = open(slave, O_RDWR|O_NOCTTY); 28392 if (slavefd < 0) 28393 return -1; 28394 APPLICATION USAGE 28395 This function is a method for portably obtaining a file descriptor of a master terminal device for 28396 a pseudo-terminal. The grantpt( ) and ptsname( ) functions can be used to manipulate mode and 28397 ownership permissions, and to obtain the name of the slave device, respectively. 28398 RATIONALE 28399 The standard developers considered the matter of adding a special device for cloning master 28400 pseudo-terminals: the /dev/ptmx device. However, consensus could not be reached, and it was 28401 felt that adding a new function would permit other implementations. The posix_openpt( ) 28402 function is designed to complement the grantpt( ), ptsname( ), and unlockpt( ) functions. 28403 On implementations supporting the /dev/ptmx clone device, opening the master device of a 28404 pseudo-terminal is simply: 28405 mfdp = open("/dev/ptmx", oflag ); 28406 if (mfdp < 0) 28407 return -1; 28408 FUTURE DIRECTIONS 28409 None. 28410 SEE ALSO 28411 grantpt( ), open( ), ptsname( ), unlockpt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28412 28413 CHANGE HISTORY 28414 First released in Issue 6. 1354 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn( ) 28415 NAME 28416 posix_spawn, posix_spawnp - spawn a process (ADVANCED REALTIME) 28417 SYNOPSIS 28418 SPN #include 28419 int posix_spawn(pid_t *restrict pid, const char *restrict path, 28420 const posix_spawn_file_actions_t *file_actions, 28421 const posix_spawnattr_t *restrict attrp, 28422 char *const argv[restrict], char *const envp[restrict]); 28423 int posix_spawnp(pid_t *restrict pid, const char *restrict file, 28424 const posix_spawn_file_actions_t *file_actions, 28425 const posix_spawnattr_t *restrict attrp, 28426 char *const argv[restrict], char * const envp[restrict]); 28427 28428 DESCRIPTION 28429 The posix_spawn( ) and posix_spawnp( ) functions shall create a new process (child process) from 28430 the specified process image. The new process image shall be constructed from a regular | 28431 executable file called the new process image file. 28432 When a C program is executed as the result of this call, it shall be entered as a C language 28433 function call as follows: 28434 int main(int argc, char *argv[]); 28435 where argc is the argument count and argv is an array of character pointers to the arguments 28436 themselves. In addition, the following variable: 28437 extern char **environ; 28438 shall be initialized as a pointer to an array of character pointers to the environment strings. | 28439 The argument argv is an array of character pointers to null-terminated strings. The last member 28440 of this array shall be a null pointer and is not counted in argc. These strings constitute the 28441 argument list available to the new process image. The value in argv[0] should point to a filename 28442 that is associated with the process image being started by the posix_spawn( ) or posix_spawnp( ) 28443 function. 28444 The argument envp is an array of character pointers to null-terminated strings. These strings 28445 constitute the environment for the new process image. The environment array is terminated by a 28446 null pointer. 28447 The number of bytes available for the child process' combined argument and environment lists 28448 is {ARG_MAX}. The implementation shall specify in the system documentation (see the Base 28449 Definitions volume of IEEE Std 1003.1-200x, Chapter 2, Conformance) whether any list 28450 overhead, such as length words, null terminators, pointers, or alignment bytes, is included in 28451 this total. 28452 The path argument to posix_spawn( ) is a pathname that identifies the new process image file to | 28453 execute. | 28454 The file parameter to posix_spawnp( ) shall be used to construct a pathname that identifies the | 28455 new process image file. If the file parameter contains a slash character, the file parameter shall be | 28456 used as the pathname for the new process image file. Otherwise, the path prefix for this file shall | 28457 be obtained by a search of the directories passed as the environment variable PATH (see the Base 28458 Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables). If this 28459 environment variable is not defined, the results of the search are implementation-defined. System Interfaces, Issue 6 1355 posix_spawn( ) System Interfaces 28460 If file_actions is a null pointer, then file descriptors open in the calling process shall remain open 28461 in the child process, except for those whose close-on-exec flag FD_CLOEXEC is set (see fcntl( )). 28462 For those file descriptors that remain open, all attributes of the corresponding open file 28463 descriptions, including file locks (see fcntl( )), shall remain unchanged. 28464 If file_actions is not NULL, then the file descriptors open in the child process shall be those open 28465 in the calling process as modified by the spawn file actions object pointed to by file_actions and 28466 the FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have 28467 been processed. The effective order of processing the spawn file actions shall be: 28468 1. The set of open file descriptors for the child process shall initially be the same set as is 28469 open for the calling process. All attributes of the corresponding open file descriptions, 28470 including file locks (see fcntl( )), shall remain unchanged. 28471 2. The signal mask, signal default actions, and the effective user and group IDs for the child 28472 process shall be changed as specified in the attributes object referenced by attrp. 28473 3. The file actions specified by the spawn file actions object shall be performed in the order in 28474 which they were added to the spawn file actions object. 28475 4. Any file descriptor that has its FD_CLOEXEC flag set (see fcntl( )) shall be closed. 28476 The posix_spawnattr_t spawn attributes object type is defined in . It shall contain at | 28477 least the attributes defined below. 28478 If the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object 28479 referenced by attrp, and the spawn-pgroup attribute of the same object is non-zero, then the 28480 child's process group shall be as specified in the spawn-pgroup attribute of the object referenced 28481 by attrp. 28482 As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of 28483 the object referenced by attrp, and the spawn-pgroup attribute of the same object is set to zero, 28484 then the child shall be in a new process group with a process group ID equal to its process ID. 28485 If the POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object 28486 referenced by attrp, the new child process shall inherit the parent's process group. 28487 PS If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute of the object 28488 referenced by attrp, but POSIX_SPAWN_SETSCHEDULER is not set, the new process image 28489 shall initially have the scheduling policy of the calling process with the scheduling parameters 28490 specified in the spawn-schedparam attribute of the object referenced by attrp. 28491 If the POSIX_SPAWN_SETSCHEDULER flag is set in spawn-flags attribute of the object 28492 referenced by attrp (regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), 28493 the new process image shall initially have the scheduling policy specified in the spawn- 28494 schedpolicy attribute of the object referenced by attrp and the scheduling parameters specified in 28495 the spawn-schedparam attribute of the same object. 28496 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp | 28497 governs the effective user ID of the child process. If this flag is not set, the child process shall | 28498 inherit the parent process' effective user ID. If this flag is set, the child process' effective user ID | 28499 shall be reset to the parent's real user ID. In either case, if the set-user-ID mode bit of the new | 28500 process image file is set, the effective user ID of the child process shall become that file's owner | 28501 ID before the new process image begins execution. | 28502 The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 28503 also governs the effective group ID of the child process. If this flag is not set, the child process | 28504 shall inherit the parent process' effective group ID. If this flag is set, the child process' effective | 28505 group ID shall be reset to the parent's real group ID. In either case, if the set-group-ID mode bit | 1356 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn( ) 28506 of the new process image file is set, the effective group ID of the child process shall become that | 28507 file's group ID before the new process image begins execution. | 28508 If the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object 28509 referenced by attrp, the child process shall initially have the signal mask specified in the spawn- 28510 sigmask attribute of the object referenced by attrp. 28511 If the POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute of the object referenced 28512 by attrp, the signals specified in the spawn-sigdefault attribute of the same object shall be set to 28513 their default actions in the child process. Signals set to the default action in the parent process 28514 shall be set to the default action in the child process. 28515 Signals set to be caught by the calling process shall be set to the default action in the child 28516 process. 28517 Except for SIGCHLD, signals set to be ignored by the calling process image shall be set to be | 28518 ignored by the child process, unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag | 28519 being set in the spawn-flags attribute of the object referenced by attrp and the signals being | 28520 indicated in the spawn-sigdefault attribute of the object referenced by attrp. 28521 If the SIGCHLD signal is set to be ignored by the calling process, it is unspecified whether the | 28522 SIGCHLD signal is set to be ignored or to the default action in the child process, unless | 28523 otherwise specified by the POSIX_SPAWN_SETSIGDEF flag being set in the spawn_flags | 28524 attribute of the object referenced by attrp and the SIGCHLD signal being indicated in the | 28525 spawn_sigdefault attribute of the object referenced by attrp. | 28526 If the value of the attrp pointer is NULL, then the default values are used. | 28527 All process attributes, other than those influenced by the attributes set in the object referenced 28528 by attrp as specified above or by the file descriptor manipulations specified in file_actions , shall 28529 appear in the new process image as though fork( ) had been called to create a child process and 28530 then a member of the exec family of functions had been called by the child process to execute the 28531 new process image. 28532 THR It is implementation-defined whether the fork handlers are run when posix_spawn( ) or 28533 posix_spawnp( ) is called. 28534 RETURN VALUE 28535 Upon successful completion, posix_spawn( ) and posix_spawnp( ) shall return the process ID of the 28536 child process to the parent process, in the variable pointed to by a non-NULL pid argument, and 28537 shall return zero as the function return value. Otherwise, no child process shall be created, the 28538 value stored into the variable pointed to by a non-NULL pid is unspecified, and an error number 28539 shall be returned as the function return value to indicate the error. If the pid argument is a null 28540 pointer, the process ID of the child is not returned to the caller. 28541 ERRORS 28542 The posix_spawn( ) and posix_spawnp( ) functions may fail if: 28543 [EINVAL] The value specified by file_actions or attrp is invalid. 28544 If this error occurs after the calling process successfully returns from the posix_spawn( ) or 28545 posix_spawnp( ) function, the child process may exit with exit status 127. 28546 If posix_spawn( ) or posix_spawnp( ) fail for any of the reasons that would cause fork( ) or one of 28547 the exec family of functions to fail, an error value shall be returned as described by fork( ) and 28548 exec, respectively (or, if the error occurs after the calling process successfully returns, the child 28549 process shall exit with exit status 127). System Interfaces, Issue 6 1357 posix_spawn( ) System Interfaces 28550 If POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by 28551 attrp, and posix_spawn( ) or posix_spawnp( ) fails while changing the child's process group, an 28552 error value shall be returned as described by setpgid( ) (or, if the error occurs after the calling 28553 process successfully returns, the child process shall exit with exit status 127). 28554 PS If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not set 28555 in the spawn-flags attribute of the object referenced by attrp, then if posix_spawn( ) or 28556 posix_spawnp( ) fails for any of the reasons that would cause sched_setparam( ) to fail, an error 28557 value shall be returned as described by sched_setparam( ) (or, if the error occurs after the calling 28558 process successfully returns, the child process shall exit with exit status 127). 28559 If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by 28560 attrp, and if posix_spawn( ) or posix_spawnp( ) fails for any of the reasons that would cause 28561 sched_setscheduler( ) to fail, an error value shall be returned as described by sched_setscheduler( ) 28562 (or, if the error occurs after the calling process successfully returns, the child process shall exit 28563 with exit status 127). 28564 If the file_actions argument is not NULL, and specifies any close, dup2, or open actions to be 28565 performed, and if posix_spawn( ) or posix_spawnp( ) fails for any of the reasons that would cause 28566 close( ), dup2( ), or open( ) to fail, an error value shall be returned as described by close( ), dup2( ), 28567 and open( ), respectively (or, if the error occurs after the calling process successfully returns, the 28568 child process shall exit with exit status 127). An open file action may, by itself, result in any of 28569 the errors described by close( ) or dup2( ), in addition to those described by open( ). 28570 EXAMPLES 28571 None. 28572 APPLICATION USAGE 28573 These functions are part of the Spawn option and need not be provided on all implementations. 28574 RATIONALE 28575 The posix_spawn( ) function and its close relation posix_spawnp( ) have been introduced to | 28576 overcome the following perceived difficulties with fork( ): the fork( ) function is difficult or | 28577 impossible to implement without swapping or dynamic address translation. | 28578 * Swapping is generally too slow for a realtime environment. 28579 * Dynamic address translation is not available everywhere that POSIX might be useful. | 28580 * Processes are too useful to simply option out of POSIX whenever it must run without 28581 address translation or other MMU services, 28582 Thus, POSIX needs process creation and file execution primitives that can be efficiently | 28583 implemented without address translation or other MMU services. | 28584 The posix_spawn( ) function is implementable as a library routine, but both posix_spawn( ) and | 28585 posix_spawnp( ) are designed as kernel operations. Also, although they may be an efficient 28586 replacement for many fork( )/exec pairs, their goal is to provide useful process creation 28587 primitives for systems that have difficulty with fork( ), not to provide drop-in replacements for 28588 fork( )/exec. 28589 This view of the role of posix_spawn( ) and posix_spawnp( ) influenced the design of their API. It 28590 does not attempt to provide the full functionality of fork( )/exec in which arbitrary user-specified 28591 operations of any sort are permitted between the creation of the child process and the execution 28592 of the new process image; any attempt to reach that level would need to provide a programming 28593 language as parameters. Instead, posix_spawn( ) and posix_spawnp( ) are process creation 28594 primitives like the Start_Process and Start_Process_Search Ada language bindings package 28595 POSIX_Process_Primitives and also like those in many operating systems that are not UNIX 1358 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn( ) 28596 systems, but with some POSIX-specific additions. 28597 To achieve its coverage goals, posix_spawn( ) and posix_spawnp( ) have control of six types of 28598 inheritance: file descriptors, process group ID, user and group ID, signal mask, scheduling, and 28599 whether each signal ignored in the parent will remain ignored in the child, or be reset to its 28600 default action in the child. 28601 Control of file descriptors is required to allow an independently written child process image to 28602 access data streams opened by and even generated or read by the parent process without being 28603 specifically coded to know which parent files and file descriptors are to be used. Control of the 28604 process group ID is required to control how the child process' job control relates to that of the 28605 parent. 28606 Control of the signal mask and signal defaulting is sufficient to support the implementation of 28607 system( ). Although support for system( ) is not explicitly one of the goals for posix_spawn( ) and 28608 posix_spawnp( ), it is covered under the ``at least 50%'' coverage goal. 28609 The intention is that the normal file descriptor inheritance across fork( ), the subsequent effect of 28610 the specified spawn file actions, and the normal file descriptor inheritance across one of the exec 28611 family of functions should fully specify open file inheritance. The implementation need make no 28612 decisions regarding the set of open file descriptors when the child process image begins 28613 execution, those decisions having already been made by the caller and expressed as the set of 28614 open file descriptors and their FD_CLOEXEC flags at the time of the call and the spawn file 28615 actions object specified in the call. We have been assured that in cases where the POSIX 28616 Start_Process Ada primitives have been implemented in a library, this method of controlling file 28617 descriptor inheritance may be implemented very easily. 28618 We can identify several problems with posix_spawn( ) and posix_spawnp( ), but there does not 28619 appear to be a solution that introduces fewer problems. Environment modification for child 28620 process attributes not specifiable via the attrp or file_actions arguments must be done in the 28621 parent process, and since the parent generally wants to save its context, it is more costly than 28622 similar functionality with fork( )/exec. It is also complicated to modify the environment of a 28623 multi-threaded process temporarily, since all threads must agree when it is safe for the 28624 environment to be changed. However, this cost is only borne by those invocations of 28625 posix_spawn( ) and posix_spawnp( ) that use the additional functionality. Since extensive 28626 modifications are not the usual case, and are particularly unlikely in time-critical code, keeping 28627 much of the environment control out of posix_spawn( ) and posix_spawnp( ) is appropriate design. 28628 The posix_spawn( ) and posix_spawnp( ) functions do not have all the power of fork( )/exec. This is 28629 to be expected. The fork( ) function is a wonderfully powerful operation. We do not expect to 28630 duplicate its functionality in a simple, fast function with no special hardware requirements. It is 28631 worth noting that posix_spawn( ) and posix_spawnp( ) are very similar to the process creation 28632 operations on many operating systems that are not UNIX systems. 28633 Requirements 28634 The requirements for posix_spawn( ) and posix_spawnp( ) are: 28635 * They must be implementable without an MMU or unusual hardware. 28636 * They must be compatible with existing POSIX standards. 28637 Additional goals are: 28638 * They should be efficiently implementable. 28639 * They should be able to replace at least 50% of typical executions of fork( ). System Interfaces, Issue 6 1359 posix_spawn( ) System Interfaces 28640 * A system with posix_spawn( ) and posix_spawnp( ) and without fork( ) should be useful, at least 28641 for realtime applications. 28642 * A system with fork( ) and the exec family should be able to implement posix_spawn( ) and 28643 posix_spawnp( ) as library routines. 28644 Two-Syntax 28645 POSIX exec has several calling sequences with approximately the same functionality. These 28646 appear to be required for compatibility with existing practice. Since the existing practice for the 28647 posix_spawn*( ) functions is otherwise substantially unlike POSIX, we feel that simplicity 28648 outweighs compatibility. There are, therefore, only two names for the posix_spawn*( ) functions. 28649 The parameter list does not differ between posix_spawn( ) and posix_spawnp( ); posix_spawnp( ) 28650 interprets the second parameter more elaborately than posix_spawn( ). 28651 Compatibility with POSIX.5 (Ada) 28652 The Start_Process and Start_Process_Search procedures from the POSIX_Process_Primitives 28653 package from the Ada language binding to POSIX.1 encapsulate fork( ) and exec functionality in a 28654 manner similar to that of posix_spawn( ) and posix_spawnp( ). Originally, in keeping with our 28655 simplicity goal, the standard developers had limited the capabilities of posix_spawn( ) and 28656 posix_spawnp( ) to a subset of the capabilities of Start_Process and Start_Process_Search; certain 28657 non-default capabilities were not supported. However, based on suggestions by the ballot group 28658 to improve file descriptor mapping or drop it, and on the advice of an Ada Language Bindings 28659 working group member, the standard developers decided that posix_spawn( ) and posix_spawnp( ) 28660 should be sufficiently powerful to implement Start_Process and Start_Process_Search. The 28661 rationale is that if the Ada language binding to such a primitive had already been approved as 28662 an IEEE standard, there can be little justification for not approving the functionally-equivalent 28663 parts of a C binding. The only three capabilities provided by posix_spawn( ) and posix_spawnp( ) 28664 that are not provided by Start_Process and Start_Process_Search are optionally specifying the 28665 child's process group ID, the set of signals to be reset to default signal handling in the child 28666 process, and the child's scheduling policy and parameters. 28667 For the Ada language binding for Start_Process to be implemented with posix_spawn( ), that 28668 binding would need to explicitly pass an empty signal mask and the parent's environment to 28669 posix_spawn( ) whenever the caller of Start_Process allowed these arguments to default, since 28670 posix_spawn( ) does not provide such defaults. The ability of Start_Process to mask user-specified 28671 signals during its execution is functionally unique to the Ada language binding and must be 28672 dealt with in the binding separately from the call to posix_spawn( ). 28673 Process Group 28674 The process group inheritance field can be used to join the child process with an existing process 28675 group. By assigning a value of zero to the spawn-pgroup attribute of the object referenced by 28676 attrp, the setpgid( ) mechanism will place the child process in a new process group. 1360 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn( ) 28677 Threads 28678 Without the posix_spawn( ) and posix_spawnp( ) functions, systems without address translation 28679 can still use threads to give an abstraction of concurrency. In many cases, thread creation 28680 suffices, but it is not always a good substitute. The posix_spawn( ) and posix_spawnp( ) functions 28681 are considerably ``heavier'' than thread creation. Processes have several important attributes that 28682 threads do not. Even without address translation, a process may have base-and-bound memory 28683 protection. Each process has a process environment including security attributes and file 28684 capabilities, and powerful scheduling attributes. Processes abstract the behavior of non- 28685 uniform-memory-architecture multi-processors better than threads, and they are more 28686 convenient to use for activities that are not closely linked. 28687 The posix_spawn( ) and posix_spawnp( ) functions may not bring support for multiple processes to 28688 every configuration. Process creation is not the only piece of operating system support required 28689 to support multiple processes. The total cost of support for multiple processes may be quite high 28690 in some circumstances. Existing practice shows that support for multiple processes is 28691 uncommon and threads are common among ``tiny kernels''. There should, therefore, probably 28692 continue to be AEPs for operating systems with only one process. 28693 Asynchronous Error Notification 28694 A library implementation of posix_spawn( ) or posix_spawnp( ) may not be able to detect all 28695 possible errors before it forks the child process. IEEE Std 1003.1-200x provides for an error 28696 indication returned from a child process which could not successfully complete the spawn 28697 operation via a special exit status which may be detected using the status value returned by 28698 wait( ) and waitpid( ). 28699 The stat_val interface and the macros used to interpret it are not well suited to the purpose of 28700 returning API errors, but they are the only path available to a library implementation. Thus, an 28701 implementation may cause the child process to exit with exit status 127 for any error detected 28702 during the spawn process after the posix_spawn( ) or posix_spawnp( ) function has successfully 28703 returned. 28704 The standard developers had proposed using two additional macros to interpret stat_val. The 28705 first, WIFSPAWNFAIL, would have detected a status that indicated that the child exited because 28706 of an error detected during the posix_spawn( ) or posix_spawnp( ) operations rather than during 28707 actual execution of the child process image; the second, WSPAWNERRNO, would have 28708 extracted the error value if WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group 28709 strongly opposed this because it would make a library implementation of posix_spawn( ) or 28710 posix_spawnp( ) dependent on kernel modifications to waitpid( ) to be able to embed special 28711 information in stat_val to indicate a spawn failure. 28712 The 8 bits of child process exit status that are guaranteed by IEEE Std 1003.1-200x to be 28713 accessible to the waiting parent process are insufficient to disambiguate a spawn error from any 28714 other kind of error that may be returned by an arbitrary process image. No other bits of the exit 28715 status are required to be visible in stat_val, so these macros could not be strictly implemented at 28716 the library level. Reserving an exit status of 127 for such spawn errors is consistent with the use 28717 of this value by system( ) and popen( ) to signal failures in these operations that occur after the 28718 function has returned but before a shell is able to execute. The exit status of 127 does not 28719 uniquely identify this class of error, nor does it provide any detailed information on the nature 28720 of the failure. Note that a kernel implementation of posix_spawn( ) or posix_spawnp( ) is permitted 28721 (and encouraged) to return any possible error as the function value, thus providing more 28722 detailed failure information to the parent process. 28723 Thus, no special macros are available to isolate asynchronous posix_spawn( ) or posix_spawnp( ) 28724 errors. Instead, errors detected by the posix_spawn( ) or posix_spawnp( ) operations in the context System Interfaces, Issue 6 1361 posix_spawn( ) System Interfaces 28725 of the child process before the new process image executes are reported by setting the child's 28726 exit status to 127. The calling process may use the WIFEXITED and WEXITSTATUS macros on 28727 the stat_val stored by the wait( ) or waitpid( ) functions to detect spawn failures to the extent that 28728 other status values with which the child process image may exit (before the parent can 28729 conclusively determine that the child process image has begun execution) are distinct from exit 28730 status 127. 28731 FUTURE DIRECTIONS 28732 None. 28733 SEE ALSO 28734 alarm( ), chmod( ), close( ), dup( ), exec, exit( ), fcntl( ), fork( ), kill( ), open( ), 28735 posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_adddup2( ), 28736 posix_spawn_file_actions_addopen( ), posix_spawn_file_actions_destroy( ), 28737 posix_spawn_file_actions_init( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), 28738 posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), 28739 posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), posix_spawnattr_getsigmask( ), 28740 posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), 28741 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 28742 sched_setparam( ), sched_setscheduler( ), setpgid( ), setuid( ), stat( ), times( ), wait( ), the Base 28743 Definitions volume of IEEE Std 1003.1-200x, 28744 CHANGE HISTORY 28745 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28746 IEEE PASC Interpretation 1003.1 #103 is applied, noting that the signal default actions are | 28747 changed as well as the signal mask in step 2. | 28748 IEEE PASC Interpretation 1003.1 #132 is applied. | 1362 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn_file_actions_addclose( ) 28749 NAME 28750 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen - add close or open 28751 action to spawn file actions object (ADVANCED REALTIME) 28752 SYNOPSIS 28753 SPN #include 28754 int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t * 28755 file_actions, int fildes); 28756 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict 28757 file_actions, int fildes, const char *restrict path, 28758 int oflag, mode_t mode); 28759 28760 DESCRIPTION 28761 These functions shall add or delete a close or open action to a spawn file actions object. | 28762 A spawn file actions object is of type posix_spawn_file_actions_t (defined in ) and is | 28763 used to specify a series of actions to be performed by a posix_spawn( ) or posix_spawnp( ) 28764 operation in order to arrive at the set of open file descriptors for the child process given the set of 28765 open file descriptors of the parent. IEEE Std 1003.1-200x does not define comparison or 28766 assignment operators for the type posix_spawn_file_actions_t. 28767 A spawn file actions object, when passed to posix_spawn( ) or posix_spawnp( ), shall specify how 28768 the set of open file descriptors in the calling process is transformed into a set of potentially open 28769 file descriptors for the spawned process. This transformation shall be as if the specified sequence 28770 of actions was performed exactly once, in the context of the spawned process (prior to execution 28771 of the new process image), in the order in which the actions were added to the object; 28772 additionally, when the new process image is executed, any file descriptor (from this new set) 28773 which has its FD_CLOEXEC flag set shall be closed (see posix_spawn( )). | 28774 The posix_spawn_file_actions_addclose( ) function shall add a close action to the object referenced | 28775 by file_actions that shall cause the file descriptor fildes to be closed (as if close(fildes) had been | 28776 called) when a new process is spawned using this file actions object. 28777 The posix_spawn_file_actions_addopen( ) function shall add an open action to the object referenced | 28778 by file_actions that shall cause the file named by path to be opened (as if open(path, oflag, mode) | 28779 had been called, and the returned file descriptor, if not fildes, had been changed to fildes) when a 28780 new process is spawned using this file actions object. If fildes was already an open file descriptor, 28781 it shall be closed before the new file is opened. 28782 The string described by path shall be copied by the posix_spawn_file_actions_addopen( ) function. | 28783 RETURN VALUE 28784 Upon successful completion, these functions shall return zero; otherwise, an error number shall 28785 be returned to indicate the error. 28786 ERRORS 28787 These functions shall fail if: 28788 [EBADF] The value specified by fildes is negative or greater than or equal to 28789 {OPEN_MAX}. 28790 These functions may fail if: 28791 [EINVAL] The value specified by file_actions is invalid. 28792 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. System Interfaces, Issue 6 1363 posix_spawn_file_actions_addclose( ) System Interfaces 28793 It shall not be considered an error for the fildes argument passed to these functions to specify a 28794 file descriptor for which the specified operation could not be performed at the time of the call. 28795 Any such error will be detected when the associated file actions object is later used during a 28796 posix_spawn( ) or posix_spawnp( ) operation. 28797 EXAMPLES 28798 None. 28799 APPLICATION USAGE 28800 These functions are part of the Spawn option and need not be provided on all implementations. 28801 RATIONALE 28802 A spawn file actions object may be initialized to contain an ordered sequence of close( ), dup2( ), 28803 and open( ) operations to be used by posix_spawn( ) or posix_spawnp( ) to arrive at the set of open 28804 file descriptors inherited by the spawned process from the set of open file descriptors in the 28805 parent at the time of the posix_spawn( ) or posix_spawnp( ) call. It had been suggested that the 28806 close( ) and dup2( ) operations alone are sufficient to rearrange file descriptors, and that files 28807 which need to be opened for use by the spawned process can be handled either by having the 28808 calling process open them before the posix_spawn( ) or posix_spawnp( ) call (and close them after), 28809 or by passing filenames to the spawned process (in argv) so that it may open them itself. The 28810 standard developers recommend that applications use one of these two methods when practical, 28811 since detailed error status on a failed open operation is always available to the application this 28812 way. However, the standard developers feel that allowing a spawn file actions object to specify 28813 open operations is still appropriate because: 28814 1. It is consistent with equivalent POSIX.5 (Ada) functionality. 28815 2. It supports the I/O redirection paradigm commonly employed by POSIX programs 28816 designed to be invoked from a shell. When such a program is the child process, it may not 28817 be designed to open files on its own. 28818 3. It allows file opens that might otherwise fail or violate file ownership/access rights if 28819 executed by the parent process. 28820 Regarding 2. above, note that the spawn open file action provides to posix_spawn( ) and 28821 posix_spawnp( ) the same capability that the shell redirection operators provide to system( ), only 28822 without the intervening execution of a shell; for example: 28823 system ("myprog 28855 CHANGE HISTORY 28856 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28857 IEEE PASC Interpretation 1003.1 #105 is applied, adding a note to the DESCRIPTION that the 28858 string pointed to by path is copied by the posix_spawn_file_actions_addopen( ) function. System Interfaces, Issue 6 1365 posix_spawn_file_actions_adddup2( ) System Interfaces 28859 NAME 28860 posix_spawn_file_actions_adddup2 - add dup2 action to spawn file actions object 28861 (ADVANCED REALTIME) 28862 SYNOPSIS 28863 SPN #include 28864 int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t * 28865 file_actions, int fildes, int newfildes); 28866 28867 DESCRIPTION 28868 The posix_spawn_file_actions_adddup2( ) function shall add a dup2( ) action to the object | 28869 referenced by file_actions that shall cause the file descriptor fildes to be duplicated as newfildes (as | 28870 if dup2(fildes, newfildes) had been called) when a new process is spawned using this file actions 28871 object. | 28872 A spawn file actions object is as defined in posix_spawn_file_actions_addclose( ). | 28873 RETURN VALUE 28874 Upon successful completion, the posix_spawn_file_actions_adddup2( ) function shall return zero; 28875 otherwise, an error number shall be returned to indicate the error. 28876 ERRORS 28877 The posix_spawn_file_actions_adddup2( ) function shall fail if: 28878 [EBADF] The value specified by fildes or newfildes is negative or greater than or equal to 28879 {OPEN_MAX}. 28880 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. 28881 The posix_spawn_file_actions_adddup2( ) function may fail if: 28882 [EINVAL] The value specified by file_actions is invalid. 28883 It shall not be considered an error for the fildes argument passed to the 28884 posix_spawn_file_actions_adddup2( ) function to specify a file descriptor for which the specified 28885 operation could not be performed at the time of the call. Any such error will be detected when 28886 the associated file actions object is later used during a posix_spawn( ) or posix_spawnp( ) 28887 operation. 28888 EXAMPLES 28889 None. 28890 APPLICATION USAGE 28891 The posix_spawn_file_actions_adddup2( ) function is part of the Spawn option and need not be 28892 provided on all implementations. 28893 RATIONALE 28894 Refer to the RATIONALE in posix_spawn_file_actions_addclose( ). 28895 FUTURE DIRECTIONS 28896 None. 28897 SEE ALSO 28898 dup( ), posix_spawn( ), posix_spawn_file_actions_addclose( ), posix_spawn_file_actions_destroy( ), 28899 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1366 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn_file_actions_adddup2( ) 28900 CHANGE HISTORY 28901 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28902 IEEE PASC Interpretation 1003.1 #104 is applied, noting that the [EBADF] error can apply to the | 28903 newfildes argument in addition to fildes. System Interfaces, Issue 6 1367 posix_spawn_file_actions_addopen( ) System Interfaces 28904 NAME 28905 posix_spawn_file_actions_addopen - add open action to spawn file actions object 28906 (ADVANCED REALTIME) 28907 SYNOPSIS 28908 SPN #include 28909 int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict 28910 file_actions, int fildes, const char *restrict path, 28911 int oflag, mode_t mode); 28912 28913 DESCRIPTION 28914 Refer to posix_spawn_file_actions_addclose( ). 1368 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawn_file_actions_destroy( ) 28915 NAME 28916 posix_spawn_file_actions_destroy, posix_spawn_file_actions_init - destroy and initialize 28917 spawn file actions object (ADVANCED REALTIME) 28918 SYNOPSIS 28919 SPN #include 28920 int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t * 28921 file_actions); 28922 int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 28923 file_actions); 28924 28925 DESCRIPTION 28926 The posix_spawn_file_actions_destroy( ) function shall destroy the object referenced by file_actions; | 28927 the object becomes, in effect, uninitialized. An implementation may cause 28928 posix_spawn_file_actions_destroy( ) to set the object referenced by file_actions to an invalid value. A 28929 destroyed spawn file actions object can be reinitialized using posix_spawn_file_actions_init( ); the 28930 results of otherwise referencing the object after it has been destroyed are undefined. 28931 The posix_spawn_file_actions_init( ) function shall initialize the object referenced by file_actions to 28932 contain no file actions for posix_spawn( ) or posix_spawnp( ) to perform. 28933 A spawn file actions object is as defined in posix_spawn_file_actions_addclose( ). | 28934 The effect of initializing an already initialized spawn file actions object is undefined. | 28935 RETURN VALUE 28936 Upon successful completion, these functions shall return zero; otherwise, an error number shall 28937 be returned to indicate the error. 28938 ERRORS 28939 The posix_spawn_file_actions_init( ) function shall fail if: 28940 [ENOMEM] Insufficient memory exists to initialize the spawn file actions object. 28941 The posix_spawn_file_actions_destroy( ) function may fail if: 28942 [EINVAL] The value specified by file_actions is invalid. 28943 EXAMPLES 28944 None. 28945 APPLICATION USAGE 28946 These functions are part of the Spawn option and need not be provided on all implementations. 28947 RATIONALE 28948 Refer to the RATIONALE in posix_spawn_file_actions_addclose( ). 28949 FUTURE DIRECTIONS 28950 None. 28951 SEE ALSO 28952 posix_spawn( ), posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 28953 CHANGE HISTORY 28954 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 28955 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1369 posix_spawn_file_actions_init( ) System Interfaces 28956 NAME 28957 posix_spawn_file_actions_init - initialize spawn file actions object (ADVANCED REALTIME) 28958 SYNOPSIS 28959 SPN #include 28960 int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 28961 file_actions); 28962 28963 DESCRIPTION 28964 Refer to posix_spawn_file_actions_destroy( ). 1370 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_destroy( ) 28965 NAME 28966 posix_spawnattr_destroy, posix_spawnattr_init - destroy and initialize spawn attributes object 28967 (ADVANCED REALTIME) 28968 SYNOPSIS 28969 SPN #include 28970 int posix_spawnattr_destroy(posix_spawnattr_t *attr); 28971 int posix_spawnattr_init(posix_spawnattr_t *attr); 28972 28973 DESCRIPTION 28974 The posix_spawnattr_destroy( ) function shall destroy a spawn attributes object. A destroyed attr | 28975 attributes object can be reinitialized using posix_spawnattr_init( ); the results of otherwise | 28976 referencing the object after it has been destroyed are undefined. An implementation may cause | 28977 posix_spawnattr_destroy( ) to set the object referenced by attr to an invalid value. 28978 The posix_spawnattr_init( ) function shall initialize a spawn attributes object attr with the default 28979 value for all of the individual attributes used by the implementation. Results are undefined if | 28980 posix_spawnattr_init( ) is called specifying an already initialized attr attributes object. | 28981 A spawn attributes object is of type posix_spawnattr_t (defined in ) and is used to | 28982 specify the inheritance of process attributes across a spawn operation. IEEE Std 1003.1-200x does | 28983 not define comparison or assignment operators for the type posix_spawnattr_t. | 28984 Each implementation shall document the individual attributes it uses and their default values | 28985 unless these values are defined by IEEE Std 1003.1-200x. Attributes not defined by 28986 IEEE Std 1003.1-200x, their default values, and the names of the associated functions to get and 28987 set those attribute values are implementation-defined. 28988 The resulting spawn attributes object (possibly modified by setting individual attribute values), 28989 is used to modify the behavior of posix_spawn( ) or posix_spawnp( ). After a spawn attributes 28990 object has been used to spawn a process by a call to a posix_spawn( ) or posix_spawnp( ), any 28991 function affecting the attributes object (including destruction) shall not affect any process that | 28992 has been spawned in this way. | 28993 RETURN VALUE 28994 Upon successful completion, posix_spawnattr_destroy( ) and posix_spawnattr_init( ) shall return 28995 zero; otherwise, an error number shall be returned to indicate the error. 28996 ERRORS 28997 The posix_spawnattr_init( ) function shall fail if: 28998 [ENOMEM] Insufficient memory exists to initialize the spawn attributes object. 28999 The posix_spawnattr_destroy( ) function may fail if: 29000 [EINVAL] The value specified by attr is invalid. 29001 EXAMPLES 29002 None. 29003 APPLICATION USAGE 29004 These functions are part of the Spawn option and need not be provided on all implementations. 29005 RATIONALE 29006 The original spawn interface proposed in IEEE Std 1003.1-200x defined the attributes that specify 29007 the inheritance of process attributes across a spawn operation as a structure. In order to be able 29008 to separate optional individual attributes under their appropriate options (that is, the spawn- 29009 schedparam and spawn-schedpolicy attributes depending upon the Process Scheduling option), and System Interfaces, Issue 6 1371 posix_spawnattr_destroy( ) System Interfaces 29010 also for extensibility and consistency with the newer POSIX interfaces, the attributes interface 29011 has been changed to an opaque data type. This interface now consists of the type 29012 posix_spawnattr_t, representing a spawn attributes object, together with associated functions to 29013 initialize or destroy the attributes object, and to set or get each individual attribute. Although the 29014 new object-oriented interface is more verbose than the original structure, it is simple to use, 29015 more extensible, and easy to implement. 29016 FUTURE DIRECTIONS 29017 None. 29018 SEE ALSO 29019 posix_spawn( ), posix_spawnattr_getsigdefault( ), posix_spawnattr_getflags( ), 29020 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29021 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), 29022 posix_spawnattr_setpgroup( ), posix_spawnattr_setsigmask( ), posix_spawnattr_setschedpolicy( ), 29023 posix_spawnattr_setschedparam( ), posix_spawnp( ), the Base Definitions volume of 29024 IEEE Std 1003.1-200x, 29025 CHANGE HISTORY 29026 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 29027 IEEE PASC Interpretation 1003.1 #106 is applied, noting that the effect of initializing an already | 29028 initialized spawn attributes option is undefined. 1372 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getflags( ) 29029 NAME 29030 posix_spawnattr_getflags, posix_spawnattr_setflags - get and set spawn-flags attribute of 29031 spawn attributes object (ADVANCED REALTIME) 29032 SYNOPSIS 29033 SPN #include 29034 int posix_spawnattr_getflags(const posix_spawnattr_t *restrict attr, 29035 short *restrict flags); 29036 int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags); 29037 29038 DESCRIPTION 29039 The posix_spawnattr_getflags( ) function shall obtain the value of the spawn-flags attribute from | 29040 the attributes object referenced by attr. | 29041 The posix_spawnattr_setflags( ) function shall set the spawn-flags attribute in an initialized | 29042 attributes object referenced by attr. | 29043 The spawn-flags attribute is used to indicate which process attributes are to be changed in the | 29044 new process image when invoking posix_spawn( ) or posix_spawnp( ). It is the bitwise-inclusive 29045 OR of zero or more of the following flags: 29046 POSIX_SPAWN_RESETIDS 29047 POSIX_SPAWN_SETPGROUP 29048 POSIX_SPAWN_SETSIGDEF 29049 POSIX_SPAWN_SETSIGMASK 29050 PS POSIX_SPAWN_SETSCHEDPARAM 29051 POSIX_SPAWN_SETSCHEDULER 29052 29053 These flags are defined in . The default value of this attribute shall be as if no flags | 29054 were set. | 29055 RETURN VALUE 29056 Upon successful completion, posix_spawnattr_getflags( ) shall return zero and store the value of 29057 the spawn-flags attribute of attr into the object referenced by the flags parameter; otherwise, an 29058 error number shall be returned to indicate the error. 29059 Upon successful completion, posix_spawnattr_setflags( ) shall return zero; otherwise, an error 29060 number shall be returned to indicate the error. 29061 ERRORS 29062 These functions may fail if: 29063 [EINVAL] The value specified by attr is invalid. 29064 The posix_spawnattr_setflags( ) function may fail if: 29065 [EINVAL] The value of the attribute being set is not valid. System Interfaces, Issue 6 1373 posix_spawnattr_getflags( ) System Interfaces 29066 EXAMPLES 29067 None. 29068 APPLICATION USAGE 29069 These functions are part of the Spawn option and need not be provided on all implementations. 29070 RATIONALE 29071 None. 29072 FUTURE DIRECTIONS 29073 None. 29074 SEE ALSO 29075 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), 29076 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29077 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setpgroup( ), 29078 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29079 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 29080 CHANGE HISTORY 29081 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1374 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getpgroup( ) 29082 NAME 29083 posix_spawnattr_getpgroup, posix_spawnattr_setpgroup - get and set spawn-pgroup attribute 29084 of spawn attributes object (ADVANCED REALTIME) 29085 SYNOPSIS 29086 SPN #include 29087 int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict attr, 29088 pid_t *restrict pgroup); 29089 int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup); 29090 29091 DESCRIPTION 29092 The posix_spawnattr_getpgroup( ) function shall obtain the value of the spawn-pgroup attribute | 29093 from the attributes object referenced by attr. 29094 The posix_spawnattr_setpgroup( ) function shall set the spawn-pgroup attribute in an initialized | 29095 attributes object referenced by attr. | 29096 The spawn-pgroup attribute represents the process group to be joined by the new process image | 29097 in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute). The | 29098 default value of this attribute shall be zero. | 29099 RETURN VALUE 29100 Upon successful completion, posix_spawnattr_getpgroup( ) shall return zero and store the value of 29101 the spawn-pgroup attribute of attr into the object referenced by the pgroup parameter; otherwise, 29102 an error number shall be returned to indicate the error. 29103 Upon successful completion, posix_spawnattr_setpgroup( ) shall return zero; otherwise, an error 29104 number shall be returned to indicate the error. 29105 ERRORS 29106 These functions may fail if: 29107 [EINVAL] The value specified by attr is invalid. 29108 The posix_spawnattr_setpgroup( ) function may fail if: 29109 [EINVAL] The value of the attribute being set is not valid. 29110 EXAMPLES 29111 None. 29112 APPLICATION USAGE 29113 These functions are part of the Spawn option and need not be provided on all implementations. 29114 RATIONALE 29115 None. 29116 FUTURE DIRECTIONS 29117 None. 29118 SEE ALSO 29119 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), 29120 posix_spawnattr_getflags( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29121 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), 29122 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29123 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1375 posix_spawnattr_getpgroup( ) System Interfaces 29124 CHANGE HISTORY 29125 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1376 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getschedparam( ) 29126 NAME 29127 posix_spawnattr_getschedparam, posix_spawnattr_setschedparam - get and set spawn- 29128 schedparam attribute of spawn attributes object (ADVANCED REALTIME) 29129 SYNOPSIS 29130 SPN PS #include 29131 #include 29132 int posix_spawnattr_getschedparam( 29133 const posix_spawnattr_t *restrict attr, 29134 struct sched_param *restrict schedparam); 29135 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict attr, 29136 const struct sched_param *restrict schedparam); 29137 29138 DESCRIPTION 29139 The posix_spawnattr_getschedparam( ) function shall obtain the value of the spawn-schedparam | 29140 attribute from the attributes object referenced by attr. 29141 The posix_spawnattr_setschedparam( ) function shall set the spawn-schedparam attribute in an | 29142 initialized attributes object referenced by attr. | 29143 The spawn-schedparam attribute represents the scheduling parameters to be assigned to the new | 29144 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or | 29145 POSIX_SPAWN_SETSCHEDPARAM is set in the spawn-flags attribute). The default value of this | 29146 attribute is unspecified. | 29147 RETURN VALUE 29148 Upon successful completion, posix_spawnattr_getschedparam( ) shall return zero and store the 29149 value of the spawn-schedparam attribute of attr into the object referenced by the schedparam 29150 parameter; otherwise, an error number shall be returned to indicate the error. 29151 Upon successful completion, posix_spawnattr_setschedparam( ) shall return zero; otherwise, an 29152 error number shall be returned to indicate the error. 29153 ERRORS 29154 These functions may fail if: 29155 [EINVAL] The value specified by attr is invalid. 29156 The posix_spawnattr_setschedparam( ) function may fail if: 29157 [EINVAL] The value of the attribute being set is not valid. 29158 EXAMPLES 29159 None. 29160 APPLICATION USAGE 29161 These functions are part of the Spawn and Process Scheduling options and need not be provided 29162 on all implementations. 29163 RATIONALE 29164 None. 29165 FUTURE DIRECTIONS 29166 None. System Interfaces, Issue 6 1377 posix_spawnattr_getschedparam( ) System Interfaces 29167 SEE ALSO 29168 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), 29169 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedpolicy( ), 29170 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), 29171 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 29172 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 29173 CHANGE HISTORY 29174 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1378 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getschedpolicy( ) 29175 NAME 29176 posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy - get and set spawn- 29177 schedpolicy attribute of spawn attributes object (ADVANCED REALTIME) 29178 SYNOPSIS 29179 SPN PS #include 29180 #include 29181 int posix_spawnattr_getschedpolicy( 29182 const posix_spawnattr_t *restrict attr, 29183 int *restrict schedpolicy); 29184 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, 29185 int schedpolicy); 29186 29187 DESCRIPTION 29188 The posix_spawnattr_getschedpolicy( ) function shall obtain the value of the spawn-schedpolicy | 29189 attribute from the attributes object referenced by attr. 29190 The posix_spawnattr_setschedpolicy( ) function shall set the spawn-schedpolicy attribute in an | 29191 initialized attributes object referenced by attr. | 29192 The spawn-schedpolicy attribute represents the scheduling policy to be assigned to the new | 29193 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set in the spawn- | 29194 flags attribute). The default value of this attribute is unspecified. | 29195 RETURN VALUE 29196 Upon successful completion, posix_spawnattr_getschedpolicy( ) shall return zero and store the 29197 value of the spawn-schedpolicy attribute of attr into the object referenced by the schedpolicy 29198 parameter; otherwise, an error number shall be returned to indicate the error. 29199 Upon successful completion, posix_spawnattr_setschedpolicy( ) shall return zero; otherwise, an 29200 error number shall be returned to indicate the error. 29201 ERRORS 29202 These functions may fail if: 29203 [EINVAL] The value specified by attr is invalid. 29204 The posix_spawnattr_setschedpolicy( ) function may fail if: 29205 [EINVAL] The value of the attribute being set is not valid. 29206 EXAMPLES 29207 None. 29208 APPLICATION USAGE 29209 These functions are part of the Spawn and Process Scheduling options and need not be provided 29210 on all implementations. 29211 RATIONALE 29212 None. 29213 FUTURE DIRECTIONS 29214 None. 29215 SEE ALSO 29216 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), 29217 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 29218 posix_spawnattr_getsigmask( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), System Interfaces, Issue 6 1379 posix_spawnattr_getschedpolicy( ) System Interfaces 29219 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setsigmask( ), 29220 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 29221 CHANGE HISTORY 29222 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1380 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getsigdefault( ) 29223 NAME 29224 posix_spawnattr_getsigdefault, posix_spawnattr_setsigdefault - get and set spawn-sigdefault 29225 attribute of spawn attributes object (ADVANCED REALTIME) 29226 SYNOPSIS 29227 SPN #include 29228 #include 29229 int posix_spawnattr_getsigdefault( 29230 const posix_spawnattr_t *restrict attr, 29231 sigset_t *restrict sigdefault); 29232 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict attr, 29233 const sigset_t *restrict sigdefault); 29234 29235 DESCRIPTION 29236 The posix_spawnattr_getsigdefault( ) function shall obtain the value of the spawn-sigdefault | 29237 attribute from the attributes object referenced by attr. 29238 The posix_spawnattr_setsigdefault( ) function shall set the spawn-sigdefault attribute in an | 29239 initialized attributes object referenced by attr. | 29240 The spawn-sigdefault attribute represents the set of signals to be forced to default signal handling | 29241 in the new process image (if POSIX_SPAWN_SETSIGDEF is set in the spawn-flags attribute) by a | 29242 spawn operation. The default value of this attribute shall be an empty signal set. | 29243 RETURN VALUE 29244 Upon successful completion, posix_spawnattr_getsigdefault( ) shall return zero and store the value 29245 of the spawn-sigdefault attribute of attr into the object referenced by the sigdefault parameter; 29246 otherwise, an error number shall be returned to indicate the error. 29247 Upon successful completion, posix_spawnattr_setsigdefault( ) shall return zero; otherwise, an error 29248 number shall be returned to indicate the error. 29249 ERRORS 29250 These functions may fail if: 29251 [EINVAL] The value specified by attr is invalid. 29252 The posix_spawnattr_setsigdefault( ) function may fail if: 29253 [EINVAL] The value of the attribute being set is not valid. 29254 EXAMPLES 29255 None. 29256 APPLICATION USAGE 29257 These functions are part of the Spawn option and need not be provided on all implementations. 29258 RATIONALE 29259 None. 29260 FUTURE DIRECTIONS 29261 None. 29262 SEE ALSO 29263 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getflags( ), 29264 posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), posix_spawnattr_getschedpolicy( ), 29265 posix_spawnattr_getsigmask( ), posix_spawnattr_setflags( ), posix_spawnattr_setpgroup( ), 29266 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), System Interfaces, Issue 6 1381 posix_spawnattr_getsigdefault( ) System Interfaces 29267 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 29268 CHANGE HISTORY 29269 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1382 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_getsigmask( ) 29270 NAME 29271 posix_spawnattr_getsigmask, posix_spawnattr_setsigmask - get and set spawn-sigmask 29272 attribute of spawn attributes object (ADVANCED REALTIME) 29273 SYNOPSIS 29274 SPN #include 29275 #include 29276 int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict attr, 29277 sigset_t *restrict sigmask); 29278 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict attr, 29279 const sigset_t *restrict sigmask); 29280 29281 DESCRIPTION 29282 The posix_spawnattr_getsigmask( ) function shall obtain the value of the spawn-sigmask attribute | 29283 from the attributes object referenced by attr. 29284 The posix_spawnattr_setsigmask( ) function shall set the spawn-sigmask attribute in an initialized | 29285 attributes object referenced by attr. | 29286 The spawn-sigmask attribute represents the signal mask in effect in the new process image of a | 29287 spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the spawn-flags attribute). The | 29288 default value of this attribute is unspecified. | 29289 RETURN VALUE 29290 Upon successful completion, posix_spawnattr_getsigmask( ) shall return zero and store the value 29291 of the spawn-sigmask attribute of attr into the object referenced by the sigmask parameter; 29292 otherwise, an error number shall be returned to indicate the error. 29293 Upon successful completion, posix_spawnattr_setsigmask( ) shall return zero; otherwise, an error 29294 number shall be returned to indicate the error. 29295 ERRORS 29296 These functions may fail if: 29297 [EINVAL] The value specified by attr is invalid. 29298 The posix_spawnattr_setsigmask( ) function may fail if: 29299 [EINVAL] The value of the attribute being set is not valid. 29300 EXAMPLES 29301 None. 29302 APPLICATION USAGE 29303 These functions are part of the Spawn option and need not be provided on all implementations. 29304 RATIONALE 29305 None. 29306 FUTURE DIRECTIONS 29307 None. 29308 SEE ALSO 29309 posix_spawn( ), posix_spawnattr_destroy( ), posix_spawnattr_init( ), posix_spawnattr_getsigdefault( ), 29310 posix_spawnattr_getflags( ), posix_spawnattr_getpgroup( ), posix_spawnattr_getschedparam( ), 29311 posix_spawnattr_getschedpolicy( ), posix_spawnattr_setsigdefault( ), posix_spawnattr_setflags( ), 29312 posix_spawnattr_setpgroup( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), 29313 posix_spawnp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , System Interfaces, Issue 6 1383 posix_spawnattr_getsigmask( ) System Interfaces 29314 CHANGE HISTORY 29315 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1384 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_init( ) 29316 NAME 29317 posix_spawnattr_init - initialize spawn attributes object (ADVANCED REALTIME) 29318 SYNOPSIS 29319 SPN #include 29320 int posix_spawnattr_init(posix_spawnattr_t *attr); 29321 29322 DESCRIPTION 29323 Refer to posix_spawnattr_destroy( ). System Interfaces, Issue 6 1385 posix_spawnattr_setflags( ) System Interfaces 29324 NAME 29325 posix_spawnattr_setflags - set spawn-flags attribute of spawn attributes object (ADVANCED 29326 REALTIME) 29327 SYNOPSIS 29328 SPN #include 29329 int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags); 29330 29331 DESCRIPTION 29332 Refer to posix_spawnattr_getflags( ). 1386 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_setpgroup( ) 29333 NAME 29334 posix_spawnattr_setpgroup - set spawn-pgroup attribute of spawn attributes object 29335 (ADVANCED REALTIME) 29336 SYNOPSIS 29337 SPN #include 29338 int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup); 29339 29340 DESCRIPTION 29341 Refer to posix_spawnattr_getpgroup( ). System Interfaces, Issue 6 1387 posix_spawnattr_setschedparam( ) System Interfaces 29342 NAME 29343 posix_spawnattr_setschedparam - set spawn-schedparam attribute of spawn attributes object 29344 (ADVANCED REALTIME) 29345 SYNOPSIS 29346 SPN PS #include 29347 #include 29348 int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict attr, 29349 const struct sched_param *restrict schedparam); 29350 29351 DESCRIPTION 29352 Refer to posix_spawnattr_getschedparam( ). 1388 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_setschedpolicy( ) 29353 NAME 29354 posix_spawnattr_setschedpolicy - set spawn-schedpolicy attribute of spawn attributes object 29355 (ADVANCED REALTIME) 29356 SYNOPSIS 29357 SPN PS #include 29358 #include 29359 int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, 29360 int schedpolicy); 29361 29362 DESCRIPTION 29363 Refer to posix_spawnattr_getschedpolicy( ). System Interfaces, Issue 6 1389 posix_spawnattr_setsigdefault( ) System Interfaces 29364 NAME 29365 posix_spawnattr_setsigdefault - set spawn-sigdefault attribute of spawn attributes object 29366 (ADVANCED REALTIME) 29367 SYNOPSIS 29368 SPN #include 29369 #include 29370 int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict attr, 29371 const sigset_t *restrict sigdefault); 29372 29373 DESCRIPTION 29374 Refer to posix_spawnattr_getsigdefault( ). 1390 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_spawnattr_setsigmask( ) 29375 NAME 29376 posix_spawnattr_setsigmask - set spawn-sigmask attribute of spawn attributes object 29377 (ADVANCED REALTIME) 29378 SYNOPSIS 29379 SPN #include 29380 #include 29381 int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict attr, 29382 const sigset_t *restrict sigmask); 29383 29384 DESCRIPTION 29385 Refer to posix_spawnattr_getsigmask( ). System Interfaces, Issue 6 1391 posix_spawnp( ) System Interfaces 29386 NAME 29387 posix_spawnp - spawn a process (ADVANCED REALTIME) 29388 SYNOPSIS 29389 SPN #include 29390 int posix_spawnp(pid_t *restrict pid, const char *restrict file, 29391 const posix_spawn_file_actions_t *file_actions, 29392 const posix_spawnattr_t *restrict attrp, 29393 char *const argv[restrict], char *const envp[restrict]); 29394 29395 DESCRIPTION 29396 Refer to posix_spawn( ). 1392 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_destroy( ) 29397 NAME 29398 posix_trace_attr_destroy, posix_trace_attr_init - trace stream attributes object destroy and 29399 initialization (TRACING) 29400 SYNOPSIS 29401 TRC #include 29402 int posix_trace_attr_destroy(trace_attr_t *attr); 29403 int posix_trace_attr_init(trace_attr_t *attr); 29404 29405 DESCRIPTION 29406 The posix_trace_attr_destroy( ) function shall destroy an initialized trace attributes object. A | 29407 destroyed attr attributes object can be reinitialized using posix_trace_attr_init( ); the results of | 29408 otherwise referencing the object after it has been destroyed are undefined. | 29409 The posix_trace_attr_init( ) function shall initialize a trace attributes object attr with the default 29410 value for all of the individual attributes used by a given implementation. The read-only 29411 generation-version and clock-resolution attributes of the newly initialized trace attributes object 29412 shall be set to their appropriate values (see Section 2.11.1.2 (on page 525)). 29413 Results are undefined if posix_trace_attr_init( ) is called specifying an already initialized attr | 29414 attributes object. | 29415 Implementations may add extensions to the trace attributes object structure as permitted in the 29416 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 2, Conformance. 29417 The resulting attributes object (possibly modified by setting individual attributes values), when 29418 used by posix_trace_create( ), defines the attributes of the trace stream created. A single attributes 29419 object can be used in multiple calls to posix_trace_create( ). After one or more trace streams have 29420 been created using an attributes object, any function affecting that attributes object, including | 29421 destruction, shall not affect any trace stream previously created. An initialized attributes object | 29422 also serves to receive the attributes of an existing trace stream or trace log when calling the 29423 posix_trace_get_attr( ) function. 29424 RETURN VALUE 29425 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 29426 return the corresponding error number. 29427 ERRORS 29428 The posix_trace_attr_destroy( ) function may fail if: 29429 [EINVAL] The value of attr is invalid. 29430 The posix_trace_attr_init( ) function shall fail if: 29431 [ENOMEM] Insufficient memory exists to initialize the trace attributes object. 29432 EXAMPLES 29433 None. 29434 APPLICATION USAGE 29435 None. 29436 RATIONALE 29437 None. System Interfaces, Issue 6 1393 posix_trace_attr_destroy( ) System Interfaces 29438 FUTURE DIRECTIONS 29439 None. 29440 SEE ALSO 29441 posix_trace_create( ), posix_trace_get_attr( ), uname( ), the Base Definitions volume of 29442 IEEE Std 1003.1-200x, 29443 CHANGE HISTORY 29444 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 29445 IEEE PASC Interpretation 1003.1 #123 is applied. | 1394 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getclockres( ) 29446 NAME 29447 posix_trace_attr_getclockres, posix_trace_attr_getcreatetime, posix_trace_attr_getgenversion, 29448 posix_trace_attr_getname, posix_trace_attr_setname - retrieve and set information about a 29449 trace stream (TRACING) 29450 SYNOPSIS 29451 TRC #include 29452 #include 29453 int posix_trace_attr_getclockres(const trace_attr_t *attr, 29454 struct timespec *resolution); 29455 int posix_trace_attr_getcreatetime(const trace_attr_t *attr, 29456 struct timespec *createtime); 29457 #include 29458 int posix_trace_attr_getgenversion(const trace_attr_t *attr, 29459 char *genversion); 29460 int posix_trace_attr_getname(const trace_attr_t *attr, 29461 char *tracename); 29462 int posix_trace_attr_setname(trace_attr_t *attr, 29463 const char *tracename); 29464 29465 DESCRIPTION 29466 The posix_trace_attr_getclockres( ) function shall copy the clock resolution of the clock used to 29467 generate timestamps from the clock-resolution attribute of the attributes object pointed to by the 29468 attr argument into the structure pointed to by the resolution argument. 29469 The posix_trace_attr_getcreatetime( ) function shall copy the trace stream creation time from the 29470 creation-time attribute of the attributes object pointed to by the attr argument into the structure 29471 pointed to by the createtime argument. The creation-time attribute shall represent the time of 29472 creation of the trace stream. 29473 The posix_trace_attr_getgenversion( ) function shall copy the string containing version information 29474 from the generation-version attribute of the attributes object pointed to by the attr argument into 29475 the string pointed to by the genversion argument. The genversion argument shall be the address of 29476 a character array which can store at least {TRACE_NAME_MAX} characters. 29477 The posix_trace_attr_getname( ) function shall copy the string containing the trace name from the 29478 trace-name attribute of the attributes object pointed to by the attr argument into the string 29479 pointed to by the tracename argument. The tracename argument shall be the address of a character 29480 array which can store at least {TRACE_NAME_MAX} characters. 29481 The posix_trace_attr_setname( ) function shall set the name in the trace-name attribute of the 29482 attributes object pointed to by the attr argument, using the trace name string supplied by the 29483 tracename argument. If the supplied string contains more than {TRACE_NAME_MAX} 29484 characters, the name copied into the trace-name attribute may be truncated to one less than the 29485 length of {TRACE_NAME_MAX} characters. The default value is a null string. 29486 RETURN VALUE 29487 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 29488 return the corresponding error number. 29489 If successful, the posix_trace_attr_getclockres( ) function stores the clock-resolution attribute value 29490 in the object pointed to by resolution. Otherwise, the content of this object is unspecified. System Interfaces, Issue 6 1395 posix_trace_attr_getclockres( ) System Interfaces 29491 If successful, the posix_trace_attr_getcreatetime( ) function stores the trace stream creation time in 29492 the object pointed to by createtime. Otherwise, the content of this object is unspecified. 29493 If successful, the posix_trace_attr_getgenversion( ) function stores the trace version information in 29494 the string pointed to by genversion. Otherwise, the content of this string is unspecified. 29495 If successful, the posix_trace_attr_getname( ) function stores the trace name in the string pointed 29496 to by tracename. Otherwise, the content of this string is unspecified. 29497 ERRORS 29498 The posix_trace_attr_getclockres( ), posix_trace_attr_getcreatetime( ), posix_trace_attr_getgenversion( ), 29499 and posix_trace_attr_getname( ) functions may fail if: 29500 [EINVAL] The value specified by one of the arguments is invalid. 29501 EXAMPLES 29502 None. 29503 APPLICATION USAGE 29504 None. 29505 RATIONALE 29506 None. 29507 FUTURE DIRECTIONS 29508 None. 29509 SEE ALSO 29510 posix_trace_attr_init( ), posix_trace_create( ), posix_trace_get_attr( ), uname( ), the Base Definitions 29511 volume of IEEE Std 1003.1-200x, , 29512 CHANGE HISTORY 29513 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. 1396 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getcreatetime( ) 29514 NAME 29515 posix_trace_attr_getcreatetime - retrieve and set information about a trace stream (TRACING) 29516 SYNOPSIS 29517 TRC #include 29518 #include 29519 int posix_trace_attr_getcreatetime(const trace_attr_t *attr, 29520 struct timespec *createtime); 29521 29522 DESCRIPTION 29523 Refer to posix_trace_attr_getclockres( ). System Interfaces, Issue 6 1397 posix_trace_attr_getgenversion( ) System Interfaces 29524 NAME 29525 posix_trace_attr_getgenversion - retrieve and set information about a trace stream 29526 (TRACING) 29527 SYNOPSIS 29528 TRC #include 29529 int posix_trace_attr_getgenversion(const trace_attr_t *attr, 29530 char *genversion); 29531 29532 DESCRIPTION 29533 Refer to posix_trace_attr_getclockres( ). 1398 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getinherited( ) 29534 NAME 29535 posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy, 29536 posix_trace_attr_getstreamfullpolicy, posix_trace_attr_setinherited, 29537 posix_trace_attr_setlogfullpolicy, posix_trace_attr_setstreamfullpolicy - retrieve and set the 29538 behavior of a trace stream (TRACING) 29539 SYNOPSIS 29540 TRC #include 29541 TRC TRI int posix_trace_attr_getinherited(const trace_attr_t *restrict attr, 29542 int *restrict inheritancepolicy); 29543 TRC TRL int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict attr, 29544 int *restrict logpolicy); 29545 TRC int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *attr, 29546 int *streampolicy); 29547 TRC TRI int posix_trace_attr_setinherited(trace_attr_t *attr, 29548 int inheritancepolicy); 29549 TRC TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr, 29550 int logpolicy); 29551 TRC int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr, 29552 int streampolicy); 29553 29554 DESCRIPTION 29555 TRI The posix_trace_attr_getinherited( ) and posix_trace_attr_setinherited( ) functions, respectively, shall 29556 get and set the inheritance policy stored in the inheritance attribute for traced processes across 29557 the fork( ) and spawn( ) operations. The inheritance attribute of the attributes object pointed to by 29558 the attr argument shall be set to one of the following values defined by manifest constants in the 29559 header: 29560 POSIX_TRACE_CLOSE_FOR_CHILD 29561 After a fork( ) or spawn( ) operation, the child shall not be traced, and tracing of the parent 29562 shall continue. 29563 POSIX_TRACE_INHERITED 29564 After a fork( ) or spawn( ) operation, if the parent is being traced, its child shall be 29565 concurrently traced using the same trace stream. 29566 The default value for the inheritance attribute is POSIX_TRACE_CLOSE_FOR_CHILD. 29567 TRL The posix_trace_attr_getlogfullpolicy( ) and posix_trace_attr_setlogfullpolicy( ) functions, | 29568 respectively, shall get and set the trace log full policy stored in the log-full-policy attribute of the | 29569 attributes object pointed to by the attr argument. 29570 The log-full-policy attribute shall be set to one of the following values defined by manifest 29571 constants in the header: 29572 POSIX_TRACE_LOOP 29573 The trace log shall loop until the associated trace stream is stopped. This policy means that 29574 when the trace log gets full, the file system shall reuse the resources allocated to the oldest 29575 trace events that were recorded. In this way, the trace log will always contain the most 29576 recent trace events flushed. 29577 POSIX_TRACE_UNTIL_FULL 29578 The trace stream shall be flushed to the trace log until the trace log is full. This condition can 29579 be deduced from the posix_log_full_status member status (see the posix_trace_status_info( ) 29580 function). The last recorded trace event shall be the POSIX_TRACE_STOP trace event. System Interfaces, Issue 6 1399 posix_trace_attr_getinherited( ) System Interfaces 29581 POSIX_TRACE_APPEND 29582 The associated trace stream shall be flushed to the trace log without log size limitation. If 29583 the application specifies POSIX_TRACE_APPEND, the implementation shall ignore the 29584 log-max-size attribute. 29585 The default value for the log-full-policy attribute is POSIX_TRACE_LOOP. 29586 The posix_trace_attr_getstreamfullpolicy( ) and posix_trace_attr_setstreamfullpolicy( ) functions, | 29587 respectively, shall get and set the trace stream full policy stored in the stream-full-policy attribute | 29588 of the attributes object pointed to by the attr argument. 29589 The stream-full-policy attribute shall be set to one of the following values defined by manifest 29590 constants in the header: 29591 POSIX_TRACE_LOOP 29592 The trace stream shall loop until explicitly stopped by the posix_trace_stop( ) function. This 29593 policy means that when the trace stream is full, the trace system shall reuse the resources 29594 allocated to the oldest trace events recorded. In this way, the trace stream will always 29595 contain the most recent trace events recorded. 29596 POSIX_TRACE_UNTIL_FULL 29597 The trace stream will run until the trace stream resources are exhausted. Then the trace 29598 stream will stop. This condition can be deduced from posix_stream_status and 29599 posix_stream_full_status statuses (see the posix_trace_status_info( ) function). When this trace 29600 stream is read, a POSIX_TRACE_STOP trace event shall be reported after reporting the last 29601 recorded trace event. The trace system shall reuse the resources allocated to any trace 29602 events already reported-see the posix_trace_getnext_event( ), posix_trace_trygetnext_event( ), 29603 and posix_trace_timedgetnext_event( ) functions-or already flushed for an active trace stream 29604 with log if the Trace Log option is supported; see the posix_trace_flush( ) function. The trace 29605 system shall restart the trace stream when it is empty and may restart it sooner. A 29606 POSIX_TRACE_START trace event shall be reported before reporting the next recorded 29607 trace event. 29608 TRL POSIX_TRACE_FLUSH 29609 If the Trace Log option is supported, this policy is identical to the 29610 POSIX_TRACE_UNTIL_FULL trace stream full policy except that the trace stream shall be 29611 flushed regularly as if posix_trace_flush( ) had been explicitly called. Defining this policy for 29612 an active trace stream without log shall be invalid. 29613 The default value for the stream-full-policy attribute shall be POSIX_TRACE_LOOP for an active 29614 trace stream without log. 29615 TRL If the Trace Log option is supported, the default value for the stream-full-policy attribute shall be 29616 POSIX_TRACE_FLUSH for an active trace stream with log. 29617 RETURN VALUE 29618 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 29619 return the corresponding error number. 29620 TRI If successful, the posix_trace_attr_getinherited( ) function shall store the inheritance attribute value | 29621 in the object pointed to by inheritancepolicy. Otherwise, the content of this object is undefined. 29622 TRL If successful, the posix_trace_attr_getlogfullpolicy( ) function shall store the log-full-policy attribute | 29623 value in the object pointed to by logpolicy. Otherwise, the content of this object is undefined. 29624 If successful, the posix_trace_attr_getstreamfullpolicy( ) function shall store the stream-full-policy | 29625 attribute value in the object pointed to by streampolicy. Otherwise, the content of this object is 29626 undefined. 1400 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getinherited( ) 29627 ERRORS 29628 These functions may fail if: 29629 [EINVAL] The value specified by at least one of the arguments is invalid. 29630 EXAMPLES 29631 None. 29632 APPLICATION USAGE 29633 None. 29634 RATIONALE 29635 None. 29636 FUTURE DIRECTIONS 29637 None. 29638 SEE ALSO 29639 fork( ), posix_trace_attr_init( ), posix_trace_create( ), posix_trace_flush( ), posix_trace_get_attr( ), 29640 posix_trace_getnext_event( ), posix_trace_start( ), posix_trace_status_info Structure, 29641 posix_trace_timedgetnext_event( ), the Base Definitions volume of IEEE Std 1003.1-200x, 29642 CHANGE HISTORY 29643 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. System Interfaces, Issue 6 1401 posix_trace_attr_getlogfullpolicy( ) System Interfaces 29644 NAME 29645 posix_trace_attr_getlogfullpolicy - retrieve and set the behavior of a trace stream (TRACING) 29646 SYNOPSIS 29647 TRC #include 29648 TRC TRL int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict attr, 29649 int *restrict logpolicy); 29650 29651 DESCRIPTION 29652 Refer to posix_trace_attr_getinherited( ). 1402 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getlogsize( ) 29653 NAME 29654 posix_trace_attr_getlogsize, posix_trace_attr_getmaxdatasize, 29655 posix_trace_attr_getmaxsystemeventsize, posix_trace_attr_getmaxusereventsize, 29656 posix_trace_attr_getstreamsize, posix_trace_attr_setlogsize, posix_trace_attr_setmaxdatasize, 29657 posix_trace_attr_setstreamsize - retrieve and set trace stream size attributes (TRACING) 29658 SYNOPSIS 29659 TRC #include 29660 #include 29661 TRC TRL int posix_trace_attr_getlogsize(const trace_attr_t *restrict attr, 29662 size_t *restrict logsize); 29663 TRC int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict attr, 29664 size_t *restrict maxdatasize); 29665 int posix_trace_attr_getmaxsystemeventsize( 29666 const trace_attr_t *restrict attr, 29667 size_t *restrict eventsize); 29668 int posix_trace_attr_getmaxusereventsize( 29669 const trace_attr_t *restrict attr, 29670 size_t data_len, size_t *restrict eventsize); 29671 int posix_trace_attr_getstreamsize(const trace_attr_t *restrict attr, 29672 size_t *restrict streamsize); 29673 TRC TRL int posix_trace_attr_setlogsize(trace_attr_t *attr, 29674 size_t logsize); 29675 TRC int posix_trace_attr_setmaxdatasize(trace_attr_t *attr, 29676 size_t maxdatasize); 29677 int posix_trace_attr_setstreamsize(trace_attr_t *attr, 29678 size_t streamsize); 29679 29680 DESCRIPTION 29681 TRL The posix_trace_attr_getlogsize( ) function shall copy the log size, in bytes, from the log-max-size 29682 attribute of the attributes object pointed to by the attr argument into the variable pointed to by 29683 the logsize argument. This log size is the maximum total of bytes that shall be allocated for 29684 system and user trace events in the trace log. The default value for the log-max-size attribute is 29685 implementation-defined. 29686 The posix_trace_attr_setlogsize( ) function shall set the maximum allowed size, in bytes, in the 29687 log-max-size attribute of the attributes object pointed to by the attr argument, using the size value 29688 supplied by the logsize argument. 29689 The trace log size shall be used if the log-full-policy attribute is set to POSIX_TRACE_LOOP or 29690 POSIX_TRACE_UNTIL_FULL. If the log-full-policy attribute is set to POSIX_TRACE_APPEND, 29691 the implementation shall ignore the log-max-size attribute. 29692 The posix_trace_attr_getmaxdatasize( ) function shall copy the maximum user trace event data 29693 size, in bytes, from the max-data-size attribute of the attributes object pointed to by the attr 29694 argument into the variable pointed to by the maxdatasize argument. The default value for the 29695 max-data-size attribute is implementation-defined. 29696 The posix_trace_attr_getmaxsystemeventsize( ) function shall calculate the maximum memory size, 29697 in bytes, required to store a single system trace event. This value is calculated for the trace 29698 stream attributes object pointed to by the attr argument and is returned in the variable pointed 29699 to by the eventsize argument. System Interfaces, Issue 6 1403 posix_trace_attr_getlogsize( ) System Interfaces 29700 The values returned as the maximum memory sizes of the user and system trace events shall be 29701 such that if the sum of the maximum memory sizes of a set of the trace events that may be 29702 recorded in a trace stream is less than or equal to the stream-min-size attribute of that trace 29703 stream, the system provides the necessary resources for recording all those trace events, without 29704 loss. 29705 The posix_trace_attr_getmaxusereventsize( ) function shall calculate the maximum memory size, in 29706 bytes, required to store a single user trace event generated by a call to posix_trace_event( ) with a 29707 data_len parameter equal to the data_len value specified in this call. This value is calculated for 29708 the trace stream attributes object pointed to by the attr argument and is returned in the variable 29709 pointed to by the eventsize argument. 29710 The posix_trace_attr_getstreamsize( ) function shall copy the stream size, in bytes, from the 29711 stream-min-size attribute of the attributes object pointed to by the attr argument into the variable 29712 pointed to by the streamsize argument. 29713 This stream size is the current total memory size reserved for system and user trace events in the 29714 trace stream. The default value for the stream-min-size attribute is implementation-defined. The 29715 stream size refers to memory used to store trace event records. Other stream data (for example, 29716 trace attribute values) shall not be included in this size. 29717 The posix_trace_attr_setmaxdatasize( ) function shall set the maximum allowed size, in bytes, in 29718 the max-data-size attribute of the attributes object pointed to by the attr argument, using the size 29719 value supplied by the maxdatasize argument. This maximum size is the maximum allowed size 29720 for the user data argument which may be passed to posix_trace_event( ). The implementation 29721 shall be allowed to truncate data passed to trace_user_event which is longer than maxdatasize. 29722 The posix_trace_attr_setstreamsize( ) function shall set the minimum allowed size, in bytes, in the 29723 stream-min-size attribute of the attributes object pointed to by the attr argument, using the size 29724 value supplied by the streamsize argument. 29725 RETURN VALUE 29726 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 29727 return the corresponding error number. 29728 TRL The posix_trace_attr_getlogsize( ) function stores the maximum trace log allowed size in the object 29729 pointed to by logsize, if successful. 29730 The posix_trace_attr_getmaxdatasize( ) function stores the maximum trace event record memory 29731 size in the object pointed to by maxdatasize, if successful. 29732 The posix_trace_attr_getmaxsystemeventsize( ) function stores the maximum memory size to store 29733 a single system trace event in the object pointed to by eventsize, if successful. 29734 The posix_trace_attr_getmaxusereventsize( ) function stores the maximum memory size to store a 29735 single user trace event in the object pointed to by eventsize, if successful. 29736 The posix_trace_attr_getstreamsize( ) function stores the maximum trace stream allowed size in 29737 the object pointed to by streamsize, if successful. 29738 ERRORS 29739 These functions may fail if: 29740 [EINVAL] The value specified by one of the arguments is invalid. 1404 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getlogsize( ) 29741 EXAMPLES 29742 None. 29743 APPLICATION USAGE 29744 None. 29745 RATIONALE 29746 None. 29747 FUTURE DIRECTIONS 29748 None. 29749 SEE ALSO 29750 posix_trace_attr_init( ), posix_trace_create( ), posix_trace_event( ), posix_trace_get_attr( ), the Base 29751 Definitions volume of IEEE Std 1003.1-200x, , 29752 CHANGE HISTORY 29753 First released in Issue 6. Derived from the IEEE Std 1003.1q-2000. System Interfaces, Issue 6 1405 posix_trace_attr_getmaxdatasize( ) System Interfaces 29754 NAME 29755 posix_trace_attr_getmaxdatasize, posix_trace_attr_getmaxsystemeventsize, 29756 posix_trace_attr_getmaxusereventsize - retrieve and set trace stream size attributes 29757 (TRACING) 29758 SYNOPSIS 29759 TRC #include 29760 #include 29761 TRC int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict attr, 29762 size_t *restrict maxdatasize); 29763 int posix_trace_attr_getmaxsystemeventsize( 29764 const trace_attr_t *restrict attr, 29765 size_t *restrict eventsize); 29766 int posix_trace_attr_getmaxusereventsize( 29767 const trace_attr_t *restrict attr, 29768 size_t data_len, size_t *restrict eventsize); 29769 29770 DESCRIPTION 29771 Refer to posix_trace_attr_getlogsize( ). 1406 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getname( ) 29772 NAME 29773 posix_trace_attr_getname - retrieve and set information about a trace stream (TRACING) 29774 SYNOPSIS 29775 TRC #include 29776 int posix_trace_attr_getname(const trace_attr_t *attr, 29777 char *tracename); 29778 29779 DESCRIPTION 29780 Refer to posix_trace_attr_getclockres( ). System Interfaces, Issue 6 1407 posix_trace_attr_getstreamfullpolicy( ) System Interfaces 29781 NAME 29782 posix_trace_attr_getstreamfullpolicy - retrieve and set the behavior of a trace stream 29783 (TRACING) 29784 SYNOPSIS 29785 TRC #include 29786 int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *attr, 29787 int *streampolicy); 29788 29789 DESCRIPTION 29790 Refer to posix_trace_attr_getinherited( ). 1408 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_getstreamsize( ) 29791 NAME 29792 posix_trace_attr_getstreamsize - retrieve and set trace stream size attributes (TRACING) 29793 SYNOPSIS 29794 TRC #include 29795 #include 29796 int posix_trace_attr_getstreamsize(const trace_attr_t *restrict attr, 29797 size_t *restrict streamsize); 29798 29799 DESCRIPTION 29800 Refer to posix_trace_attr_getlogsize( ). System Interfaces, Issue 6 1409 posix_trace_attr_init( ) System Interfaces 29801 NAME 29802 posix_trace_attr_init - trace stream attributes object initialization (TRACING) 29803 SYNOPSIS 29804 TRC #include 29805 int posix_trace_attr_init(trace_attr_t *attr); 29806 29807 DESCRIPTION 29808 Refer to posix_trace_attr_destroy( ). 1410 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_setinherited( ) 29809 NAME 29810 posix_trace_attr_setinherited - retrieve and set the behavior of a trace stream (TRACING) 29811 SYNOPSIS 29812 TRC #include 29813 TRC TRI int posix_trace_attr_setinherited(trace_attr_t *attr, 29814 int inheritancepolicy); 29815 29816 DESCRIPTION 29817 Refer to posix_trace_attr_getinherited( ). System Interfaces, Issue 6 1411 posix_trace_attr_setlogfullpolicy( ) System Interfaces 29818 NAME 29819 posix_trace_attr_setlogfullpolicy - retrieve and set the behavior of a trace stream (TRACING) 29820 SYNOPSIS 29821 TRC #include 29822 TRC TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr, 29823 int logpolicy); 29824 29825 DESCRIPTION 29826 Refer to posix_trace_attr_getinherited( ). 1412 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_setlogsize( ) 29827 NAME 29828 posix_trace_attr_setlogsize - retrieve and set trace stream size attributes (TRACING) 29829 SYNOPSIS 29830 TRC #include 29831 #include 29832 TRC TRL int posix_trace_attr_setlogsize(trace_attr_t *attr, 29833 size_t logsize); 29834 29835 DESCRIPTION 29836 Refer to posix_trace_attr_getlogsize( ). System Interfaces, Issue 6 1413 posix_trace_attr_setmaxdatasize( ) System Interfaces 29837 NAME 29838 posix_trace_attr_setmaxdatasize - retrieve and set trace stream size attributes (TRACING) 29839 SYNOPSIS 29840 TRC #include 29841 #include 29842 int posix_trace_attr_setmaxdatasize(trace_attr_t *attr, 29843 size_t maxdatasize); 29844 29845 DESCRIPTION 29846 Refer to posix_trace_attr_getlogsize( ). 1414 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_setname( ) 29847 NAME 29848 posix_trace_attr_setname - retrieve and set information about a trace stream (TRACING) 29849 SYNOPSIS 29850 TRC #include 29851 int posix_trace_attr_setname(trace_attr_t *attr, 29852 const char *tracename); 29853 29854 DESCRIPTION 29855 Refer to posix_trace_attr_getclockres( ). System Interfaces, Issue 6 1415 posix_trace_attr_setstreamfullpolicy( ) System Interfaces 29856 NAME 29857 posix_trace_attr_setstreamfullpolicy - retrieve and set the behavior of a trace stream 29858 (TRACING) 29859 SYNOPSIS 29860 TRC #include 29861 TRC TRL int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr, 29862 int logpolicy); 29863 29864 DESCRIPTION 29865 Refer to posix_trace_attr_getinherited( ). 1416 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_attr_setstreamsize( ) 29866 NAME 29867 posix_trace_attr_setstreamsize - retrieve and set trace stream size attributes (TRACING) 29868 SYNOPSIS 29869 TRC #include 29870 #include 29871 int posix_trace_attr_setstreamsize(trace_attr_t *attr, 29872 size_t streamsize); 29873 29874 DESCRIPTION 29875 Refer to posix_trace_attr_getlogsize( ). System Interfaces, Issue 6 1417 posix_trace_clear( ) System Interfaces 29876 NAME 29877 posix_trace_clear - clear trace stream and trace log (TRACING) 29878 SYNOPSIS 29879 TRC #include 29880 #include 29881 int posix_trace_clear(trace_id_t trid); 29882 29883 DESCRIPTION 29884 The posix_trace_clear( ) function shall reinitialize the trace stream identified by the argument trid 29885 as if it were returning from the posix_trace_create( ) function, except that the same allocated | 29886 resources shall be reused, the mapping of trace event type identifiers to trace event names shall | 29887 be unchanged, and the trace stream status shall remain unchanged (that is, if it was running, it | 29888 remains running and if it was suspended, it remains suspended). | 29889 All trace events in the trace stream recorded before the call to posix_trace_clear( ) shall be lost. | 29890 The posix_stream_full_status status shall be set to POSIX_TRACE_NOT_FULL. There is no | 29891 guarantee that all trace events that occurred during the posix_trace_clear( ) call are recorded; the 29892 behavior with respect to trace points that may occur during this call, is unspecified. 29893 TRL If the Trace Log option is supported and the trace stream has been created with a log, the 29894 posix_trace_clear( ) function shall reinitialize the trace stream with the same behavior as if the 29895 trace stream was created without the log, plus it shall reinitialize the trace log associated with 29896 the trace stream identified by the argument trid as if it were returning from the 29897 posix_trace_create_withlog( ) function, except that the same allocated resources, for the trace log, 29898 may be reused and the associated trace stream status remains unchanged. The first trace event 29899 recorded in the trace log after the call to posix_trace_clear( ) shall be the same as the first trace 29900 event recorded in the active trace stream after the call to posix_trace_clear( ). The 29901 posix_log_full_status status shall be set to POSIX_TRACE_NOT_FULL. There is no guarantee that 29902 all trace events that occurred during the posix_trace_clear( ) call are recorded in the trace log; the 29903 behavior with respect to trace points that may occur during this call is unspecified. If the log full 29904 policy is POSIX_TRACE_APPEND, the effect of a call to this function is unspecified for the trace 29905 log associated with the trace stream identified by the trid argument. 29906 RETURN VALUE 29907 Upon successful completion, the posix_trace_clear( ) function shall return a value of zero. 29908 Otherwise, it shall return the corresponding error number. 29909 ERRORS 29910 The posix_trace_clear( ) function shall fail if: | 29911 [EINVAL] The value of the trid argument does not correspond to an active trace stream. 29912 EXAMPLES 29913 None. 29914 APPLICATION USAGE 29915 None. 29916 RATIONALE 29917 None. 29918 FUTURE DIRECTIONS 29919 None. 1418 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_clear( ) 29920 SEE ALSO 29921 posix_trace_attr_init( ), posix_trace_create( ), posix_trace_flush( ), posix_trace_get_attr( ), the Base 29922 Definitions volume of IEEE Std 1003.1-200x, , 29923 CHANGE HISTORY 29924 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 29925 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1419 posix_trace_close( ) System Interfaces 29926 NAME 29927 posix_trace_close, posix_trace_open, posix_trace_rewind - trace log management (TRACING) 29928 SYNOPSIS 29929 TRC TRL #include 29930 int posix_trace_close(trace_id_t trid); 29931 int posix_trace_open(int file_desc, trace_id_t *trid); 29932 int posix_trace_rewind(trace_id_t trid); 29933 29934 DESCRIPTION 29935 The posix_trace_close( ) function shall deallocate the trace log identifier indicated by trid, and all 29936 of its associated resources. If there is no valid trace log pointed to by the trid, this function shall 29937 fail. 29938 The posix_trace_open( ) function shall allocate the necessary resources and establishes the 29939 connection between a trace log identified by the file_desc argument and a trace stream identifier 29940 identified by the object pointed to by the trid argument. The file_desc argument should be a valid 29941 open file descriptor that corresponds to a trace log. The file_desc argument shall be open for 29942 reading. The current trace event timestamp, which specifies the timestamp of the trace event 29943 that will be read by the next call to posix_trace_getnext_event( ), shall be set to the timestamp of 29944 the oldest trace event recorded in the trace log identified by trid. 29945 The posix_trace_open( ) function shall return a trace stream identifier in the variable pointed to by 29946 the trid argument, that may only be used by the following functions: 29947 posix_trace_close( ) posix_trace_get_attr( ) 29948 posix_trace_eventid_equal( ) posix_trace_get_status( ) 29949 posix_trace_eventid_get_name( ) posix_trace_getnext_event( ) 29950 posix_trace_eventtypelist_getnext_id( ) posix_trace_rewind( ) 29951 posix_trace_eventtypelist_rewind( ) 29952 In particular, notice that the operations normally used by a trace controller process, such as 29953 posix_trace_start( ), posix_trace_stop( ), or posix_trace_shutdown( ), cannot be invoked using the 29954 trace stream identifier returned by the posix_trace_open( ) function. 29955 The posix_trace_rewind( ) function shall reset the current trace event timestamp, which specifies 29956 the timestamp of the trace event that will be read by the next call to posix_trace_getnext_event( ), 29957 to the timestamp of the oldest trace event recorded in the trace log identified by trid. 29958 RETURN VALUE 29959 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 29960 return the corresponding error number. 29961 If successful, the posix_trace_open( ) function stores the trace stream identifier value in the object 29962 pointed to by trid. 29963 ERRORS 29964 The posix_trace_open( ) function shall fail if: | 29965 [EINTR] The operation was interrupted by a signal and thus no trace log was opened. 29966 [EINVAL] The object pointed to by file_desc does not correspond to a valid trace log. 29967 The posix_trace_close( ) and posix_trace_rewind( ) functions may fail if: 29968 [EINVAL] The object pointed to by trid does not correspond to a valid trace log. 1420 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_close( ) 29969 EXAMPLES 29970 None. 29971 APPLICATION USAGE 29972 None. 29973 RATIONALE 29974 None. 29975 FUTURE DIRECTIONS 29976 None. 29977 SEE ALSO 29978 posix_trace_get_attr( ), posix_trace_get_filter( ), posix_trace_getnext_event( ), the Base Definitions 29979 volume of IEEE Std 1003.1-200x, 29980 CHANGE HISTORY 29981 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 29982 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1421 posix_trace_create( ) System Interfaces 29983 NAME 29984 posix_trace_create, posix_trace_create_withlog, posix_trace_flush, posix_trace_shutdown - 29985 trace stream initialization, flush, and shutdown from a process (TRACING) 29986 SYNOPSIS 29987 TRC #include 29988 #include 29989 int posix_trace_create(pid_t pid, 29990 const trace_attr_t *restrict attr, 29991 trace_id_t *restrict trid); 29992 TRC TRL int posix_trace_create_withlog(pid_t pid, 29993 const trace_attr_t *restrict attr, int file_desc, 29994 trace_id_t *restrict trid); 29995 int posix_trace_flush(trace_id_t trid); 29996 TRC int posix_trace_shutdown(trace_id_t trid); 29997 29998 DESCRIPTION 29999 The posix_trace_create( ) function shall create an active trace stream. It allocates all the resources 30000 needed by the trace stream being created for tracing the process specified by pid in accordance 30001 with the attr argument. The attr argument represents the initial attributes of the trace stream and 30002 shall have been initialized by the function posix_trace_attr_init( ) prior the posix_trace_create( ) 30003 call. If the argument attr is NULL, the default attributes shall be used. The attr attributes object 30004 shall be manipulated through a set of functions described in the posix_trace_attr family of 30005 functions. If the attributes of the object pointed to by attr are modified later, the attributes of the 30006 trace stream shall not be affected. The creation-time attribute of the newly created trace stream 30007 shall be set to the value of the system clock, if the Timers option is not supported, or to the value 30008 of the CLOCK_REALTIME clock, if the Timers option is supported. 30009 The pid argument represents the target process to be traced. If the process executing this 30010 function does not have appropriate privileges to trace the process identified by pid, an error shall 30011 be returned. If the pid argument is zero, the calling process shall be traced. 30012 The posix_trace_create( ) function shall store the trace stream identifier of the new trace stream in 30013 the object pointed to by the trid argument. This trace stream identifier shall be used in 30014 subsequent calls to control tracing. The trid argument may only be used by the following 30015 functions: 30016 posix_trace_clear( ) posix_trace_getnext_event( ) 30017 posix_trace_eventid_equal( ) posix_trace_shutdown( ) 30018 posix_trace_eventid_get_name( ) posix_trace_start( ) 30019 posix_trace_eventtypelist_getnext_id( ) posix_trace_stop( ) 30020 posix_trace_eventtypelist_rewind( ) posix_trace_timedgetnext_event( ) 30021 posix_trace_get_attr( ) posix_trace_trid_eventid_open( ) 30022 posix_trace_get_status( ) posix_trace_trygetnext_event( ) 30023 TEF If the Trace Event Filter option is supported, the following additional functions may use the trid 30024 argument: 30025 posix_trace_get_filter( ) posix_trace_set_filter( ) 30026 1422 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_create( ) 30027 In particular, notice that the operations normally used by a trace analyzer process, such as 30028 posix_trace_rewind( ) or posix_trace_close( ), cannot be invoked using the trace stream identifier 30029 returned by the posix_trace_create( ) function. 30030 TEF A trace stream shall be created in a suspended state. If the Trace Event Filter option is 30031 supported, its trace event type filter shall be empty. 30032 The posix_trace_create( ) function may be called multiple times from the same or different 30033 processes, with the system-wide limit indicated by the runtime invariant value 30034 {TRACE_SYS_MAX}, which has the minimum value {_POSIX_TRACE_SYS_MAX}. 30035 The trace stream identifier returned by the posix_trace_create( ) function in the argument pointed 30036 to by trid is valid only in the process that made the function call. If it is used from another 30037 process, that is a child process, in functions defined in IEEE Std 1003.1-200x, these functions shall 30038 return with the error [EINVAL]. 30039 TRL The posix_trace_create_withlog( ) function shall be equivalent to posix_trace_create( ), except that it | 30040 associates a trace log with this stream. The file_desc argument shall be the file descriptor | 30041 designating the trace log destination. The function shall fail if this file descriptor refers to a file 30042 with a file type that is not compatible with the log policy associated with the trace log. The list of 30043 the appropriate file types that are compatible with each log policy is implementation-defined. | 30044 The posix_trace_create_withlog( ) function shall return in the parameter pointed to by trid the trace 30045 stream identifier, which uniquely identifies the newly created trace stream, and shall be used in 30046 subsequent calls to control tracing. The trid argument may only be used by the following 30047 functions: 30048 posix_trace_clear( ) posix_trace_getnext_event( ) 30049 posix_trace_eventid_equal( ) posix_trace_shutdown( ) 30050 posix_trace_eventid_get_name( ) posix_trace_start( ) 30051 posix_trace_eventtypelist_getnext_id( ) posix_trace_stop( ) 30052 posix_trace_eventtypelist_rewind( ) posix_trace_timedgetnext_event( ) 30053 posix_trace_flush( ) posix_trace_trid_eventid_open( ) 30054 posix_trace_get_attr( ) posix_trace_trygetnext_event( ) 30055 posix_trace_get_status( ) 30056 30057 TRL TEF If the Trace Event Filter option is supported, the following additional functions may use the trid 30058 argument: 30059 posix_trace_get_filter( ) posix_trace_set_filter( ) 30060 30061 TRL In particular, notice that the operations normally used by a trace analyzer process, such as 30062 posix_trace_rewind( ) or posix_trace_close( ), cannot be invoked using the trace stream identifier 30063 returned by the posix_trace_create_withlog( ) function. 30064 The posix_trace_flush( ) function shall initiate a flush operation which copies the contents of the | 30065 trace stream identified by the argument trid into the trace log associated with the trace stream at | 30066 the creation time. If no trace log has been associated with the trace stream pointed to by trid, this 30067 function shall return an error. The termination of the flush operation can be polled by the 30068 posix_trace_get_status( ) function. During the flush operation, it shall be possible to trace new 30069 trace events up to the point when the trace stream becomes full. After flushing is completed, the 30070 space used by the flushed trace events shall be available for tracing new trace events. System Interfaces, Issue 6 1423 posix_trace_create( ) System Interfaces 30071 If flushing the trace stream causes the resulting trace log to become full, the trace log full policy 30072 shall be applied. If the trace log-full-policy attribute is set, the following occurs: 30073 POSIX_TRACE_UNTIL_FULL 30074 The trace events that have not yet been flushed shall be discarded. | 30075 POSIX_TRACE_LOOP 30076 The trace events that have not yet been flushed shall be written to the beginning of the trace | 30077 log, overwriting previous trace events stored there. 30078 POSIX_TRACE_APPEND 30079 The trace events that had not yet been flushed shall be appended to the trace log. 30080 30081 The posix_trace_shutdown( ) function shall stop the tracing of trace events in the trace stream 30082 identified by trid, as if posix_trace_stop( ) had been invoked. The posix_trace_shutdown( ) function 30083 shall free all the resources associated with the trace stream. 30084 The posix_trace_shutdown( ) function shall not return until all the resources associated with the 30085 trace stream have been freed. When the posix_trace_shutdown( ) function returns, the trid 30086 argument becomes an invalid trace stream identifier. A call to this function shall unconditionally 30087 deallocate the resources regardless of whether all trace events have been retrieved by the 30088 analyzer process. Any thread blocked on one of the trace_getnext_event( ) functions (which 30089 specified this trid) before this call is unblocked with the error [EINVAL]. 30090 If the process exits, invokes an exec( ) call, or is terminated, the trace streams that the process had 30091 created and that have not yet been shut down, shall be automatically shut down as if an explicit 30092 call were made to the posix_trace_shutdown( ) function. 30093 TRL For an active trace stream with log, when the posix_trace_shutdown( ) function is called, all trace 30094 events that have not yet been flushed to the trace log shall be flushed, as in the 30095 posix_trace_flush( ) function, and the trace log shall be closed. 30096 When a trace log is closed, all the information that may be retrieved later from the trace log | 30097 through the trace interface shall have been written to the trace log. This information includes the | 30098 trace attributes, the list of trace event types (with the mapping between trace event names and 30099 trace event type identifiers), and the trace status. 30100 In addition, unspecified information shall be written to the trace log to allow detection of a valid | 30101 trace log during the posix_trace_open( ) operation. 30102 The posix_trace_shutdown( ) function shall not return until all trace events have been flushed. 30103 RETURN VALUE 30104 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30105 return the corresponding error number. 30106 TRL The posix_trace_create( ) andposix_trace_create_withlog( )functions store the trace stream identifier 30107 value in the object pointed to by trid, if successful. 30108 ERRORS 30109 TRL The posix_trace_create( ) andposix_trace_create_withlog( )functions shall fail if: 30110 [EAGAIN] No more trace streams can be started now. {TRACE_SYS_MAX} has been 30111 exceeded. 30112 [EINTR] The operation was interrupted by a signal. No trace stream was created. 30113 [EINVAL] One or more of the trace parameters specified by the attr parameter is invalid. 1424 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_create( ) 30114 [ENOMEM] The implementation does not currently have sufficient memory to create the 30115 trace stream with the specified parameters. 30116 [EPERM] The caller does not have appropriate privilege to trace the process specified by 30117 pid. 30118 [ESRCH] The pid argument does not refer to an existing process. 30119 TRL The posix_trace_create_withlog( ) function shall fail if: 30120 [EBADF] The file_desc argument is not a valid file descriptor open for writing. 30121 [EINVAL] The file_desc argument refers to a file with a file type that does not support the 30122 log policy associated with the trace log. 30123 [ENOSPC] No space left on device. The device corresponding to the argument file_desc 30124 does not contain the space required to create this trace log. 30125 30126 TRL Theposix_trace_flush( )and posix_trace_shutdown( ) functions shall fail if: 30127 [EINVAL] The value of the trid argument does not correspond to an active trace stream 30128 with log. 30129 [EFBIG] The trace log file has attempted to exceed an implementation-defined 30130 maximum file size. 30131 [ENOSPC] No space left on device. 30132 30133 EXAMPLES 30134 None. 30135 APPLICATION USAGE 30136 None. 30137 RATIONALE 30138 None. 30139 FUTURE DIRECTIONS 30140 None. 30141 SEE ALSO 30142 clock_getres( ), exec, posix_trace_attr_init( ), posix_trace_clear( ), posix_trace_close( ), 30143 posix_trace_eventid_equal( ), posix_trace_eventtypelist_getnext_id( ), posix_trace_flush( ), 30144 posix_trace_get_attr( ), posix_trace_get_filter( ), posix_trace_get_status( ), posix_trace_getnext_event( ), 30145 posix_trace_open( ), posix_trace_rewind( ), posix_trace_set_filter( ), posix_trace_shutdown( ), 30146 posix_trace_start( ), posix_trace_timedgetnext_event( ), posix_trace_trid_eventid_open( ), 30147 posix_trace_start( ), time( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 30148 30149 CHANGE HISTORY 30150 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. System Interfaces, Issue 6 1425 posix_trace_event( ) System Interfaces 30151 NAME 30152 posix_trace_event, posix_trace_eventid_open - trace functions for instrumenting application 30153 code (TRACING) 30154 SYNOPSIS 30155 TRC #include 30156 #include 30157 void posix_trace_event(trace_event_id_t event_id, 30158 const void *restrictdata_ptr, size_t data_len); 30159 int posix_trace_eventid_open(const char *restrict event_name, 30160 trace_event_id_t *restrict event_id); 30161 30162 DESCRIPTION 30163 The posix_trace_event( ) function shall record the event_id and the user data pointed to by data_ptr 30164 in the trace stream into which the calling process is being traced and in which event_id is not 30165 filtered out. If the total size of the user trace event data represented by data_len is not greater 30166 than the declared maximum size for user trace event data, then the truncation-status attribute of 30167 the trace event recorded is POSIX_TRACE_NOT_TRUNCATED. Otherwise, the user trace event 30168 data is truncated to this declared maximum size and the truncation-status attribute of the trace 30169 event recorded is POSIX_TRACE_TRUNCATED_RECORD. 30170 If there is no trace stream created for the process or if the created trace stream is not running or if 30171 the trace event specified by event_id is filtered out in the trace stream, the posix_trace_event( ) | 30172 function shall have no effect. | 30173 The posix_trace_eventid_open( ) function shall associate a user trace event name with a trace event | 30174 type identifier for the calling process. The trace event name is the string pointed to by the 30175 argument event_name. It shall have a maximum of {TRACE_EVENT_NAME_MAX} characters 30176 (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). The number of user 30177 trace event type identifiers that can be defined for any given process is limited by the maximum 30178 value {TRACE_USER_EVENT_MAX}, which has the minimum value 30179 {POSIX_TRACE_USER_EVENT_MAX}. 30180 If the Trace Inherit option is not supported, the posix_trace_eventid_open( ) function shall | 30181 associate the user trace event name pointed to by the event_name argument with a trace event 30182 type identifier that is unique for the traced process, and is returned in the variable pointed to by 30183 the event_id argument. If the user trace event name has already been mapped for the traced | 30184 process, then the previously assigned trace event type identifier shall be returned. If the per- 30185 process user trace event name limit represented by {TRACE_USER_EVENT_MAX} has been 30186 reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see Table 2-7 (on page 30187 529)) user trace event shall be returned. 30188 TRI If the Trace Inherit option is supported, the posix_trace_eventid_open( ) function shall associate the | 30189 user trace event name pointed to by the event_name argument with a trace event type identifier 30190 that is unique for all the processes being traced in this same trace stream, and is returned in the 30191 variable pointed to by the event_id argument. If the user trace event name has already been | 30192 mapped for the traced processes, then the previously assigned trace event type identifier shall be 30193 returned. If the per-process user trace event name limit represented by 30194 {TRACE_USER_EVENT_MAX} has been reached, the pre-defined 30195 POSIX_TRACE_UNNAMED_USEREVENT (Table 2-7 (on page 529)) user trace event shall be 30196 returned. 30197 Note: The above procedure, together with the fact that multiple processes can only be traced into the 30198 same trace stream by inheritance, ensure that all the processes that are traced into a trace 30199 stream have the same mapping of trace event names to trace event type identifiers. 1426 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_event( ) 30200 30201 If there is no trace stream created, the posix_trace_eventid_open( ) function shall store this 30202 information for future trace streams created for this process. 30203 RETURN VALUE 30204 No return value is defined for the posix_trace_event( ) function. 30205 Upon successful completion, the posix_trace_eventid_open( ) function shall return a value of zero. 30206 Otherwise, it shall return the corresponding error number. The posix_trace_eventid_open( ) 30207 function stores the trace event type identifier value in the object pointed to by event_id, if 30208 successful. 30209 ERRORS 30210 The posix_trace_eventid_open( ) function shall fail if: | 30211 [ENAMETOOLONG] 30212 The size of the name pointed to by event_name argument was longer than the 30213 implementation-defined value {TRACE_EVENT_NAME_MAX}. 30214 EXAMPLES 30215 None. 30216 APPLICATION USAGE 30217 None. 30218 RATIONALE 30219 None. 30220 FUTURE DIRECTIONS 30221 None. 30222 SEE ALSO 30223 posix_trace_start( ), posix_trace_trid_eventid_open( ), the Base Definitions volume of 30224 IEEE Std 1003.1-200x, , 30225 CHANGE HISTORY 30226 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30227 IEEE PASC Interpretation 1003.1 #123 is applied. | 30228 IEEE PASC Interpretation 1003.1 #127 is applied, correcting some editorial errors in the names of | 30229 the posix_trace_eventid_open( ) function and the event_id argument. | System Interfaces, Issue 6 1427 posix_trace_eventid_equal( ) System Interfaces 30230 NAME 30231 posix_trace_eventid_equal, posix_trace_eventid_get_name, posix_trace_trid_eventid_open - 30232 manipulate trace event type identifier (TRACING) 30233 SYNOPSIS 30234 TRC #include 30235 int posix_trace_eventid_equal(trace_id_t trid, trace_event_id_t event1, | 30236 trace_event_id_t event2); | 30237 int posix_trace_eventid_get_name(trace_id_t trid, | 30238 trace_event_id_t event, char *event_name); | 30239 TRC TEF int posix_trace_trid_eventid_open(trace_id_t trid, | 30240 const char *restrict event_name, 30241 trace_event_id_t *restrict event); | 30242 | 30243 DESCRIPTION 30244 The posix_trace_eventid_equal( ) function shall compare the trace event type identifiers event1 and 30245 event2 from the same trace stream or the same trace log identified by the trid argument. If the 30246 trace event type identifiers event1 and event2 are from different trace streams, the return value 30247 shall be unspecified. 30248 The posix_trace_eventid_get_name( ) function shall return in the argument pointed to by 30249 event_name, the trace event name associated with the trace event type identifier identified by the 30250 argument event, for the trace stream or for the trace log identified by the trid argument. The 30251 name of the trace event shall have a maximum of {TRACE_EVENT_NAME_MAX} characters 30252 (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). Successive calls to 30253 this function with the same trace event type identifier and the same trace stream identifier shall 30254 return the same event name. 30255 TEF The posix_trace_trid_eventid_open( ) function shall associate a user trace event name with a trace | 30256 event type identifier for a given trace stream. The trace stream is identified by the trid argument, 30257 and it shall be an active trace stream. The trace event name is the string pointed to by the 30258 argument event_name. It shall have a maximum of {TRACE_EVENT_NAME_MAX} characters 30259 (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}). The number of user 30260 trace event type identifiers that can be defined for any given process is limited by the maximum 30261 value {TRACE_USER_EVENT_MAX}, which has the minimum value 30262 {_POSIX_TRACE_USER_EVENT_MAX}. 30263 If the Trace Inherit option is not supported, the posix_trace_trid_eventid_open( ) function shall | 30264 associate the user trace event name pointed to by the event_name argument with a trace event 30265 type identifier that is unique for the process being traced in the trace stream identified by the trid 30266 argument, and is returned in the variable pointed to by the event argument. If the user trace 30267 event name has already been mapped for the traced process, then the previously assigned trace 30268 event type identifier shall be returned. If the per-process user trace event name limit represented 30269 by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined 30270 POSIX_TRACE_UNNAMED_USEREVENT (see Table 2-7 (on page 529)) user trace event shall 30271 be returned. 30272 TEF TRI If the Trace Inherit option is supported, the posix_trace_trid_eventid_open( ) function shall | 30273 associate the user trace event name pointed to by the event_name argument with a trace event 30274 type identifier that is unique for all the processes being traced in the trace stream identified by 30275 the trid argument, and is returned in the variable pointed to by the event argument. If the user 30276 trace event name has already been mapped for the traced processes, then the previously 30277 assigned trace event type identifier shall be returned. If the per-process user trace event name 30278 limit represented by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined 1428 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_eventid_equal( ) 30279 POSIX_TRACE_UNNAMED_USEREVENT (see Table 2-7 (on page 529)) user trace event shall 30280 be returned. 30281 RETURN VALUE 30282 TEF Upon successful completion, the posix_trace_eventid_get_name( ) and 30283 posix_trace_trid_eventid_open( )functions shall return a value of zero. Otherwise, they shall return 30284 the corresponding error number. 30285 The posix_trace_eventid_equal( ) function shall return a non-zero value if event1 and event2 are 30286 equal; otherwise, a value of zero shall be returned. No errors are defined. If either event1 or 30287 event2 are not valid trace event type identifiers for the trace stream specified by trid or if the trid 30288 is invalid, the behavior shall be unspecified. 30289 The posix_trace_eventid_get_name( ) function stores the trace event name value in the object 30290 pointed to by event_name, if successful. 30291 TEF The posix_trace_trid_eventid_open( ) function stores the trace event type identifier value in the 30292 object pointed to by event, if successful. 30293 ERRORS 30294 TEF The posix_trace_eventid_get_name( ) andposix_trace_trid_eventid_open( )functions shall fail if: | 30295 [EINVAL] The trid argument was not a valid trace stream identifier. 30296 TEF The posix_trace_trid_eventid_open( ) function shall fail if: | 30297 TEF [ENAMETOOLONG] | 30298 The size of the name pointed to by event_name argument was longer than the 30299 implementation-defined value {TRACE_EVENT_NAME_MAX}. | 30300 The posix_trace_eventid_get_name( ) function shall fail if: | 30301 [EINVAL] The trace event type identifier event was not associated with any name. 30302 EXAMPLES 30303 None. 30304 APPLICATION USAGE 30305 None. 30306 RATIONALE 30307 None. 30308 FUTURE DIRECTIONS 30309 None. 30310 SEE ALSO 30311 posix_trace_event( ), posix_trace_getnext_event( ), the Base Definitions volume of 30312 IEEE Std 1003.1-200x, 30313 CHANGE HISTORY 30314 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30315 IEEE PASC Interpretations 1003.1 #123 and #129 are applied. | System Interfaces, Issue 6 1429 posix_trace_eventid_get_name( ) System Interfaces 30316 NAME 30317 posix_trace_eventid_get_name - manipulate trace event type identifier (TRACING) 30318 SYNOPSIS 30319 TRC #include 30320 int posix_trace_eventid_get_name(trace_id_t trid, | 30321 trace_event_id_t event, char *event_name); | 30322 | 30323 DESCRIPTION 30324 Refer to posix_trace_eventid_equal( ). 1430 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_eventid_open( ) 30325 NAME 30326 posix_trace_eventid_open - trace functions for instrumenting application code (TRACING) 30327 SYNOPSIS 30328 TRC #include 30329 #include 30330 int posix_trace_eventid_open(const char *restrict event_name, 30331 trace_event_id_t *restrict event_id); 30332 30333 DESCRIPTION 30334 Refer to posix_trace_event( ). System Interfaces, Issue 6 1431 posix_trace_eventset_add( ) System Interfaces 30335 NAME 30336 posix_trace_eventset_add, posix_trace_eventset_del, posix_trace_eventset_empty, 30337 posix_trace_eventset_fill, posix_trace_eventset_ismember - manipulate trace event type sets 30338 (TRACING) 30339 SYNOPSIS 30340 TRC TEF #include 30341 int posix_trace_eventset_add(trace_event_id_t event_id, 30342 trace_event_set_t *set); 30343 int posix_trace_eventset_del(trace_event_id_t event_id, 30344 trace_event_set_t *set); 30345 int posix_trace_eventset_empty(trace_event_set_t *set); 30346 int posix_trace_eventset_fill(trace_event_set_t *set, int what); 30347 int posix_trace_eventset_ismember(trace_event_id_t event_id, 30348 const trace_event_set_t *restrict set, 30349 int *restrict ismember); 30350 30351 DESCRIPTION 30352 These primitives manipulate sets of trace event types. They operate on data objects addressable 30353 by the application, not on the current trace event filter of any trace stream. 30354 The posix_trace_eventset_add( ) and posix_trace_eventset_del( ) functions, respectively, shall add or 30355 delete the individual trace event type specified by the value of the argument event_id to or from 30356 the trace event type set pointed to by the argument set. Adding a trace event type already in the 30357 set or deleting a trace event type not in the set shall not be considered an error. 30358 The posix_trace_eventset_empty( ) function shall initialize the trace event type set pointed to by 30359 the set argument such that all trace event types defined, both system and user, shall be excluded 30360 from the set. 30361 The posix_trace_eventset_fill( ) function shall initialize the trace event type set pointed to by the 30362 argument set, such that the set of trace event types defined by the argument what shall be 30363 included in the set. The value of the argument what shall consist of one of the following values, 30364 as defined in the header: 30365 POSIX_TRACE_WOPID_EVENTS 30366 All the process-independent implementation-defined system trace event types are included 30367 in the set. 30368 POSIX_TRACE_SYSTEM_EVENTS All the implementation-defined system trace event types are 30369 included in the set, as are those defined in IEEE Std 1003.1-200x. 30370 POSIX_TRACE_ALL_EVENTS All trace event types defined, both system and user, are included 30371 in the set. 30372 Applications shall call either posix_trace_eventset_empty( ) or posix_trace_eventset_fill( ) at least 30373 once for each object of type trace_event_set_t prior to any other use of that object. If such an 30374 object is not initialized in this way, but is nonetheless supplied as an argument to any of the 30375 posix_trace_eventset_add( ), posix_trace_eventset_del( ), or posix_trace_eventset_ismember( ) functions, 30376 the results are undefined. 30377 The posix_trace_eventset_ismember( ) function shall test whether the trace event type specified by 30378 the value of the argument event_id is a member of the set pointed to by the argument set. The 30379 value returned in the object pointed to by ismember argument is zero if the trace event type 30380 identifier is not a member of the set and a value different from zero if it is a member of the set. | 1432 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_eventset_add( ) 30381 RETURN VALUE 30382 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30383 return the corresponding error number. 30384 ERRORS 30385 These functions may fail if: 30386 [EINVAL] The value of one of the arguments is invalid. 30387 EXAMPLES 30388 None. 30389 APPLICATION USAGE 30390 None. 30391 RATIONALE 30392 None. 30393 FUTURE DIRECTIONS 30394 None. 30395 SEE ALSO 30396 posix_trace_set_filter( ), posix_trace_trid_eventid_open( ), the Base Definitions volume of 30397 IEEE Std 1003.1-200x, 30398 CHANGE HISTORY 30399 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. System Interfaces, Issue 6 1433 posix_trace_eventtypelist_getnext_id( ) System Interfaces 30400 NAME 30401 posix_trace_eventtypelist_getnext_id, posix_trace_eventtypelist_rewind - iterate over a 30402 mapping of trace event types (TRACING) 30403 SYNOPSIS 30404 TRC #include 30405 int posix_trace_eventtypelist_getnext_id(trace_id_t trid, 30406 trace_event_id_t *restrict event, int *restrict unavailable); | 30407 int posix_trace_eventtypelist_rewind(trace_id_t trid); | 30408 30409 DESCRIPTION 30410 The first time posix_trace_eventtypelist_getnext_id( ) is called, the function shall return in the 30411 variable pointed to by event the first trace event type identifier of the list of trace events of the 30412 trace stream identified by the trid argument. Successive calls to 30413 posix_trace_eventtypelist_getnext_id( ) return in the variable pointed to by event the next trace 30414 event type identifier in that same list. Each time a trace event type identifier is successfully 30415 written into the variable pointed to by the event argument, the variable pointed to by the 30416 unavailable argument shall be set to zero. When no more trace event type identifiers are 30417 available, and so none is returned, the variable pointed to by the unavailable argument shall be 30418 set to a value different from zero. 30419 The posix_trace_eventtypelist_rewind( ) function shall reset the next trace event type identifier to 30420 be read to the first trace event type identifier from the list of trace events used in the trace stream 30421 identified by trid. 30422 RETURN VALUE 30423 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30424 return the corresponding error number. 30425 The posix_trace_eventtypelist_getnext_id( ) function stores the trace event type identifier value in 30426 the object pointed to by event, if successful. 30427 ERRORS 30428 These functions shall fail if: | 30429 [EINVAL] The trid argument was not a valid trace stream identifier. 30430 EXAMPLES 30431 None. 30432 APPLICATION USAGE 30433 None. 30434 RATIONALE 30435 None. 30436 FUTURE DIRECTIONS 30437 None. 30438 SEE ALSO 30439 posix_trace_event( ), posix_trace_getnext_event( ), posix_trace_trid_eventid_open( ), the Base 30440 Definitions volume of IEEE Std 1003.1-200x, 30441 CHANGE HISTORY 30442 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30443 IEEE PASC Interpretations 1003.1 #123 and #129 are applied. | 1434 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_flush( ) 30444 NAME 30445 posix_trace_flush - trace stream flush from a process (TRACING) 30446 SYNOPSIS 30447 TRC #include 30448 #include 30449 int posix_trace_flush(trace_id_t trid); 30450 30451 DESCRIPTION 30452 Refer to posix_trace_create( ). System Interfaces, Issue 6 1435 posix_trace_get_attr( ) System Interfaces 30453 NAME 30454 posix_trace_get_attr, posix_trace_get_status - retrieve the trace attributes or trace statuses 30455 (TRACING) 30456 SYNOPSIS 30457 TRC #include 30458 int posix_trace_get_attr(trace_id_t trid, trace_attr_t *attr); 30459 int posix_trace_get_status(trace_id_t trid, 30460 struct posix_trace_status_info *statusinfo); 30461 30462 DESCRIPTION 30463 The posix_trace_get_attr( ) function shall copy the attributes of the active trace stream identified 30464 TRL by trid into the object pointed to by the attr argument. If the Trace Log option is supported, trid 30465 may represent a pre-recorded trace log. 30466 The posix_trace_get_status( ) function shall return, in the structure pointed to by the statusinfo 30467 argument, the current trace status for the trace stream identified by the trid argument. These 30468 status values returned in the structure pointed to by statusinfo shall have been appropriately 30469 TRL read to ensure that the returned values are consistent. If the Trace Log option is supported and 30470 the trid argument refers to a pre-recorded trace stream, the status shall be the status of the 30471 completed trace stream. 30472 Each time the posix_trace_get_status( ) function is used, the overrun status of the trace stream 30473 TRL shall be reset to POSIX_TRACE_NO_OVERRUN immediately after the call completes. If the 30474 Trace Log option is supported, the posix_trace_get_status( ) function shall behave the same as 30475 when the option is not supported except for the following differences: 30476 * If the trid argument refers to a trace stream with log, each time the posix_trace_get_status( ) 30477 function is used, the log overrun status of the trace stream shall be reset to 30478 POSIX_TRACE_NO_OVERRUN and the flush_error status shall be reset to zero immediately 30479 after the call completes. 30480 * If the trid argument refers to a pre-recorded trace stream, the status returned shall be the 30481 status of the completed trace stream and the status values of the trace stream shall not be 30482 reset. 30483 30484 RETURN VALUE 30485 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30486 return the corresponding error number. 30487 The posix_trace_get_attr( ) function stores the trace attributes in the object pointed to by attr, if 30488 successful. 30489 The posix_trace_get_status( ) function stores the trace status in the object pointed to by statusinfo, 30490 if successful. 30491 ERRORS 30492 These functions shall fail if: | 30493 [EINVAL] The trace stream argument trid does not correspond to a valid active trace 30494 stream or a valid trace log. 1436 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_get_attr( ) 30495 EXAMPLES 30496 None. 30497 APPLICATION USAGE 30498 None. 30499 RATIONALE 30500 None. 30501 FUTURE DIRECTIONS 30502 None. 30503 SEE ALSO 30504 posix_trace_attr_destroy( ), posix_trace_attr_init( ), posix_trace_create( ), posix_trace_open( ), the Base 30505 Definitions volume of IEEE Std 1003.1-200x, 30506 CHANGE HISTORY 30507 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30508 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1437 posix_trace_get_filter( ) System Interfaces 30509 NAME 30510 posix_trace_get_filter, posix_trace_set_filter - retrieve and set filter of an initialized trace 30511 stream (TRACING) 30512 SYNOPSIS 30513 TRC TEF #include 30514 int posix_trace_get_filter(trace_id_t trid, trace_event_set_t *set); 30515 int posix_trace_set_filter(trace_id_t trid, 30516 const trace_event_set_t *set, int how); 30517 30518 DESCRIPTION 30519 The posix_trace_get_filter( ) function shall retrieve, into the argument pointed to by set, the actual | 30520 trace event filter from the trace stream specified by trid. 30521 The posix_trace_set_filter( ) function shall change the set of filtered trace event types after a trace | 30522 stream identified by the trid argument is created. This function may be called prior to starting | 30523 the trace stream, or while the trace stream is active. By default, if no call is made to 30524 posix_trace_set_filter( ), all trace events shall be recorded (that is, none of the trace event types are 30525 filtered out). 30526 If this function is called while the trace is in progress, a special system trace event, 30527 POSIX_TRACE_FILTER, shall be recorded in the trace indicating both the old and the new sets 30528 of filtered trace event types (see Table 2-4 (on page 528) and Table 2-6 (on page 529)). 30529 If the posix_trace_set_filter( ) function is interrupted by a signal, an error shall be returned and the | 30530 filter shall not be changed. In this case, the state of the trace stream shall not be changed. | 30531 The value of the argument how indicates the manner in which the set is to be changed and shall 30532 have one of the following values, as defined in the header: 30533 POSIX_TRACE_SET_EVENTSET 30534 The resulting set of trace event types to be filtered shall be the trace event type set pointed 30535 to by the argument set. 30536 POSIX_TRACE_ADD_EVENTSET 30537 The resulting set of trace event types to be filtered shall be the union of the current set and 30538 the trace event type set pointed to by the argument set. 30539 POSIX_TRACE_SUB_EVENTSET 30540 The resulting set of trace event types to be filtered shall be all trace event types in the 30541 current set that are not in the set pointed to by the argument set; that is, remove each 30542 element of the specified set from the current filter. 30543 RETURN VALUE 30544 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30545 return the corresponding error number. 30546 The posix_trace_get_filter( ) function stores the set of filtered trace event types in set, if successful. 30547 ERRORS 30548 These functions shall fail if: | 30549 [EINVAL] The value of the trid argument does not correspond to an active trace stream 30550 or the value of the argument pointed to by set is invalid. 30551 [EINTR] The operation was interrupted by a signal. 1438 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_get_filter( ) 30552 EXAMPLES 30553 None. 30554 APPLICATION USAGE 30555 None. 30556 RATIONALE 30557 None. 30558 FUTURE DIRECTIONS 30559 None. 30560 SEE ALSO 30561 posix_trace_eventset_add( ), the Base Definitions volume of IEEE Std 1003.1-200x, 30562 CHANGE HISTORY 30563 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30564 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1439 posix_trace_get_status( ) System Interfaces 30565 NAME 30566 posix_trace_get_status - retrieve the trace statuses (TRACING) 30567 SYNOPSIS 30568 TRC #include 30569 int posix_trace_get_status(trace_id_t trid, 30570 struct posix_trace_status_info *statusinfo); 30571 30572 DESCRIPTION 30573 Refer to posix_trace_get_attr( ). 1440 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_getnext_event( ) 30574 NAME 30575 posix_trace_getnext_event, posix_trace_timedgetnext_event, posix_trace_trygetnext_event - 30576 retrieve a trace event (TRACING) 30577 SYNOPSIS 30578 TRC #include 30579 #include 30580 int posix_trace_getnext_event(trace_id_t trid, 30581 struct posix_trace_event_info *restrict event, 30582 void *restrict data, size_t num_bytes, 30583 size_t *restrict data_len, int *restrict unavailable); 30584 TRC TMO int posix_trace_timedgetnext_event(trace_id_t trid, 30585 struct posix_trace_event_info *restrict event, 30586 void *restrict data, size_t num_bytes, 30587 size_t *restrict data_len, int *restrict unavailable, 30588 const struct timespec *restrict abs_timeout); 30589 TRC int posix_trace_trygetnext_event(trace_id_t trid, 30590 struct posix_trace_event_info *restrict event, 30591 void *restrict data, size_t num_bytes, 30592 size_t *restrict data_len, int *restrict unavailable); 30593 30594 DESCRIPTION 30595 The posix_trace_getnext_event( ) function shall report a recorded trace event either from an active | 30596 TRL trace stream without log or a pre-recorded trace stream identified by the trid argument. The 30597 posix_trace_trygetnext_event( ) function shall report a recorded trace event from an active trace | 30598 stream without log identified by the trid argument. 30599 The trace event information associated with the recorded trace event shall be copied by the 30600 function into the structure pointed to by the argument event and the data associated with the 30601 trace event shall be copied into the buffer pointed to by the data argument. 30602 The posix_trace_getnext_event( ) function shall block if the trid argument identifies an active trace 30603 stream and there is currently no trace event ready to be retrieved. When returning, if a recorded 30604 trace event was reported, the variable pointed to by the unavailable argument shall be set to zero. 30605 Otherwise, the variable pointed to by the unavailable argument shall be set to a value different 30606 from zero. 30607 TMO The posix_trace_timedgetnext_event( ) function shall attempt to get another trace event from an | 30608 active trace stream without log, as in the posix_trace_getnext_event( ) function. However, if no | 30609 trace event is available from the trace stream, the implied wait shall be terminated when the | 30610 timeout specified by the argument abs_timeout expires, and the function shall return the error | 30611 [ETIMEDOUT]. 30612 The timeout shall expire when the absolute time specified by abs_timeout passes, as measured by | 30613 the clock upon which timeouts are based (that is, when the value of that clock equals or exceeds 30614 abs_timeout), or if the absolute time specified by abs_timeout has already passed at the time of the 30615 call. 30616 TMO TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; | 30617 if the Timers option is not supported, the timeout shall be based on the system clock as returned | 30618 by the time( ) function. The resolution of the timeout shall be the resolution of the clock on which | 30619 it is based. The timespec data type is defined in the header. | 30620 TMO Under no circumstance shall the function fail with a timeout if a trace event is immediately | 30621 available from the trace stream. The validity of the abs_timeout argument need not be checked if System Interfaces, Issue 6 1441 posix_trace_getnext_event( ) System Interfaces 30622 a trace event is immediately available from the trace stream. 30623 The behavior of this function for a pre-recorded trace stream is unspecified. 30624 TRL The posix_trace_trygetnext_event( ) function shall not block. This function shall return an error if 30625 the trid argument identifies a pre-recorded trace stream. If a recorded trace event was reported, 30626 the variable pointed to by the unavailable argument shall be set to zero. Otherwise, if no trace 30627 event was reported, the variable pointed to by the unavailable argument shall be set to a value 30628 different from zero. 30629 The argument num_bytes shall be the size of the buffer pointed to by the data argument. The 30630 argument data_len reports to the application the length in bytes of the data record just 30631 transferred. If num_bytes is greater than or equal to the size of the data associated with the trace 30632 event pointed to by the event argument, all the recorded data shall be transferred. In this case, the 30633 truncation-status member of the trace event structure shall be either 30634 POSIX_TRACE_NOT_TRUNCATED, if the trace event data was recorded without truncation 30635 while tracing, or POSIX_TRACE_TRUNCATED_RECORD, if the trace event data was truncated 30636 when it was recorded. If the num_bytes argument is less than the length of recorded trace event 30637 data, the data transferred shall be truncated to a length of num_bytes, the value stored in the 30638 variable pointed to by data_len shall be equal to num_bytes, and the truncation-status member of 30639 the event structure argument shall be set to POSIX_TRACE_TRUNCATED_READ (see the 30640 posix_trace_event_info( ) function). 30641 The report of a trace event shall be sequential starting from the oldest recorded trace event. Trace 30642 events shall be reported in the order in which they were generated, up to an implementation- 30643 defined time resolution that causes the ordering of trace events occurring very close to each 30644 other to be unknown. Once reported, a trace event cannot be reported again from an active trace 30645 stream. Once a trace event is reported from an active trace stream without log, the trace stream 30646 shall make the resources associated with that trace event available to record future generated 30647 trace events. 30648 RETURN VALUE 30649 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30650 return the corresponding error number. 30651 If successful, these functions store: 30652 * The recorded trace event in the object pointed to by event 30653 * The trace event information associated with the recorded trace event in the object pointed to 30654 by data 30655 * The length of this trace event information in the object pointed to by data_len 30656 * The value of zero in the object pointed to by unavailable 30657 ERRORS 30658 These functions shall fail if: | 30659 [EINVAL] The trace stream identifier argument trid is invalid. 30660 The posix_trace_getnext_event( ) and posix_trace_timedgetnext_event( ) functions shall fail if: | 30661 [EINTR] The operation was interrupted by a signal, and so the call had no effect. 30662 The posix_trace_trygetnext_event( ) function shall fail if: | 30663 [EINVAL] The trace stream identifier argument trid does not correspond to an active 30664 trace stream. 1442 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_getnext_event( ) 30665 TMO The posix_trace_timedgetnext_event( ) function shall fail if: | 30666 [EINVAL] There is no trace event immediately available from the trace stream, and the 30667 timeout argument is invalid. 30668 [ETIMEDOUT] No trace event was available from the trace stream before the specified 30669 timeout timeout expired. 30670 30671 EXAMPLES 30672 None. 30673 APPLICATION USAGE 30674 None. 30675 RATIONALE 30676 None. 30677 FUTURE DIRECTIONS 30678 None. 30679 SEE ALSO 30680 posix_trace_create( ), posix_trace_event_info Structure, posix_trace_open( ), the Base Definitions 30681 volume of IEEE Std 1003.1-200x, , 30682 CHANGE HISTORY 30683 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30684 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1443 posix_trace_open( ) System Interfaces 30685 NAME 30686 posix_trace_open - trace log management (TRACING) 30687 SYNOPSIS 30688 TCT TRL #include 30689 int posix_trace_open(int file_desc, trace_id_t *trid); 30690 30691 DESCRIPTION 30692 Refer to posix_trace_close( ). 1444 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_rewind( ) 30693 NAME 30694 posix_trace_rewind - trace log management (TRACING) 30695 SYNOPSIS 30696 TCT TRL #include 30697 int posix_trace_rewind(trace_id_t trid); 30698 30699 DESCRIPTION 30700 Refer to posix_trace_close( ). System Interfaces, Issue 6 1445 posix_trace_set_filter( ) System Interfaces 30701 NAME 30702 posix_trace_set_filter - set filter of an initialized trace stream (TRACING) 30703 SYNOPSIS 30704 TRC TEF #include 30705 int posix_trace_set_filter(trace_id_t trid, 30706 const trace_event_set_t *set, int how); 30707 30708 DESCRIPTION 30709 Refer to posix_trace_get_filter( ). 1446 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_shutdown( ) 30710 NAME 30711 posix_trace_shutdown - trace stream shutdown from a process (TRACING) 30712 SYNOPSIS 30713 TRC #include 30714 #include 30715 int posix_trace_shutdown(trace_id_t trid); 30716 30717 DESCRIPTION 30718 Refer to posix_trace_create( ). System Interfaces, Issue 6 1447 posix_trace_start( ) System Interfaces 30719 NAME 30720 posix_trace_start, posix_trace_stop - trace start and stop (TRACING) 30721 SYNOPSIS 30722 TRC #include 30723 int posix_trace_start(trace_id_t trid); 30724 int posix_trace_stop (trace_id_t trid); 30725 30726 DESCRIPTION 30727 The posix_trace_start( ) and posix_trace_stop( ) functions, respectively, shall start and stop the 30728 trace stream identified by the argument trid. 30729 The effect of calling the posix_trace_start( ) function shall be recorded in the trace stream as the 30730 POSIX_TRACE_START system trace event and the status of the trace stream shall become 30731 POSIX_TRACE_RUNNING. If the trace stream is in progress when this function is called, the 30732 POSIX_TRACE_START system trace event shall not be recorded and the trace stream shall 30733 continue to run. If the trace stream is full, the POSIX_TRACE_START system trace event shall 30734 not be recorded and the status of the trace stream shall not be changed. 30735 The effect of calling the posix_trace_stop( ) function shall be recorded in the trace stream as the 30736 POSIX_TRACE_STOP system trace event and the status of the trace stream shall become 30737 POSIX_TRACE_SUSPENDED. If the trace stream is suspended when this function is called, the 30738 POSIX_TRACE_STOP system trace event shall not be recorded and the trace stream shall remain 30739 suspended. If the trace stream is full, the POSIX_TRACE_STOP system trace event shall not be 30740 recorded and the status of the trace stream shall not be changed. 30741 RETURN VALUE 30742 Upon successful completion, these functions shall return a value of zero. Otherwise, they shall 30743 return the corresponding error number. 30744 ERRORS 30745 These functions shall fail if: | 30746 [EINVAL] The value of the argument trid does not correspond to an active trace stream 30747 and thus no trace stream was started or stopped. 30748 [EINTR] The operation was interrupted by a signal and thus the trace stream was not 30749 necessarily started or stopped. 30750 EXAMPLES 30751 None. 30752 APPLICATION USAGE 30753 None. 30754 RATIONALE 30755 None. 30756 FUTURE DIRECTIONS 30757 None. 30758 SEE ALSO 30759 posix_trace_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1448 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_start( ) 30760 CHANGE HISTORY 30761 First released in Issue 6. Derived from IEEE Std 1003.1q-2000. | 30762 IEEE PASC Interpretation 1003.1 #123 is applied. | System Interfaces, Issue 6 1449 posix_trace_timedgetnext_event( ) System Interfaces 30763 NAME 30764 posix_trace_timedgetnext_event, - retrieve a trace event (TRACING) 30765 SYNOPSIS 30766 TRC TMO #include 30767 #include 30768 int posix_trace_timedgetnext_event(trace_id_t trid, 30769 struct posix_trace_event_info *restrict event, 30770 void *restrict data, size_t num_bytes, 30771 size_t *restrict data_len, int *restrict unavailable, 30772 const struct timespec *restrict abs_timeout); 30773 30774 DESCRIPTION 30775 Refer to posix_trace_getnext_event( ). 1450 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_trace_trid_eventid_open( ) 30776 NAME 30777 posix_trace_trid_eventid_open - manipulate trace event type identifier (TRACING) 30778 SYNOPSIS 30779 TRC TEF #include 30780 int posix_trace_trid_eventid_open(trace_id_t trid, 30781 const char *restrict event_name, 30782 trace_event_id_t *restrict event); | 30783 | 30784 DESCRIPTION 30785 Refer to posix_trace_eventid_equal( ). System Interfaces, Issue 6 1451 posix_trace_trygetnext_event( ) System Interfaces 30786 NAME 30787 posix_trace_trygetnext_event - retrieve a trace event (TRACING) 30788 SYNOPSIS 30789 TRC #include 30790 #include 30791 int posix_trace_trygetnext_event(trace_id_t trid, 30792 struct posix_trace_event_info *restrict event, 30793 void *restrict data, size_t num_bytes, 30794 size_t *restrict data_len, int *restrict unavailable); 30795 30796 DESCRIPTION 30797 Refer to posix_trace_getnext_event( ). 1452 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_typed_mem_get_info( ) 30798 NAME 30799 posix_typed_mem_get_info - query typed memory information (ADVANCED REALTIME) 30800 SYNOPSIS 30801 TYM #include 30802 int posix_typed_mem_get_info(int fildes, 30803 struct posix_typed_mem_info *info); 30804 30805 DESCRIPTION 30806 The posix_typed_mem_get_info( ) function shall return, in the posix_tmi_length field of the 30807 posix_typed_mem_info structure pointed to by info, the maximum length which may be 30808 successfully allocated by the typed memory object designated by fildes. This maximum length 30809 shall take into account the flag POSIX_TYPED_MEM_ALLOCATE or 30810 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified when the typed memory object 30811 represented by fildes was opened. The maximum length is dynamic; therefore, the value returned 30812 is valid only while the current mapping of the corresponding typed memory pool remains 30813 unchanged. 30814 If fildes represents a typed memory object opened with neither the 30815 POSIX_TYPED_MEM_ALLOCATE flag nor the POSIX_TYPED_MEM_ALLOCATE_CONTIG 30816 flag specified, the returned value of info->posix_tmi_length is unspecified. 30817 The posix_typed_mem_get_info( ) function may return additional implementation-defined 30818 information in other fields of the posix_typed_mem_info structure pointed to by info. 30819 If the memory object specified by fildes is not a typed memory object, then the behavior of this 30820 function is undefined. 30821 RETURN VALUE 30822 Upon successful completion, the posix_typed_mem_get_info( ) function shall return zero; 30823 otherwise, the corresponding error status value shall be returned. 30824 ERRORS 30825 The posix_typed_mem_get_info( ) function shall fail if: 30826 [EBADF] The fildes argument is not a valid open file descriptor. 30827 [ENODEV] The fildes argument is not connected to a memory object supported by this 30828 function. 30829 This function shall not return an error code of [EINTR]. 30830 EXAMPLES 30831 None. 30832 APPLICATION USAGE 30833 None. 30834 RATIONALE 30835 An application that needs to allocate a block of typed memory with length dependent upon the 30836 amount of memory currently available must either query the typed memory object to obtain the 30837 amount available, or repeatedly invoke mmap( ) attempting to guess an appropriate length. 30838 While the latter method is existing practice with malloc( ), it is awkward and imprecise. The 30839 posix_typed_mem_get_info( ) function allows an application to immediately determine available 30840 memory. This is particularly important for typed memory objects that may in some cases be 30841 scarce resources. Note that when a typed memory pool is a shared resource, some form of 30842 mutual exclusion or synchronization may be required while typed memory is being queried and System Interfaces, Issue 6 1453 posix_typed_mem_get_info( ) System Interfaces 30843 allocated to prevent race conditions. 30844 The existing fstat( ) function is not suitable for this purpose. We realize that implementations 30845 may wish to provide other attributes of typed memory objects (for example, alignment 30846 requirements, page size, and so on). The fstat( ) function returns a structure which is not 30847 extensible and, furthermore, contains substantial information that is inappropriate for typed 30848 memory objects. 30849 FUTURE DIRECTIONS 30850 None. 30851 SEE ALSO 30852 fstat( ), mmap( ), posix_typed_mem_open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 30853 30854 CHANGE HISTORY 30855 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 1454 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_typed_mem_open( ) 30856 NAME 30857 posix_typed_mem_open - open a typed memory object (ADVANCED REALTIME) 30858 SYNOPSIS 30859 TYM #include 30860 int posix_typed_mem_open(const char *name, int oflag, int tflag); 30861 30862 DESCRIPTION 30863 The posix_typed_mem_open( ) function shall establish a connection between the typed memory 30864 object specified by the string pointed to by name and a file descriptor. It shall create an open file 30865 description that refers to the typed memory object and a file descriptor that refers to that open 30866 file description. The file descriptor is used by other functions to refer to that typed memory 30867 object. It is unspecified whether the name appears in the file system and is visible to other | 30868 functions that take pathnames as arguments. The name argument shall conform to the | 30869 construction rules for a pathname. If name begins with the slash character, then processes calling | 30870 posix_typed_mem_open( ) with the same value of name shall refer to the same typed memory 30871 object. If name does not begin with the slash character, the effect is implementation-defined. The 30872 interpretation of slash characters other than the leading slash character in name is 30873 implementation-defined. 30874 Each typed memory object supported in a system shall be identified by a name which specifies | 30875 not only its associated typed memory pool, but also the path or port by which it is accessed. That 30876 is, the same typed memory pool accessed via several different ports shall have several different | 30877 corresponding names. The binding between names and typed memory objects is established in 30878 an implementation-defined manner. Unlike shared memory objects, there is no way within | 30879 IEEE Std 1003.1-200x for a program to create a typed memory object. | 30880 The value of tflag shall determine how the typed memory object behaves when subsequently | 30881 mapped by calls to mmap( ). At most, one of the following flags defined in may | 30882 be specified: 30883 POSIX_TYPED_MEM_ALLOCATE 30884 Allocate on mmap( ). 30885 POSIX_TYPED_MEM_ALLOCATE_CONTIG 30886 Allocate contiguously on mmap( ). 30887 POSIX_TYPED_MEM_MAP_ALLOCATABLE 30888 Map on mmap( ), without affecting allocatability. 30889 If tflag has the flag POSIX_TYPED_MEM_ALLOCATE specified, any subsequent call to mmap( ) 30890 using the returned file descriptor shall result in allocation and mapping of typed memory from 30891 the specified typed memory pool. The allocated memory may be a contiguous previously 30892 unallocated area of the typed memory pool or several non-contiguous previously unallocated 30893 areas (mapped to a contiguous portion of the process address space). If tflag has the flag 30894 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to mmap( ) using the 30895 returned file descriptor shall result in allocation and mapping of a single contiguous previously 30896 unallocated area of the typed memory pool (also mapped to a contiguous portion of the process 30897 address space). If tflag has none of the flags POSIX_TYPED_MEM_ALLOCATE or 30898 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to mmap( ) using the 30899 returned file descriptor shall map an application-chosen area from the specified typed memory 30900 pool such that this mapped area becomes unavailable for allocation until unmapped by all 30901 processes. If tflag has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, any 30902 subsequent call to mmap( ) using the returned file descriptor shall map an application-chosen 30903 area from the specified typed memory pool without an effect on the availability of that area for System Interfaces, Issue 6 1455 posix_typed_mem_open( ) System Interfaces 30904 allocation; that is, mapping such an object leaves each byte of the mapped area unallocated if it 30905 was unallocated prior to the mapping or allocated if it was allocated prior to the mapping. The 30906 appropriate privilege to specify the POSIX_TYPED_MEM_MAP_ALLOCATABLE flag is 30907 implementation-defined. 30908 If successful, posix_typed_mem_open( ) shall return a file descriptor for the typed memory object 30909 that is the lowest numbered file descriptor not currently open for that process. The open file 30910 description is new, and therefore the file descriptor shall not share it with any other processes. It | 30911 is unspecified whether the file offset is set. The FD_CLOEXEC file descriptor flag associated | 30912 with the new file descriptor shall be cleared. 30913 The behavior of msync( ), ftruncate( ), and all file operations other than mmap( ), 30914 posix_mem_offset( ), posix_typed_mem_get_info( ), fstat( ), dup( ), dup2( ), and close( ), is unspecified 30915 when passed a file descriptor connected to a typed memory object by this function. 30916 The file status flags of the open file description shall be set according to the value of oflag. 30917 Applications shall specify exactly one of the three access mode values described below and 30918 defined in the header, as the value of oflag. 30919 O_RDONLY Open for read access only. 30920 O_WRONLY Open for write access only. 30921 O_RDWR Open for read or write access. 30922 RETURN VALUE 30923 Upon successful completion, the posix_typed_mem_open( ) function shall return a non-negative 30924 integer representing the lowest numbered unused file descriptor. Otherwise, it shall return -1 30925 and set errno to indicate the error. 30926 ERRORS 30927 The posix_typed_mem_open( ) function shall fail if: 30928 [EACCES] The typed memory object exists and the permissions specified by oflag are 30929 denied. 30930 [EINTR] The posix_typed_mem_open( ) operation was interrupted by a signal. 30931 [EINVAL] The flags specified in tflag are invalid (more than one of 30932 POSIX_TYPED_MEM_ALLOCATE, 30933 POSIX_TYPED_MEM_ALLOCATE_CONTIG, or 30934 POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified). 30935 [EMFILE] Too many file descriptors are currently in use by this process. 30936 [ENAMETOOLONG] 30937 The length of the name argument exceeds {PATH_MAX} or a pathname | 30938 component is longer than {NAME_MAX}. | 30939 [ENFILE] Too many file descriptors are currently open in the system. 30940 [ENOENT] The named typed memory object does not exist. 30941 [EPERM] The caller lacks the appropriate privilege to specify the flag 30942 POSIX_TYPED_MEM_MAP_ALLOCATABLE in argument tflag. 1456 Technical Standard (2001) (Draft April 16, 2001) System Interfaces posix_typed_mem_open( ) 30943 EXAMPLES 30944 None. 30945 APPLICATION USAGE 30946 None. 30947 RATIONALE 30948 None. 30949 FUTURE DIRECTIONS 30950 None. 30951 SEE ALSO 30952 close( ), dup( ), exec, fcntl( ), fstat( ), ftruncate( ), mmap( ), msync( ), posix_mem_offset( ), 30953 posix_typed_mem_get_info( ), umask( ), the Base Definitions volume of IEEE Std 1003.1-200x, 30954 30955 CHANGE HISTORY 30956 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. System Interfaces, Issue 6 1457 pow( ) System Interfaces 30957 NAME 30958 pow, powf, powl - power function 30959 SYNOPSIS 30960 #include 30961 double pow(double x, double y); 30962 float powf(float x, float y); 30963 long double powl(long double x, long double y); 30964 DESCRIPTION 30965 CX The functionality described on this reference page is aligned with the ISO C standard. Any 30966 conflict between the requirements described here and the ISO C standard is unintentional. This 30967 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 30968 These functions shall compute the value of x raised to the power y, xy. If x is negative, the 30969 application shall ensure that y is an integer value. 30970 An application wishing to check for error situations should set errno to zero and call 30971 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 30972 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 30973 zero, an error has occurred. 30974 RETURN VALUE 30975 Upon successful completion, these functions shall return the value of x raised to the power y. 30976 MX For finite values of x < 0, and finite non-integer values of y, a domain error shall occur and either 30977 a NaN (if representable), oran implementation-defined value shall be returned. 30978 If the correct value would cause overflow, a range error shall occur and pow( ), powf( ), and 30979 powl( ) shall return HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 30980 If the correct value would cause underflow, and is not representable, a range error may occur, 30981 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 30982 MX If x or y is a NaN, a NaN shall be returned (unless specified elsewhere in this description). 30983 For any value of y (including NaN), if x is +1, 1.0 shall be returned. 30984 For any value of x (including NaN), if y is ±0, 1.0 shall be returned. 30985 For any odd integer value of y > 0, if x is ±0, ±0 shall be returned. 30986 For y > 0 and not an odd integer, if x is ±0, +0 shall be returned. 30987 If x is -1, and y is ±Inf, 1.0 shall be returned. 30988 For |x| < 1, if y is -Inf, +Inf shall be returned. 30989 For |x| > 1, if y is -Inf, +0 shall be returned. 30990 For |x| < 1, if y is +Inf, +0 shall be returned. 30991 For |x| > 1, if y is +Inf, +Inf shall be returned. 30992 For y an odd integer < 0, if x is -Inf, -0 shall be returned. 30993 For y < 0 and not an odd integer, if x is -Inf, +0 shall be returned. 30994 For y an odd integer > 0, if x is -Inf, -Inf shall be returned. 30995 For y > 0 and not an odd integer, if x is -Inf, +Inf shall be returned. 1458 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pow( ) 30996 For y < 0, if x is +Inf, +0 shall be returned. 30997 For y > 0, if x is +Inf, +Inf shall be returned. 30998 For y an odd integer < 0, if x is ±0, a pole error shall occur and ±HUGE_VAL, ±HUGE_VALF, and 30999 ±HUGE_VALL shall be returned for pow( ), powf( ), and powl( ), respectively. 31000 For y < 0 and not an odd integer, if x is ±0, a pole error shall occur and HUGE_VAL, 31001 HUGE_VALF, and HUGE_VALL shall be returned for pow( ), powf( ), and powl( ), respectively. 31002 If the correct value would cause underflow, and is representable, a range error may occur and 31003 the correct value shall be returned. 31004 ERRORS 31005 These functions shall fail if: 31006 Domain Error The value of x is negative and y is a finite non-integer. 31007 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 31008 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 31009 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 31010 shall be raised. | 31011 MX Pole Error The value of x is zero and y is negative. 31012 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 31013 then errno shall be set to [ERANGE]. If the integer expression | 31014 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 31015 zero floating-point exception shall be raised. | 31016 Range Error The result overflows. 31017 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 31018 then errno shall be set to [ERANGE]. If the integer expression | 31019 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 31020 floating-point exception shall be raised. | 31021 These functions may fail if: 31022 Range Error The result underflows. 31023 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 31024 then errno shall be set to [ERANGE]. If the integer expression | 31025 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 31026 floating-point exception shall be raised. | 31027 EXAMPLES 31028 None. 31029 APPLICATION USAGE 31030 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 31031 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 31032 RATIONALE 31033 None. 31034 FUTURE DIRECTIONS 31035 None. System Interfaces, Issue 6 1459 pow( ) System Interfaces 31036 SEE ALSO 31037 exp( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 31038 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 31039 CHANGE HISTORY 31040 First released in Issue 1. Derived from Issue 1 of the SVID. 31041 Issue 5 31042 The DESCRIPTION is updated to indicate how an application should check for an error. This 31043 text was previously published in the APPLICATION USAGE section. 31044 Issue 6 31045 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 31046 The powf( ) and powl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 31047 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 31048 revised to align with the ISO/IEC 9899: 1999 standard. 31049 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 31050 marked. 1460 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pread( ) 31051 NAME 31052 pread - read from a file 31053 SYNOPSIS 31054 XSI #include 31055 ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); 31056 31057 DESCRIPTION 31058 Refer to read( ). System Interfaces, Issue 6 1461 printf( ) System Interfaces 31059 NAME 31060 printf - print formatted output 31061 SYNOPSIS 31062 #include 31063 int printf(const char *restrict format, ...); 31064 DESCRIPTION 31065 Refer to fprintf( ). 1462 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pselect( ) 31066 NAME 31067 pselect, select - synchronous I/O multiplexing 31068 SYNOPSIS 31069 #include 31070 int pselect(int nfds, fd_set *restrict readfds, 31071 fd_set *restrict writefds, fd_set *restrict errorfds, 31072 const struct timespec *restrict timeout, 31073 const sigset_t *restrict sigmask); 31074 int select(int nfds, fd_set *restrict readfds, 31075 fd_set *restrict writefds, fd_set *restrict errorfds, 31076 struct timeval *restrict timeout); 31077 void FD_CLR(int fd, fd_set *fdset); 31078 int FD_ISSET(int fd, fd_set *fdset); 31079 void FD_SET(int fd, fd_set *fdset); 31080 void FD_ZERO(fd_set *fdset); 31081 DESCRIPTION 31082 The pselect( ) function shall examine the file descriptor sets whose addresses are passed in the 31083 readfds, writefds, and errorfds parameters to see if some of their descriptors are ready for reading, 31084 are ready for writing, or have an exceptional condition pending, respectively. 31085 The select( ) function shall be equivalent to the pselect( ) function, except as follows: 31086 * For the select( ) function, the timeout period is given in seconds and microseconds in an 31087 argument of type struct timeval, whereas for the pselect( ) function the timeout period is 31088 given in seconds and nanoseconds in an argument of type struct timespec. 31089 * The select( ) function has no sigmask argument; it shall behave as pselect( ) does when sigmask 31090 is a null pointer. 31091 * Upon successful completion, the select( ) function may modify the object pointed to by the 31092 timeout argument. 31093 The pselect( ) and select( ) functions shall support regular files, terminal and pseudo-terminal 31094 XSR devices, STREAMS-based files, FIFOs, pipes, and sockets. The behavior of pselect( ) and select( ) 31095 on file descriptors that refer to other types of file is unspecified. 31096 The nfds argument specifies the range of descriptors to be tested. The first nfds descriptors shall 31097 be checked in each set; that is, the descriptors from zero through nfds-1 in the descriptor sets 31098 shall be examined. 31099 If the readfds argument is not a null pointer, it points to an object of type fd_set that on input 31100 specifies the file descriptors to be checked for being ready to read, and on output indicates 31101 which file descriptors are ready to read. 31102 If the writefds argument is not a null pointer, it points to an object of type fd_set that on input 31103 specifies the file descriptors to be checked for being ready to write, and on output indicates 31104 which file descriptors are ready to write. 31105 If the errorfds argument is not a null pointer, it points to an object of type fd_set that on input 31106 specifies the file descriptors to be checked for error conditions pending, and on output indicates 31107 which file descriptors have error conditions pending. 31108 Upon successful completion, the pselect( ) or select( ) function shall modify the objects pointed to 31109 by the readfds, writefds, and errorfds arguments to indicate which file descriptors are ready for 31110 reading, ready for writing, or have an error condition pending, respectively, and shall return the 31111 total number of ready descriptors in all the output sets. For each file descriptor less than nfds, the System Interfaces, Issue 6 1463 pselect( ) System Interfaces 31112 corresponding bit shall be set on successful completion if it was set on input and the associated 31113 condition is true for that file descriptor. 31114 If none of the selected descriptors are ready for the requested operation, the pselect( ) or select( ) | 31115 function shall block until at least one of the requested operations becomes ready, until the | 31116 timeout occurs, or until interrupted by a signal. The timeout parameter controls how long the | 31117 pselect( ) or select( ) function shall take before timing out. If the timeout parameter is not a null | 31118 pointer, it specifies a maximum interval to wait for the selection to complete. If the specified 31119 time interval expires without any requested operation becoming ready, the function shall return. 31120 If the timeout parameter is a null pointer, then the call to pselect( ) or select( ) shall block 31121 indefinitely until at least one descriptor meets the specified criteria. To effect a poll, the timeout 31122 parameter should not be a null pointer, and should point to a zero-valued timespec structure. 31123 The use of a timeout does not affect any pending timers set up by alarm( ), ualarm( ), or 31124 setitimer( ). 31125 Implementations may place limitations on the maximum timeout interval supported. All 31126 implementations shall support a maximum timeout interval of at least 31 days. If the timeout 31127 argument specifies a timeout interval greater than the implementation-defined maximum value, 31128 the maximum value shall be used as the actual timeout value. Implementations may also place 31129 limitations on the granularity of timeout intervals. If the requested timeout interval requires a 31130 finer granularity than the implementation supports, the actual timeout interval shall be rounded 31131 up to the next supported value. 31132 If sigmask is not a null pointer, then the pselect( ) function shall replace the signal mask of the 31133 process by the set of signals pointed to by sigmask before examining the descriptors, and shall 31134 restore the signal mask of the process before returning. 31135 A descriptor shall be considered ready for reading when a call to an input function with 31136 O_NONBLOCK clear would not block, whether or not the function would transfer data 31137 successfully. (The function might return data, an end-of-file indication, or an error other than 31138 one indicating that it is blocked, and in each of these cases the descriptor shall be considered 31139 ready for reading.) 31140 A descriptor shall be considered ready for writing when a call to an output function with 31141 O_NONBLOCK clear would not block, whether or not the function would transfer data 31142 successfully. 31143 If a socket has a pending error, it shall be considered to have an exceptional condition pending. 31144 Otherwise, what constitutes an exceptional condition is file type-specific. For a file descriptor for 31145 use with a socket, it is protocol-specific except as noted below. For other file types it is 31146 implementation-defined. If the operation is meaningless for a particular file type, pselect( ) or 31147 select( ) shall indicate that the descriptor is ready for read or write operations, and shall indicate 31148 that the descriptor has no exceptional condition pending. 31149 If a descriptor refers to a socket, the implied input function is the recvmsg( ) function with 31150 parameters requesting normal and ancillary data, such that the presence of either type shall 31151 cause the socket to be marked as readable. The presence of out-of-band data shall be checked if | 31152 the socket option SO_OOBINLINE has been enabled, as out-of-band data is enqueued with | 31153 normal data. If the socket is currently listening, then it shall be marked as readable if an | 31154 incoming connection request has been received, and a call to the accept( ) function shall complete | 31155 without blocking. | 31156 If a descriptor refers to a socket, the implied output function is the sendmsg( ) function supplying 31157 an amount of normal data equal to the current value of the SO_SNDLOWAT option for the 31158 socket. If a non-blocking call to the connect( ) function has been made for a socket, and the 31159 connection attempt has either succeeded or failed leaving a pending error, the socket shall be 1464 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pselect( ) 31160 marked as writable. 31161 A socket shall be considered to have an exceptional condition pending if a receive operation 31162 with O_NONBLOCK clear for the open file description and with the MSG_OOB flag set would 31163 return out-of-band data without blocking. (It is protocol-specific whether the MSG_OOB flag 31164 would be used to read out-of-band data.) A socket shall also be considered to have an 31165 exceptional condition pending if an out-of-band data mark is present in the receive queue. Other 31166 circumstances under which a socket may be considered to have an exceptional condition 31167 pending are protocol-specific and implementation-defined. 31168 If the readfds, writefds, and errorfds arguments are all null pointers and the timeout argument is not 31169 a null pointer, the pselect( ) or select( ) function shall block for the time specified, or until | 31170 interrupted by a signal. If the readfds, writefds, and errorfds arguments are all null pointers and the | 31171 timeout argument is a null pointer, the pselect( ) or select( ) function shall block until interrupted | 31172 by a signal. | 31173 File descriptors associated with regular files shall always select true for ready to read, ready to 31174 write, and error conditions. 31175 On failure, the objects pointed to by the readfds, writefds, and errorfds arguments shall not be | 31176 modified. If the timeout interval expires without the specified condition being true for any of the | 31177 specified file descriptors, the objects pointed to by the readfds, writefds, and errorfds arguments | 31178 shall have all bits set to 0. | 31179 File descriptor masks of type fd_set can be initialized and tested with FD_CLR( ), FD_ISSET( ), 31180 FD_SET( ), and FD_ZERO( ). It is unspecified whether each of these is a macro or a function. If a 31181 macro definition is suppressed in order to access an actual function, or a program defines an 31182 external identifier with any of these names, the behavior is undefined. 31183 FD_CLR(fd, fdsetp) shall remove the file descriptor fd from the set pointed to by fdsetp. If fd is not | 31184 a member of this set, there shall be no effect on the set, nor will an error be returned. 31185 FD_ISSET(fd, fdsetp) shall evaluate to non-zero if the file descriptor fd is a member of the set | 31186 pointed to by fdsetp, and shall evaluate to zero otherwise. 31187 FD_SET(fd, fdsetp) shall add the file descriptor fd to the set pointed to by fdsetp. If the file | 31188 descriptor fd is already in this set, there shall be no effect on the set, nor will an error be returned. 31189 FD_ZERO(fdsetp) shall initialize the descriptor set pointed to by fdsetp to the null set. No error is | 31190 returned if the set is not empty at the time FD_ZERO( ) is invoked. 31191 The behavior of these macros is undefined if the fd argument is less than 0 or greater than or 31192 equal to FD_SETSIZE, or if fd is not a valid file descriptor, or if any of the arguments are 31193 expressions with side effects. 31194 RETURN VALUE 31195 Upon successful completion, the pselect( ) and select( ) functions shall return the total number of 31196 bits set in the bit masks. Otherwise, -1 shall be returned, and shall set errno to indicate the error. 31197 FD_CLR( ), FD_SET( ), and FD_ZERO( ) not return a value. FD_ISSET( ) shall return a non-zero 31198 value if the bit for the file descriptor fd is set in the file descriptor set pointed to by fdset, and 0 31199 otherwise. 31200 ERRORS 31201 Under the following conditions, pselect( ) and select( ) shall fail and set errno to: 31202 [EBADF] One or more of the file descriptor sets specified a file descriptor that is not a 31203 valid open file descriptor. System Interfaces, Issue 6 1465 pselect( ) System Interfaces 31204 [EINTR] The function was interrupted before any of the selected events occurred and 31205 before the timeout interval expired. 31206 XSI If SA_RESTART has been set for the interrupting signal, it is implementation- 31207 defined whether the function restarts or returns with [EINTR]. 31208 [EINVAL] An invalid timeout interval was specified. 31209 [EINVAL] The nfds argument is less than 0 or greater than FD_SETSIZE. 31210 XSR [EINVAL] One of the specified file descriptors refers to a STREAM or multiplexer that is 31211 linked (directly or indirectly) downstream from a multiplexer. 31212 EXAMPLES 31213 None. 31214 APPLICATION USAGE 31215 None. 31216 RATIONALE 31217 In previous versions of the Single UNIX Specification, the select( ) function was defined in the 31218 header. This is now changed to . The rationale for this change was 31219 as follows: the introduction of the pselect( ) function included the header and the 31220 header defines all the related definitions for the pselect( ) and select( ) functions. 31221 Backwards-compatibility to existing XSI implementations is handled by allowing 31222 to include . 31223 FUTURE DIRECTIONS 31224 None. 31225 SEE ALSO 31226 accept( ), alarm( ), connect( ), fcntl( ), poll( ), read( ), recvmsg( ), sendmsg( ), setitimer( ), ualarm( ), 31227 write( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 31228 CHANGE HISTORY 31229 First released in Issue 4, Version 2. 31230 Issue 5 31231 Moved from X/OPEN UNIX extension to BASE. 31232 In the ERRORS section, the text has been changed to indicate that [EINVAL] is returned when 31233 nfds is less than 0 or greater than FD_SETSIZE. It previously stated less than 0, or greater than or 31234 equal to FD_SETSIZE. 31235 Text about timeout is moved from the APPLICATION USAGE section to the DESCRIPTION. 31236 Issue 6 31237 The Open Group Corrigendum U026/6 is applied, changing the occurrences of readfs and writefs 31238 in the select( ) DESCRIPTION to be readfds and writefds. 31239 Text referring to sockets is added to the DESCRIPTION. 31240 The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are 31241 marked as part of the XSI STREAMS Option Group. 31242 The following new requirements on POSIX implementations derive from alignment with the 31243 Single UNIX Specification: 31244 * These functions are now mandatory. 31245 The pselect( ) function is added for alignment with IEEE Std 1003.1g-2000 and additional detail 31246 related to sockets semantics is added to the DESCRIPTION. 1466 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pselect( ) 31247 The select( ) function now requires inclusion of . 31248 The restrict keyword is added to the select( ) prototype for alignment with the 31249 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1467 pthread_atfork( ) System Interfaces 31250 NAME 31251 pthread_atfork - register fork handlers 31252 SYNOPSIS 31253 THR #include 31254 int pthread_atfork(void (*prepare)(void), void (*parent)(void), 31255 void (*child)(void)); 31256 31257 DESCRIPTION 31258 The pthread_atfork( ) function shall declare fork handlers to be called before and after fork( ), in 31259 the context of the thread that called fork( ). The prepare fork handler shall be called before fork( ) 31260 processing commences. The parent fork handle shall be called after fork( ) processing completes 31261 in the parent process. The child fork handler shall be called after fork( ) processing completes in 31262 the child process. If no handling is desired at one or more of these three points, the 31263 corresponding fork handler address(es) may be set to NULL. 31264 The order of calls to pthread_atfork( ) is significant. The parent and child fork handlers shall be 31265 called in the order in which they were established by calls to pthread_atfork( ). The prepare fork 31266 handlers shall be called in the opposite order. 31267 RETURN VALUE 31268 Upon successful completion, pthread_atfork( ) shall return a value of zero; otherwise, an error 31269 number shall be returned to indicate the error. 31270 ERRORS 31271 The pthread_atfork( ) function shall fail if: 31272 [ENOMEM] Insufficient table space exists to record the fork handler addresses. 31273 The pthread_atfork( ) function shall not return an error code of [EINTR]. 31274 EXAMPLES 31275 None. 31276 APPLICATION USAGE 31277 None. 31278 RATIONALE 31279 There are at least two serious problems with the semantics of fork( ) in a multi-threaded 31280 program. One problem has to do with state (for example, memory) covered by mutexes. 31281 Consider the case where one thread has a mutex locked and the state covered by that mutex is 31282 inconsistent while another thread calls fork( ). In the child, the mutex is in the locked state 31283 (locked by a nonexistent thread and thus can never be unlocked). Having the child simply 31284 reinitialize the mutex is unsatisfactory since this approach does not resolve the question about 31285 how to correct or otherwise deal with the inconsistent state in the child. 31286 It is suggested that programs that use fork( ) call an exec function very soon afterwards in the 31287 child process, thus resetting all states. In the meantime, only a short list of async-signal-safe 31288 library routines are promised to be available. 31289 Unfortunately, this solution does not address the needs of multi-threaded libraries. Application 31290 programs may not be aware that a multi-threaded library is in use, and they feel free to call any 31291 number of library routines between the fork( ) and exec calls, just as they always have. Indeed, 31292 they may be extant single-threaded programs and cannot, therefore, be expected to obey new 31293 restrictions imposed by the threads library. 1468 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_atfork( ) 31294 On the other hand, the multi-threaded library needs a way to protect its internal state during 31295 fork( ) in case it is re-entered later in the child process. The problem arises especially in multi- 31296 threaded I/O libraries, which are almost sure to be invoked between the fork( ) and exec calls to 31297 effect I/O redirection. The solution may require locking mutex variables during fork( ), or it may 31298 entail simply resetting the state in the child after the fork( ) processing completes. 31299 The pthread_atfork( ) function provides multi-threaded libraries with a means to protect 31300 themselves from innocent application programs that call fork( ), and it provides multi-threaded 31301 application programs with a standard mechanism for protecting themselves from fork( ) calls in 31302 a library routine or the application itself. 31303 The expected usage is that the prepare handler acquires all mutex locks and the other two fork 31304 handlers release them. 31305 For example, an application can supply a prepare routine that acquires the necessary mutexes the 31306 library maintains and supply child and parent routines that release those mutexes, thus ensuring 31307 that the child gets a consistent snapshot of the state of the library (and that no mutexes are left 31308 stranded). Alternatively, some libraries might be able to supply just a child routine that | 31309 reinitializes the mutexes in the library and all associated states to some known value (for | 31310 example, what it was when the image was originally executed). 31311 When fork( ) is called, only the calling thread is duplicated in the child process. Synchronization 31312 variables remain in the same state in the child as they were in the parent at the time fork( ) was 31313 called. Thus, for example, mutex locks may be held by threads that no longer exist in the child 31314 process, and any associated states may be inconsistent. The parent process may avoid this by 31315 explicit code that acquires and releases locks critical to the child via pthread_atfork( ). In addition, 31316 any critical threads need to be recreated and reinitialized to the proper state in the child (also via | 31317 pthread_atfork( )). 31318 A higher-level package may acquire locks on its own data structures before invoking lower-level 31319 packages. Under this scenario, the order specified for fork handler calls allows a simple rule of 31320 initialization for avoiding package deadlock: a package initializes all packages on which it 31321 depends before it calls the pthread_atfork( ) function for itself. 31322 FUTURE DIRECTIONS 31323 None. 31324 SEE ALSO 31325 atexit( ), fork( ), the Base Definitions volume of IEEE Std 1003.1-200x, 31326 CHANGE HISTORY 31327 First released in Issue 5. Derived from the POSIX Threads Extension. 31328 IEEE PASC Interpretation 1003.1c #4 is applied. | 31329 Issue 6 31330 The pthread_atfork( ) function is marked as part of the Threads option. 31331 The header is added to the SYNOPSIS. System Interfaces, Issue 6 1469 pthread_attr_destroy( ) System Interfaces 31332 NAME 31333 pthread_attr_destroy, pthread_attr_init - destroy and initialize threads attributes object 31334 SYNOPSIS 31335 THR #include 31336 int pthread_attr_destroy(pthread_attr_t *attr); 31337 int pthread_attr_init(pthread_attr_t *attr); 31338 31339 DESCRIPTION 31340 The pthread_attr_destroy( ) function shall destroy a thread attributes object. An implementation | 31341 may cause pthread_attr_destroy( ) to set attr to an implementation-defined invalid value. A | 31342 destroyed attr attributes object can be reinitialized using pthread_attr_init( ); the results of | 31343 otherwise referencing the object after it has been destroyed are undefined. | 31344 The pthread_attr_init( ) function shall initialize a thread attributes object attr with the default 31345 value for all of the individual attributes used by a given implementation. 31346 The resulting attributes object (possibly modified by setting individual attribute values), when 31347 used by pthread_create( ) defines the attributes of the thread created. A single attributes object can 31348 be used in multiple simultaneous calls to pthread_create( ). Results are undefined if | 31349 pthread_attr_init( ) is called specifying an already initialized attr attributes object. | 31350 RETURN VALUE 31351 Upon successful completion, pthread_attr_destroy( ) and pthread_attr_init( ) shall return a value of 31352 0; otherwise, an error number shall be returned to indicate the error. 31353 ERRORS 31354 The pthread_attr_init( ) function shall fail if: 31355 [ENOMEM] Insufficient memory exists to initialize the thread attributes object. 31356 These functions shall not return an error code of [EINTR]. 31357 EXAMPLES 31358 None. 31359 APPLICATION USAGE 31360 None. 31361 RATIONALE 31362 Attributes objects are provided for threads, mutexes, and condition variables as a mechanism to 31363 support probable future standardization in these areas without requiring that the function itself 31364 be changed. 31365 Attributes objects provide clean isolation of the configurable aspects of threads. For example, 31366 ``stack size'' is an important attribute of a thread, but it cannot be expressed portably. When 31367 porting a threaded program, stack sizes often need to be adjusted. The use of attributes objects 31368 can help by allowing the changes to be isolated in a single place, rather than being spread across 31369 every instance of thread creation. 31370 Attributes objects can be used to set up ``classes' of threads with similar attributes; for example, 31371 ``threads with large stacks and high priority'' or ``threads with minimal stacks''. These classes 31372 can be defined in a single place and then referenced wherever threads need to be created. 31373 Changes to ``class'' decisions become straightforward, and detailed analysis of each 31374 pthread_create( ) call is not required. 31375 The attributes objects are defined as opaque types as an aid to extensibility. If these objects had 31376 been specified as structures, adding new attributes would force recompilation of all multi- 1470 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_destroy( ) 31377 threaded programs when the attributes objects are extended; this might not be possible if 31378 different program components were supplied by different vendors. 31379 Additionally, opaque attributes objects present opportunities for improving performance. 31380 Argument validity can be checked once when attributes are set, rather than each time a thread is 31381 created. Implementations often need to cache kernel objects that are expensive to create. 31382 Opaque attributes objects provide an efficient mechanism to detect when cached objects become 31383 invalid due to attribute changes. 31384 Since assignment is not necessarily defined on a given opaque type, implementation-defined | 31385 default values cannot be defined in a portable way. The solution to this problem is to allow 31386 attributes objects to be initialized dynamically by attributes object initialization functions, so 31387 that default values can be supplied automatically by the implementation. 31388 The following proposal was provided as a suggested alternative to the supplied attributes: 31389 1. Maintain the style of passing a parameter formed by the bitwise-inclusive OR of flags to 31390 the initialization routines (pthread_create( ), pthread_mutex_init( ), pthread_cond_init( )). The 31391 parameter containing the flags should be an opaque type for extensibility. If no flags are 31392 set in the parameter, then the objects are created with default characteristics. An 31393 implementation may specify implementation-defined flag values and associated behavior. 31394 2. If further specialization of mutexes and condition variables is necessary, implementations 31395 may specify additional procedures that operate on the pthread_mutex_t and 31396 pthread_cond_t objects (instead of on attributes objects). 31397 The difficulties with this solution are: 31398 1. A bitmask is not opaque if bits have to be set into bitvector attributes objects using 31399 explicitly-coded bitwise-inclusive OR operations. If the set of options exceeds an int, 31400 application programmers need to know the location of each bit. If bits are set or read by 31401 encapsulation (that is, get and set functions), then the bitmask is merely an 31402 implementation of attributes objects as currently defined and should not be exposed to the 31403 programmer. 31404 2. Many attributes are not Boolean or very small integral values. For example, scheduling 31405 policy may be placed in 3-bit or 4-bit, but priority requires 5-bit or more, thereby taking up | 31406 at least 8 bits out of a possible 16 bits on machines with 16-bit integers. Because of this, the | 31407 bitmask can only reasonably control whether particular attributes are set or not, and it 31408 cannot serve as the repository of the value itself. The value needs to be specified as a 31409 function parameter (which is non-extensible), or by setting a structure field (which is non- 31410 opaque), or by get and set functions (making the bitmask a redundant addition to the 31411 attributes objects). 31412 Stack size is defined as an optional attribute because the very notion of a stack is inherently 31413 machine-dependent. Some implementations may not be able to change the size of the stack, for 31414 example, and others may not need to because stack pages may be discontiguous and can be 31415 allocated and released on demand. 31416 The attribute mechanism has been designed in large measure for extensibility. Future extensions 31417 to the attribute mechanism or to any attributes object defined in this volume of 31418 IEEE Std 1003.1-200x has to be done with care so as not to affect binary-compatibility. 31419 Attributes objects, even if allocated by means of dynamic allocation functions such as malloc( ), 31420 may have their size fixed at compile time. This means, for example, a pthread_create( ) in an 31421 implementation with extensions to the pthread_attr_t cannot look beyond the area that the 31422 binary application assumes is valid. This suggests that implementations should maintain a size 31423 field in the attributes object, as well as possibly version information, if extensions in different System Interfaces, Issue 6 1471 pthread_attr_destroy( ) System Interfaces 31424 directions (possibly by different vendors) are to be accommodated. 31425 FUTURE DIRECTIONS 31426 None. 31427 SEE ALSO 31428 pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), pthread_attr_getdetachstate( ), 31429 pthread_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 31430 CHANGE HISTORY 31431 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31432 Issue 6 31433 The pthread_attr_destroy( ) and pthread_attr_init( ) functions marked as part of the Threads 31434 option. 31435 IEEE PASC Interpretation 1003.1 #107 is applied, noting that the effect of initializing an already 31436 initialized thread attributes object is undefined. 1472 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getdetachstate( ) 31437 NAME 31438 pthread_attr_getdetachstate, pthread_attr_setdetachstate - get and set detachstate attribute 31439 SYNOPSIS 31440 THR #include 31441 int pthread_attr_getdetachstate(const pthread_attr_t *attr, 31442 int *detachstate); 31443 int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); 31444 31445 DESCRIPTION 31446 The detachstate attribute controls whether the thread is created in a detached state. If the thread 31447 is created detached, then use of the ID of the newly created thread by the pthread_detach( ) or 31448 pthread_join( ) function is an error. 31449 The pthread_attr_getdetachstate( ) and pthread_attr_setdetachstate( ) functions, respectively, shall 31450 get and set the detachstate attribute in the attr object. 31451 For pthread_attr_getdetachstate( ), detachstate shall be set to either 31452 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. 31453 For pthread_attr_setdetachstate( ), the application shall set detachstate to either 31454 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. 31455 A value of PTHREAD_CREATE_DETACHED shall cause all threads created with attr to be in 31456 the detached state, whereas using a value of PTHREAD_CREATE_JOINABLE shall cause all 31457 threads created with attr to be in the joinable state. The default value of the detachstate attribute 31458 shall be PTHREAD_CREATE_JOINABLE. 31459 RETURN VALUE 31460 Upon successful completion, pthread_attr_getdetachstate( ) and pthread_attr_setdetachstate( ) shall 31461 return a value of 0; otherwise, an error number shall be returned to indicate the error. 31462 The pthread_attr_getdetachstate( ) function stores the value of the detachstate attribute in detachstate 31463 if successful. 31464 ERRORS 31465 The pthread_attr_setdetachstate( ) function shall fail if: 31466 [EINVAL] The value of detachstate was not valid 31467 These functions shall not return an error code of [EINTR]. 31468 EXAMPLES 31469 None. 31470 APPLICATION USAGE 31471 None. 31472 RATIONALE 31473 None. 31474 FUTURE DIRECTIONS 31475 None. 31476 SEE ALSO 31477 pthread_attr_destroy( ), pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), pthread_create( ), the 31478 Base Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1473 pthread_attr_getdetachstate( ) System Interfaces 31479 CHANGE HISTORY 31480 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31481 Issue 6 31482 The pthread_attr_setdetachstate( ) and pthread_attr_getdetachstate( ) functions are marked as part of 31483 the Threads option. 31484 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1474 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getguardsize( ) 31485 NAME 31486 pthread_attr_getguardsize, pthread_attr_setguardsize - get and set the thread guardsize 31487 attribute 31488 SYNOPSIS 31489 XSI #include 31490 int pthread_attr_getguardsize(const pthread_attr_t *restrict attr, 31491 size_t *restrict guardsize); 31492 int pthread_attr_setguardsize(pthread_attr_t *attr, 31493 size_t guardsize); 31494 31495 DESCRIPTION 31496 The pthread_attr_getguardsize( ) function shall get the guardsize attribute in the attr object. This | 31497 attribute shall be returned in the guardsize parameter. | 31498 The pthread_attr_setguardsize( ) function shall set the guardsize attribute in the attr object. The new | 31499 value of this attribute shall be obtained from the guardsize parameter. If guardsize is zero, a guard | 31500 area shall not be provided for threads created with attr. If guardsize is greater than zero, a guard 31501 area of at least size guardsize bytes shall be provided for each thread created with attr. | 31502 The guardsize attribute controls the size of the guard area for the created thread's stack. The | 31503 guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is | 31504 created with guard protection, the implementation allocates extra memory at the overflow end | 31505 of the stack as a buffer against stack overflow of the stack pointer. If an application overflows | 31506 into this buffer an error shall result (possibly in a SIGSEGV signal being delivered to the thread). | 31507 A conforming implementation may round up the value contained in guardsize to a multiple of | 31508 the configurable system variable {PAGESIZE} (see ). If an implementation 31509 rounds up the value of guardsize to a multiple of {PAGESIZE}, a call to pthread_attr_getguardsize( ) 31510 specifying attr shall store in the guardsize parameter the guard size specified by the previous 31511 pthread_attr_setguardsize( ) function call. 31512 The default value of the guardsize attribute is {PAGESIZE} bytes. The actual value of {PAGESIZE} | 31513 is implementation-defined. | 31514 If the stackaddr or stack attribute has been set (that is, the caller is allocating and managing its 31515 own thread stacks), the guardsize attribute shall be ignored and no protection shall be provided | 31516 by the implementation. It is the responsibility of the application to manage stack overflow along | 31517 with stack allocation and management in this case. 31518 RETURN VALUE 31519 If successful, the pthread_attr_getguardsize( ) and pthread_attr_setguardsize( ) functions shall return 31520 zero; otherwise, an error number shall be returned to indicate the error. 31521 ERRORS 31522 The pthread_attr_getguardsize( ) and pthread_attr_setguardsize( ) functions shall fail if: 31523 [EINVAL] The attribute attr is invalid. 31524 [EINVAL] The parameter guardsize is invalid. 31525 These functions shall not return an error code of [EINTR]. System Interfaces, Issue 6 1475 pthread_attr_getguardsize( ) System Interfaces 31526 EXAMPLES 31527 None. 31528 APPLICATION USAGE 31529 None. 31530 RATIONALE 31531 The guardsize attribute is provided to the application for two reasons: 31532 1. Overflow protection can potentially result in wasted system resources. An application 31533 that creates a large number of threads, and which knows its threads never overflow their 31534 stack, can save system resources by turning off guard areas. 31535 2. When threads allocate large data structures on the stack, large guard areas may be needed 31536 to detect stack overflow. 31537 FUTURE DIRECTIONS 31538 None. 31539 SEE ALSO 31540 The Base Definitions volume of IEEE Std 1003.1-200x, , 31541 CHANGE HISTORY 31542 First released in Issue 5. 31543 Issue 6 31544 In the ERRORS section, a third [EINVAL] error condition is removed as it is covered by the 31545 second error condition. 31546 The restrict keyword is added to the pthread_attr_getguardsize( ) prototype for alignment with the 31547 ISO/IEC 9899: 1999 standard. 1476 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getinheritsched( ) 31548 NAME 31549 pthread_attr_getinheritsched, pthread_attr_setinheritsched - get and set inheritsched attribute 31550 (REALTIME THREADS) 31551 SYNOPSIS 31552 THR TPS #include 31553 int pthread_attr_getinheritsched(const pthread_attr_t *restrict attr, 31554 int *restrict inheritsched); 31555 int pthread_attr_setinheritsched(pthread_attr_t *attr, 31556 int inheritsched); 31557 31558 DESCRIPTION 31559 The pthread_attr_getinheritsched( ), and pthread_attr_setinheritsched( ) functions, respectively, shall 31560 get and set the inheritsched attribute in the attr argument. 31561 When the attributes objects are used by pthread_create( ), the inheritsched attribute determines 31562 how the other scheduling attributes of the created thread shall be set. | 31563 PTHREAD_INHERIT_SCHED 31564 Specifies that the thread scheduling attributes shall be inherited from the creating thread, 31565 and the scheduling attributes in this attr argument shall be ignored. 31566 PTHREAD_EXPLICIT_SCHED 31567 Specifies that the thread scheduling attributes shall be set to the corresponding values from 31568 this attributes object. 31569 The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined in | 31570 the header. | 31571 The following ``thread scheduling attributes'' defined by IEEE Std 1003.1-200x are affected by | 31572 the inheritsched attribute: scheduling policy (schedpolicy), scheduling parameters (schedparam), | 31573 and scheduling contention scope (contentionscope). | 31574 RETURN VALUE 31575 If successful, the pthread_attr_getinheritsched( ) and pthread_attr_setinheritsched( ) functions shall 31576 return zero; otherwise, an error number shall be returned to indicate the error. 31577 ERRORS 31578 The pthread_attr_setinheritsched( ) function may fail if: 31579 [EINVAL] The value of inheritsched is not valid. 31580 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 31581 These functions shall not return an error code of [EINTR]. 31582 EXAMPLES 31583 None. 31584 APPLICATION USAGE 31585 After these attributes have been set, a thread can be created with the specified attributes using 31586 pthread_create( ). Using these routines does not affect the current running thread. 31587 RATIONALE 31588 None. System Interfaces, Issue 6 1477 pthread_attr_getinheritsched( ) System Interfaces 31589 FUTURE DIRECTIONS 31590 None. 31591 SEE ALSO 31592 pthread_attr_destroy( ), pthread_attr_getscope( ), pthread_attr_getschedpolicy( ), 31593 pthread_attr_getschedparam( ), pthread_create( ), the Base Definitions volume of 31594 IEEE Std 1003.1-200x, , 31595 CHANGE HISTORY 31596 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31597 Marked as part of the Realtime Threads Feature Group. 31598 Issue 6 31599 The pthread_attr_getinheritsched( ) and pthread_attr_setinheritsched( ) functions are marked as part 31600 of the Threads and Thread Execution Scheduling options. 31601 The [ENOSYS] error condition has been removed as stubs need not be provided if an 31602 implementation does not support the Thread Execution Scheduling option. 31603 The restrict keyword is added to the pthread_attr_getinheritsched( ) prototype for alignment with 31604 the ISO/IEC 9899: 1999 standard. 1478 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getschedparam( ) 31605 NAME 31606 pthread_attr_getschedparam, pthread_attr_setschedparam - get and set schedparam attribute 31607 SYNOPSIS 31608 THR #include 31609 int pthread_attr_getschedparam(const pthread_attr_t *restrict attr, 31610 struct sched_param *restrict param); 31611 int pthread_attr_setschedparam(pthread_attr_t *restrict attr, 31612 const struct sched_param *restrict param); 31613 31614 DESCRIPTION 31615 The pthread_attr_getschedparam( ), and pthread_attr_setschedparam( ) functions, respectively, shall 31616 get and set the scheduling parameter attributes in the attr argument. The contents of the param | 31617 structure are defined in the header. For the SCHED_FIFO and SCHED_RR policies, | 31618 the only required member of param is sched_priority. 31619 TSP For the SCHED_SPORADIC policy, the required members of the param structure are 31620 sched_priority, sched_ss_low_priority, sched_ss_repl_period, sched_ss_init_budget, and 31621 sched_ss_max_repl. The specified sched_ss_repl_period must be greater than or equal to the 31622 specified sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. 31623 The value of sched_ss_max_repl shall be within the inclusive range [1,{SS_REPL_MAX}] for the 31624 function to succeed; if not, the function shall fail. 31625 RETURN VALUE 31626 If successful, the pthread_attr_getschedparam( ) and pthread_attr_setschedparam( ) functions shall 31627 return zero; otherwise, an error number shall be returned to indicate the error. 31628 ERRORS 31629 The pthread_attr_setschedparam( ) function may fail if: 31630 [EINVAL] The value of param is not valid. 31631 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 31632 These functions shall not return an error code of [EINTR]. 31633 EXAMPLES 31634 None. 31635 APPLICATION USAGE 31636 After these attributes have been set, a thread can be created with the specified attributes using 31637 pthread_create( ). Using these routines does not affect the current running thread. 31638 RATIONALE 31639 None. 31640 FUTURE DIRECTIONS 31641 None. 31642 SEE ALSO 31643 pthread_attr_destroy( ), pthread_attr_getscope( ), pthread_attr_getinheritsched( ), 31644 pthread_attr_getschedpolicy( ), pthread_create( ), the Base Definitions volume of 31645 IEEE Std 1003.1-200x, , System Interfaces, Issue 6 1479 pthread_attr_getschedparam( ) System Interfaces 31646 CHANGE HISTORY 31647 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31648 Issue 6 31649 The pthread_attr_getschedparam( ) and pthread_attr_setschedparam( ) functions are marked as part 31650 of the Threads option. 31651 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999. 31652 The restrict keyword is added to the pthread_attr_getschedparam( ) and 31653 pthread_attr_setschedparam( ) prototypes for alignment with the ISO/IEC 9899: 1999 standard. 1480 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getschedpolicy( ) 31654 NAME 31655 pthread_attr_getschedpolicy, pthread_attr_setschedpolicy - get and set schedpolicy attribute 31656 (REALTIME THREADS) 31657 SYNOPSIS 31658 THR TPS #include 31659 int pthread_attr_getschedpolicy(const pthread_attr_t *restrict attr, 31660 int *restrict policy); 31661 int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); 31662 31663 DESCRIPTION 31664 The pthread_attr_getschedpolicy( ) and pthread_attr_setschedpolicy( ) functions, respectively, shall 31665 get and set the schedpolicy attribute in the attr argument. 31666 The supported values of policy shall include SCHED_FIFO, SCHED_RR, and SCHED_OTHER, | 31667 which are defined in the header. When threads executing with the scheduling policy | 31668 TSP SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC are waiting on a mutex, they shall acquire | 31669 the mutex in priority order when the mutex is unlocked. | 31670 RETURN VALUE 31671 If successful, the pthread_attr_getschedpolicy( ) and pthread_attr_setschedpolicy( ) functions shall 31672 return zero; otherwise, an error number shall be returned to indicate the error. 31673 ERRORS 31674 The pthread_attr_setschedpolicy( ) function may fail if: 31675 [EINVAL] The value of policy is not valid. 31676 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 31677 These functions shall not return an error code of [EINTR]. 31678 EXAMPLES 31679 None. 31680 APPLICATION USAGE 31681 After these attributes have been set, a thread can be created with the specified attributes using 31682 pthread_create( ). Using these routines does not affect the current running thread. 31683 RATIONALE 31684 None. 31685 FUTURE DIRECTIONS 31686 None. 31687 SEE ALSO 31688 pthread_attr_destroy( ), pthread_attr_getscope( ), pthread_attr_getinheritsched( ), 31689 pthread_attr_getschedparam( ), pthread_create( ), the Base Definitions volume of 31690 IEEE Std 1003.1-200x, , 31691 CHANGE HISTORY 31692 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31693 Marked as part of the Realtime Threads Feature Group. System Interfaces, Issue 6 1481 pthread_attr_getschedpolicy( ) System Interfaces 31694 Issue 6 31695 The pthread_attr_getschedpolicy( ) and pthread_attr_setschedpolicy( ) functions are marked as part of 31696 the Threads and Thread Execution Scheduling options. 31697 The [ENOSYS] error condition has been removed as stubs need not be provided if an 31698 implementation does not support the Thread Execution Scheduling option. 31699 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999. 31700 The restrict keyword is added to the pthread_attr_getschedpolicy( ) prototype for alignment with 31701 the ISO/IEC 9899: 1999 standard. 1482 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getscope( ) 31702 NAME 31703 pthread_attr_getscope, pthread_attr_setscope - get and set contentionscope attribute 31704 (REALTIME THREADS) 31705 SYNOPSIS 31706 THR TPS #include 31707 int pthread_attr_getscope(const pthread_attr_t *restrict attr, 31708 int *restrict contentionscope); 31709 int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope); 31710 31711 DESCRIPTION 31712 The pthread_attr_getscope( ) and pthread_attr_setscope( ) functions, respectively, shall get and set | 31713 the contentionscope attribute in the attr object. | 31714 The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying 31715 system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process 31716 scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and | 31717 PTHREAD_SCOPE_PROCESS are defined in the header. | 31718 RETURN VALUE 31719 If successful, the pthread_attr_getscope( ) and pthread_attr_setscope( ) functions shall return zero; 31720 otherwise, an error number shall be returned to indicate the error. 31721 ERRORS 31722 The pthread_attr_setscope( ) function may fail if: 31723 [EINVAL] The value of contentionscope is not valid. 31724 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 31725 These functions shall not return an error code of [EINTR]. 31726 EXAMPLES 31727 None. 31728 APPLICATION USAGE 31729 After these attributes have been set, a thread can be created with the specified attributes using 31730 pthread_create( ). Using these routines does not affect the current running thread. 31731 RATIONALE 31732 None. 31733 FUTURE DIRECTIONS 31734 None. 31735 SEE ALSO 31736 pthread_attr_destroy( ), pthread_attr_getinheritsched( ), pthread_attr_getschedpolicy( ), 31737 pthread_attr_getschedparam( ), pthread_create( ), the Base Definitions volume of 31738 IEEE Std 1003.1-200x, , 31739 CHANGE HISTORY 31740 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31741 Marked as part of the Realtime Threads Feature Group. System Interfaces, Issue 6 1483 pthread_attr_getscope( ) System Interfaces 31742 Issue 6 31743 The pthread_attr_getscope( ) and pthread_attr_setscope( ) functions are marked as part of the 31744 Threads and Thread Execution Scheduling options. 31745 The [ENOSYS] error condition has been removed as stubs need not be provided if an 31746 implementation does not support the Thread Execution Scheduling option. 31747 The restrict keyword is added to the pthread_attr_getscope( ) prototype for alignment with the 31748 ISO/IEC 9899: 1999 standard. 1484 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getstack( ) 31749 NAME 31750 pthread_attr_getstack, pthread_attr_setstack - get and set stack attributes 31751 SYNOPSIS 31752 THR #include 31753 TSA TSS int pthread_attr_getstack(const pthread_attr_t *restrict attr, 31754 void **restrict stackaddr, size_t *restrict stacksize); 31755 int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, 31756 size_t stacksize); 31757 31758 DESCRIPTION 31759 The pthread_attr_getstack( ) and pthread_attr_setstack( ) functions, respectively, shall get and set 31760 the thread creation stack attributes stackaddr and stacksize in the attr object. 31761 The stack attributes specify the area of storage to be used for the created thread's stack. The base 31762 (lowest addressable byte) of the storage shall be stackaddr, and the size of the storage shall be 31763 stacksize bytes. The stacksize shall be at least {PTHREAD_STACK_MIN}. The stackaddr shall be 31764 aligned appropriately to be used as a stack; for example, pthread_attr_setstack( ) may fail with 31765 [EINVAL] if (stackaddr & 0x7) is not 0. All pages within the stack described by stackaddr and 31766 stacksize shall be both readable and writable by the thread. 31767 RETURN VALUE 31768 Upon successful completion, these functions shall return a value of 0; otherwise, an error 31769 number shall be returned to indicate the error. 31770 The pthread_attr_getstack( ) function shall store the stack attribute values in stackaddr and stacksize 31771 if successful. 31772 ERRORS 31773 The pthread_attr_setstack( ) function shall fail if: 31774 [EINVAL] The value of stacksize is less than {PTHREAD_STACK_MIN} or exceeds an 31775 implementation-defined limit. 31776 The pthread_attr_setstack( ) function may fail if: 31777 [EINVAL] The value of stackaddr does not have proper alignment to be used as a stack, or 31778 if (stackaddr + stacksize) lacks proper alignment. 31779 [EACCES] The stack page(s) described by stackaddr and stacksize are not both readable 31780 and writable by the thread. 31781 These functions shall not return an error code of [EINTR]. 31782 EXAMPLES 31783 None. 31784 APPLICATION USAGE 31785 These functions are appropriate for use by applications in an environment where the stack for a 31786 thread must be placed in some particular region of memory. 31787 While it might seem that an application could detect stack overflow by providing a protected 31788 page outside the specified stack region, this cannot be done portably. Implementations are free 31789 to place the thread's initial stack pointer anywhere within the specified region to accommodate 31790 the machine's stack pointer behavior and allocation requirements. Furthermore, on some 31791 architectures, such as the IA-64, ``overflow'' might mean that two separate stack pointers 31792 allocated within the region will overlap somewhere in the middle of the region. System Interfaces, Issue 6 1485 pthread_attr_getstack( ) System Interfaces 31793 RATIONALE 31794 None. 31795 FUTURE DIRECTIONS 31796 None. 31797 SEE ALSO 31798 pthread_attr_init( ), pthread_attr_setdetachstate( ), pthread_attr_setstacksize( ), pthread_create( ), the 31799 Base Definitions volume of IEEE Std 1003.1-200x, , 31800 CHANGE HISTORY 31801 First released in Issue 6. Developed as an XSI extension and brought into the BASE by IEEE 31802 PASC Interpretation 1003.1 #101. 1486 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getstackaddr( ) 31803 NAME 31804 pthread_attr_getstackaddr, pthread_attr_setstackaddr - get and set stackaddr attribute 31805 SYNOPSIS 31806 THR TSA #include 31807 OB int pthread_attr_getstackaddr(const pthread_attr_t *restrict attr, 31808 void **restrict stackaddr); 31809 int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); 31810 31811 DESCRIPTION 31812 The pthread_attr_getstackaddr( ) and pthread_attr_setstackaddr( ) functions, respectively, shall get 31813 and set the thread creation stackaddr attribute in the attr object. 31814 The stackaddr attribute specifies the location of storage to be used for the created thread's stack. 31815 The size of the storage shall be at least {PTHREAD_STACK_MIN}. 31816 RETURN VALUE 31817 Upon successful completion, pthread_attr_getstackaddr( ) and pthread_attr_setstackaddr( ) shall 31818 return a value of 0; otherwise, an error number shall be returned to indicate the error. 31819 The pthread_attr_getstackaddr( ) function stores the stackaddr attribute value in stackaddr if 31820 successful. 31821 ERRORS 31822 No errors are defined. 31823 These functions shall not return an error code of [EINTR]. 31824 EXAMPLES 31825 None. 31826 APPLICATION USAGE 31827 The specification of the stackaddr attribute presents several ambiguities that make portable use of 31828 these interfaces impossible. The description of the single address parameter as a ``stack'' does 31829 not specify a particular relationship between the address and the ``stack'' implied by that 31830 address. For example, the address may be taken as the low memory address of a buffer intended 31831 for use as a stack, or it may be taken as the address to be used as the initial stack pointer register 31832 value for the new thread. These two are not the same except for a machine on which the stack 31833 grows ``up'' from low memory to high, and on which a ``push'' operation first stores the value in 31834 memory and then increments the stack pointer register. Further, on a machine where the stack 31835 grows ``down'' from high memory to low, interpretation of the address as the ``low memory'' 31836 address requires a determination of the intended size of the stack. IEEE Std 1003.1-200x has 31837 introduced the new interfaces pthread_attr_setstack( ) and pthread_attr_getstack( ) to resolve these 31838 ambiguities. 31839 RATIONALE 31840 None. 31841 FUTURE DIRECTIONS 31842 None. 31843 SEE ALSO 31844 pthread_attr_destroy( ), pthread_attr_getdetachstate( ), pthread_attr_getstack( ), 31845 pthread_attr_getstacksize( ), pthread_attr_setstack( ), pthread_create( ), the Base Definitions volume 31846 of IEEE Std 1003.1-200x, , System Interfaces, Issue 6 1487 pthread_attr_getstackaddr( ) System Interfaces 31847 CHANGE HISTORY 31848 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31849 Issue 6 31850 The pthread_attr_getstackaddr( ) and pthread_attr_setstackaddr( ) functions are marked as part of 31851 the Threads and Thread Stack Address Attribute options. 31852 The restrict keyword is added to the pthread_attr_getstackaddr( ) prototype for alignment with the 31853 ISO/IEC 9899: 1999 standard. 31854 These functions are marked obsolescent. 1488 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_getstacksize( ) 31855 NAME 31856 pthread_attr_getstacksize, pthread_attr_setstacksize - get and set stacksize attribute 31857 SYNOPSIS 31858 THR TSA #include 31859 int pthread_attr_getstacksize(const pthread_attr_t *restrict attr, 31860 size_t *restrict stacksize); 31861 int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize); 31862 31863 DESCRIPTION 31864 The pthread_attr_getstacksize( ) and pthread_attr_setstacksize( ) functions, respectively, shall get 31865 and set the thread creation stacksize attribute in the attr object. 31866 The stacksize attribute shall define the minimum stack size (in bytes) allocated for the created 31867 threads stack. 31868 RETURN VALUE 31869 Upon successful completion, pthread_attr_getstacksize( ) and pthread_attr_setstacksize( ) shall 31870 return a value of 0; otherwise, an error number shall be returned to indicate the error. 31871 The pthread_attr_getstacksize( ) function stores the stacksize attribute value in stacksize if 31872 successful. 31873 ERRORS 31874 The pthread_attr_setstacksize( ) function shall fail if: 31875 [EINVAL] The value of stacksize is less than {PTHREAD_STACK_MIN} or exceeds a 31876 system-imposed limit. 31877 These functions shall not return an error code of [EINTR]. 31878 EXAMPLES 31879 None. 31880 APPLICATION USAGE 31881 None. 31882 RATIONALE 31883 None. 31884 FUTURE DIRECTIONS 31885 None. 31886 SEE ALSO 31887 pthread_attr_destroy( ), pthread_attr_getstackaddr( ), pthread_attr_getdetachstate( ), pthread_create( ), 31888 the Base Definitions volume of IEEE Std 1003.1-200x, , 31889 CHANGE HISTORY 31890 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 31891 Issue 6 31892 The pthread_attr_getstacksize( ) and pthread_attr_setstacksize( ) functions are marked as part of the 31893 Threads and Thread Stack Address Attribute options. 31894 The restrict keyword is added to the pthread_attr_getstacksize( ) prototype for alignment with the 31895 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1489 pthread_attr_init( ) System Interfaces 31896 NAME 31897 pthread_attr_init - initialize threads attributes object 31898 SYNOPSIS 31899 THR #include 31900 int pthread_attr_init(pthread_attr_t *attr); 31901 31902 DESCRIPTION 31903 Refer to pthread_attr_destroy( ). 1490 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_setdetachstate( ) 31904 NAME 31905 pthread_attr_setdetachstate - set detachstate attribute 31906 SYNOPSIS 31907 THR #include 31908 int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); 31909 31910 DESCRIPTION 31911 Refer to pthread_attr_getdetachstate( ). System Interfaces, Issue 6 1491 pthread_attr_setguardsize( ) System Interfaces 31912 NAME 31913 pthread_attr_setguardsize - set thread guardsize attribute 31914 SYNOPSIS 31915 XSI #include 31916 int pthread_attr_setguardsize(pthread_attr_t *attr, 31917 size_t guardsize); 31918 31919 DESCRIPTION 31920 Refer to pthread_attr_getguardsize( ). 1492 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_setinheritsched( ) 31921 NAME 31922 pthread_attr_setinheritsched - set inheritsched attribute (REALTIME THREADS) 31923 SYNOPSIS 31924 THR TPS #include 31925 int pthread_attr_setinheritsched(pthread_attr_t *attr, 31926 int inheritsched); 31927 31928 DESCRIPTION 31929 Refer to pthread_attr_getinheritsched( ). System Interfaces, Issue 6 1493 pthread_attr_setschedparam( ) System Interfaces 31930 NAME 31931 pthread_attr_setschedparam - set schedparam attribute 31932 SYNOPSIS 31933 THR #include 31934 int pthread_attr_setschedparam(pthread_attr_t *restrict attr, 31935 const struct sched_param *restrict param); 31936 31937 DESCRIPTION 31938 Refer to pthread_attr_getschedparam( ). 1494 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_setschedpolicy( ) 31939 NAME 31940 pthread_attr_setschedpolicy - set schedpolicy attribute (REALTIME THREADS) 31941 SYNOPSIS 31942 THR TPS #include 31943 int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); 31944 31945 DESCRIPTION 31946 Refer to pthread_attr_getschedpolicy( ). System Interfaces, Issue 6 1495 pthread_attr_setscope( ) System Interfaces 31947 NAME 31948 pthread_attr_setscope - set contentionscope attribute (REALTIME THREADS) 31949 SYNOPSIS 31950 THR TPS #include 31951 int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope); 31952 31953 DESCRIPTION 31954 Refer to pthread_attr_getscope( ). 1496 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_setstack( ) 31955 NAME 31956 pthread_attr_setstack - set stack attribute 31957 SYNOPSIS 31958 XSI #include 31959 int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, 31960 size_t stacksize); 31961 31962 DESCRIPTION 31963 Refer to pthread_attr_getstack( ). System Interfaces, Issue 6 1497 pthread_attr_setstackaddr( ) System Interfaces 31964 NAME 31965 pthread_attr_setstackaddr - set stackaddr attribute 31966 SYNOPSIS 31967 THR TSA #include 31968 OB int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); 31969 31970 DESCRIPTION 31971 Refer to pthread_attr_getstackaddr( ). 1498 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_attr_setstacksize( ) 31972 NAME 31973 pthread_attr_setstacksize - set stacksize attribute 31974 SYNOPSIS 31975 THR TSA #include 31976 int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize); 31977 31978 DESCRIPTION 31979 Refer to pthread_attr_getstacksize( ). System Interfaces, Issue 6 1499 pthread_barrier_destroy( ) System Interfaces 31980 NAME 31981 pthread_barrier_destroy, pthread_barrier_init - destroy and initialize a barrier object 31982 (ADVANCED REALTIME THREADS) 31983 SYNOPSIS 31984 THR BAR #include 31985 int pthread_barrier_destroy(pthread_barrier_t *barrier); 31986 int pthread_barrier_init(pthread_barrier_t *restrict barrier, 31987 const pthread_barrierattr_t *restrict attr, unsigned count); 31988 31989 DESCRIPTION 31990 The pthread_barrier_destroy( ) function shall destroy the barrier referenced by barrier and release 31991 any resources used by the barrier. The effect of subsequent use of the barrier is undefined until 31992 the barrier is reinitialized by another call to pthread_barrier_init( ). An implementation may use 31993 this function to set barrier to an invalid value. The results are undefined if 31994 pthread_barrier_destroy( ) is called when any thread is blocked on the barrier, or if this function is 31995 called with an uninitialized barrier. 31996 The pthread_barrier_init( ) function shall allocate any resources required to use the barrier 31997 referenced by barrier and shall initialize the barrier with attributes referenced by attr. If attr is 31998 NULL, the default barrier attributes shall be used; the effect is the same as passing the address of 31999 a default barrier attributes object. The results are undefined if pthread_barrier_init( ) is called 32000 when any thread is blocked on the barrier (that is, has not returned from the 32001 pthread_barrier_wait( ) call). The results are undefined if a barrier is used without first being 32002 initialized. The results are undefined if pthread_barrier_init( ) is called specifying an already 32003 initialized barrier. 32004 The count argument specifies the number of threads that must call pthread_barrier_wait( ) before 32005 any of them successfully return from the call. The value specified by count must be greater than 32006 zero. 32007 If the pthread_barrier_init( ) function fails, the barrier shall not be initialized and the contents of | 32008 barrier are undefined. 32009 Only the object referenced by barrier may be used for performing synchronization. The result of 32010 referring to copies of that object in calls to pthread_barrier_destroy( ) or pthread_barrier_wait( ) is 32011 undefined. 32012 RETURN VALUE 32013 Upon successful completion, these functions shall return zero; otherwise, an error number shall 32014 be returned to indicate the error. 32015 ERRORS 32016 The pthread_barrier_destroy( ) function may fail if: 32017 [EBUSY] The implementation has detected an attempt to destroy a barrier while it is in 32018 use (for example, while being used in a pthread_barrier_wait( ) call) by another 32019 thread. 32020 [EINVAL] The value specified by barrier is invalid. 32021 The pthread_barrier_init( ) function shall fail if: 32022 [EAGAIN] The system lacks the necessary resources to initialize another barrier. 32023 [EINVAL] The value specified by count is equal to zero. 1500 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_barrier_destroy( ) 32024 [ENOMEM] Insufficient memory exists to initialize the barrier. 32025 The pthread_barrier_init( ) function may fail if: 32026 [EBUSY] The implementation has detected an attempt to reinitialize a barrier while it is 32027 in use (for example, while being used in a pthread_barrier_wait( ) call) by 32028 another thread. 32029 [EINVAL] The value specified by attr is invalid. 32030 These functions shall not return an error code of [EINTR]. 32031 EXAMPLES 32032 None. 32033 APPLICATION USAGE 32034 The pthread_barrier_destroy( ) and pthread_barrier_init( ) functions are part of the Barriers option 32035 and need not be provided on all implementations. 32036 RATIONALE 32037 None. 32038 FUTURE DIRECTIONS 32039 None. 32040 SEE ALSO 32041 pthread_barrier_wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 32042 CHANGE HISTORY 32043 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. System Interfaces, Issue 6 1501 pthread_barrier_init( ) System Interfaces 32044 NAME 32045 pthread_barrier_init - initialize a barrier object (ADVANCED REALTIME THREADS) 32046 SYNOPSIS 32047 THR BAR #include 32048 int pthread_barrier_init(pthread_barrier_t *restrict barrier, 32049 const pthread_barrierattr_t *restrict attr, unsigned count); 32050 32051 DESCRIPTION 32052 Refer to pthread_barrier_destroy( ). 1502 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_barrier_wait( ) 32053 NAME 32054 pthread_barrier_wait - synchronize at a barrier (ADVANCED REALTIME THREADS) 32055 SYNOPSIS 32056 THR BAR #include 32057 int pthread_barrier_wait(pthread_barrier_t *barrier); 32058 32059 DESCRIPTION 32060 The pthread_barrier_wait( ) function shall synchronize participating threads at the barrier 32061 referenced by barrier. The calling thread shall block until the required number of threads have | 32062 called pthread_barrier_wait( ) specifying the barrier. | 32063 When the required number of threads have called pthread_barrier_wait( ) specifying the barrier, 32064 the constant PTHREAD_BARRIER_SERIAL_THREAD shall be returned to one unspecified 32065 thread and zero shall be returned to each of the remaining threads. At this point, the barrier shall 32066 be reset to the state it had as a result of the most recent pthread_barrier_init( ) function that 32067 referenced it. 32068 The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in and its value | 32069 shall be distinct from any other value returned by pthread_barrier_wait( ). 32070 The results are undefined if this function is called with an uninitialized barrier. 32071 If a signal is delivered to a thread blocked on a barrier, upon return from the signal handler the 32072 thread shall resume waiting at the barrier if the barrier wait has not completed (that is, if the 32073 required number of threads have not arrived at the barrier during the execution of the signal 32074 handler); otherwise, the thread shall continue as normal from the completed barrier wait. Until 32075 the thread in the signal handler returns from it, it is unspecified whether other threads may 32076 proceed past the barrier once they have all reached it. 32077 A thread that has blocked on a barrier shall not prevent any unblocked thread that is eligible to 32078 use the same processing resources from eventually making forward progress in its execution. 32079 Eligibility for processing resources shall be determined by the scheduling policy. 32080 RETURN VALUE 32081 Upon successful completion, the pthread_barrier_wait( ) function shall return 32082 PTHREAD_BARRIER_SERIAL_THREAD for a single (arbitrary) thread synchronized at the 32083 barrier and zero for each of the other threads. Otherwise, an error number shall be returned to 32084 indicate the error. 32085 ERRORS 32086 The pthread_barrier_wait( ) function may fail if: 32087 [EINVAL] The value specified by barrier does not refer to an initialized barrier object. 32088 This function shall not return an error code of [EINTR]. 32089 EXAMPLES 32090 None. 32091 APPLICATION USAGE 32092 Applications using this function may be subject to priority inversion, as discussed in the Base 32093 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 32094 The pthread_barrier_wait( ) function is part of the Barriers option and need not be provided on all 32095 implementations. System Interfaces, Issue 6 1503 pthread_barrier_wait( ) System Interfaces 32096 RATIONALE 32097 None. 32098 FUTURE DIRECTIONS 32099 None. 32100 SEE ALSO 32101 pthread_barrier_destroy( ), pthread_barrier_init( ), the Base Definitions volume of 32102 IEEE Std 1003.1-200x, 32103 CHANGE HISTORY 32104 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 32105 In the SYNOPSIS, the inclusion of is no longer required. 1504 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_barrierattr_destroy( ) 32106 NAME 32107 pthread_barrierattr_destroy, pthread_barrierattr_init - destroy and initialize barrier attributes 32108 object (ADVANCED REALTIME THREADS) 32109 SYNOPSIS 32110 THR BAR #include 32111 int pthread_barrierattr_destroy(pthread_barrierattr_t *attr); 32112 int pthread_barrierattr_init(pthread_barrierattr_t *attr); 32113 32114 DESCRIPTION 32115 The pthread_barrierattr_destroy( ) function shall destroy a barrier attributes object. A destroyed | 32116 attr attributes object can be reinitialized using pthread_barrierattr_init( ); the results of otherwise | 32117 referencing the object after it has been destroyed are undefined. An implementation may cause | 32118 pthread_barrierattr_destroy( ) to set the object referenced by attr to an invalid value. 32119 The pthread_barrierattr_init( ) function shall initialize a barrier attributes object attr with the 32120 default value for all of the attributes defined by the implementation. 32121 Results are undefined if pthread_barrierattr_init( ) is called specifying an already initialized attr | 32122 attributes object. | 32123 After a barrier attributes object has been used to initialize one or more barriers, any function 32124 affecting the attributes object (including destruction) shall not affect any previously initialized | 32125 barrier. | 32126 RETURN VALUE 32127 If successful, the pthread_barrierattr_destroy( ) and pthread_barrierattr_init( ) functions shall return 32128 zero; otherwise, an error number shall be returned to indicate the error. 32129 ERRORS 32130 The pthread_barrierattr_destroy( ) function may fail if: 32131 [EINVAL] The value specified by attr is invalid. 32132 The pthread_barrierattr_init( ) function shall fail if: 32133 [ENOMEM] Insufficient memory exists to initialize the barrier attributes object. 32134 These functions shall not return an error code of [EINTR]. 32135 EXAMPLES 32136 None. 32137 APPLICATION USAGE 32138 The pthread_barrierattr_destroy( ) and pthread_barrierattr_init( ) functions are part of the Barriers 32139 option and need not be provided on all implementations. 32140 RATIONALE 32141 None. 32142 FUTURE DIRECTIONS 32143 None. 32144 SEE ALSO 32145 pthread_barrierattr_getpshared( ), pthread_barrierattr_setpshared( ), the Base Definitions volume of 32146 IEEE Std 1003.1-200x, . System Interfaces, Issue 6 1505 pthread_barrierattr_destroy( ) System Interfaces 32147 CHANGE HISTORY 32148 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 32149 In the SYNOPSIS, the inclusion of is no longer required. 1506 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_barrierattr_getpshared( ) 32150 NAME 32151 pthread_barrierattr_getpshared, pthread_barrierattr_setpshared - get and set process-shared 32152 attribute of barrier attributes object (ADVANCED REALTIME THREADS) 32153 SYNOPSIS 32154 THR #include 32155 BAR TSH int pthread_barrierattr_getpshared( 32156 const pthread_barrierattr_t *restrict attr, 32157 int *restrict pshared); 32158 int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, 32159 int pshared); 32160 32161 DESCRIPTION 32162 The pthread_barrierattr_getpshared( ) function shall obtain the value of the process-shared | 32163 attribute from the attributes object referenced by attr. The pthread_barrierattr_setpshared( ) | 32164 function shall set the process-shared attribute in an initialized attributes object referenced by | 32165 attr. | 32166 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a barrier to be | 32167 operated upon by any thread that has access to the memory where the barrier is allocated. If the 32168 process-shared attribute is PTHREAD_PROCESS_PRIVATE, the barrier shall only be operated 32169 upon by threads created within the same process as the thread that initialized the barrier; if 32170 threads of different processes attempt to operate on such a barrier, the behavior is undefined. 32171 The default value of the attribute shall be PTHREAD_PROCESS_PRIVATE. Both constants | 32172 PTHREAD_PROCESS_SHARED and PTHREAD_PROCESS_PRIVATE are defined in | 32173 . 32174 Additional attributes, their default values, and the names of the associated functions to get and | 32175 set those attribute values are implementation-defined. 32176 RETURN VALUE 32177 If successful, the pthread_barrierattr_getpshared( ) function shall return zero and store the value of 32178 the process-shared attribute of attr into the object referenced by the pshared parameter. 32179 Otherwise, an error number shall be returned to indicate the error. 32180 If successful, the pthread_barrierattr_setpshared( ) function shall return zero; otherwise, an error 32181 number shall be returned to indicate the error. 32182 ERRORS 32183 These functions may fail if: 32184 [EINVAL] The value specified by attr is invalid. 32185 The pthread_barrierattr_setpshared( ) function may fail if: 32186 [EINVAL] The new value specified for the process-shared attribute is not one of the legal 32187 values PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE. 32188 These functions shall not return an error code of [EINTR]. System Interfaces, Issue 6 1507 pthread_barrierattr_getpshared( ) System Interfaces 32189 EXAMPLES 32190 None. 32191 APPLICATION USAGE 32192 The pthread_barrierattr_getpshared( ) and pthread_barrierattr_setpshared( ) functions are part of the 32193 Barriers option and need not be provided on all implementations. 32194 RATIONALE 32195 None. 32196 FUTURE DIRECTIONS 32197 None. 32198 SEE ALSO 32199 pthread_barrier_init( ), pthread_barrierattr_destroy( ), pthread_barrierattr_init( ), the Base Definitions 32200 volume of IEEE Std 1003.1-200x, 32201 CHANGE HISTORY 32202 First released in Issue 6. Derived from IEEE Std 1003.1j-2000 1508 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_barrierattr_init( ) 32203 NAME 32204 pthread_barrierattr_init - initialize barrier attributes object (ADVANCED REALTIME 32205 THREADS) 32206 SYNOPSIS 32207 THR BAR #include 32208 int pthread_barrierattr_init(pthread_barrierattr_t *attr); 32209 32210 DESCRIPTION 32211 Refer to pthread_barrierattr_destroy( ). System Interfaces, Issue 6 1509 pthread_barrierattr_setpshared( ) System Interfaces 32212 NAME 32213 pthread_barrierattr_setpshared - set process-shared attribute of barrier attributes object 32214 (ADVANCED REALTIME THREADS) 32215 SYNOPSIS 32216 THR #include 32217 BAR TSH int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, 32218 int pshared); 32219 32220 DESCRIPTION 32221 Refer to pthread_barrierattr_getpshared( ). 1510 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cancel( ) 32222 NAME 32223 pthread_cancel - cancel execution of a thread 32224 SYNOPSIS 32225 THR #include 32226 int pthread_cancel(pthread_t thread); 32227 32228 DESCRIPTION 32229 The pthread_cancel( ) function shall request that thread be canceled. The target thread's 32230 cancelability state and type determines when the cancelation takes effect. When the cancelation 32231 is acted on, the cancelation cleanup handlers for thread shall be called. When the last cancelation 32232 cleanup handler returns, the thread-specific data destructor functions shall be called for thread. 32233 When the last destructor function returns, thread shall be terminated. 32234 The cancelation processing in the target thread shall run asynchronously with respect to the 32235 calling thread returning from pthread_cancel( ). 32236 RETURN VALUE 32237 If successful, the pthread_cancel( ) function shall return zero; otherwise, an error number shall be 32238 returned to indicate the error. 32239 ERRORS 32240 The pthread_cancel( ) function may fail if: 32241 [ESRCH] No thread could be found corresponding to that specified by the given thread 32242 ID. 32243 The pthread_cancel( ) function shall not return an error code of [EINTR]. 32244 EXAMPLES 32245 None. 32246 APPLICATION USAGE 32247 None. 32248 RATIONALE 32249 Two alternative functions were considered to sending the cancelation notification to a thread. 32250 One would be to define a new SIGCANCEL signal that had the cancelation semantics when 32251 delivered; the other was to define the new pthread_cancel( ) function, which would trigger the 32252 cancelation semantics. 32253 The advantage of a new signal was that so much of the delivery criteria were identical to that 32254 used when trying to deliver a signal that making cancelation notification a signal was seen as 32255 consistent. Indeed, many implementations implement cancelation using a special signal. On the 32256 other hand, there would be no signal functions that could be used with this signal except 32257 pthread_kill ( ), and the behavior of the delivered cancelation signal would be unlike any 32258 previously existing defined signal. 32259 The benefits of a special function include the recognition that this signal would be defined 32260 because of the similar delivery criteria and that this is the only common behavior between a 32261 cancelation request and a signal. In addition, the cancelation delivery mechanism does not have 32262 to be implemented as a signal. There are also strong, if not stronger, parallels with language 32263 exception mechanisms than with signals that are potentially obscured if the delivery mechanism 32264 is visibly closer to signals. 32265 In the end, it was considered that as there were so many exceptions to the use of the new signal 32266 with existing signals functions that it would be misleading. A special function has resolved this System Interfaces, Issue 6 1511 pthread_cancel( ) System Interfaces 32267 problem. This function was carefully defined so that an implementation wishing to provide the 32268 cancelation functions on top of signals could do so. The special function also means that 32269 implementations are not obliged to implement cancelation with signals. 32270 FUTURE DIRECTIONS 32271 None. 32272 SEE ALSO 32273 pthread_exit( ), pthread_cond_wait( ), pthread_cond_timedwait( ), pthread_join( ), 32274 pthread_setcancelstate( ), the Base Definitions volume of IEEE Std 1003.1-200x, 32275 CHANGE HISTORY 32276 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32277 Issue 6 32278 The pthread_cancel( ) function is marked as part of the Threads option. 1512 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cleanup_pop( ) 32279 NAME 32280 pthread_cleanup_pop, pthread_cleanup_push - establish cancelation handlers 32281 SYNOPSIS 32282 THR #include 32283 void pthread_cleanup_pop(int execute); 32284 void pthread_cleanup_push(void (*routine)(void*), void *arg); 32285 32286 DESCRIPTION 32287 The pthread_cleanup_pop( ) function shall remove the routine at the top of the calling thread's 32288 cancelation cleanup stack and optionally invoke it (if execute is non-zero). 32289 The pthread_cleanup_push( ) function shall push the specified cancelation cleanup handler routine 32290 onto the calling thread's cancelation cleanup stack. The cancelation cleanup handler shall be 32291 popped from the cancelation cleanup stack and invoked with the argument arg when: 32292 * The thread exits (that is, calls pthread_exit( )). 32293 * The thread acts upon a cancelation request. 32294 * The thread calls pthread_cleanup_pop( ) with a non-zero execute argument. 32295 These functions may be implemented as macros. The application shall ensure that they appear 32296 as statements, and in pairs within the same lexical scope (that is, the pthread_cleanup_push( ) 32297 macro may be thought to expand to a token list whose first token is '{' with 32298 pthread_cleanup_pop( ) expanding to a token list whose last token is the corresponding '}'). 32299 The effect of calling longjmp( ) or siglongjmp( ) is undefined if there have been any calls to 32300 pthread_cleanup_push( ) or pthread_cleanup_pop( ) made without the matching call since the jump 32301 buffer was filled. The effect of calling longjmp( ) or siglongjmp( ) from inside a cancelation 32302 cleanup handler is also undefined unless the jump buffer was also filled in the cancelation 32303 cleanup handler. 32304 RETURN VALUE 32305 The pthread_cleanup_push( ) and pthread_cleanup_pop( ) functions shall not return a value. 32306 ERRORS 32307 No errors are defined. 32308 These functions shall not return an error code of [EINTR]. 32309 EXAMPLES 32310 The following is an example using thread primitives to implement a cancelable, writers-priority 32311 read-write lock: 32312 typedef struct { 32313 pthread_mutex_t lock; 32314 pthread_cond_t rcond, 32315 wcond; 32316 int lock_count; /* < 0 .. Held by writer. */ 32317 /* > 0 .. Held by lock_count readers. */ 32318 /* = 0 .. Held by nobody. */ 32319 int waiting_writers; /* Count of waiting writers. */ 32320 } rwlock; 32321 void 32322 waiting_reader_cleanup(void *arg) 32323 { System Interfaces, Issue 6 1513 pthread_cleanup_pop( ) System Interfaces 32324 rwlock *l; 32325 l = (rwlock *) arg; 32326 pthread_mutex_unlock(&l->lock); 32327 } 32328 void 32329 lock_for_read(rwlock *l) 32330 { 32331 pthread_mutex_lock(&l->lock); 32332 pthread_cleanup_push(waiting_reader_cleanup, l); 32333 while ((l->lock_count < 0) && (l->waiting_writers != 0)) 32334 pthread_cond_wait(&l->rcond, &l->lock); 32335 l->lock_count++; 32336 /* 32337 * Note the pthread_cleanup_pop executes 32338 * waiting_reader_cleanup. 32339 */ 32340 pthread_cleanup_pop(1); 32341 } 32342 void 32343 release_read_lock(rwlock *l) 32344 { 32345 pthread_mutex_lock(&l->lock); 32346 if (- -l->lock_count == 0) 32347 pthread_cond_signal(&l->wcond); 32348 pthread_mutex_unlock(l); 32349 } 32350 void 32351 waiting_writer_cleanup(void *arg) 32352 { 32353 rwlock *l; 32354 l = (rwlock *) arg; 32355 if ((- -l->waiting_writers == 0) && (l->lock_count >= 0)) { 32356 /* 32357 * This only happens if we have been canceled. 32358 */ 32359 pthread_cond_broadcast(&l->wcond); 32360 } 32361 pthread_mutex_unlock(&l->lock); 32362 } 32363 void 32364 lock_for_write(rwlock *l) 32365 { 32366 pthread_mutex_lock(&l->lock); 32367 l->waiting_writers++; 32368 pthread_cleanup_push(waiting_writer_cleanup, l); 32369 while (l->lock_count != 0) 32370 pthread_cond_wait(&l->wcond, &l->lock); 32371 l->lock_count = -1; 32372 /* 1514 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cleanup_pop( ) 32373 * Note the pthread_cleanup_pop executes 32374 * waiting_writer_cleanup. 32375 */ 32376 pthread_cleanup_pop(1); 32377 } 32378 void 32379 release_write_lock(rwlock *l) 32380 { 32381 pthread_mutex_lock(&l->lock); 32382 l->lock_count = 0; 32383 if (l->waiting_writers == 0) 32384 pthread_cond_broadcast(&l->rcond) 32385 else 32386 pthread_cond_signal(&l->wcond); 32387 pthread_mutex_unlock(&l->lock); 32388 } 32389 /* 32390 * This function is called to initialize the read/write lock. 32391 */ 32392 void 32393 initialize_rwlock(rwlock *l) 32394 { 32395 pthread_mutex_init(&l->lock, pthread_mutexattr_default); 32396 pthread_cond_init(&l->wcond, pthread_condattr_default); 32397 pthread_cond_init(&l->rcond, pthread_condattr_default); 32398 l->lock_count = 0; 32399 l->waiting_writers = 0; 32400 } 32401 reader_thread() 32402 { 32403 lock_for_read(&lock); 32404 pthread_cleanup_push(release_read_lock, &lock); 32405 /* 32406 * Thread has read lock. 32407 */ 32408 pthread_cleanup_pop(1); 32409 } 32410 writer_thread() 32411 { 32412 lock_for_write(&lock); 32413 pthread_cleanup_push(release_write_lock, &lock); 32414 /* 32415 * Thread has write lock. 32416 */ 32417 pthread_cleanup_pop(1); 32418 } System Interfaces, Issue 6 1515 pthread_cleanup_pop( ) System Interfaces 32419 APPLICATION USAGE 32420 The two routines that push and pop cancelation cleanup handlers, pthread_cleanup_push( ) and 32421 pthread_cleanup_pop( ), can be thought of as left and right parentheses. They always need to be 32422 matched. 32423 RATIONALE 32424 The restriction that the two routines that push and pop cancelation cleanup handlers, 32425 pthread_cleanup_push( ) and pthread_cleanup_pop( ), have to appear in the same lexical scope 32426 allows for efficient macro or compiler implementations and efficient storage management. A 32427 sample implementation of these routines as macros might look like this: 32428 #define pthread_cleanup_push(rtn,arg) { \ 32429 struct _pthread_handler_rec __cleanup_handler, **__head; \ 32430 __cleanup_handler.rtn = rtn; \ 32431 __cleanup_handler.arg = arg; \ 32432 (void) pthread_getspecific(_pthread_handler_key, &__head); \ 32433 __cleanup_handler.next = *__head; \ 32434 *__head = &__cleanup_handler; 32435 #define pthread_cleanup_pop(ex) \ 32436 *__head = __cleanup_handler.next; \ 32437 if (ex) (*__cleanup_handler.rtn)(__cleanup_handler.arg); \ 32438 } 32439 A more ambitious implementation of these routines might do even better by allowing the 32440 compiler to note that the cancelation cleanup handler is a constant and can be expanded inline. 32441 This volume of IEEE Std 1003.1-200x currently leaves unspecified the effect of calling longjmp( ) 32442 from a signal handler executing in a POSIX System Interfaces function. If an implementation 32443 wants to allow this and give the programmer reasonable behavior, the longjmp( ) function has to 32444 call all cancelation cleanup handlers that have been pushed but not popped since the time 32445 setjmp( ) was called. 32446 Consider a multi-threaded function called by a thread that uses signals. If a signal were 32447 delivered to a signal handler during the operation of qsort( ) and that handler were to call 32448 longjmp( ) (which, in turn, did not call the cancelation cleanup handlers) the helper threads 32449 created by the qsort( ) function would not be canceled. Instead, they would continue to execute 32450 and write into the argument array even though the array might have been popped off of the 32451 stack. 32452 Note that the specified cleanup handling mechanism is especially tied to the C language and, 32453 while the requirement for a uniform mechanism for expressing cleanup is language- 32454 independent, the mechanism used in other languages may be quite different. In addition, this 32455 mechanism is really only necessary due to the lack of a real exception mechanism in the C 32456 language, which would be the ideal solution. 32457 There is no notion of a cancelation cleanup-safe function. If an application has no cancelation 32458 points in its signal handlers, blocks any signal whose handler may have cancelation points while 32459 calling async-unsafe functions, or disables cancelation while calling async-unsafe functions, all 32460 functions may be safely called from cancelation cleanup routines. 32461 FUTURE DIRECTIONS 32462 None. 1516 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cleanup_pop( ) 32463 SEE ALSO 32464 pthread_cancel( ), pthread_setcancelstate( ), the Base Definitions volume of IEEE Std 1003.1-200x, 32465 32466 CHANGE HISTORY 32467 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32468 Issue 6 32469 The pthread_cleanup_pop( ) and pthread_cleanup_push( ) functions are marked as part of the 32470 Threads option. 32471 The APPLICATION USAGE section is added. 32472 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1517 pthread_cond_broadcast( ) System Interfaces 32473 NAME 32474 pthread_cond_broadcast, pthread_cond_signal - broadcast or signal a condition 32475 SYNOPSIS 32476 THR #include 32477 int pthread_cond_broadcast(pthread_cond_t *cond); 32478 int pthread_cond_signal(pthread_cond_t *cond); 32479 32480 DESCRIPTION 32481 These functions shall unblock threads blocked on a condition variable. | 32482 The pthread_cond_broadcast( ) function shall unblock all threads currently blocked on the 32483 specified condition variable cond. 32484 The pthread_cond_signal( ) function shall unblock at least one of the threads that are blocked on 32485 the specified condition variable cond (if any threads are blocked on cond). 32486 If more than one thread is blocked on a condition variable, the scheduling policy shall determine | 32487 the order in which threads are unblocked. When each thread unblocked as a result of a | 32488 pthread_cond_broadcast( ) or pthread_cond_signal( ) returns from its call to pthread_cond_wait( ) or 32489 pthread_cond_timedwait( ), the thread shall own the mutex with which it called | 32490 pthread_cond_wait( ) or pthread_cond_timedwait( ). The thread(s) that are unblocked shall contend 32491 for the mutex according to the scheduling policy (if applicable), and as if each had called 32492 pthread_mutex_lock( ). 32493 The pthread_cond_broadcast( ) or pthread_cond_signal( ) functions may be called by a thread 32494 whether or not it currently owns the mutex that threads calling pthread_cond_wait( ) or 32495 pthread_cond_timedwait( ) have associated with the condition variable during their waits; 32496 however, if predictable scheduling behavior is required, then that mutex shall be locked by the 32497 thread calling pthread_cond_broadcast( ) or pthread_cond_signal( ). 32498 The pthread_cond_broadcast( ) and pthread_cond_signal( ) functions shall have no effect if there are | 32499 no threads currently blocked on cond. | 32500 RETURN VALUE 32501 If successful, the pthread_cond_broadcast( ) and pthread_cond_signal( ) functions shall return zero; 32502 otherwise, an error number shall be returned to indicate the error. 32503 ERRORS 32504 The pthread_cond_broadcast( ) and pthread_cond_signal( ) function may fail if: 32505 [EINVAL] The value cond does not refer to an initialized condition variable. 32506 These functions shall not return an error code of [EINTR]. 32507 EXAMPLES 32508 None. 32509 APPLICATION USAGE 32510 The pthread_cond_broadcast( ) function is used whenever the shared-variable state has been 32511 changed in a way that more than one thread can proceed with its task. Consider a single 32512 producer/multiple consumer problem, where the producer can insert multiple items on a list 32513 that is accessed one item at a time by the consumers. By calling the pthread_cond_broadcast( ) 32514 function, the producer would notify all consumers that might be waiting, and thereby the 32515 application would receive more throughput on a multi-processor. In addition, 32516 pthread_cond_broadcast( ) makes it easier to implement a read-write lock. The 32517 pthread_cond_broadcast( ) function is needed in order to wake up all waiting readers when a 1518 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_broadcast( ) 32518 writer releases its lock. Finally, the two-phase commit algorithm can use this broadcast function 32519 to notify all clients of an impending transaction commit. 32520 It is not safe to use the pthread_cond_signal( ) function in a signal handler that is invoked 32521 asynchronously. Even if it were safe, there would still be a race between the test of the Boolean 32522 pthread_cond_wait( ) that could not be efficiently eliminated. 32523 Mutexes and condition variables are thus not suitable for releasing a waiting thread by signaling 32524 from code running in a signal handler. 32525 RATIONALE 32526 Multiple Awakenings by Condition Signal 32527 On a multi-processor, it may be impossible for an implementation of pthread_cond_signal( ) to 32528 avoid the unblocking of more than one thread blocked on a condition variable. For example, 32529 consider the following partial implementation of pthread_cond_wait( ) and pthread_cond_signal( ), 32530 executed by two threads in the order given. One thread is trying to wait on the condition 32531 variable, another is concurrently executing pthread_cond_signal( ), while a third thread is already 32532 waiting. 32533 pthread_cond_wait(mutex, cond): 32534 value = cond->value; /* 1 */ 32535 pthread_mutex_unlock(mutex); /* 2 */ 32536 pthread_mutex_lock(cond->mutex); /* 10 */ 32537 if (value == cond->value) { /* 11 */ 32538 me->next_cond = cond->waiter; 32539 cond->waiter = me; 32540 pthread_mutex_unlock(cond->mutex); 32541 unable_to_run(me); 32542 } else 32543 pthread_mutex_unlock(cond->mutex); /* 12 */ 32544 pthread_mutex_lock(mutex); /* 13 */ 32545 pthread_cond_signal(cond): 32546 pthread_mutex_lock(cond->mutex); /* 3 */ 32547 cond->value++; /* 4 */ 32548 if (cond->waiter) { /* 5 */ 32549 sleeper = cond->waiter; /* 6 */ 32550 cond->waiter = sleeper->next_cond; /* 7 */ 32551 able_to_run(sleeper); /* 8 */ 32552 } 32553 pthread_mutex_unlock(cond->mutex); /* 9 */ 32554 The effect is that more than one thread can return from its call to pthread_cond_wait( ) or 32555 pthread_cond_timedwait( ) as a result of one call to pthread_cond_signal( ). This effect is called 32556 ``spurious wakeup''. Note that the situation is self-correcting in that the number of threads that 32557 are so awakened is finite; for example, the next thread to call pthread_cond_wait( ) after the 32558 sequence of events above blocks. 32559 While this problem could be resolved, the loss of efficiency for a fringe condition that occurs 32560 only rarely is unacceptable, especially given that one has to check the predicate associated with a 32561 condition variable anyway. Correcting this problem would unnecessarily reduce the degree of 32562 concurrency in this basic building block for all higher-level synchronization operations. 32563 An added benefit of allowing spurious wakeups is that applications are forced to code a 32564 predicate-testing-loop around the condition wait. This also makes the application tolerate System Interfaces, Issue 6 1519 pthread_cond_broadcast( ) System Interfaces 32565 superfluous condition broadcasts or signals on the same condition variable that may be coded in 32566 some other part of the application. The resulting applications are thus more robust. Therefore, 32567 IEEE Std 1003.1-200x explicitly documents that spurious wakeups may occur. 32568 FUTURE DIRECTIONS 32569 None. 32570 SEE ALSO 32571 pthread_cond_destroy( ), pthread_cond_timedwait( ), pthread_cond_wait( ), the Base Definitions 32572 volume of IEEE Std 1003.1-200x, 32573 CHANGE HISTORY 32574 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32575 Issue 6 32576 The pthread_cond_broadcast( ) and pthread_cond_signal( ) functions are marked as part of the 32577 Threads option. 32578 The APPLICATION USAGE section is added. 1520 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_destroy( ) 32579 NAME 32580 pthread_cond_destroy, pthread_cond_init - destroy and initialize condition variables 32581 SYNOPSIS 32582 THR #include 32583 int pthread_cond_destroy(pthread_cond_t *cond); 32584 int pthread_cond_init(pthread_cond_t *restrict cond, 32585 const pthread_condattr_t *restrict attr); 32586 pthread_cond_t cond = PTHREAD_COND_INITIALIZER; 32587 32588 DESCRIPTION 32589 The pthread_cond_destroy( ) function shall destroy the given condition variable specified by cond; 32590 the object becomes, in effect, uninitialized. An implementation may cause pthread_cond_destroy( ) 32591 to set the object referenced by cond to an invalid value. A destroyed condition variable object can 32592 be reinitialized using pthread_cond_init( ); the results of otherwise referencing the object after it | 32593 has been destroyed are undefined. 32594 It shall be safe to destroy an initialized condition variable upon which no threads are currently 32595 blocked. Attempting to destroy a condition variable upon which other threads are currently 32596 blocked results in undefined behavior. 32597 The pthread_cond_init( ) function shall initialize the condition variable referenced by cond with 32598 attributes referenced by attr. If attr is NULL, the default condition variable attributes shall be | 32599 used; the effect is the same as passing the address of a default condition variable attributes | 32600 object. Upon successful initialization, the state of the condition variable shall become initialized. | 32601 Only cond itself may be used for performing synchronization. The result of referring to copies of 32602 cond in calls to pthread_cond_wait( ), pthread_cond_timedwait( ), pthread_cond_signal( ), 32603 pthread_cond_broadcast( ), and pthread_cond_destroy( ) is undefined. 32604 Attempting to initialize an already initialized condition variable results in undefined behavior. 32605 In cases where default condition variable attributes are appropriate, the macro 32606 PTHREAD_COND_INITIALIZER can be used to initialize condition variables that are statically 32607 allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_cond_init( ) 32608 with parameter attr specified as NULL, except that no error checks are performed. 32609 RETURN VALUE 32610 If successful, the pthread_cond_destroy( ) and pthread_cond_init( ) functions shall return zero; 32611 otherwise, an error number shall be returned to indicate the error. 32612 The [EBUSY] and [EINVAL] error checks, if implemented, shall act as if they were performed 32613 immediately at the beginning of processing for the function and caused an error return prior to 32614 modifying the state of the condition variable specified by cond. 32615 ERRORS 32616 The pthread_cond_destroy( ) function may fail if: 32617 [EBUSY] The implementation has detected an attempt to destroy the object referenced 32618 by cond while it is referenced (for example, while being used in a 32619 pthread_cond_wait( ) or pthread_cond_timedwait( )) by another thread. 32620 [EINVAL] The value specified by cond is invalid. 32621 The pthread_cond_init( ) function shall fail if: 32622 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 32623 another condition variable. System Interfaces, Issue 6 1521 pthread_cond_destroy( ) System Interfaces 32624 [ENOMEM] Insufficient memory exists to initialize the condition variable. 32625 The pthread_cond_init( ) function may fail if: 32626 [EBUSY] The implementation has detected an attempt to reinitialize the object | 32627 referenced by cond, a previously initialized, but not yet destroyed, condition 32628 variable. 32629 [EINVAL] The value specified by attr is invalid. 32630 These functions shall not return an error code of [EINTR]. 32631 EXAMPLES 32632 A condition variable can be destroyed immediately after all the threads that are blocked on it are 32633 awakened. For example, consider the following code: 32634 struct list { 32635 pthread_mutex_t lm; 32636 ... 32637 } 32638 struct elt { 32639 key k; 32640 int busy; 32641 pthread_cond_t notbusy; 32642 ... 32643 } 32644 /* Find a list element and reserve it. */ 32645 struct elt * 32646 list_find(struct list *lp, key k) 32647 { 32648 struct elt *ep; 32649 pthread_mutex_lock(&lp->lm); 32650 while ((ep = find_elt(l, k) != NULL) && ep->busy) 32651 pthread_cond_wait(&ep->notbusy, &lp->lm); 32652 if (ep != NULL) 32653 ep->busy = 1; 32654 pthread_mutex_unlock(&lp->lm); 32655 return(ep); 32656 } 32657 delete_elt(struct list *lp, struct elt *ep) 32658 { 32659 pthread_mutex_lock(&lp->lm); 32660 assert(ep->busy); 32661 ... remove ep from list ... 32662 ep->busy = 0; /* Paranoid. */ 32663 (A) pthread_cond_broadcast(&ep->notbusy); 32664 pthread_mutex_unlock(&lp->lm); 32665 (B) pthread_cond_destroy(&rp->notbusy); 32666 free(ep); 32667 } 32668 In this example, the condition variable and its list element may be freed (line B) immediately 32669 after all threads waiting for it are awakened (line A), since the mutex and the code ensure that no 32670 other thread can touch the element to be deleted. 1522 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_destroy( ) 32671 APPLICATION USAGE 32672 None. 32673 RATIONALE 32674 See pthread_mutex_init( ); a similar rationale applies to condition variables. 32675 FUTURE DIRECTIONS 32676 None. 32677 SEE ALSO 32678 pthread_cond_broadcast( ), pthread_cond_signal( ), pthread_cond_timedwait( ), pthread_cond_wait( ), 32679 the Base Definitions volume of IEEE Std 1003.1-200x, 32680 CHANGE HISTORY 32681 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32682 Issue 6 32683 The pthread_cond_destroy( ) and pthread_cond_init( ) functions are marked as part of the Threads 32684 option. 32685 IEEE PASC Interpretation 1003.1c #34 is applied, updating the DESCRIPTION. 32686 The restrict keyword is added to the pthread_cond_init( ) prototype for alignment with the 32687 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1523 pthread_cond_init( ) System Interfaces 32688 NAME 32689 pthread_cond_init - initialize condition variables 32690 SYNOPSIS 32691 THR #include 32692 int pthread_cond_init(pthread_cond_t *restrict cond, 32693 const pthread_condattr_t *restrict attr); 32694 pthread_cond_t cond = PTHREAD_COND_INITIALIZER; 32695 32696 DESCRIPTION 32697 Refer to pthread_cond_destroy( ). 1524 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_signal( ) 32698 NAME 32699 pthread_cond_signal - signal a condition 32700 SYNOPSIS 32701 THR #include 32702 int pthread_cond_signal(pthread_cond_t *cond); 32703 32704 DESCRIPTION 32705 Refer to pthread_cond_broadcast( ). System Interfaces, Issue 6 1525 pthread_cond_timedwait( ) System Interfaces 32706 NAME 32707 pthread_cond_timedwait, pthread_cond_wait - wait on a condition 32708 SYNOPSIS 32709 THR #include 32710 int pthread_cond_timedwait(pthread_cond_t *restrict cond, 32711 pthread_mutex_t *restrict mutex, 32712 const struct timespec *restrict abstime); 32713 int pthread_cond_wait(pthread_cond_t *restrict cond, 32714 pthread_mutex_t *restrict mutex); 32715 32716 DESCRIPTION 32717 The pthread_cond_timedwait( ) and pthread_cond_wait( ) functions shall block on a condition | 32718 variable. They shall be called with mutex locked by the calling thread or undefined behavior | 32719 results. 32720 These functions atomically release mutex and cause the calling thread to block on the condition 32721 variable cond; atomically here means ``atomically with respect to access by another thread to the 32722 mutex and then the condition variable''. That is, if another thread is able to acquire the mutex 32723 after the about-to-block thread has released it, then a subsequent call to pthread_cond_broadcast( ) 32724 or pthread_cond_signal( ) in that thread shall behave as if it were issued after the about-to-block 32725 thread has blocked. 32726 Upon successful return, the mutex shall have been locked and shall be owned by the calling | 32727 thread. | 32728 When using condition variables there is always a Boolean predicate involving shared variables 32729 associated with each condition wait that is true if the thread should proceed. Spurious wakeups 32730 from the pthread_cond_timedwait( ) or pthread_cond_wait( ) functions may occur. Since the return 32731 from pthread_cond_timedwait( ) or pthread_cond_wait( ) does not imply anything about the value 32732 of this predicate, the predicate should be re-evaluated upon such return. 32733 The effect of using more than one mutex for concurrent pthread_cond_timedwait( ) or 32734 pthread_cond_wait( ) operations on the same condition variable is undefined; that is, a condition 32735 variable becomes bound to a unique mutex when a thread waits on the condition variable, and 32736 this (dynamic) binding shall end when the wait returns. 32737 A condition wait (whether timed or not) is a cancelation point. When the cancelability enable 32738 state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a 32739 cancelation request while in a condition wait is that the mutex is (in effect) re-acquired before 32740 calling the first cancelation cleanup handler. The effect is as if the thread were unblocked, 32741 allowed to execute up to the point of returning from the call to pthread_cond_timedwait( ) or 32742 pthread_cond_wait( ), but at that point notices the cancelation request and instead of returning to 32743 the caller of pthread_cond_timedwait( ) or pthread_cond_wait( ), starts the thread cancelation 32744 activities, which includes calling cancelation cleanup handlers. 32745 A thread that has been unblocked because it has been canceled while blocked in a call to 32746 pthread_cond_timedwait( ) or pthread_cond_wait( ) shall not consume any condition signal that 32747 may be directed concurrently at the condition variable if there are other threads blocked on the 32748 condition variable. 32749 The pthread_cond_timedwait( ) function shall be equivalent to pthread_cond_wait( ), except that an | 32750 error is returned if the absolute time specified by abstime passes (that is, system time equals or 32751 exceeds abstime) before the condition cond is signaled or broadcasted, or if the absolute time 32752 CS 1526 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_timedwait( ) 32753 specified by abstime has already been passed at the time of the call. If the Clock Selection option 32754 is supported, the condition variable shall have a clock attribute which specifies the clock that 32755 shall be used to measure the time specified by the abstime argument. When such timeouts occur, 32756 pthread_cond_timedwait( ) shall nonetheless release and re-acquire the mutex referenced by mutex. 32757 The pthread_cond_timedwait( ) function is also a cancelation point. 32758 If a signal is delivered to a thread waiting for a condition variable, upon return from the signal 32759 handler the thread resumes waiting for the condition variable as if it was not interrupted, or it 32760 shall return zero due to spurious wakeup. 32761 RETURN VALUE 32762 Except in the case of [ETIMEDOUT], all these error checks shall act as if they were performed 32763 immediately at the beginning of processing for the function and shall cause an error return, in 32764 effect, prior to modifying the state of the mutex specified by mutex or the condition variable 32765 specified by cond. 32766 Upon successful completion, a value of zero shall be returned; otherwise, an error number shall 32767 be returned to indicate the error. 32768 ERRORS 32769 The pthread_cond_timedwait( ) function shall fail if: 32770 [ETIMEDOUT] The time specified by abstime to pthread_cond_timedwait( ) has passed. 32771 The pthread_cond_timedwait( ) and pthread_cond_wait( ) functions may fail if: 32772 [EINVAL] The value specified by cond, mutex, or abstime is invalid. 32773 [EINVAL] Different mutexes were supplied for concurrent pthread_cond_timedwait( ) or 32774 pthread_cond_wait( ) operations on the same condition variable. 32775 [EPERM] The mutex was not owned by the current thread at the time of the call. 32776 These functions shall not return an error code of [EINTR]. 32777 EXAMPLES 32778 None. 32779 APPLICATION USAGE 32780 None. 32781 RATIONALE 32782 Condition Wait Semantics 32783 It is important to note that when pthread_cond_wait( ) and pthread_cond_timedwait( ) return 32784 without error, the associated predicate may still be false. Similarly, when 32785 pthread_cond_timedwait( ) returns with the timeout error, the associated predicate may be true 32786 due to an unavoidable race between the expiration of the timeout and the predicate state change. 32787 Some implementations, particularly on a multi-processor, may sometimes cause multiple 32788 threads to wake up when the condition variable is signaled simultaneously on different 32789 processors. 32790 In general, whenever a condition wait returns, the thread has to re-evaluate the predicate 32791 associated with the condition wait to determine whether it can safely proceed, should wait 32792 again, or should declare a timeout. A return from the wait does not imply that the associated 32793 predicate is either true or false. 32794 It is thus recommended that a condition wait be enclosed in the equivalent of a ``while loop'' 32795 that checks the predicate. System Interfaces, Issue 6 1527 pthread_cond_timedwait( ) System Interfaces 32796 Timed Wait Semantics 32797 An absolute time measure was chosen for specifying the timeout parameter for two reasons. 32798 First, a relative time measure can be easily implemented on top of a function that specifies 32799 absolute time, but there is a race condition associated with specifying an absolute timeout on top 32800 of a function that specifies relative timeouts. For example, assume that clock_gettime( ) returns 32801 the current time and cond_relative_timed_wait( ) uses relative timeouts: 32802 clock_gettime(CLOCK_REALTIME, &now) 32803 reltime = sleep_til_this_absolute_time -now; 32804 cond_relative_timed_wait(c, m, &reltime); 32805 If the thread is preempted between the first statement and the last statement, the thread blocks 32806 for too long. Blocking, however, is irrelevant if an absolute timeout is used. An absolute timeout 32807 also need not be recomputed if it is used multiple times in a loop, such as that enclosing a 32808 condition wait. 32809 For cases when the system clock is advanced discontinuously by an operator, it is expected that 32810 implementations process any timed wait expiring at an intervening time as if that time had 32811 actually occurred. 32812 Cancelation and Condition Wait 32813 A condition wait, whether timed or not, is a cancelation point. That is, the functions 32814 pthread_cond_wait( ) or pthread_cond_timedwait( ) are points where a pending (or concurrent) 32815 cancelation request is noticed. The reason for this is that an indefinite wait is possible at these 32816 points-whatever event is being waited for, even if the program is totally correct, might never 32817 occur; for example, some input data being awaited might never be sent. By making condition 32818 wait a cancelation point, the thread can be canceled and perform its cancelation cleanup handler 32819 even though it may be stuck in some indefinite wait. 32820 A side effect of acting on a cancelation request while a thread is blocked on a condition variable 32821 is to re-acquire the mutex before calling any of the cancelation cleanup handlers. This is done in 32822 order to ensure that the cancelation cleanup handler is executed in the same state as the critical 32823 code that lies both before and after the call to the condition wait function. This rule is also 32824 required when interfacing to POSIX threads from languages, such as Ada or C++, which may 32825 choose to map cancelation onto a language exception; this rule ensures that each exception 32826 handler guarding a critical section can always safely depend upon the fact that the associated 32827 mutex has already been locked regardless of exactly where within the critical section the 32828 exception was raised. Without this rule, there would not be a uniform rule that exception 32829 handlers could follow regarding the lock, and so coding would become very cumbersome. 32830 Therefore, since some statement has to be made regarding the state of the lock when a 32831 cancelation is delivered during a wait, a definition has been chosen that makes application 32832 coding most convenient and error free. 32833 When acting on a cancelation request while a thread is blocked on a condition variable, the 32834 implementation is required to ensure that the thread does not consume any condition signals 32835 directed at that condition variable if there are any other threads waiting on that condition 32836 variable. This rule is specified in order to avoid deadlock conditions that could occur if these two 32837 independent requests (one acting on a thread and the other acting on the condition variable) 32838 were not processed independently. 1528 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_timedwait( ) 32839 Performance of Mutexes and Condition Variables 32840 Mutexes are expected to be locked only for a few instructions. This practice is almost 32841 automatically enforced by the desire of programmers to avoid long serial regions of execution 32842 (which would reduce total effective parallelism). 32843 When using mutexes and condition variables, one tries to ensure that the usual case is to lock the 32844 mutex, access shared data, and unlock the mutex. Waiting on a condition variable should be a 32845 relatively rare situation. For example, when implementing a read-write lock, code that acquires a 32846 read-lock typically needs only to increment the count of readers (under mutual-exclusion) and 32847 return. The calling thread would actually wait on the condition variable only when there is 32848 already an active writer. So the efficiency of a synchronization operation is bounded by the cost 32849 of mutex lock/unlock and not by condition wait. Note that in the usual case there is no context 32850 switch. 32851 This is not to say that the efficiency of condition waiting is unimportant. Since there needs to be 32852 at least one context switch per Ada rendezvous, the efficiency of waiting on a condition variable 32853 is important. The cost of waiting on a condition variable should be little more than the minimal 32854 cost for a context switch plus the time to unlock and lock the mutex. 32855 Features of Mutexes and Condition Variables 32856 It had been suggested that the mutex acquisition and release be decoupled from condition wait. 32857 This was rejected because it is the combined nature of the operation that, in fact, facilitates 32858 realtime implementations. Those implementations can atomically move a high-priority thread 32859 between the condition variable and the mutex in a manner that is transparent to the caller. This 32860 can prevent extra context switches and provide more deterministic acquisition of a mutex when 32861 the waiting thread is signaled. Thus, fairness and priority issues can be dealt with directly by the 32862 scheduling discipline. Furthermore, the current condition wait operation matches existing 32863 practice. 32864 Scheduling Behavior of Mutexes and Condition Variables 32865 Synchronization primitives that attempt to interfere with scheduling policy by specifying an 32866 ordering rule are considered undesirable. Threads waiting on mutexes and condition variables 32867 are selected to proceed in an order dependent upon the scheduling policy rather than in some 32868 fixed order (for example, FIFO or priority). Thus, the scheduling policy determines which 32869 thread(s) are awakened and allowed to proceed. 32870 Timed Condition Wait 32871 The pthread_cond_timedwait( ) function allows an application to give up waiting for a particular 32872 condition after a given amount of time. An example of its use follows: 32873 (void) pthread_mutex_lock(&t.mn); 32874 t.waiters++; 32875 clock_gettime(CLOCK_REALTIME, &ts); 32876 ts.tv_sec += 5; 32877 rc = 0; 32878 while (! mypredicate(&t) && rc == 0) 32879 rc = pthread_cond_timedwait(&t.cond, &t.mn, &ts); 32880 t.waiters- -; 32881 if (rc == 0) setmystate(&t); 32882 (void) pthread_mutex_unlock(&t.mn); System Interfaces, Issue 6 1529 pthread_cond_timedwait( ) System Interfaces 32883 By making the timeout parameter absolute, it does not need to be recomputed each time the 32884 program checks its blocking predicate. If the timeout was relative, it would have to be 32885 recomputed before each call. This would be especially difficult since such code would need to 32886 take into account the possibility of extra wakeups that result from extra broadcasts or signals on 32887 the condition variable that occur before either the predicate is true or the timeout is due. 32888 FUTURE DIRECTIONS 32889 None. 32890 SEE ALSO 32891 pthread_cond_signal( ), pthread_cond_broadcast( ), the Base Definitions volume of 32892 IEEE Std 1003.1-200x, 32893 CHANGE HISTORY 32894 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32895 Issue 6 32896 The pthread_cond_timedwait( ) and pthread_cond_wait( ) functions are marked as part of the 32897 Threads option. 32898 The Open Group Corrigendum U021/9 is applied, correcting the prototype for the 32899 pthread_cond_wait( ) function. 32900 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding semantics for 32901 the Clock Selection option. 32902 The ERRORS section has an additional case for [EPERM] in response to IEEE PASC 32903 Interpretation 1003.1c #28. 32904 The restrict keyword is added to the pthread_cond_timedwait( ) and pthread_cond_wait( ) 32905 prototypes for alignment with the ISO/IEC 9899: 1999 standard. 1530 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_cond_wait( ) 32906 NAME 32907 pthread_cond_wait - wait on a condition 32908 SYNOPSIS 32909 THR #include 32910 int pthread_cond_wait(pthread_cond_t *restrict cond, 32911 pthread_mutex_t *restrict mutex); 32912 32913 DESCRIPTION 32914 Refer to pthread_cond_timedwait( ). System Interfaces, Issue 6 1531 pthread_condattr_destroy( ) System Interfaces 32915 NAME 32916 pthread_condattr_destroy, pthread_condattr_init - destroy and initialize condition variable 32917 attributes object 32918 SYNOPSIS 32919 THR #include 32920 int pthread_condattr_destroy(pthread_condattr_t *attr); 32921 int pthread_condattr_init(pthread_condattr_t *attr); 32922 32923 DESCRIPTION 32924 The pthread_condattr_destroy( ) function shall destroy a condition variable attributes object; the 32925 object becomes, in effect, uninitialized. An implementation may cause pthread_condattr_destroy( ) 32926 to set the object referenced by attr to an invalid value. A destroyed attr attributes object can be | 32927 reinitialized using pthread_condattr_init( ); the results of otherwise referencing the object after it | 32928 has been destroyed are undefined. | 32929 The pthread_condattr_init( ) function shall initialize a condition variable attributes object attr with 32930 the default value for all of the attributes defined by the implementation. 32931 Results are undefined if pthread_condattr_init( ) is called specifying an already initialized attr | 32932 attributes object. | 32933 After a condition variable attributes object has been used to initialize one or more condition 32934 variables, any function affecting the attributes object (including destruction) shall not affect any | 32935 previously initialized condition variables. 32936 This volume of IEEE Std 1003.1-200x requires two attributes, the clock attribute and the process- 32937 shared attribute. 32938 Additional attributes, their default values, and the names of the associated functions to get and 32939 set those attribute values are implementation-defined. 32940 RETURN VALUE 32941 If successful, the pthread_condattr_destroy( ) and pthread_condattr_init( ) functions shall return 32942 zero; otherwise, an error number shall be returned to indicate the error. 32943 ERRORS 32944 The pthread_condattr_destroy( ) function may fail if: 32945 [EINVAL] The value specified by attr is invalid. 32946 The pthread_condattr_init( ) function shall fail if: 32947 [ENOMEM] Insufficient memory exists to initialize the condition variable attributes object. 32948 These functions shall not return an error code of [EINTR]. 32949 EXAMPLES 32950 None. 32951 APPLICATION USAGE 32952 None. 32953 RATIONALE 32954 See pthread_attr_init( ) and pthread_mutex_init( ). 32955 A process-shared attribute has been defined for condition variables for the same reason it has been 32956 defined for mutexes. 1532 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_condattr_destroy( ) 32957 FUTURE DIRECTIONS 32958 None. 32959 SEE ALSO 32960 pthread_cond_destroy( ), pthread_condattr_getpshared( ), pthread_create( ), pthread_mutex_destroy( ), 32961 the Base Definitions volume of IEEE Std 1003.1-200x, 32962 CHANGE HISTORY 32963 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 32964 Issue 6 32965 The pthread_condattr_destroy( ) and pthread_condattr_init( ) functions are marked as part of the 32966 Threads option. System Interfaces, Issue 6 1533 pthread_condattr_getclock( ) System Interfaces 32967 NAME 32968 pthread_condattr_getclock, pthread_condattr_setclock - get and set the clock selection 32969 condition variable attribute (ADVANCED REALTIME) 32970 SYNOPSIS 32971 THR CS #include 32972 int pthread_condattr_getclock(const pthread_condattr_t *restrict attr, 32973 clockid_t *restrict clock_id); 32974 int pthread_condattr_setclock(pthread_condattr_t *attr, 32975 clockid_t clock_id); 32976 32977 DESCRIPTION 32978 The pthread_condattr_getclock( ) function shall obtain the value of the clock attribute from the 32979 attributes object referenced by attr. The pthread_condattr_setclock( ) function shall set the clock | 32980 attribute in an initialized attributes object referenced by attr. If pthread_condattr_setclock( ) is 32981 called with a clock_id argument that refers to a CPU-time clock, the call shall fail. 32982 The clock attribute is the clock ID of the clock that shall be used to measure the timeout service of 32983 pthread_cond_timedwait( ). The default value of the clock attribute shall refer to the system clock. 32984 RETURN VALUE 32985 If successful, the pthread_condattr_getclock( ) function shall return zero and store the value of the 32986 clock attribute of attr into the object referenced by the clock_id argument. Otherwise, an error 32987 number shall be returned to indicate the error. 32988 If successful, the pthread_condattr_setclock( ) function shall return zero; otherwise, an error 32989 number shall be returned to indicate the error. 32990 ERRORS 32991 These functions may fail if: 32992 [EINVAL] The value specified by attr is invalid. 32993 The pthread_condattr_setclock( ) function may fail if: 32994 [EINVAL] The value specified by clock_id does not refer to a known clock, or is a CPU- 32995 time clock. 32996 These functions shall not return an error code of [EINTR]. 32997 EXAMPLES 32998 None. 32999 APPLICATION USAGE 33000 None. 33001 RATIONALE 33002 None. 33003 FUTURE DIRECTIONS 33004 None. 33005 SEE ALSO 33006 pthread_cond_init( ), pthread_cond_timedwait( ), pthread_condattr_destroy( ), 33007 pthread_condattr_getpshared( ) (on page 1536),1 pthread_condattr_init( ), 33008 pthread_condattr_setpshared( ) (on page 1540),1 pthread_create( ), pthread_mutex_init( ), the Base 33009 Definitions volume of IEEE Std 1003.1-200x, 1534 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_condattr_getclock( ) 33010 CHANGE HISTORY 33011 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. System Interfaces, Issue 6 1535 pthread_condattr_getpshared( ) System Interfaces 33012 NAME 33013 pthread_condattr_getpshared, pthread_condattr_setpshared - get and set the process-shared 33014 condition variable attributes 33015 SYNOPSIS 33016 THR TSH #include 33017 int pthread_condattr_getpshared(const pthread_condattr_t *restrict attr, 33018 int *restrict pshared); 33019 int pthread_condattr_setpshared(pthread_condattr_t *attr, 33020 int pshared); 33021 33022 DESCRIPTION 33023 The pthread_condattr_getpshared( ) function shall obtain the value of the process-shared attribute 33024 from the attributes object referenced by attr. The pthread_condattr_setpshared( ) function shall set | 33025 the process-shared attribute in an initialized attributes object referenced by attr. | 33026 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition 33027 variable to be operated upon by any thread that has access to the memory where the condition 33028 variable is allocated, even if the condition variable is allocated in memory that is shared by 33029 multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the 33030 condition variable shall only be operated upon by threads created within the same process as the | 33031 thread that initialized the condition variable; if threads of differing processes attempt to operate | 33032 on such a condition variable, the behavior is undefined. The default value of the attribute is | 33033 PTHREAD_PROCESS_PRIVATE. 33034 RETURN VALUE 33035 If successful, the pthread_condattr_setpshared( ) function shall return zero; otherwise, an error 33036 number shall be returned to indicate the error. 33037 If successful, the pthread_condattr_getpshared( ) function shall return zero and store the value of 33038 the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, 33039 an error number shall be returned to indicate the error. 33040 ERRORS 33041 The pthread_condattr_getpshared( ) and pthread_condattr_setpshared( ) functions may fail if: 33042 [EINVAL] The value specified by attr is invalid. 33043 The pthread_condattr_setpshared( ) function may fail if: 33044 [EINVAL] The new value specified for the attribute is outside the range of legal values 33045 for that attribute. 33046 These functions shall not return an error code of [EINTR]. 33047 EXAMPLES 33048 None. 33049 APPLICATION USAGE 33050 None. 33051 RATIONALE 33052 None. 1536 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_condattr_getpshared( ) 33053 FUTURE DIRECTIONS 33054 None. 33055 SEE ALSO 33056 pthread_create( ), pthread_cond_destroy( ), pthread_condattr_destroy( ), pthread_mutex_destroy( ), the 33057 Base Definitions volume of IEEE Std 1003.1-200x, 33058 CHANGE HISTORY 33059 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33060 Issue 6 33061 The pthread_condattr_getpshared( ) and pthread_condattr_setpshared( ) functions are marked as part 33062 of the Threads and Thread Process-Shared Synchronization options. 33063 The restrict keyword is added to the pthread_condattr_getpshared( ) prototype for alignment with 33064 the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1537 pthread_condattr_init( ) System Interfaces 33065 NAME 33066 pthread_condattr_init - initialize condition variable attributes object 33067 SYNOPSIS 33068 THR #include 33069 int pthread_condattr_init(pthread_condattr_t *attr); 33070 33071 DESCRIPTION 33072 Refer to pthread_condattr_destroy( ). 1538 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_condattr_setclock( ) 33073 NAME 33074 pthread_condattr_setclock - set the clock selection condition variable attribute 33075 SYNOPSIS 33076 THR CS #include 33077 int pthread_condattr_setclock(pthread_condattr_t *attr, 33078 clockid_t clock_id); 33079 33080 DESCRIPTION 33081 Refer to pthread_condattr_getclock( ). System Interfaces, Issue 6 1539 pthread_condattr_setpshared( ) System Interfaces 33082 NAME 33083 pthread_condattr_setpshared - set the process-shared condition variable attributes 33084 SYNOPSIS 33085 THR TSH #include 33086 int pthread_condattr_setpshared(pthread_condattr_t *attr, 33087 int pshared); 33088 33089 DESCRIPTION 33090 Refer to pthread_condattr_getpshared( ). 1540 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_create( ) 33091 NAME 33092 pthread_create - thread creation 33093 SYNOPSIS 33094 THR #include 33095 int pthread_create(pthread_t *restrict thread, 33096 const pthread_attr_t *restrict attr, 33097 void *(*start_routine)(void*), void *restrict arg); 33098 33099 DESCRIPTION 33100 The pthread_create( ) function shall create a new thread, with attributes specified by attr, within a | 33101 process. If attr is NULL, the default attributes shall be used. If the attributes specified by attr are | 33102 modified later, the thread's attributes shall not be affected. Upon successful completion, | 33103 pthread_create( ) shall store the ID of the created thread in the location referenced by thread. 33104 The thread is created executing start_routine with arg as its sole argument. If the start_routine 33105 returns, the effect shall be as if there was an implicit call to pthread_exit( ) using the return value 33106 of start_routine as the exit status. Note that the thread in which main( ) was originally invoked 33107 differs from this. When it returns from main( ), the effect shall be as if there was an implicit call 33108 to exit( ) using the return value of main( ) as the exit status. 33109 The signal state of the new thread shall be initialized as follows: 33110 * The signal mask shall be inherited from the creating thread. 33111 * The set of signals pending for the new thread shall be empty. 33112 The floating-point environment shall be inherited from the creating thread. | 33113 If pthread_create( ) fails, no new thread is created and the contents of the location referenced by | 33114 thread are undefined. 33115 TCT If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time clock 33116 accessible, and the initial value of this clock shall be set to zero. 33117 RETURN VALUE 33118 If successful, the pthread_create( ) function shall return zero; otherwise, an error number shall be 33119 returned to indicate the error. 33120 ERRORS 33121 The pthread_create( ) function shall fail if: 33122 [EAGAIN] The system lacked the necessary resources to create another thread, or the 33123 system-imposed limit on the total number of threads in a process 33124 PTHREAD_THREADS_MAX would be exceeded. 33125 [EINVAL] The value specified by attr is invalid. 33126 [EPERM] The caller does not have appropriate permission to set the required 33127 scheduling parameters or scheduling policy. 33128 The pthread_create( ) function shall not return an error code of [EINTR]. System Interfaces, Issue 6 1541 pthread_create( ) System Interfaces 33129 EXAMPLES 33130 None. 33131 APPLICATION USAGE 33132 None. 33133 RATIONALE 33134 A suggested alternative to pthread_create( ) would be to define two separate operations: create 33135 and start. Some applications would find such behavior more natural. Ada, in particular, 33136 separates the ``creation'' of a task from its ``activation''. 33137 Splitting the operation was rejected by the standard developers for many reasons: 33138 * The number of calls required to start a thread would increase from one to two and thus place 33139 an additional burden on applications that do not require the additional synchronization. The 33140 second call, however, could be avoided by the additional complication of a start-up state 33141 attribute. 33142 * An extra state would be introduced: ``created but not started''. This would require the 33143 standard to specify the behavior of the thread operations when the target has not yet started 33144 executing. 33145 * For those applications that require such behavior, it is possible to simulate the two separate 33146 steps with the facilities that are currently provided. The start_routine( ) can synchronize by 33147 waiting on a condition variable that is signaled by the start operation. 33148 An Ada implementor can choose to create the thread at either of two points in the Ada program: 33149 when the task object is created, or when the task is activated (generally at a ``begin''). If the first 33150 approach is adopted, the start_routine( ) needs to wait on a condition variable to receive the 33151 order to begin ``activation''. The second approach requires no such condition variable or extra 33152 synchronization. In either approach, a separate Ada task control block would need to be created 33153 when the task object is created to hold rendezvous queues, and so on. 33154 An extension of the preceding model would be to allow the state of the thread to be modified 33155 between the create and start. This would allow the thread attributes object to be eliminated. This 33156 has been rejected because: 33157 * All state in the thread attributes object has to be able to be set for the thread. This would 33158 require the definition of functions to modify thread attributes. There would be no reduction 33159 in the number of function calls required to set up the thread. In fact, for an application that 33160 creates all threads using identical attributes, the number of function calls required to set up 33161 the threads would be dramatically increased. Use of a thread attributes object permits the 33162 application to make one set of attribute setting function calls. Otherwise, the set of attribute 33163 setting function calls needs to be made for each thread creation. 33164 * Depending on the implementation architecture, functions to set thread state would require 33165 kernel calls, or for other implementation reasons would not be able to be implemented as 33166 macros, thereby increasing the cost of thread creation. 33167 * The ability for applications to segregate threads by class would be lost. 33168 Another suggested alternative uses a model similar to that for process creation, such as ``thread 33169 fork''. The fork semantics would provide more flexibility and the ``create'' function can be 33170 implemented simply by doing a thread fork followed immediately by a call to the desired ``start 33171 routine'' for the thread. This alternative has these problems: 33172 * For many implementations, the entire stack of the calling thread would need to be 33173 duplicated, since in many architectures there is no way to determine the size of the calling 33174 frame. 1542 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_create( ) 33175 * Efficiency is reduced since at least some part of the stack has to be copied, even though in 33176 most cases the thread never needs the copied context, since it merely calls the desired start 33177 routine. 33178 FUTURE DIRECTIONS 33179 None. 33180 SEE ALSO 33181 fork( ), pthread_exit( ), pthread_join( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33182 33183 CHANGE HISTORY 33184 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33185 Issue 6 33186 The pthread_create( ) function is marked as part of the Threads option. 33187 The following new requirements on POSIX implementations derive from alignment with the 33188 Single UNIX Specification: 33189 * The [EPERM] mandatory error condition is added. 33190 The thread CPU-time clock semantics are added for alignment with IEEE Std 1003.1d-1999. 33191 The restrict keyword is added to the pthread_create( ) prototype for alignment with the 33192 ISO/IEC 9899: 1999 standard. | 33193 The DESCRIPTION is updated to make it explicit that the floating-point environment is | 33194 inherited from the creating thread. | System Interfaces, Issue 6 1543 pthread_detach( ) System Interfaces 33195 NAME 33196 pthread_detach - detach a thread 33197 SYNOPSIS 33198 THR #include 33199 int pthread_detach(pthread_t thread); 33200 33201 DESCRIPTION 33202 The pthread_detach( ) function shall indicate to the implementation that storage for the thread | 33203 thread can be reclaimed when that thread terminates. If thread has not terminated, 33204 pthread_detach( ) shall not cause it to terminate. The effect of multiple pthread_detach( ) calls on 33205 the same target thread is unspecified. 33206 RETURN VALUE 33207 If the call succeeds, pthread_detach( ) shall return 0; otherwise, an error number shall be returned 33208 to indicate the error. 33209 ERRORS 33210 The pthread_detach( ) function shall fail if: 33211 [EINVAL] The implementation has detected that the value specified by thread does not 33212 refer to a joinable thread. 33213 [ESRCH] No thread could be found corresponding to that specified by the given thread 33214 ID. 33215 The pthread_detach( ) function shall not return an error code of [EINTR]. 33216 EXAMPLES 33217 None. 33218 APPLICATION USAGE 33219 None. 33220 RATIONALE 33221 The pthread_join( ) or pthread_detach( ) functions should eventually be called for every thread that 33222 is created so that storage associated with the thread may be reclaimed. 33223 It has been suggested that a ``detach'' function is not necessary; the detachstate thread creation 33224 attribute is sufficient, since a thread need never be dynamically detached. However, need arises 33225 in at least two cases: 33226 1. In a cancelation handler for a pthread_join( ) it is nearly essential to have a pthread_detach( ) 33227 function in order to detach the thread on which pthread_join( ) was waiting. Without it, it 33228 would be necessary to have the handler do another pthread_join( ) to attempt to detach the 33229 thread, which would both delay the cancelation processing for an unbounded period and 33230 introduce a new call to pthread_join( ), which might itself need a cancelation handler. A 33231 dynamic detach is nearly essential in this case. 33232 2. In order to detach the ``initial thread'' (as may be desirable in processes that set up server 33233 threads). 33234 FUTURE DIRECTIONS 33235 None. 1544 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_detach( ) 33236 SEE ALSO 33237 pthread_join( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33238 CHANGE HISTORY 33239 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33240 Issue 6 33241 The pthread_detach( ) function is marked as part of the Threads option. System Interfaces, Issue 6 1545 pthread_equal( ) System Interfaces 33242 NAME 33243 pthread_equal - compare thread IDs 33244 SYNOPSIS 33245 THR #include 33246 int pthread_equal(pthread_t t1, pthread_t t2); 33247 33248 DESCRIPTION 33249 This function shall compare the thread IDs t1 and t2. | 33250 RETURN VALUE 33251 The pthread_equal( ) function shall return a non-zero value if t1 and t2 are equal; otherwise, zero 33252 shall be returned. 33253 If either t1 or t2 are not valid thread IDs, the behavior is undefined. 33254 ERRORS 33255 No errors are defined. 33256 The pthread_equal( ) function shall not return an error code of [EINTR]. 33257 EXAMPLES 33258 None. 33259 APPLICATION USAGE 33260 None. 33261 RATIONALE 33262 Implementations may choose to define a thread ID as a structure. This allows additional 33263 flexibility and robustness over using an int. For example, a thread ID could include a sequence 33264 number that allows detection of ``dangling IDs'' (copies of a thread ID that has been detached). | 33265 Since the C language does not support comparison on structure types, the pthread_equal( ) | 33266 function is provided to compare thread IDs. 33267 FUTURE DIRECTIONS 33268 None. 33269 SEE ALSO 33270 pthread_create( ), pthread_self( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33271 CHANGE HISTORY 33272 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33273 Issue 6 33274 The pthread_equal( ) function is marked as part of the Threads option. 1546 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_exit( ) 33275 NAME 33276 pthread_exit - thread termination 33277 SYNOPSIS 33278 THR #include 33279 void pthread_exit(void *value_ptr); 33280 33281 DESCRIPTION 33282 The pthread_exit( ) function shall terminate the calling thread and make the value value_ptr 33283 available to any successful join with the terminating thread. Any cancelation cleanup handlers 33284 that have been pushed and not yet popped shall be popped in the reverse order that they were 33285 pushed and then executed. After all cancelation cleanup handlers have been executed, if the 33286 thread has any thread-specific data, appropriate destructor functions shall be called in an 33287 unspecified order. Thread termination does not release any application visible process resources, 33288 including, but not limited to, mutexes and file descriptors, nor does it perform any process-level 33289 cleanup actions, including, but not limited to, calling any atexit( ) routines that may exist. 33290 An implicit call to pthread_exit( ) is made when a thread other than the thread in which main( ) 33291 was first invoked returns from the start routine that was used to create it. The function's return 33292 value shall serve as the thread's exit status. 33293 The behavior of pthread_exit( ) is undefined if called from a cancelation cleanup handler or 33294 destructor function that was invoked as a result of either an implicit or explicit call to 33295 pthread_exit( ). 33296 After a thread has terminated, the result of access to local (auto) variables of the thread is 33297 undefined. Thus, references to local variables of the exiting thread should not be used for the 33298 pthread_exit( ) value_ptr parameter value. 33299 The process shall exit with an exit status of 0 after the last thread has been terminated. The 33300 behavior shall be as if the implementation called exit( ) with a zero argument at thread 33301 termination time. 33302 RETURN VALUE 33303 The pthread_exit( ) function cannot return to its caller. 33304 ERRORS 33305 No errors are defined. | 33306 EXAMPLES 33307 None. 33308 APPLICATION USAGE 33309 None. 33310 RATIONALE 33311 The normal mechanism by which a thread terminates is to return from the routine that was 33312 specified in the pthread_create( ) call that started it. The pthread_exit( ) function provides the 33313 capability for a thread to terminate without requiring a return from the start routine of that 33314 thread, thereby providing a function analogous to exit( ). 33315 Regardless of the method of thread termination, any cancelation cleanup handlers that have 33316 been pushed and not yet popped are executed, and the destructors for any existing thread- 33317 specific data are executed. This volume of IEEE Std 1003.1-200x requires that cancelation 33318 cleanup handlers be popped and called in order. After all cancelation cleanup handlers have 33319 been executed, thread-specific data destructors are called, in an unspecified order, for each item 33320 of thread-specific data that exists in the thread. This ordering is necessary because cancelation System Interfaces, Issue 6 1547 pthread_exit( ) System Interfaces 33321 cleanup handlers may rely on thread-specific data. 33322 As the meaning of the status is determined by the application (except when the thread has been 33323 canceled, in which case it is PTHREAD_CANCELED), the implementation has no idea what an 33324 illegal status value is, which is why no address error checking is done. 33325 FUTURE DIRECTIONS 33326 None. 33327 SEE ALSO 33328 exit( ), pthread_create( ), pthread_join( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33329 33330 CHANGE HISTORY 33331 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33332 Issue 6 33333 The pthread_exit( ) function is marked as part of the Threads option. 1548 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_getconcurrency( ) 33334 NAME 33335 pthread_getconcurrency, pthread_setconcurrency - get and set level of concurrency 33336 SYNOPSIS 33337 XSI #include 33338 int pthread_getconcurrency(void); 33339 int pthread_setconcurrency(int new_level); 33340 33341 DESCRIPTION 33342 Unbound threads in a process may or may not be required to be simultaneously active. By 33343 default, the threads implementation ensures that a sufficient number of threads are active so that 33344 the process can continue to make progress. While this conserves system resources, it may not 33345 produce the most effective level of concurrency. 33346 The pthread_setconcurrency( ) function allows an application to inform the threads 33347 implementation of its desired concurrency level, new_level. The actual level of concurrency 33348 provided by the implementation as a result of this function call is unspecified. 33349 If new_level is zero, it causes the implementation to maintain the concurrency level at its 33350 discretion as if pthread_setconcurrency( ) had never been called. 33351 The pthread_getconcurrency( ) function shall return the value set by a previous call to the 33352 pthread_setconcurrency( ) function. If the pthread_setconcurrency( ) function was not previously 33353 called, this function shall return zero to indicate that the implementation is maintaining the 33354 concurrency level. 33355 A call to pthread_setconcurrency( ) shall inform the implementation of its desired concurrency | 33356 level. The implementation shall use this as a hint, not a requirement. | 33357 If an implementation does not support multiplexing of user threads on top of several kernel- 33358 scheduled entities, the pthread_setconcurrency( ) and pthread_getconcurrency( ) functions are | 33359 provided for source code compatibility but they shall have no effect when called. To maintain | 33360 the function semantics, the new_level parameter is saved when pthread_setconcurrency( ) is called 33361 so that a subsequent call to pthread_getconcurrency( ) shall return the same value. 33362 RETURN VALUE 33363 If successful, the pthread_setconcurrency( ) function shall return zero; otherwise, an error number 33364 shall be returned to indicate the error. 33365 The pthread_getconcurrency( ) function shall always return the concurrency level set by a previous 33366 call to pthread_setconcurrency( ). If the pthread_setconcurrency( ) function has never been called, 33367 pthread_getconcurrency( ) shall return zero. 33368 ERRORS 33369 The pthread_setconcurrency( ) function shall fail if: 33370 [EINVAL] The value specified by new_level is negative. 33371 [EAGAIN] The value specific by new_level would cause a system resource to be exceeded. 33372 These functions shall not return an error code of [EINTR]. System Interfaces, Issue 6 1549 pthread_getconcurrency( ) System Interfaces 33373 EXAMPLES 33374 None. 33375 APPLICATION USAGE 33376 Use of these functions changes the state of the underlying concurrency upon which the 33377 application depends. Library developers are advised to not use the pthread_getconcurrency( ) and 33378 pthread_setconcurrency( ) functions since their use may conflict with an applications use of these 33379 functions. 33380 RATIONALE 33381 None. 33382 FUTURE DIRECTIONS 33383 None. 33384 SEE ALSO 33385 The Base Definitions volume of IEEE Std 1003.1-200x, 33386 CHANGE HISTORY 33387 First released in Issue 5. 1550 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_getcpuclockid( ) 33388 NAME 33389 pthread_getcpuclockid - access a thread CPU-time clock (ADVANCED REALTIME 33390 THREADS) 33391 SYNOPSIS 33392 THR TCT #include 33393 #include 33394 int pthread_getcpuclockid(pthread_t thread_id, clockid_t *clock_id); 33395 33396 DESCRIPTION 33397 The pthread_getcpuclockid( ) function shall return in clock_id the clock ID of the CPU-time clock of 33398 the thread specified by thread_id, if the thread specified by thread_id exists. 33399 RETURN VALUE 33400 Upon successful completion, pthread_getcpuclockid( ) shall return zero; otherwise, an error 33401 number shall be returned to indicate the error. 33402 ERRORS 33403 The pthread_getcpuclockid( ) function may fail if: 33404 [ESRCH] The value specified by thread_id does not refer to an existing thread. 33405 EXAMPLES 33406 None. 33407 APPLICATION USAGE 33408 The pthread_getcpuclockid( ) function is part of the Thread CPU-Time Clocks option and need not 33409 be provided on all implementations. 33410 RATIONALE 33411 None. 33412 FUTURE DIRECTIONS 33413 None. 33414 SEE ALSO 33415 clock_getcpuclockid( ), clock_getres( ), timer_create( ), the Base Definitions volume of 33416 IEEE Std 1003.1-200x, , 33417 CHANGE HISTORY 33418 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 33419 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1551 pthread_getschedparam( ) System Interfaces 33420 NAME 33421 pthread_getschedparam, pthread_setschedparam - dynamic thread scheduling parameters 33422 access (REALTIME THREADS) 33423 SYNOPSIS 33424 THR TPS #include 33425 int pthread_getschedparam(pthread_t thread, int *restrict policy, 33426 struct sched_param *restrict param); 33427 int pthread_setschedparam(pthread_t thread, int policy, 33428 const struct sched_param *param); 33429 33430 DESCRIPTION 33431 The pthread_getschedparam( ) and pthread_setschedparam( ) functions shall, respectively, get and set | 33432 the scheduling policy and parameters of individual threads within a multi-threaded process to | 33433 be retrieved and set. For SCHED_FIFO and SCHED_RR, the only required member of the | 33434 sched_param structure is the priority sched_priority. For SCHED_OTHER, the affected 33435 scheduling parameters are implementation-defined. 33436 The pthread_getschedparam( ) function shall retrieve the scheduling policy and scheduling 33437 parameters for the thread whose thread ID is given by thread and shall store those values in 33438 policy and param, respectively. The priority value returned from pthread_getschedparam( ) shall be 33439 the value specified by the most recent pthread_setschedparam( ), pthread_setschedprio( ), or | 33440 pthread_create( ) call affecting the target thread. It shall not reflect any temporary adjustments to 33441 its priority as a result of any priority inheritance or ceiling functions. The pthread_setschedparam( ) | 33442 function shall set the scheduling policy and associated scheduling parameters for the thread | 33443 whose thread ID is given by thread to the policy and associated parameters provided in policy 33444 and param, respectively. 33445 The policy parameter may have the value SCHED_OTHER, SCHED_FIFO, or SCHED_RR. The 33446 scheduling parameters for the SCHED_OTHER policy are implementation-defined. The 33447 SCHED_FIFO and SCHED_RR policies shall have a single scheduling parameter, priority. 33448 TSP If _POSIX_THREAD_SPORADIC_SERVER is defined, then the policy argument may have the 33449 value SCHED_SPORADIC, with the exception for the pthread_setschedparam( ) function that if the 33450 scheduling policy was not SCHED_SPORADIC at the time of the call, it is implementation- 33451 defined whether the function is supported; in other words, the implementation need not allow 33452 the application to dynamically change the scheduling policy to SCHED_SPORADIC. The 33453 sporadic server scheduling policy has the associated parameters sched_ss_low_priority, 33454 sched_ss_repl_period, sched_ss_init_budget, sched_priority, and sched_ss_max_repl. The specified 33455 sched_ss_repl_period shall be greater than or equal to the specified sched_ss_init_budget for the 33456 function to succeed; if it is not, then the function shall fail. The value of sched_ss_max_repl shall 33457 be within the inclusive range [1,{SS_REPL_MAX}] for the function to succeed; if not, the function 33458 shall fail. 33459 If the pthread_setschedparam( ) function fails, the scheduling parameters shall not be changed for | 33460 the target thread. | 33461 RETURN VALUE 33462 If successful, the pthread_getschedparam( ) and pthread_setschedparam( ) functions shall return zero; 33463 otherwise, an error number shall be returned to indicate the error. 1552 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_getschedparam( ) 33464 ERRORS 33465 The pthread_getschedparam( ) function may fail if: 33466 [ESRCH] The value specified by thread does not refer to a existing thread. 33467 The pthread_setschedparam( ) function may fail if: 33468 [EINVAL] The value specified by policy or one of the scheduling parameters associated 33469 with the scheduling policy policy is invalid. 33470 [ENOTSUP] An attempt was made to set the policy or scheduling parameters to an 33471 unsupported value. 33472 TSP [ENOTSUP] An attempt was made to dynamically change the scheduling policy to 33473 SCHED_SPORADIC, and the implementation does not support this change. 33474 [EPERM] The caller does not have the appropriate permission to set either the 33475 scheduling parameters or the scheduling policy of the specified thread. 33476 [EPERM] The implementation does not allow the application to modify one of the 33477 parameters to the value specified. 33478 [ESRCH] The value specified by thread does not refer to a existing thread. 33479 These functions shall not return an error code of [EINTR]. 33480 EXAMPLES 33481 None. 33482 APPLICATION USAGE 33483 None. 33484 RATIONALE 33485 None. 33486 FUTURE DIRECTIONS 33487 None. 33488 SEE ALSO 33489 pthread_setschedprio( ), sched_getparam( ), sched_getscheduler( ), the Base Definitions volume of | 33490 IEEE Std 1003.1-200x, , 33491 CHANGE HISTORY 33492 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33493 Issue 6 33494 The pthread_getschedparam( ) and pthread_setschedparam( ) functions are marked as part of the 33495 Threads and Thread Execution Scheduling options. 33496 The [ENOSYS] error condition has been removed as stubs need not be provided if an 33497 implementation does not support the Thread Execution Scheduling option. 33498 The Open Group Corrigendum U026/2 is applied, correcting the prototype for the 33499 pthread_setschedparam( ) function so that its second argument is of type int. 33500 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999. 33501 The restrict keyword is added to the pthread_getschedparam( ) prototype for alignment with the 33502 ISO/IEC 9899: 1999 standard. 33503 The Open Group Corrigendum U047/1 is applied. | System Interfaces, Issue 6 1553 pthread_getschedparam( ) System Interfaces 33504 IEEE PASC Interpretation 1003.1 #96 is applied, noting that priority values can also be set by a | 33505 call to the pthread_setschedprio( ) function. | 1554 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_getspecific( ) 33506 NAME 33507 pthread_getspecific, pthread_setspecific - thread-specific data management 33508 SYNOPSIS 33509 THR #include 33510 void *pthread_getspecific(pthread_key_t key); 33511 int pthread_setspecific(pthread_key_t key, const void *value); 33512 33513 DESCRIPTION 33514 The pthread_getspecific( ) function shall return the value currently bound to the specified key on 33515 behalf of the calling thread. 33516 The pthread_setspecific( ) function shall associate a thread-specific value with a key obtained via a 33517 previous call to pthread_key_create( ). Different threads may bind different values to the same 33518 key. These values are typically pointers to blocks of dynamically allocated memory that have 33519 been reserved for use by the calling thread. 33520 The effect of calling pthread_getspecific( ) or pthread_setspecific( ) with a key value not obtained 33521 from pthread_key_create( ) or after key has been deleted with pthread_key_delete( ) is undefined. 33522 Both pthread_getspecific( ) and pthread_setspecific( ) may be called from a thread-specific data 33523 destructor function. A call to pthread_getspecific( ) for the thread-specific data key being 33524 destroyed shall return the value NULL, unless the value is changed (after the destructor starts) 33525 by a call to pthread_setspecific( ). Calling pthread_setspecific( ) from a thread-specific data 33526 destructor routine may result either in lost storage (after at least 33527 PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop. 33528 Both functions may be implemented as macros. 33529 RETURN VALUE 33530 The pthread_getspecific( ) function shall return the thread-specific data value associated with the 33531 given key. If no thread-specific data value is associated with key, then the value NULL shall be 33532 returned. 33533 If successful, the pthread_setspecific( ) function shall return zero; otherwise, an error number shall 33534 be returned to indicate the error. 33535 ERRORS 33536 No errors are returned from pthread_getspecific( ). 33537 The pthread_setspecific( ) function shall fail if: 33538 [ENOMEM] Insufficient memory exists to associate the value with the key. 33539 The pthread_setspecific( ) function may fail if: 33540 [EINVAL] The key value is invalid. 33541 These functions shall not return an error code of [EINTR]. System Interfaces, Issue 6 1555 pthread_getspecific( ) System Interfaces 33542 EXAMPLES 33543 None. 33544 APPLICATION USAGE 33545 None. 33546 RATIONALE 33547 Performance and ease-of-use of pthread_getspecific( ) is critical for functions that rely on 33548 maintaining state in thread-specific data. Since no errors are required to be detected by it, and 33549 since the only error that could be detected is the use of an invalid key, the function to 33550 pthread_getspecific( ) has been designed to favor speed and simplicity over error reporting. 33551 FUTURE DIRECTIONS 33552 None. 33553 SEE ALSO 33554 pthread_key_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33555 CHANGE HISTORY 33556 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33557 Issue 6 33558 The pthread_getspecific( ) and pthread_setspecific( ) functions are marked as part of the Threads 33559 option. 33560 IEEE PASC Interpretation 1003.1c #3 (Part 6) is applied, updating the DESCRIPTION. 1556 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_join( ) 33561 NAME 33562 pthread_join - wait for thread termination 33563 SYNOPSIS 33564 THR #include 33565 int pthread_join(pthread_t thread, void **value_ptr); 33566 33567 DESCRIPTION 33568 The pthread_join( ) function shall suspend execution of the calling thread until the target thread 33569 terminates, unless the target thread has already terminated. On return from a successful 33570 pthread_join( ) call with a non-NULL value_ptr argument, the value passed to pthread_exit( ) by 33571 the terminating thread shall be made available in the location referenced by value_ptr. When a 33572 pthread_join( ) returns successfully, the target thread has been terminated. The results of multiple 33573 simultaneous calls to pthread_join( ) specifying the same target thread are undefined. If the 33574 thread calling pthread_join( ) is canceled, then the target thread shall not be detached. 33575 It is unspecified whether a thread that has exited but remains unjoined counts against 33576 _PTHREAD_THREADS_MAX. 33577 RETURN VALUE 33578 If successful, the pthread_join( ) function shall return zero; otherwise, an error number shall be 33579 returned to indicate the error. 33580 ERRORS 33581 The pthread_join( ) function shall fail if: 33582 [EINVAL] The implementation has detected that the value specified by thread does not 33583 refer to a joinable thread. 33584 [ESRCH] No thread could be found corresponding to that specified by the given thread 33585 ID. 33586 The pthread_join( ) function may fail if: 33587 [EDEADLK] A deadlock was detected or the value of thread specifies the calling thread. 33588 The pthread_join( ) function shall not return an error code of [EINTR]. 33589 EXAMPLES 33590 An example of thread creation and deletion follows: 33591 typedef struct { 33592 int *ar; 33593 long n; 33594 } subarray; 33595 void * 33596 incer(void *arg) 33597 { 33598 long i; 33599 for (i = 0; i < ((subarray *)arg)->n; i++) 33600 ((subarray *)arg)->ar[i]++; 33601 } 33602 main() 33603 { 33604 int ar[1000000]; System Interfaces, Issue 6 1557 pthread_join( ) System Interfaces 33605 pthread_t th1, th2; 33606 subarray sb1, sb2; 33607 sb1.ar = &ar[0]; 33608 sb1.n = 500000; 33609 (void) pthread_create(&th1, NULL, incer, &sb1); 33610 sb2.ar = &ar[500000]; 33611 sb2.n = 500000; 33612 (void) pthread_create(&th2, NULL, incer, &sb2); 33613 (void) pthread_join(th1, NULL); 33614 (void) pthread_join(th2, NULL); 33615 } 33616 APPLICATION USAGE 33617 None. 33618 RATIONALE 33619 The pthread_join( ) function is a convenience that has proven useful in multi-threaded 33620 applications. It is true that a programmer could simulate this function if it were not provided by 33621 passing extra state as part of the argument to the start_routine( ). The terminating thread would 33622 set a flag to indicate termination and broadcast a condition that is part of that state; a joining 33623 thread would wait on that condition variable. While such a technique would allow a thread to 33624 wait on more complex conditions (for example, waiting for multiple threads to terminate), 33625 waiting on individual thread termination is considered widely useful. Also, including the 33626 pthread_join( ) function in no way precludes a programmer from coding such complex waits. 33627 Thus, while not a primitive, including pthread_join( ) in this volume of IEEE Std 1003.1-200x was 33628 considered valuable. 33629 The pthread_join( ) function provides a simple mechanism allowing an application to wait for a 33630 thread to terminate. After the thread terminates, the application may then choose to clean up 33631 resources that were used by the thread. For instance, after pthread_join( ) returns, any 33632 application-provided stack storage could be reclaimed. 33633 The pthread_join( ) or pthread_detach( ) function should eventually be called for every thread that 33634 is created with the detachstate attribute set to PTHREAD_CREATE_JOINABLE so that storage 33635 associated with the thread may be reclaimed. 33636 The interaction between pthread_join( ) and cancelation is well-defined for the following reasons: 33637 * The pthread_join ( ) function, like all other non-async-cancel-safe functions, can only be called 33638 with deferred cancelability type. 33639 * Cancelation cannot occur in the disabled cancelability state. 33640 Thus, only the default cancelability state need be considered. As specified, either the 33641 pthread_join( ) call is canceled, or it succeeds, but not both. The difference is obvious to the 33642 application, since either a cancelation handler is run or pthread_join( ) returns. There are no race 33643 conditions since pthread_join( ) was called in the deferred cancelability state. 33644 FUTURE DIRECTIONS 33645 None. 33646 SEE ALSO 33647 pthread_create( ), wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1558 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_join( ) 33648 CHANGE HISTORY 33649 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33650 Issue 6 33651 The pthread_join( ) function is marked as part of the Threads option. System Interfaces, Issue 6 1559 pthread_key_create( ) System Interfaces 33652 NAME 33653 pthread_key_create - thread-specific data key creation 33654 SYNOPSIS 33655 THR #include 33656 int pthread_key_create(pthread_key_t *key, void (*destructor)(void*)); 33657 33658 DESCRIPTION 33659 The pthread_key_create( ) function shall create a thread-specific data key visible to all threads in 33660 the process. Key values provided by pthread_key_create( ) are opaque objects used to locate 33661 thread-specific data. Although the same key value may be used by different threads, the values 33662 bound to the key by pthread_setspecific( ) are maintained on a per-thread basis and persist for the 33663 life of the calling thread. 33664 Upon key creation, the value NULL shall be associated with the new key in all active threads. 33665 Upon thread creation, the value NULL shall be associated with all defined keys in the new 33666 thread. 33667 An optional destructor function may be associated with each key value. At thread exit, if a key 33668 value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with 33669 that key, the value of the key is set to NULL, and then the function pointed to is called with the 33670 previously associated value as its sole argument. The order of destructor calls is unspecified if 33671 more than one destructor exists for a thread when it exits. 33672 If, after all the destructors have been called for all non-NULL values with associated destructors, 33673 there are still some non-NULL values with associated destructors, then the process is repeated. 33674 If, after at least {PTHREAD_DESTRUCTOR_ITERATIONS} iterations of destructor calls for 33675 outstanding non-NULL values, there are still some non-NULL values with associated 33676 destructors, implementations may stop calling destructors, or they may continue calling 33677 destructors until no non-NULL values with associated destructors exist, even though this might 33678 result in an infinite loop. 33679 RETURN VALUE 33680 If successful, the pthread_key_create( ) function shall store the newly created key value at *key and 33681 shall return zero. Otherwise, an error number shall be returned to indicate the error. 33682 ERRORS 33683 The pthread_key_create( ) function shall fail if: 33684 [EAGAIN] The system lacked the necessary resources to create another thread-specific 33685 data key, or the system-imposed limit on the total number of keys per process 33686 PTHREAD_KEYS_MAX has been exceeded. 33687 [ENOMEM] Insufficient memory exists to create the key. 33688 The pthread_key_create( ) function shall not return an error code of [EINTR]. 1560 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_key_create( ) 33689 EXAMPLES 33690 The following example demonstrates a function that initializes a thread-specific data key when 33691 it is first called, and associates a thread-specific object with each calling thread, initializing this 33692 object when necessary. 33693 static pthread_key_t key; 33694 static pthread_once_t key_once = PTHREAD_ONCE_INIT; 33695 static void 33696 make_key() 33697 { 33698 (void) pthread_key_create(&key, NULL); 33699 } 33700 func() 33701 { 33702 void *ptr; 33703 (void) pthread_once(&key_once, make_key); 33704 if ((ptr = pthread_getspecific(key)) == NULL) { 33705 ptr = malloc(OBJECT_SIZE); 33706 ... 33707 (void) pthread_setspecific(key, ptr); 33708 } 33709 ... 33710 } 33711 Note that the key has to be initialized before pthread_getspecific( ) or pthread_setspecific( ) can be 33712 used. The pthread_key_create( ) call could either be explicitly made in a module initialization 33713 routine, or it can be done implicitly by the first call to a module as in this example. Any attempt 33714 to use the key before it is initialized is a programming error, making the code below incorrect. 33715 static pthread_key_t key; 33716 func() 33717 { 33718 void *ptr; 33719 /* KEY NOT INITIALIZED!!! THIS WON'T WORK!!! */ 33720 if ((ptr = pthread_getspecific(key)) == NULL && 33721 pthread_setspecific(key, NULL) != 0) { 33722 pthread_key_create(&key, NULL); 33723 ... 33724 } 33725 } 33726 APPLICATION USAGE 33727 None. System Interfaces, Issue 6 1561 pthread_key_create( ) System Interfaces 33728 RATIONALE 33729 Destructor Functions 33730 Normally, the value bound to a key on behalf of a particular thread is a pointer to storage 33731 allocated dynamically on behalf of the calling thread. The destructor functions specified with 33732 pthread_key_create( ) are intended to be used to free this storage when the thread exits. Thread 33733 cancelation cleanup handlers cannot be used for this purpose because thread-specific data may 33734 persist outside the lexical scope in which the cancelation cleanup handlers operate. 33735 If the value associated with a key needs to be updated during the lifetime of the thread, it may 33736 be necessary to release the storage associated with the old value before the new value is bound. 33737 Although the pthread_setspecific( ) function could do this automatically, this feature is not needed 33738 often enough to justify the added complexity. Instead, the programmer is responsible for freeing 33739 the stale storage: 33740 pthread_getspecific(key, &old); 33741 new = allocate(); 33742 destructor(old); 33743 pthread_setspecific(key, new); 33744 Note: The above example could leak storage if run with asynchronous cancelation enabled. No such 33745 problems occur in the default cancelation state if no cancelation points occur between the get 33746 and set. 33747 There is no notion of a destructor-safe function. If an application does not call pthread_exit( ) 33748 from a signal handler, or if it blocks any signal whose handler may call pthread_exit( ) while 33749 calling async-unsafe functions, all functions may be safely called from destructors. 33750 Non-Idempotent Data Key Creation 33751 There were requests to make pthread_key_create( ) idempotent with respect to a given key address 33752 parameter. This would allow applications to call pthread_key_create( ) multiple times for a given 33753 key address and be guaranteed that only one key would be created. Doing so would require the 33754 key value to be previously initialized (possibly at compile time) to a known null value and 33755 would require that implicit mutual-exclusion be performed based on the address and contents of 33756 the key parameter in order to guarantee that exactly one key would be created. 33757 Unfortunately, the implicit mutual-exclusion would not be limited to only pthread_key_create( ). 33758 On many implementations, implicit mutual-exclusion would also have to be performed by 33759 pthread_getspecific( ) and pthread_setspecific( ) in order to guard against using incompletely stored 33760 or not-yet-visible key values. This could significantly increase the cost of important operations, 33761 particularly pthread_getspecific( ). 33762 Thus, this proposal was rejected. The pthread_key_create( ) function performs no implicit 33763 synchronization. It it the responsibility of the programmer to ensure that it is called exactly once 33764 per key before use of the key. Several straightforward mechanisms can already be used to 33765 accomplish this, including calling explicit module initialization functions, using mutexes, and 33766 using pthread_once( ). This places no significant burden on the programmer, introduces no 33767 possibly confusing ad hoc implicit synchronization mechanism, and potentially allows 33768 commonly used thread-specific data operations to be more efficient. 33769 FUTURE DIRECTIONS 33770 None. 1562 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_key_create( ) 33771 SEE ALSO 33772 pthread_getspecific( ), pthread_key_delete( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33773 33774 CHANGE HISTORY 33775 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33776 Issue 6 33777 The pthread_key_create( ) function is marked as part of the Threads option. 33778 IEEE PASC Interpretation 1003.1c #8 is applied, updating the DESCRIPTION. System Interfaces, Issue 6 1563 pthread_key_delete( ) System Interfaces 33779 NAME 33780 pthread_key_delete - thread-specific data key deletion 33781 SYNOPSIS 33782 THR #include 33783 int pthread_key_delete(pthread_key_t key); 33784 33785 DESCRIPTION 33786 The pthread_key_delete( ) function shall delete a thread-specific data key previously returned by 33787 pthread_key_create( ). The thread-specific data values associated with key need not be NULL at 33788 the time pthread_key_delete( ) is called. It is the responsibility of the application to free any 33789 application storage or perform any cleanup actions for data structures related to the deleted key 33790 or associated thread-specific data in any threads; this cleanup can be done either before or after 33791 pthread_key_delete( ) is called. Any attempt to use key following the call to pthread_key_delete( ) 33792 results in undefined behavior. 33793 The pthread_key_delete( ) function shall be callable from within destructor functions. No 33794 destructor functions shall be invoked by pthread_key_delete( ). Any destructor function that may 33795 have been associated with key shall no longer be called upon thread exit. 33796 RETURN VALUE 33797 If successful, the pthread_key_delete( ) function shall return zero; otherwise, an error number shall 33798 be returned to indicate the error. 33799 ERRORS 33800 The pthread_key_delete( ) function may fail if: 33801 [EINVAL] The key value is invalid. 33802 The pthread_key_delete( ) function shall not return an error code of [EINTR]. 33803 EXAMPLES 33804 None. 33805 APPLICATION USAGE 33806 None. 33807 RATIONALE 33808 A thread-specific data key deletion function has been included in order to allow the resources 33809 associated with an unused thread-specific data key to be freed. Unused thread-specific data keys 33810 can arise, among other scenarios, when a dynamically loaded module that allocated a key is 33811 unloaded. 33812 Conforming applications are responsible for performing any cleanup actions needed for data | 33813 structures associated with the key to be deleted, including data referenced by thread-specific 33814 data values. No such cleanup is done by pthread_key_delete( ). In particular, destructor functions 33815 are not called. There are several reasons for this division of responsibility: 33816 1. The associated destructor functions used to free thread-specific data at thread exit time are 33817 only guaranteed to work correctly when called in the thread that allocated the thread- 33818 specific data. (Destructors themselves may utilize thread-specific data.) Thus, they cannot 33819 be used to free thread-specific data in other threads at key deletion time. Attempting to 33820 have them called by other threads at key deletion time would require other threads to be 33821 asynchronously interrupted. But since interrupted threads could be in an arbitrary state, 33822 including holding locks necessary for the destructor to run, this approach would fail. In 33823 general, there is no safe mechanism whereby an implementation could free thread-specific 33824 data at key deletion time. 1564 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_key_delete( ) 33825 2. Even if there were a means of safely freeing thread-specific data associated with keys to be 33826 deleted, doing so would require that implementations be able to enumerate the threads 33827 with non-NULL data and potentially keep them from creating more thread-specific data 33828 while the key deletion is occurring. This special case could cause extra synchronization in 33829 the normal case, which would otherwise be unnecessary. 33830 For an application to know that it is safe to delete a key, it has to know that all the threads that 33831 might potentially ever use the key do not attempt to use it again. For example, it could know this 33832 if all the client threads have called a cleanup procedure declaring that they are through with the 33833 module that is being shut down, perhaps by zero'ing a reference count. 33834 FUTURE DIRECTIONS 33835 None. 33836 SEE ALSO 33837 pthread_key_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33838 CHANGE HISTORY 33839 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33840 Issue 6 33841 The pthread_key_delete( ) function is marked as part of the Threads option. System Interfaces, Issue 6 1565 pthread_kill( ) System Interfaces 33842 NAME 33843 pthread_kill - send a signal to a thread 33844 SYNOPSIS 33845 THR #include 33846 int pthread_kill(pthread_t thread, int sig); 33847 33848 DESCRIPTION 33849 The pthread_kill ( ) function shall request that a signal be delivered to the specified thread. | 33850 As in kill( ), if sig is zero, error checking shall be performed but no signal shall actually be sent. | 33851 RETURN VALUE 33852 Upon successful completion, the function shall return a value of zero. Otherwise, the function 33853 shall return an error number. If the pthread_kill ( ) function fails, no signal shall be sent. 33854 ERRORS 33855 The pthread_kill ( ) function shall fail if: 33856 [ESRCH] No thread could be found corresponding to that specified by the given thread 33857 ID. 33858 [EINVAL] The value of the sig argument is an invalid or unsupported signal number. 33859 The pthread_kill ( ) function shall not return an error code of [EINTR]. 33860 EXAMPLES 33861 None. 33862 APPLICATION USAGE 33863 The pthread_kill ( ) function provides a mechanism for asynchronously directing a signal at a 33864 thread in the calling process. This could be used, for example, by one thread to affect broadcast 33865 delivery of a signal to a set of threads. 33866 Note that pthread_kill ( ) only causes the signal to be handled in the context of the given thread; 33867 the signal action (termination or stopping) affects the process as a whole. 33868 RATIONALE 33869 None. 33870 FUTURE DIRECTIONS 33871 None. 33872 SEE ALSO 33873 kill( ), pthread_self( ), raise( ), the Base Definitions volume of IEEE Std 1003.1-200x, 33874 CHANGE HISTORY 33875 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 33876 Issue 6 33877 The pthread_kill ( ) function is marked as part of the Threads option. 33878 The APPLICATION USAGE section is added. 1566 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_destroy( ) 33879 NAME 33880 pthread_mutex_destroy, pthread_mutex_init - destroy and initialize a mutex 33881 SYNOPSIS 33882 THR #include 33883 int pthread_mutex_destroy(pthread_mutex_t *mutex); 33884 int pthread_mutex_init(pthread_mutex_t *restrict mutex, 33885 const pthread_mutexattr_t *restrict attr); 33886 pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 33887 33888 DESCRIPTION 33889 The pthread_mutex_destroy( ) function shall destroy the mutex object referenced by mutex; the 33890 mutex object becomes, in effect, uninitialized. An implementation may cause 33891 pthread_mutex_destroy( ) to set the object referenced by mutex to an invalid value. A destroyed | 33892 mutex object can be reinitialized using pthread_mutex_init( ); the results of otherwise referencing | 33893 the object after it has been destroyed are undefined. 33894 It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked 33895 mutex results in undefined behavior. 33896 The pthread_mutex_init( ) function shall initialize the mutex referenced by mutex with attributes 33897 specified by attr. If attr is NULL, the default mutex attributes are used; the effect shall be the 33898 same as passing the address of a default mutex attributes object. Upon successful initialization, 33899 the state of the mutex becomes initialized and unlocked. 33900 Only mutex itself may be used for performing synchronization. The result of referring to copies 33901 of mutex in calls to pthread_mutex_lock( ), pthread_mutex_trylock( ), pthread_mutex_unlock( ), and 33902 pthread_mutex_destroy( ) is undefined. 33903 Attempting to initialize an already initialized mutex results in undefined behavior. 33904 In cases where default mutex attributes are appropriate, the macro 33905 PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. 33906 The effect shall be equivalent to dynamic initialization by a call to pthread_mutex_init( ) with 33907 parameter attr specified as NULL, except that no error checks are performed. 33908 RETURN VALUE 33909 If successful, the pthread_mutex_destroy( ) and pthread_mutex_init( ) functions shall return zero; 33910 otherwise, an error number shall be returned to indicate the error. 33911 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 33912 immediately at the beginning of processing for the function and shall cause an error return prior 33913 to modifying the state of the mutex specified by mutex. 33914 ERRORS 33915 The pthread_mutex_destroy( ) function may fail if: 33916 [EBUSY] The implementation has detected an attempt to destroy the object referenced 33917 by mutex while it is locked or referenced (for example, while being used in a 33918 pthread_cond_timedwait( ) or pthread_cond_wait( )) by another thread. 33919 [EINVAL] The value specified by mutex is invalid. 33920 The pthread_mutex_init( ) function shall fail if: 33921 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 33922 another mutex. System Interfaces, Issue 6 1567 pthread_mutex_destroy( ) System Interfaces 33923 [ENOMEM] Insufficient memory exists to initialize the mutex. 33924 [EPERM] The caller does not have the privilege to perform the operation. 33925 The pthread_mutex_init( ) function may fail if: 33926 [EBUSY] The implementation has detected an attempt to reinitialize the object | 33927 referenced by mutex, a previously initialized, but not yet destroyed, mutex. 33928 [EINVAL] The value specified by attr is invalid. 33929 These functions shall not return an error code of [EINTR]. 33930 EXAMPLES 33931 None. 33932 APPLICATION USAGE 33933 None. 33934 RATIONALE 33935 Alternate Implementations Possible 33936 This volume of IEEE Std 1003.1-200x supports several alternative implementations of mutexes. 33937 An implementation may store the lock directly in the object of type pthread_mutex_t. 33938 Alternatively, an implementation may store the lock in the heap and merely store a pointer, 33939 handle, or unique ID in the mutex object. Either implementation has advantages or may be 33940 required on certain hardware configurations. So that portable code can be written that is 33941 invariant to this choice, this volume of IEEE Std 1003.1-200x does not define assignment or 33942 equality for this type, and it uses the term ``initialize'' to reinforce the (more restrictive) notion 33943 that the lock may actually reside in the mutex object itself. 33944 Note that this precludes an over-specification of the type of the mutex or condition variable and 33945 motivates the opacity of the type. 33946 An implementation is permitted, but not required, to have pthread_mutex_destroy( ) store an 33947 illegal value into the mutex. This may help detect erroneous programs that try to lock (or 33948 otherwise reference) a mutex that has already been destroyed. 33949 Tradeoff Between Error Checks and Performance Supported 33950 Many of the error checks were made optional in order to let implementations trade off 33951 performance versus degree of error checking according to the needs of their specific applications 33952 and execution environment. As a general rule, errors or conditions caused by the system (such as 33953 insufficient memory) always need to be reported, but errors due to an erroneously coded 33954 application (such as failing to provide adequate synchronization to prevent a mutex from being 33955 deleted while in use) are made optional. 33956 A wide range of implementations is thus made possible. For example, an implementation 33957 intended for application debugging may implement all of the error checks, but an 33958 implementation running a single, provably correct application under very tight performance 33959 constraints in an embedded computer might implement minimal checks. An implementation 33960 might even be provided in two versions, similar to the options that compilers provide: a full- 33961 checking, but slower version; and a limited-checking, but faster version. To forbid this 33962 optionality would be a disservice to users. 33963 By carefully limiting the use of ``undefined behavior'' only to things that an erroneous (badly 33964 coded) application might do, and by defining that resource-not-available errors are mandatory, 33965 this volume of IEEE Std 1003.1-200x ensures that a fully-conforming application is portable 1568 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_destroy( ) 33966 across the full range of implementations, while not forcing all implementations to add overhead 33967 to check for numerous things that a correct program never does. 33968 Why No Limits Defined 33969 Defining symbols for the maximum number of mutexes and condition variables was considered 33970 but rejected because the number of these objects may change dynamically. Furthermore, many 33971 implementations place these objects into application memory; thus, there is no explicit 33972 maximum. 33973 Static Initializers for Mutexes and Condition Variables 33974 Providing for static initialization of statically allocated synchronization objects allows modules 33975 with private static synchronization variables to avoid runtime initialization tests and overhead. 33976 Furthermore, it simplifies the coding of self-initializing modules. Such modules are common in 33977 C libraries, where for various reasons the design calls for self-initialization instead of requiring 33978 an explicit module initialization function to be called. An example use of static initialization 33979 follows. 33980 Without static initialization, a self-initializing routine foo( ) might look as follows: 33981 static pthread_once_t foo_once = PTHREAD_ONCE_INIT; 33982 static pthread_mutex_t foo_mutex; 33983 void foo_init() 33984 { 33985 pthread_mutex_init(&foo_mutex, NULL); 33986 } 33987 void foo() 33988 { 33989 pthread_once(&foo_once, foo_init); 33990 pthread_mutex_lock(&foo_mutex); 33991 /* Do work. */ 33992 pthread_mutex_unlock(&foo_mutex); 33993 } 33994 With static initialization, the same routine could be coded as follows: 33995 static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; 33996 void foo() 33997 { 33998 pthread_mutex_lock(&foo_mutex); 33999 /* Do work. */ 34000 pthread_mutex_unlock(&foo_mutex); 34001 } 34002 Note that the static initialization both eliminates the need for the initialization test inside 34003 pthread_once( ) and the fetch of &foo_mutex to learn the address to be passed to 34004 pthread_mutex_lock( ) or pthread_mutex_unlock( ). 34005 Thus, the C code written to initialize static objects is simpler on all systems and is also faster on a 34006 large class of systems; those where the (entire) synchronization object can be stored in 34007 application memory. 34008 Yet the locking performance question is likely to be raised for machines that require mutexes to 34009 be allocated out of special memory. Such machines actually have to have mutexes and possibly System Interfaces, Issue 6 1569 pthread_mutex_destroy( ) System Interfaces 34010 condition variables contain pointers to the actual hardware locks. For static initialization to work 34011 on such machines, pthread_mutex_lock( ) also has to test whether or not the pointer to the actual 34012 lock has been allocated. If it has not, pthread_mutex_lock( ) has to initialize it before use. The 34013 reservation of such resources can be made when the program is loaded, and hence return codes 34014 have not been added to mutex locking and condition variable waiting to indicate failure to 34015 complete initialization. 34016 This runtime test in pthread_mutex_lock( ) would at first seem to be extra work; an extra test is 34017 required to see whether the pointer has been initialized. On most machines this would actually 34018 be implemented as a fetch of the pointer, testing the pointer against zero, and then using the 34019 pointer if it has already been initialized. While the test might seem to add extra work, the extra 34020 effort of testing a register is usually negligible since no extra memory references are actually 34021 done. As more and more machines provide caches, the real expenses are memory references, not 34022 instructions executed. 34023 Alternatively, depending on the machine architecture, there are often ways to eliminate all 34024 overhead in the most important case: on the lock operations that occur after the lock has been 34025 initialized. This can be done by shifting more overhead to the less frequent operation: 34026 initialization. Since out-of-line mutex allocation also means that an address has to be 34027 dereferenced to find the actual lock, one technique that is widely applicable is to have static 34028 initialization store a bogus value for that address; in particular, an address that causes a machine 34029 fault to occur. When such a fault occurs upon the first attempt to lock such a mutex, validity 34030 checks can be done, and then the correct address for the actual lock can be filled in. Subsequent 34031 lock operations incur no extra overhead since they do not ``fault''. This is merely one technique 34032 that can be used to support static initialization, while not adversely affecting the performance of 34033 lock acquisition. No doubt there are other techniques that are highly machine-dependent. 34034 The locking overhead for machines doing out-of-line mutex allocation is thus similar for 34035 modules being implicitly initialized, where it is improved for those doing mutex allocation 34036 entirely inline. The inline case is thus made much faster, and the out-of-line case is not 34037 significantly worse. 34038 Besides the issue of locking performance for such machines, a concern is raised that it is possible 34039 that threads would serialize contending for initialization locks when attempting to finish 34040 initializing statically allocated mutexes. (Such finishing would typically involve taking an 34041 internal lock, allocating a structure, storing a pointer to the structure in the mutex, and releasing 34042 the internal lock.) First, many implementations would reduce such serialization by hashing on 34043 the mutex address. Second, such serialization can only occur a bounded number of times. In 34044 particular, it can happen at most as many times as there are statically allocated synchronization 34045 objects. Dynamically allocated objects would still be initialized via pthread_mutex_init( ) or 34046 pthread_cond_init( ). 34047 Finally, if none of the above optimization techniques for out-of-line allocation yields sufficient 34048 performance for an application on some implementation, the application can avoid static 34049 initialization altogether by explicitly initializing all synchronization objects with the 34050 corresponding pthread_*_init( ) functions, which are supported by all implementations. An 34051 implementation can also document the tradeoffs and advise which initialization technique is 34052 more efficient for that particular implementation. 1570 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_destroy( ) 34053 Destroying Mutexes 34054 A mutex can be destroyed immediately after it is unlocked. For example, consider the following 34055 code: 34056 struct obj { 34057 pthread_mutex_t om; 34058 int refcnt; 34059 ... 34060 }; 34061 obj_done(struct obj *op) 34062 { 34063 pthread_mutex_lock(&op->om); 34064 if (- -op->refcnt == 0) { 34065 pthread_mutex_unlock(&op->om); 34066 (A) pthread_mutex_destroy(&op->om); 34067 (B) free(op); 34068 } else 34069 (C) pthread_mutex_unlock(&op->om); 34070 } 34071 In this case obj is reference counted and obj_done( ) is called whenever a reference to the object is 34072 dropped. Implementations are required to allow an object to be destroyed and freed and 34073 potentially unmapped (for example, lines A and B) immediately after the object is unlocked (line 34074 C). 34075 FUTURE DIRECTIONS 34076 None. 34077 SEE ALSO 34078 pthread_mutex_getprioceiling( ), pthread_mutex_lock( ), pthread_mutex_timedlock( ), 34079 pthread_mutexattr_getpshared( ), the Base Definitions volume of IEEE Std 1003.1-200x, 34080 34081 CHANGE HISTORY 34082 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34083 Issue 6 34084 The pthread_mutex_destroy( ) and pthread_mutex_init( ) functions are marked as part of the 34085 Threads option. 34086 The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with 34087 IEEE Std 1003.1d-1999. 34088 IEEE PASC Interpretation 1003.1c #34 is applied, updating the DESCRIPTION. 34089 The restrict keyword is added to the pthread_mutex_init( ) prototype for alignment with the 34090 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1571 pthread_mutex_getprioceiling( ) System Interfaces 34091 NAME 34092 pthread_mutex_getprioceiling, pthread_mutex_setprioceiling - get and set the priority ceiling 34093 of a mutex (REALTIME THREADS) 34094 SYNOPSIS 34095 THR TPP #include 34096 int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict mutex, 34097 int *restrict prioceiling); 34098 int pthread_mutex_setprioceiling(pthread_mutex_t *restrict mutex, 34099 int prioceiling, int *restrict old_ceiling); 34100 34101 DESCRIPTION 34102 The pthread_mutex_getprioceiling( ) function shall return the current priority ceiling of the mutex. 34103 The pthread_mutex_setprioceiling( ) function shall either lock the mutex if it is unlocked, or block | 34104 until it can successfully lock the mutex, then it shall change the mutex's priority ceiling and | 34105 release the mutex. When the change is successful, the previous value of the priority ceiling shall | 34106 be returned in old_ceiling. The process of locking the mutex need not adhere to the priority | 34107 protect protocol. 34108 If the pthread_mutex_setprioceiling( ) function fails, the mutex priority ceiling shall not be 34109 changed. 34110 RETURN VALUE 34111 If successful, the pthread_mutex_getprioceiling( ) and pthread_mutex_setprioceiling( ) functions shall 34112 return zero; otherwise, an error number shall be returned to indicate the error. 34113 ERRORS 34114 The pthread_mutex_getprioceiling( ) and pthread_mutex_setprioceiling( ) functions may fail if: 34115 [EINVAL] The priority requested by prioceiling is out of range. 34116 [EINVAL] The value specified by mutex does not refer to a currently existing mutex. 34117 [EPERM] The caller does not have the privilege to perform the operation. 34118 These functions shall not return an error code of [EINTR]. 34119 EXAMPLES 34120 None. 34121 APPLICATION USAGE 34122 None. 34123 RATIONALE 34124 None. 34125 FUTURE DIRECTIONS 34126 None. 34127 SEE ALSO 34128 pthread_mutex_destroy( ), pthread_mutex_lock( ), pthread_mutex_timedlock( ), the Base Definitions 34129 volume of IEEE Std 1003.1-200x, 34130 CHANGE HISTORY 34131 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34132 Marked as part of the Realtime Threads Feature Group. 1572 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_getprioceiling( ) 34133 Issue 6 34134 The pthread_mutex_getprioceiling( ) and pthread_mutex_setprioceiling( ) functions are marked as 34135 part of the Threads and Thread Priority Protection options. 34136 The [ENOSYS] error condition has been removed as stubs need not be provided if an 34137 implementation does not support the Thread Priority Protection option. 34138 The [ENOSYS] error denoting non-support of the priority ceiling protocol for mutexes has been 34139 removed. This is since if the implementation provides the functions (regardless of whether 34140 _POSIX_PTHREAD_PRIO_PROTECT is defined), they must function as in the DESCRIPTION 34141 and therefore the priority ceiling protocol for mutexes is supported. 34142 The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with 34143 IEEE Std 1003.1d-1999. 34144 The restrict keyword is added to the pthread_mutex_getprioceiling( ) and 34145 pthread_mutex_setprioceiling( ) prototypes for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1573 pthread_mutex_init( ) System Interfaces 34146 NAME 34147 pthread_mutex_init - initialize a mutex 34148 SYNOPSIS 34149 THR #include 34150 int pthread_mutex_init(pthread_mutex_t *restrict mutex, 34151 const pthread_mutexattr_t *restrict attr); 34152 pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 34153 34154 DESCRIPTION 34155 Refer to pthread_mutex_destroy( ). 1574 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_lock( ) 34156 NAME 34157 pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a 34158 mutex 34159 SYNOPSIS 34160 THR #include 34161 int pthread_mutex_lock(pthread_mutex_t *mutex); 34162 int pthread_mutex_trylock(pthread_mutex_t *mutex); 34163 int pthread_mutex_unlock(pthread_mutex_t *mutex); 34164 34165 DESCRIPTION 34166 The mutex object referenced by mutex shall be locked by calling pthread_mutex_lock( ). If the 34167 mutex is already locked, the calling thread shall block until the mutex becomes available. This 34168 operation shall return with the mutex object referenced by mutex in the locked state with the 34169 calling thread as its owner. 34170 XSI If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection shall not be provided. 34171 Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it 34172 has not locked or a mutex which is unlocked, undefined behavior results. 34173 If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking shall be provided. 34174 If a thread attempts to relock a mutex that it has already locked, an error shall be returned. If a | 34175 thread attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error | 34176 shall be returned. | 34177 If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex shall maintain the 34178 concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock | 34179 count shall be set to one. Every time a thread relocks this mutex, the lock count shall be | 34180 incremented by one. Each time the thread unlocks the mutex, the lock count shall be | 34181 decremented by one. When the lock count reaches zero, the mutex shall become available for | 34182 other threads to acquire. If a thread attempts to unlock a mutex that it has not locked or a mutex | 34183 which is unlocked, an error shall be returned. | 34184 If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex 34185 results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling 34186 thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in 34187 undefined behavior. 34188 The pthread_mutex_trylock( ) function shall be equivalent to pthread_mutex_lock( ), except that if | 34189 the mutex object referenced by mutex is currently locked (by any thread, including the current 34190 thread), the call shall return immediately. If the mutex type is PTHREAD_MUTEX_RECURSIVE | 34191 and the mutex is currently owned by the calling thread, the mutex lock count shall be | 34192 incremented by one and the pthread_mutex_trylock( ) function shall immediately return success. | 34193 XSI The pthread_mutex_unlock( ) function shall release the mutex object referenced by mutex. The 34194 manner in which a mutex is released is dependent upon the mutex's type attribute. If there are 34195 threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock( ) is called, 34196 resulting in the mutex becoming available, the scheduling policy shall determine which thread | 34197 shall acquire the mutex. | 34198 XSI (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become available 34199 when the count reaches zero and the calling thread no longer has any locks on this mutex). 34200 If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the 34201 thread shall resume waiting for the mutex as if it was not interrupted. System Interfaces, Issue 6 1575 pthread_mutex_lock( ) System Interfaces 34202 RETURN VALUE 34203 If successful, the pthread_mutex_lock( ) and pthread_mutex_unlock( ) functions shall return zero; 34204 otherwise, an error number shall be returned to indicate the error. 34205 The pthread_mutex_trylock( ) function shall return zero if a lock on the mutex object referenced by 34206 mutex is acquired. Otherwise, an error number is returned to indicate the error. 34207 ERRORS 34208 The pthread_mutex_lock( ) and pthread_mutex_trylock( ) functions shall fail if: 34209 [EINVAL] The mutex was created with the protocol attribute having the value 34210 PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than 34211 the mutex's current priority ceiling. 34212 The pthread_mutex_trylock( ) function shall fail if: 34213 [EBUSY] The mutex could not be acquired because it was already locked. 34214 The pthread_mutex_lock( ), pthread_mutex_trylock( ), and pthread_mutex_unlock( ) functions may 34215 fail if: 34216 [EINVAL] The value specified by mutex does not refer to an initialized mutex object. 34217 XSI [EAGAIN] The mutex could not be acquired because the maximum number of recursive 34218 locks for mutex has been exceeded. 34219 The pthread_mutex_lock( ) function may fail if: 34220 [EDEADLK] The current thread already owns the mutex. 34221 The pthread_mutex_unlock( ) function may fail if: 34222 [EPERM] The current thread does not own the mutex. 34223 These functions shall not return an error code of [EINTR]. 34224 EXAMPLES 34225 None. 34226 APPLICATION USAGE 34227 None. 34228 RATIONALE 34229 Mutex objects are intended to serve as a low-level primitive from which other thread 34230 synchronization functions can be built. As such, the implementation of mutexes should be as 34231 efficient as possible, and this has ramifications on the features available at the interface. 34232 The mutex functions and the particular default settings of the mutex attributes have been 34233 motivated by the desire to not preclude fast, inlined implementations of mutex locking and 34234 unlocking. 34235 For example, deadlocking on a double-lock is explicitly allowed behavior in order to avoid 34236 requiring more overhead in the basic mechanism than is absolutely necessary. (More ``friendly'' 34237 mutexes that detect deadlock or that allow multiple locking by the same thread are easily 34238 constructed by the user via the other mechanisms provided. For example, pthread_self( ) can be 34239 used to record mutex ownership.) Implementations might also choose to provide such extended 34240 features as options via special mutex attributes. 34241 Since most attributes only need to be checked when a thread is going to be blocked, the use of 34242 attributes does not slow the (common) mutex-locking case. 1576 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_lock( ) 34243 Likewise, while being able to extract the thread ID of the owner of a mutex might be desirable, it 34244 would require storing the current thread ID when each mutex is locked, and this could incur 34245 unacceptable levels of overhead. Similar arguments apply to a mutex_tryunlock operation. 34246 FUTURE DIRECTIONS 34247 None. 34248 SEE ALSO 34249 pthread_mutex_destroy( ), pthread_mutex_timedlock( ), the Base Definitions volume of 34250 IEEE Std 1003.1-200x, 34251 CHANGE HISTORY 34252 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34253 Issue 6 34254 The pthread_mutex_lock( ), pthread_mutex_trylock( ), and pthread_mutex_unlock( ) functions are 34255 marked as part of the Threads option. 34256 The following new requirements on POSIX implementations derive from alignment with the 34257 Single UNIX Specification: 34258 * The behavior when attempting to relock a mutex is defined. 34259 The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with 34260 IEEE Std 1003.1d-1999. System Interfaces, Issue 6 1577 pthread_mutex_setprioceiling( ) System Interfaces 34261 NAME 34262 pthread_mutex_setprioceiling - change the priority ceiling of a mutex (REALTIME 34263 THREADS) 34264 SYNOPSIS 34265 THR TPP #include 34266 int pthread_mutex_setprioceiling(pthread_mutex_t *restrict mutex, 34267 int prioceiling, int *restrict old_ceiling); 34268 34269 DESCRIPTION 34270 Refer to pthread_mutex_getprioceiling( ). 1578 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_timedlock( ) 34271 NAME 34272 pthread_mutex_timedlock - lock a mutex (ADVANCED REALTIME) 34273 SYNOPSIS 34274 THR TMO #include 34275 #include 34276 int pthread_mutex_timedlock(pthread_mutex_t *restrict mutex, 34277 const struct timespec *restrict abs_timeout); 34278 34279 DESCRIPTION 34280 The pthread_mutex_timedlock( ) function shall lock the mutex object referenced by mutex. If the | 34281 mutex is already locked, the calling thread shall block until the mutex becomes available as in | 34282 the pthread_mutex_lock( ) function. If the mutex cannot be locked without waiting for another | 34283 thread to unlock the mutex, this wait shall be terminated when the specified timeout expires. 34284 The timeout shall expire when the absolute time specified by abs_timeout passes, as measured by | 34285 the clock on which timeouts are based (that is, when the value of that clock equals or exceeds 34286 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 34287 of the call. 34288 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; if | 34289 the Timers option is not supported, the timeout shall be based on the system clock as returned | 34290 by the time( ) function. | 34291 The resolution of the timeout shall be the resolution of the clock on which it is based. The | 34292 timespec data type is defined in the header. | 34293 Under no circumstance shall the function fail with a timeout if the mutex can be locked | 34294 immediately. The validity of the abs_timeout parameter need not be checked if the mutex can be 34295 locked immediately. 34296 As a consequence of the priority inheritance rules (for mutexes initialized with the 34297 PRIO_INHERIT protocol), if a timed mutex wait is terminated because its timeout expires, the 34298 priority of the owner of the mutex shall be adjusted as necessary to reflect the fact that this | 34299 thread is no longer among the threads waiting for the mutex. | 34300 RETURN VALUE 34301 If successful, the pthread_mutex_timedlock( ) function shall return zero; otherwise, an error 34302 number shall be returned to indicate the error. 34303 ERRORS 34304 The pthread_mutex_timedlock( ) function shall fail if: 34305 [EINVAL] The mutex was created with the protocol attribute having the value 34306 PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than 34307 the mutex' current priority ceiling. 34308 [EINVAL] The process or thread would have blocked, and the abs_timeout parameter 34309 specified a nanoseconds field value less than zero or greater than or equal to 34310 1 000 million. 34311 [ETIMEDOUT] The mutex could not be locked before the specified timeout expired. 34312 The pthread_mutex_timedlock( ) function may fail if: 34313 [EINVAL] The value specified by mutex does not refer to an initialized mutex object. System Interfaces, Issue 6 1579 pthread_mutex_timedlock( ) System Interfaces 34314 XSI [EAGAIN] The mutex could not be acquired because the maximum number of recursive 34315 locks for mutex has been exceeded. 34316 [EDEADLK] The current thread already owns the mutex. 34317 This function shall not return an error code of [EINTR]. 34318 EXAMPLES 34319 None. 34320 APPLICATION USAGE 34321 The pthread_mutex_timedlock( ) function is part of the Threads and Timeouts options and need 34322 not be provided on all implementations. 34323 RATIONALE 34324 None. 34325 FUTURE DIRECTIONS 34326 None. 34327 SEE ALSO 34328 pthread_mutex_destroy( ), pthread_mutex_lock( ), pthread_mutex_trylock( ), time( ), the Base 34329 Definitions volume of IEEE Std 1003.1-200x, , 34330 CHANGE HISTORY 34331 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1580 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutex_trylock( ) 34332 NAME 34333 pthread_mutex_trylock, pthread_mutex_unlock - lock and unlock a mutex 34334 SYNOPSIS 34335 THR #include 34336 int pthread_mutex_trylock(pthread_mutex_t *mutex); 34337 int pthread_mutex_unlock(pthread_mutex_t *mutex); 34338 34339 DESCRIPTION 34340 Refer to pthread_mutex_lock( ). System Interfaces, Issue 6 1581 pthread_mutexattr_destroy( ) System Interfaces 34341 NAME 34342 pthread_mutexattr_destroy, pthread_mutexattr_init - destroy and initialize mutex attributes 34343 object 34344 SYNOPSIS 34345 THR #include 34346 int pthread_mutexattr_destroy(pthread_mutexattr_t *attr); 34347 int pthread_mutexattr_init(pthread_mutexattr_t *attr); 34348 34349 DESCRIPTION 34350 The pthread_mutexattr_destroy( ) function shall destroy a mutex attributes object; the object 34351 becomes, in effect, uninitialized. An implementation may cause pthread_mutexattr_destroy( ) to 34352 set the object referenced by attr to an invalid value. A destroyed attr attributes object can be | 34353 reinitialized using pthread_mutexattr_init( ); the results of otherwise referencing the object after it | 34354 has been destroyed are undefined. | 34355 The pthread_mutexattr_init( ) function shall initialize a mutex attributes object attr with the 34356 default value for all of the attributes defined by the implementation. 34357 Results are undefined if pthread_mutexattr_init( ) is called specifying an already initialized attr | 34358 attributes object. | 34359 After a mutex attributes object has been used to initialize one or more mutexes, any function 34360 affecting the attributes object (including destruction) shall not affect any previously initialized | 34361 mutexes. | 34362 RETURN VALUE 34363 Upon successful completion, pthread_mutexattr_destroy( ) and pthread_mutexattr_init( ) shall 34364 return zero; otherwise, an error number shall be returned to indicate the error. 34365 ERRORS 34366 The pthread_mutexattr_destroy( ) function may fail if: 34367 [EINVAL] The value specified by attr is invalid. 34368 The pthread_mutexattr_init( ) function shall fail if: 34369 [ENOMEM] Insufficient memory exists to initialize the mutex attributes object. 34370 These functions shall not return an error code of [EINTR]. 34371 EXAMPLES 34372 None. 34373 APPLICATION USAGE 34374 None. 34375 RATIONALE 34376 See pthread_attr_init( ) for a general explanation of attributes. Attributes objects allow 34377 implementations to experiment with useful extensions and permit extension of this volume of 34378 IEEE Std 1003.1-200x without changing the existing functions. Thus, they provide for future 34379 extensibility of this volume of IEEE Std 1003.1-200x and reduce the temptation to standardize 34380 prematurely on semantics that are not yet widely implemented or understood. 34381 Examples of possible additional mutex attributes that have been discussed are spin_only, 34382 limited_spin, no_spin, recursive, and metered. (To explain what the latter attributes might mean: 34383 recursive mutexes would allow for multiple re-locking by the current owner; metered mutexes 34384 would transparently keep records of queue length, wait time, and so on.) Since there is not yet 1582 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_destroy( ) 34385 wide agreement on the usefulness of these resulting from shared implementation and usage 34386 experience, they are not yet specified in this volume of IEEE Std 1003.1-200x. Mutex attributes 34387 objects, however, make it possible to test out these concepts for possible standardization at a 34388 later time. 34389 Mutex Attributes and Performance 34390 Care has been taken to ensure that the default values of the mutex attributes have been defined 34391 such that mutexes initialized with the defaults have simple enough semantics so that the locking 34392 and unlocking can be done with the equivalent of a test-and-set instruction (plus possibly a few 34393 other basic instructions). 34394 There is at least one implementation method that can be used to reduce the cost of testing at 34395 lock-time if a mutex has non-default attributes. One such method that an implementation can 34396 employ (and this can be made fully transparent to fully conforming POSIX applications) is to 34397 secretly pre-lock any mutexes that are initialized to non-default attributes. Any later attempt to 34398 lock such a mutex causes the implementation to branch to the ``slow path'' as if the mutex were 34399 unavailable; then, on the slow path, the implementation can do the ``real work'' to lock a non- 34400 default mutex. The underlying unlock operation is more complicated since the implementation 34401 never really wants to release the pre-lock on this kind of mutex. This illustrates that, depending 34402 on the hardware, there may be certain optimizations that can be used so that whatever mutex 34403 attributes are considered ``most frequently used'' can be processed most efficiently. 34404 Process Shared Memory and Synchronization 34405 The existence of memory mapping functions in this volume of IEEE Std 1003.1-200x leads to the 34406 possibility that an application may allocate the synchronization objects from this section in 34407 memory that is accessed by multiple processes (and therefore, by threads of multiple processes). 34408 In order to permit such usage, while at the same time keeping the usual case (that is, usage 34409 within a single process) efficient, a process-shared option has been defined. 34410 If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option, then the 34411 process-shared attribute can be used to indicate that mutexes or condition variables may be 34412 accessed by threads of multiple processes. 34413 The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the process-shared 34414 attribute so that the most efficient forms of these synchronization objects are created by default. 34415 Synchronization variables that are initialized with the PTHREAD_PROCESS_PRIVATE process- 34416 shared attribute may only be operated on by threads in the process that initialized them. 34417 Synchronization variables that are initialized with the PTHREAD_PROCESS_SHARED process- 34418 shared attribute may be operated on by any thread in any process that has access to it. In 34419 particular, these processes may exist beyond the lifetime of the initializing process. For example, 34420 the following code implements a simple counting semaphore in a mapped file that may be used 34421 by many processes. 34422 /* sem.h */ 34423 struct semaphore { 34424 pthread_mutex_t lock; 34425 pthread_cond_t nonzero; 34426 unsigned count; 34427 }; 34428 typedef struct semaphore semaphore_t; 34429 semaphore_t *semaphore_create(char *semaphore_name); 34430 semaphore_t *semaphore_open(char *semaphore_name); System Interfaces, Issue 6 1583 pthread_mutexattr_destroy( ) System Interfaces 34431 void semaphore_post(semaphore_t *semap); 34432 void semaphore_wait(semaphore_t *semap); 34433 void semaphore_close(semaphore_t *semap); 34434 /* sem.c */ 34435 #include 34436 #include 34437 #include 34438 #include 34439 #include 34440 #include "sem.h" 34441 semaphore_t * 34442 semaphore_create(char *semaphore_name) 34443 { 34444 int fd; 34445 semaphore_t *semap; 34446 pthread_mutexattr_t psharedm; 34447 pthread_condattr_t psharedc; 34448 fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666); 34449 if (fd < 0) 34450 return (NULL); 34451 (void) ftruncate(fd, sizeof(semaphore_t)); 34452 (void) pthread_mutexattr_init(&psharedm); 34453 (void) pthread_mutexattr_setpshared(&psharedm, 34454 PTHREAD_PROCESS_SHARED); 34455 (void) pthread_condattr_init(&psharedc); 34456 (void) pthread_condattr_setpshared(&psharedc, 34457 PTHREAD_PROCESS_SHARED); 34458 semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), 34459 PROT_READ | PROT_WRITE, MAP_SHARED, 34460 fd, 0); 34461 close (fd); 34462 (void) pthread_mutex_init(&semap->lock, &psharedm); 34463 (void) pthread_cond_init(&semap->nonzero, &psharedc); 34464 semap->count = 0; 34465 return (semap); 34466 } 34467 semaphore_t * 34468 semaphore_open(char *semaphore_name) 34469 { 34470 int fd; 34471 semaphore_t *semap; 34472 fd = open(semaphore_name, O_RDWR, 0666); 34473 if (fd < 0) 34474 return (NULL); 34475 semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), 34476 PROT_READ | PROT_WRITE, MAP_SHARED, 34477 fd, 0); 34478 close (fd); 34479 return (semap); 34480 } 1584 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_destroy( ) 34481 void 34482 semaphore_post(semaphore_t *semap) 34483 { 34484 pthread_mutex_lock(&semap->lock); 34485 if (semap->count == 0) 34486 pthread_cond_signal(&semapx->nonzero); 34487 semap->count++; 34488 pthread_mutex_unlock(&semap->lock); 34489 } 34490 void 34491 semaphore_wait(semaphore_t *semap) 34492 { 34493 pthread_mutex_lock(&semap->lock); 34494 while (semap->count == 0) 34495 pthread_cond_wait(&semap->nonzero, &semap->lock); 34496 semap->count- -; 34497 pthread_mutex_unlock(&semap->lock); 34498 } 34499 void 34500 semaphore_close(semaphore_t *semap) 34501 { 34502 munmap((void *) semap, sizeof(semaphore_t)); 34503 } 34504 The following code is for three separate processes that create, post, and wait on a semaphore in 34505 the file /tmp/semaphore. Once the file is created, the post and wait programs increment and 34506 decrement the counting semaphore (waiting and waking as required) even though they did not 34507 initialize the semaphore. 34508 /* create.c */ 34509 #include "pthread.h" 34510 #include "sem.h" 34511 int 34512 main() 34513 { 34514 semaphore_t *semap; 34515 semap = semaphore_create("/tmp/semaphore"); 34516 if (semap == NULL) 34517 exit(1); 34518 semaphore_close(semap); 34519 return (0); 34520 } 34521 /* post */ 34522 #include "pthread.h" 34523 #include "sem.h" 34524 int 34525 main() 34526 { 34527 semaphore_t *semap; System Interfaces, Issue 6 1585 pthread_mutexattr_destroy( ) System Interfaces 34528 semap = semaphore_open("/tmp/semaphore"); 34529 if (semap == NULL) 34530 exit(1); 34531 semaphore_post(semap); 34532 semaphore_close(semap); 34533 return (0); 34534 } 34535 /* wait */ 34536 #include "pthread.h" 34537 #include "sem.h" 34538 int 34539 main() 34540 { 34541 semaphore_t *semap; 34542 semap = semaphore_open("/tmp/semaphore"); 34543 if (semap == NULL) 34544 exit(1); 34545 semaphore_wait(semap); 34546 semaphore_close(semap); 34547 return (0); 34548 } 34549 FUTURE DIRECTIONS 34550 None. 34551 SEE ALSO 34552 pthread_cond_destroy( ), pthread_create( ), pthread_mutex_destroy( ), pthread_mutexattr_destroy( ), the 34553 Base Definitions volume of IEEE Std 1003.1-200x, 34554 CHANGE HISTORY 34555 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34556 Issue 6 34557 The pthread_mutexattr_destroy( ) and pthread_mutexattr_init( ) functions are marked as part of the 34558 Threads option. 34559 IEEE PASC Interpretation 1003.1c #27 is applied, updating the ERRORS section. 1586 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_getprioceiling( ) 34560 NAME 34561 pthread_mutexattr_getprioceiling, pthread_mutexattr_setprioceiling - get and set prioceiling 34562 attribute of mutex attributes object (REALTIME THREADS) 34563 SYNOPSIS 34564 THR TPP #include 34565 int pthread_mutexattr_getprioceiling( 34566 const pthread_mutexattr_t *restrict attr, 34567 int *restrict prioceiling); 34568 int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, 34569 int prioceiling); 34570 34571 DESCRIPTION 34572 The pthread_mutexattr_getprioceiling( ) and pthread_mutexattr_setprioceiling( ) functions, 34573 respectively, shall get and set the priority ceiling attribute of a mutex attributes object pointed to 34574 by attr which was previously created by the function pthread_mutexattr_init( ). 34575 The prioceiling attribute contains the priority ceiling of initialized mutexes. The values of 34576 prioceiling are within the maximum range of priorities defined by SCHED_FIFO. 34577 The prioceiling attribute defines the priority ceiling of initialized mutexes, which is the minimum 34578 priority level at which the critical section guarded by the mutex is executed. In order to avoid 34579 priority inversion, the priority ceiling of the mutex shall be set to a priority higher than or equal | 34580 to the highest priority of all the threads that may lock that mutex. The values of prioceiling are | 34581 within the maximum range of priorities defined under the SCHED_FIFO scheduling policy. 34582 RETURN VALUE 34583 Upon successful completion, the pthread_mutexattr_getprioceiling( ) and 34584 pthread_mutexattr_setprioceiling( ) functions shall return zero; otherwise, an error number shall be 34585 returned to indicate the error. 34586 ERRORS 34587 The pthread_mutexattr_getprioceiling( ) and pthread_mutexattr_setprioceiling( ) functions may fail if: 34588 [EINVAL] The value specified by attr or prioceiling is invalid. 34589 [EPERM] The caller does not have the privilege to perform the operation. 34590 These functions shall not return an error code of [EINTR]. 34591 EXAMPLES 34592 None. 34593 APPLICATION USAGE 34594 None. 34595 RATIONALE 34596 None. 34597 FUTURE DIRECTIONS 34598 None. 34599 SEE ALSO 34600 pthread_cond_destroy( ), pthread_create( ), pthread_mutex_destroy( ), the Base Definitions volume of 34601 IEEE Std 1003.1-200x, System Interfaces, Issue 6 1587 pthread_mutexattr_getprioceiling( ) System Interfaces 34602 CHANGE HISTORY 34603 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34604 Marked as part of the Realtime Threads Feature Group. 34605 Issue 6 34606 The pthread_mutexattr_getprioceiling( ) and pthread_mutexattr_setprioceiling( ) functions are 34607 marked as part of the Threads and Thread Priority Protection options. 34608 The [ENOSYS] error condition has been removed as stubs need not be provided if an 34609 implementation does not support the Thread Priority Protection option. 34610 The [ENOTSUP] error condition has been removed since these functions do not have a protocol 34611 argument. 34612 The restrict keyword is added to the pthread_mutexattr_getprioceiling( ) prototype for alignment 34613 with the ISO/IEC 9899: 1999 standard. 1588 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_getprotocol( ) 34614 NAME 34615 pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol - get and set protocol attribute 34616 of mutex attributes object (REALTIME THREADS) 34617 SYNOPSIS 34618 THR #include 34619 TPP|TPI int pthread_mutexattr_getprotocol( 34620 const pthread_mutexattr_t *restrict attr, 34621 int *restrict protocol); 34622 int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, 34623 int protocol); 34624 34625 DESCRIPTION 34626 The pthread_mutexattr_getprotocol( ) and pthread_mutexattr_setprotocol( ) functions, respectively, 34627 shall get and set the protocol attribute of a mutex attributes object pointed to by attr which was 34628 previously created by the function pthread_mutexattr_init( ). 34629 The protocol attribute defines the protocol to be followed in utilizing mutexes. The value of 34630 protocol may be one of: 34631 PTHREAD_PRIO_NONE 34632 TPI PTHREAD_PRIO_INHERIT 34633 TPP PTHREAD_PRIO_PROTECT 34634 34635 which are defined in the header. | 34636 When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute, its priority | 34637 and scheduling shall not be affected by its mutex ownership. | 34638 TPI When a thread is blocking higher priority threads because of owning one or more mutexes with 34639 the PTHREAD_PRIO_INHERIT protocol attribute, it shall execute at the higher of its priority or | 34640 the priority of the highest priority thread waiting on any of the mutexes owned by this thread | 34641 and initialized with this protocol. | 34642 TPP When a thread owns one or more mutexes initialized with the PTHREAD_PRIO_PROTECT | 34643 protocol, it shall execute at the higher of its priority or the highest of the priority ceilings of all | 34644 the mutexes owned by this thread and initialized with this attribute, regardless of whether other 34645 threads are blocked on any of these mutexes or not. 34646 While a thread is holding a mutex which has been initialized with the 34647 PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it shall not be 34648 subject to being moved to the tail of the scheduling queue at its priority in the event that its 34649 original priority is changed, such as by a call to sched_setparam( ). Likewise, when a thread 34650 unlocks a mutex that has been initialized with the PTHREAD_PRIO_INHERIT or 34651 PTHREAD_PRIO_PROTECT protocol attributes, it shall not be subject to being moved to the tail 34652 of the scheduling queue at its priority in the event that its original priority is changed. 34653 If a thread simultaneously owns several mutexes initialized with different protocols, it shall 34654 execute at the highest of the priorities that it would have obtained by each of these protocols. 34655 TPI When a thread makes a call to pthread_mutex_lock( ), the mutex was initialized with the protocol 34656 attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked 34657 because the mutex is owned by another thread, that owner thread shall inherit the priority level 34658 of the calling thread as long as it continues to own the mutex. The implementation shall update 34659 its execution priority to the maximum of its assigned priority and all its inherited priorities. System Interfaces, Issue 6 1589 pthread_mutexattr_getprotocol( ) System Interfaces 34660 Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority 34661 inheritance effect shall be propagated to this other owner thread, in a recursive manner. 34662 RETURN VALUE 34663 Upon successful completion, the pthread_mutexattr_getprotocol( ) and 34664 pthread_mutexattr_setprotocol( ) functions shall return zero; otherwise, an error number shall be 34665 returned to indicate the error. 34666 ERRORS 34667 The pthread_mutexattr_setprotocol( ) function shall fail if: 34668 [ENOTSUP] The value specified by protocol is an unsupported value. 34669 The pthread_mutexattr_getprotocol( ) and pthread_mutexattr_setprotocol( ) functions may fail if: 34670 [EINVAL] The value specified by attr or protocol is invalid. 34671 [EPERM] The caller does not have the privilege to perform the operation. 34672 These functions shall not return an error code of [EINTR]. 34673 EXAMPLES 34674 None. 34675 APPLICATION USAGE 34676 None. 34677 RATIONALE 34678 None. 34679 FUTURE DIRECTIONS 34680 None. 34681 SEE ALSO 34682 pthread_cond_destroy( ), pthread_create( ), pthread_mutex_destroy( ), the Base Definitions volume of 34683 IEEE Std 1003.1-200x, 34684 CHANGE HISTORY 34685 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34686 Marked as part of the Realtime Threads Feature Group. 34687 Issue 6 34688 The pthread_mutexattr_getprotocol( ) and pthread_mutexattr_setprotocol( ) functions are marked as 34689 part of the Threads option and either the Thread Priority Protection or Thread Priority 34690 Inheritance options. 34691 The [ENOSYS] error condition has been removed as stubs need not be provided if an 34692 implementation does not support the Thread Priority Protection or Thread Priority Inheritance 34693 options. 34694 The restrict keyword is added to the pthread_mutexattr_getprotocol( ) prototype for alignment 34695 with the ISO/IEC 9899: 1999 standard. 1590 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_getpshared( ) 34696 NAME 34697 pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - get and set process-shared 34698 attribute 34699 SYNOPSIS 34700 THR TSH #include 34701 int pthread_mutexattr_getpshared( 34702 const pthread_mutexattr_t *restrict attr, 34703 int *restrict pshared); 34704 int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, 34705 int pshared); 34706 34707 DESCRIPTION 34708 The pthread_mutexattr_getpshared( ) function shall obtain the value of the process-shared attribute 34709 from the attributes object referenced by attr. The pthread_mutexattr_setpshared( ) function shall | 34710 set the process-shared attribute in an initialized attributes object referenced by attr. | 34711 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be 34712 operated upon by any thread that has access to the memory where the mutex is allocated, even if 34713 the mutex is allocated in memory that is shared by multiple processes. If the process-shared 34714 attribute is PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated upon by threads 34715 created within the same process as the thread that initialized the mutex; if threads of differing 34716 processes attempt to operate on such a mutex, the behavior is undefined. The default value of 34717 the attribute shall be PTHREAD_PROCESS_PRIVATE. 34718 RETURN VALUE 34719 Upon successful completion, pthread_mutexattr_setpshared( ) shall return zero; otherwise, an error 34720 number shall be returned to indicate the error. 34721 Upon successful completion, pthread_mutexattr_getpshared( ) shall return zero and stores the 34722 value of the process-shared attribute of attr into the object referenced by the pshared parameter. 34723 Otherwise, an error number shall be returned to indicate the error. 34724 ERRORS 34725 The pthread_mutexattr_getpshared( ) and pthread_mutexattr_setpshared( ) functions may fail if: 34726 [EINVAL] The value specified by attr is invalid. 34727 The pthread_mutexattr_setpshared( ) function may fail if: 34728 [EINVAL] The new value specified for the attribute is outside the range of legal values 34729 for that attribute. 34730 These functions shall not return an error code of [EINTR]. 34731 EXAMPLES 34732 None. 34733 APPLICATION USAGE 34734 None. 34735 RATIONALE 34736 None. System Interfaces, Issue 6 1591 pthread_mutexattr_getpshared( ) System Interfaces 34737 FUTURE DIRECTIONS 34738 None. 34739 SEE ALSO 34740 pthread_cond_destroy( ), pthread_create( ), pthread_mutex_destroy( ), pthread_mutexattr_destroy( ), the 34741 Base Definitions volume of IEEE Std 1003.1-200x, 34742 CHANGE HISTORY 34743 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34744 Issue 6 34745 The pthread_mutexattr_getpshared( ) and pthread_mutexattr_setpshared( ) functions are marked as 34746 part of the Threads and Thread Process-Shared Synchronization options. 34747 The restrict keyword is added to the pthread_mutexattr_getpshared( ) prototype for alignment 34748 with the ISO/IEC 9899: 1999 standard. 1592 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_gettype( ) 34749 NAME 34750 pthread_mutexattr_gettype, pthread_mutexattr_settype - get and set a mutex type attribute 34751 SYNOPSIS 34752 XSI #include 34753 int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict attr, 34754 int *restrict type); 34755 int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type); 34756 34757 DESCRIPTION 34758 The pthread_mutexattr_gettype( ) and pthread_mutexattr_settype( ) functions, respectively, shall get 34759 and set the mutex type attribute. This attribute is set in the type parameter to these functions. The 34760 default value of the type attribute is PTHREAD_MUTEX_DEFAULT. 34761 The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types 34762 include: 34763 PTHREAD_MUTEX_NORMAL 34764 This type of mutex does not detect deadlock. A thread attempting to relock this mutex 34765 without first unlocking it shall deadlock. Attempting to unlock a mutex locked by a 34766 different thread results in undefined behavior. Attempting to unlock an unlocked mutex 34767 results in undefined behavior. 34768 PTHREAD_MUTEX_ERRORCHECK 34769 This type of mutex provides error checking. A thread attempting to relock this mutex 34770 without first unlocking it shall return with an error. A thread attempting to unlock a mutex 34771 which another thread has locked shall return with an error. A thread attempting to unlock 34772 an unlocked mutex shall return with an error. 34773 PTHREAD_MUTEX_RECURSIVE 34774 A thread attempting to relock this mutex without first unlocking it shall succeed in locking 34775 the mutex. The relocking deadlock which can occur with mutexes of type 34776 PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this | 34777 mutex shall require the same number of unlocks to release the mutex before another thread | 34778 can acquire the mutex. A thread attempting to unlock a mutex which another thread has | 34779 locked shall return with an error. A thread attempting to unlock an unlocked mutex shall | 34780 return with an error. | 34781 PTHREAD_MUTEX_DEFAULT 34782 Attempting to recursively lock a mutex of this type results in undefined behavior. 34783 Attempting to unlock a mutex of this type which was not locked by the calling thread 34784 results in undefined behavior. Attempting to unlock a mutex of this type which is not 34785 locked results in undefined behavior. An implementation may map this mutex to one of the | 34786 other mutex types. 34787 RETURN VALUE 34788 Upon successful completion, the pthread_mutexattr_gettype( ) function shall return zero and store 34789 the value of the type attribute of attr into the object referenced by the type parameter. Otherwise, 34790 an error shall be returned to indicate the error. 34791 If successful, the pthread_mutexattr_settype( ) function shall return zero; otherwise, an error 34792 number shall be returned to indicate the error. System Interfaces, Issue 6 1593 pthread_mutexattr_gettype( ) System Interfaces 34793 ERRORS 34794 The pthread_mutexattr_settype( ) function shall fail if: 34795 [EINVAL] The value type is invalid. 34796 The pthread_mutexattr_gettype( ) and pthread_mutexattr_settype( ) functions may fail if: 34797 [EINVAL] The value specified by attr is invalid. 34798 These functions shall not return an error code of [EINTR]. 34799 EXAMPLES 34800 None. 34801 APPLICATION USAGE 34802 It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE mutex with 34803 condition variables because the implicit unlock performed for a pthread_cond_timedwait( ) or 34804 pthread_cond_wait( ) may not actually release the mutex (if it had been locked multiple times). If 34805 this happens, no other thread can satisfy the condition of the predicate. 34806 RATIONALE 34807 None. 34808 FUTURE DIRECTIONS 34809 None. 34810 SEE ALSO 34811 pthread_cond_timedwait( ), pthread_cond_wait( ), the Base Definitions volume of 34812 IEEE Std 1003.1-200x, 34813 CHANGE HISTORY 34814 First released in Issue 5. 34815 Issue 6 34816 The Open Group Corrigendum U033/3 is applied. The SYNOPSIS for 34817 pthread_mutexattr_gettype( ) is updated so that the first argument is of type const 34818 pthread_mutexattr_t *. 34819 The restrict keyword is added to the pthread_mutexattr_gettype( ) prototype for alignment with 34820 the ISO/IEC 9899: 1999 standard. 1594 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_init( ) 34821 NAME 34822 pthread_mutexattr_init - initialize mutex attributes object 34823 SYNOPSIS 34824 THR #include 34825 int pthread_mutexattr_init(pthread_mutexattr_t *attr); 34826 34827 DESCRIPTION 34828 Refer to pthread_mutexattr_destroy( ). System Interfaces, Issue 6 1595 pthread_mutexattr_setprioceiling( ) System Interfaces 34829 NAME 34830 pthread_mutexattr_setprioceiling - set prioceiling attribute of mutex attributes object 34831 (REALTIME THREADS) 34832 SYNOPSIS 34833 THR TPP #include 34834 int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, 34835 int prioceiling); 34836 34837 DESCRIPTION 34838 Refer to pthread_mutexattr_getprioceiling( ). 1596 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_setprotocol( ) 34839 NAME 34840 pthread_mutexattr_setprotocol - set protocol attribute of mutex attributes object (REALTIME 34841 THREADS) 34842 SYNOPSIS 34843 THR #include 34844 TPP|TPI int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, 34845 int protocol); 34846 34847 DESCRIPTION 34848 Refer to pthread_mutexattr_setprotocol( ). System Interfaces, Issue 6 1597 pthread_mutexattr_setpshared( ) System Interfaces 34849 NAME 34850 pthread_mutexattr_setpshared - set process-shared attribute 34851 SYNOPSIS 34852 THR TSH #include 34853 int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, 34854 int pshared); 34855 34856 DESCRIPTION 34857 Refer to pthread_mutexattr_getpshared( ). 1598 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_mutexattr_settype( ) 34858 NAME 34859 pthread_mutexattr_settype - set a mutex type attribute 34860 SYNOPSIS 34861 XSI #include 34862 int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type); 34863 34864 DESCRIPTION 34865 Refer to pthread_mutexattr_gettype( ). System Interfaces, Issue 6 1599 pthread_once( ) System Interfaces 34866 NAME 34867 pthread_once - dynamic package initialization 34868 SYNOPSIS 34869 THR #include 34870 int pthread_once(pthread_once_t *once_control, 34871 void (*init_routine)(void)); 34872 pthread_once_t once_control = PTHREAD_ONCE_INIT; 34873 34874 DESCRIPTION 34875 The first call to pthread_once( ) by any thread in a process, with a given once_control, shall call the 34876 init_routine with no arguments. Subsequent calls of pthread_once( ) with the same once_control 34877 shall not call the init_routine. On return from pthread_once( ), init_routine shall have completed. | 34878 The once_control parameter shall determine whether the associated initialization routine has | 34879 been called. 34880 The pthread_once( ) function is not a cancelation point. However, if init_routine is a cancelation 34881 point and is canceled, the effect on once_control shall be as if pthread_once( ) was never called. 34882 The constant PTHREAD_ONCE_INIT is defined in the header. | 34883 The behavior of pthread_once( ) is undefined if once_control has automatic storage duration or is 34884 not initialized by PTHREAD_ONCE_INIT. 34885 RETURN VALUE 34886 Upon successful completion, pthread_once( ) shall return zero; otherwise, an error number shall 34887 be returned to indicate the error. 34888 ERRORS 34889 The pthread_once( ) function may fail if: 34890 [EINVAL] If either once_control or init_routine is invalid. 34891 The pthread_once( ) function shall not return an error code of [EINTR]. 34892 EXAMPLES 34893 None. 34894 APPLICATION USAGE 34895 None. 34896 RATIONALE 34897 Some C libraries are designed for dynamic initialization. That is, the global initialization for the 34898 library is performed when the first procedure in the library is called. In a single-threaded 34899 program, this is normally implemented using a static variable whose value is checked on entry 34900 to a routine, as follows: 34901 static int random_is_initialized = 0; 34902 extern int initialize_random(); 34903 int random_function() 34904 { 34905 if (random_is_initialized == 0) { 34906 initialize_random(); 34907 random_is_initialized = 1; 34908 } 34909 ... /* Operations performed after initialization. */ 34910 } 1600 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_once( ) 34911 To keep the same structure in a multi-threaded program, a new primitive is needed. Otherwise, 34912 library initialization has to be accomplished by an explicit call to a library-exported initialization 34913 function prior to any use of the library. 34914 For dynamic library initialization in a multi-threaded process, a simple initialization flag is not 34915 sufficient; the flag needs to be protected against modification by multiple threads 34916 simultaneously calling into the library. Protecting the flag requires the use of a mutex; however, 34917 mutexes have to be initialized before they are used. Ensuring that the mutex is only initialized 34918 once requires a recursive solution to this problem. 34919 The use of pthread_once( ) not only supplies an implementation-guaranteed means of dynamic 34920 initialization, it provides an aid to the reliable construction of multi-threaded and realtime 34921 systems. The preceding example then becomes: 34922 #include 34923 static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; 34924 extern int initialize_random(); 34925 int random_function() 34926 { 34927 (void) pthread_once(&random_is_initialized, initialize_random); 34928 ... /* Operations performed after initialization. */ 34929 } 34930 Note that a pthread_once_t cannot be an array because some compilers do not accept the 34931 construct &. 34932 FUTURE DIRECTIONS 34933 None. 34934 SEE ALSO 34935 The Base Definitions volume of IEEE Std 1003.1-200x, 34936 CHANGE HISTORY 34937 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 34938 Issue 6 34939 The pthread_once( ) function is marked as part of the Threads option. 34940 The [EINVAL] error is added as a may fail case for if either argument is invalid. System Interfaces, Issue 6 1601 pthread_rwlock_destroy( ) System Interfaces 34941 NAME 34942 pthread_rwlock_destroy, pthread_rwlock_init - destroy and initialize a read-write lock object 34943 SYNOPSIS 34944 THR #include 34945 int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); 34946 int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, 34947 const pthread_rwlockattr_t *restrict attr); 34948 34949 DESCRIPTION 34950 The pthread_rwlock_destroy( ) function shall destroy the read-write lock object referenced by 34951 rwlock and release any resources used by the lock. The effect of subsequent use of the lock is | 34952 undefined until the lock is reinitialized by another call to pthread_rwlock_init( ). An | 34953 implementation may cause pthread_rwlock_destroy( ) to set the object referenced by rwlock to an 34954 invalid value. Results are undefined if pthread_rwlock_destroy( ) is called when any thread holds 34955 rwlock. Attempting to destroy an uninitialized read-write lock results in undefined behavior. 34956 The pthread_rwlock_init( ) function shall allocate any resources required to use the read-write 34957 lock referenced by rwlock and initializes the lock to an unlocked state with attributes referenced 34958 by attr. If attr is NULL, the default read-write lock attributes shall be used; the effect is the same | 34959 as passing the address of a default read-write lock attributes object. Once initialized, the lock can | 34960 be used any number of times without being reinitialized. Results are undefined if | 34961 pthread_rwlock_init( ) is called specifying an already initialized read-write lock. Results are 34962 undefined if a read-write lock is used without first being initialized. 34963 If the pthread_rwlock_init( ) function fails, rwlock shall not be initialized and the contents of rwlock | 34964 are undefined. 34965 Only the object referenced by rwlock may be used for performing synchronization. The result of 34966 referring to copies of that object in calls to pthread_rwlock_destroy( ), pthread_rwlock_rdlock( ), 34967 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), 34968 pthread_rwlock_trywrlock( ), pthread_rwlock_unlock( ), or pthread_rwlock_wrlock( ) is undefined. 34969 RETURN VALUE 34970 If successful, the pthread_rwlock_destroy( ) and pthread_rwlock_init( ) functions shall return zero; 34971 otherwise, an error number shall be returned to indicate the error. 34972 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 34973 immediately at the beginning of processing for the function and caused an error return prior to 34974 modifying the state of the read-write lock specified by rwlock. 34975 ERRORS 34976 The pthread_rwlock_destroy( ) function may fail if: 34977 [EBUSY] The implementation has detected an attempt to destroy the object referenced 34978 by rwlock while it is locked. 34979 [EINVAL] The value specified by rwlock is invalid. 34980 The pthread_rwlock_init( ) function shall fail if: 34981 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 34982 another read-write lock. 34983 [ENOMEM] Insufficient memory exists to initialize the read-write lock. | 34984 [EPERM] The caller does not have the privilege to perform the operation. | 1602 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_destroy( ) 34985 The pthread_rwlock_init( ) function may fail if: 34986 [EBUSY] The implementation has detected an attempt to reinitialize the object | 34987 referenced by rwlock, a previously initialized but not yet destroyed read-write 34988 lock. 34989 [EINVAL] The value specified by attr is invalid. 34990 These functions shall not return an error code of [EINTR]. 34991 EXAMPLES 34992 None. 34993 APPLICATION USAGE 34994 None. 34995 RATIONALE 34996 None. 34997 FUTURE DIRECTIONS 34998 None. 34999 SEE ALSO 35000 pthread_rwlock_rdlock( ), pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), 35001 pthread_rwlock_tryrdlock( ), pthread_rwlock_trywrlock( ), pthread_rwlock_unlock( ), 35002 pthread_rwlock_wrlock( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35003 CHANGE HISTORY 35004 First released in Issue 5. 35005 Issue 6 35006 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35007 * The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35008 now part of the Threads option (previously it was part of the Read-Write Locks option in 35009 IEEE Std 1003.1j-2000 and also part of the XSI extension). The initializer macro is also deleted 35010 from the SYNOPSIS. 35011 * The DESCRIPTION is updated as follows: 35012 - It explicitly notes allocation of resources upon initialization of a read-write lock object. 35013 - A paragraph is added specifying that copies of read-write lock objects may not be used. 35014 * An [EINVAL] error is added to the ERRORS section for pthread_rwlock_init( ), indicating that 35015 the rwlock value is invalid. 35016 * The SEE ALSO section is updated. 35017 The restrict keyword is added to the pthread_rwlock_init( ) prototype for alignment with the 35018 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1603 pthread_rwlock_init( ) System Interfaces 35019 NAME 35020 pthread_rwlock_init - initialize a read-write lock object 35021 SYNOPSIS 35022 THR #include 35023 int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, 35024 const pthread_rwlockattr_t *restrict attr); 35025 35026 DESCRIPTION 35027 Refer to pthread_rwlock_destroy( ). 1604 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_rdlock( ) 35028 NAME 35029 pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock a read-write lock object for reading 35030 SYNOPSIS 35031 THR #include 35032 int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); 35033 int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); 35034 35035 DESCRIPTION 35036 The pthread_rwlock_rdlock( ) function shall apply a read lock to the read-write lock referenced by 35037 rwlock. The calling thread acquires the read lock if a writer does not hold the lock and there are 35038 no writers blocked on the lock. 35039 TPS If the Thread Execution Scheduling option is supported, and the threads involved in the lock are 35040 executing with the scheduling policies SCHED_FIFO or SCHED_RR, the calling thread shall not 35041 acquire the lock if a writer holds the lock or if writers of higher or equal priority are blocked on 35042 the lock; otherwise, the calling thread shall acquire the lock. 35043 TPS TSP If the Threads Execution Scheduling option is supported, and the threads involved in the lock 35044 are executing with the SCHED_SPORADIC scheduling policy, the calling thread shall not 35045 acquire the lock if a writer holds the lock or if writers of higher or equal priority are blocked on 35046 the lock; otherwise, the calling thread shall acquire the lock. 35047 If the Thread Execution Scheduling option is not supported, it is implementation-defined 35048 whether the calling thread acquires the lock when a writer does not hold the lock and there are 35049 writers blocked on the lock. If a writer holds the lock, the calling thread shall not acquire the 35050 read lock. If the read lock is not acquired, the calling thread shall block until it can acquire the | 35051 lock. The calling thread may deadlock if at the time the call is made it holds a write lock. | 35052 A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the 35053 pthread_rwlock_rdlock( ) function n times). If so, the application shall ensure that the thread 35054 performs matching unlocks (that is, it calls the pthread_rwlock_unlock( ) function n times). 35055 The maximum number of simultaneous read locks that an implementation guarantees can be 35056 applied to a read-write lock shall be implementation-defined. The pthread_rwlock_rdlock( ) 35057 function may fail if this maximum would be exceeded. 35058 The pthread_rwlock_tryrdlock( ) function shall apply a read lock as in the pthread_rwlock_rdlock( ) 35059 function, with the exception that the function shall fail if the equivalent pthread_rwlock_rdlock( ) 35060 call would have blocked the calling thread. In no case shall the pthread_rwlock_tryrdlock( ) 35061 function ever block; it always either acquires the lock or fails and returns immediately. 35062 Results are undefined if any of these functions are called with an uninitialized read-write lock. 35063 If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the 35064 signal handler the thread resumes waiting for the read-write lock for reading as if it was not 35065 interrupted. 35066 RETURN VALUE 35067 If successful, the pthread_rwlock_rdlock( ) function shall return zero; otherwise, an error number 35068 shall be returned to indicate the error. 35069 The pthread_rwlock_tryrdlock( ) function shall return zero if the lock for reading on the read-write 35070 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned to 35071 indicate the error. System Interfaces, Issue 6 1605 pthread_rwlock_rdlock( ) System Interfaces 35072 ERRORS 35073 The pthread_rwlock_tryrdlock( ) function shall fail if: 35074 [EBUSY] The read-write lock could not be acquired for reading because a writer holds 35075 the lock or a writer with the appropriate priority was blocked on it. 35076 The pthread_rwlock_rdlock( ) and pthread_rwlock_tryrdlock( ) functions may fail if: 35077 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35078 object. 35079 [EAGAIN] The read lock could not be acquired because the maximum number of read 35080 locks for rwlock has been exceeded. 35081 The pthread_rwlock_rdlock( ) function may fail if: 35082 [EDEADLK] The current thread already owns the read-write lock for writing. 35083 These functions shall not return an error code of [EINTR]. 35084 EXAMPLES 35085 None. 35086 APPLICATION USAGE 35087 Applications using these functions may be subject to priority inversion, as discussed in the Base 35088 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 35089 RATIONALE 35090 None. 35091 FUTURE DIRECTIONS 35092 None. 35093 SEE ALSO 35094 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_timedrdlock( ), 35095 pthread_rwlock_timedwrlock( ), pthread_rwlock_trywrlock( ), pthread_rwlock_unlock( ), 35096 pthread_rwlock_wrlock( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35097 CHANGE HISTORY 35098 First released in Issue 5. 35099 Issue 6 35100 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35101 * The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35102 now part of the Threads option (previously it was part of the Read-Write Locks option in 35103 IEEE Std 1003.1j-2000 and also part of the XSI extension). 35104 * The DESCRIPTION is updated as follows: 35105 - Conditions under which writers have precedence over readers are specified. 35106 - Failure of pthread_rwlock_tryrdlock( ) is clarified. 35107 - A paragraph on the maximum number of read locks is added. 35108 * In the ERRORS sections, [EBUSY] is modified to take into account write priority, and 35109 [EDEADLK] is deleted as a pthread_rwlock_tryrdlock( ) error. 35110 * The SEE ALSO section is updated. 1606 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_timedrdlock( ) 35111 NAME 35112 pthread_rwlock_timedrdlock - lock a read-write lock for reading 35113 SYNOPSIS 35114 THR TMO #include 35115 #include 35116 int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict rwlock, 35117 const struct timespec *restrict abs_timeout); 35118 35119 DESCRIPTION 35120 The pthread_rwlock_timedrdlock( ) function shall apply a read lock to the read-write lock 35121 referenced by rwlock as in the pthread_rwlock_rdlock( ) function. However, if the lock cannot be 35122 acquired without waiting for other threads to unlock the lock, this wait shall be terminated 35123 when the specified timeout expires. The timeout shall expire when the absolute time specified | 35124 by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the | 35125 value of that clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout 35126 has already been passed at the time of the call. 35127 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock. If | 35128 the Timers option is not supported, the timeout shall be based on the system clock as returned | 35129 by the time( ) function. The resolution of the timeout shall be the resolution of the clock on which | 35130 it is based. The timespec data type is defined in the header. Under no circumstances | 35131 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 35132 abs_timeout parameter need not be checked if the lock can be immediately acquired. 35133 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a read- 35134 write lock via a call to pthread_rwlock_timedrdlock( ), upon return from the signal handler the 35135 thread shall resume waiting for the lock as if it was not interrupted. 35136 The calling thread may deadlock if at the time the call is made it holds a write lock on rwlock. 35137 The results are undefined if this function is called with an uninitialized read-write lock. 35138 RETURN VALUE 35139 The pthread_rwlock_timedrdlock( ) function shall return zero if the lock for reading on the read- 35140 write lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned 35141 to indicate the error. 35142 ERRORS 35143 The pthread_rwlock_timedrdlock( ) function shall fail if: 35144 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired. 35145 The pthread_rwlock_timedrdlock( ) function may fail if: 35146 [EAGAIN] The read lock could not be acquired because the maximum number of read 35147 locks for lock would be exceeded. 35148 [EDEADLK] The calling thread already holds a write lock on rwlock. 35149 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35150 object, or the abs_timeout nanosecond value is less than zero or greater than or 35151 equal to 1 000 million. 35152 This function shall not return an error code of [EINTR]. System Interfaces, Issue 6 1607 pthread_rwlock_timedrdlock( ) System Interfaces 35153 EXAMPLES 35154 None. 35155 APPLICATION USAGE 35156 Applications using this function may be subject to priority inversion, as discussed in the Base 35157 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 35158 The pthread_rwlock_timedrdlock( ) function is part of the Threads and Timeouts options and need 35159 not be provided on all implementations. 35160 RATIONALE 35161 None. 35162 FUTURE DIRECTIONS 35163 None. 35164 SEE ALSO 35165 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 35166 pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), pthread_rwlock_trywrlock( ), 35167 pthread_rwlock_unlock( ), pthread_rwlock_wrlock( ), the Base Definitions volume of 35168 IEEE Std 1003.1-200x, , 35169 CHANGE HISTORY 35170 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 1608 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_timedwrlock( ) 35171 NAME 35172 pthread_rwlock_timedwrlock - lock a read-write lock for writing 35173 SYNOPSIS 35174 THR TMO #include 35175 #include 35176 int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict rwlock, 35177 const struct timespec *restrict abs_timeout); 35178 35179 DESCRIPTION 35180 The pthread_rwlock_timedwrlock( ) function shall apply a write lock to the read-write lock 35181 referenced by rwlock as in the pthread_rwlock_wrlock( ) function. However, if the lock cannot be 35182 acquired without waiting for other threads to unlock the lock, this wait shall be terminated 35183 when the specified timeout expires. The timeout shall expire when the absolute time specified | 35184 by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the | 35185 value of that clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout 35186 has already been passed at the time of the call. 35187 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock. If | 35188 the Timers option is not supported, the timeout shall be based on the system clock as returned | 35189 by the time( ) function. The resolution of the timeout shall be the resolution of the clock on which | 35190 it is based. The timespec data type is defined in the header. Under no circumstances | 35191 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 35192 abs_timeout parameter need not be checked if the lock can be immediately acquired. 35193 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a read- 35194 write lock via a call to pthread_rwlock_timedwrlock( ), upon return from the signal handler the 35195 thread shall resume waiting for the lock as if it was not interrupted. 35196 The calling thread may deadlock if at the time the call is made it holds the read-write lock. The 35197 results are undefined if this function is called with an uninitialized read-write lock. 35198 RETURN VALUE 35199 The pthread_rwlock_timedwrlock( ) function shall return zero if the lock for writing on the read- 35200 write lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned 35201 to indicate the error. 35202 ERRORS 35203 The pthread_rwlock_timedwrlock( ) function shall fail if: 35204 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired. 35205 The pthread_rwlock_timedwrlock( ) function may fail if: 35206 [EDEADLK] The calling thread already holds the rwlock. 35207 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35208 object, or the abs_timeout nanosecond value is less than zero or greater than or 35209 equal to 1 000 million. 35210 This function shall not return an error code of [EINTR]. System Interfaces, Issue 6 1609 pthread_rwlock_timedwrlock( ) System Interfaces 35211 EXAMPLES 35212 None. 35213 APPLICATION USAGE 35214 Applications using this function may be subject to priority inversion, as discussed in the Base 35215 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 35216 The pthread_rwlock_timedwrlock( ) function is part of the Threads and Timeouts options and need 35217 not be provided on all implementations. 35218 RATIONALE 35219 None. 35220 FUTURE DIRECTIONS 35221 None. 35222 SEE ALSO 35223 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 35224 pthread_rwlock_timedrdlock( ), pthread_rwlock_tryrdlock( ), pthread_rwlock_trywrlock( ), 35225 pthread_rwlock_unlock( ), pthread_rwlock_wrlock( ), the Base Definitions volume of 35226 IEEE Std 1003.1-200x, , 35227 CHANGE HISTORY 35228 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 1610 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_tryrdlock( ) 35229 NAME 35230 pthread_rwlock_tryrdlock - lock a read-write lock object for reading 35231 SYNOPSIS 35232 THR #include 35233 int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); 35234 35235 DESCRIPTION 35236 Refer to pthread_rwlock_rdlock( ). System Interfaces, Issue 6 1611 pthread_rwlock_trywrlock( ) System Interfaces 35237 NAME 35238 pthread_rwlock_trywrlock, pthread_rwlock_wrlock - lock a read-write lock object for writing 35239 SYNOPSIS 35240 THR #include 35241 int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); 35242 int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); 35243 35244 DESCRIPTION 35245 The pthread_rwlock_trywrlock( ) function shall apply a write lock like the pthread_rwlock_wrlock( ) 35246 function, with the exception that the function shall fail if any thread currently holds rwlock (for 35247 reading or writing). 35248 The pthread_rwlock_wrlock( ) function shall apply a write lock to the read-write lock referenced 35249 by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds 35250 the read-write lock rwlock. Otherwise, the thread shall block until it can acquire the lock. The | 35251 calling thread may deadlock if at the time the call is made it holds the read-write lock (whether a | 35252 read or write lock). | 35253 Implementations may favor writers over readers to avoid writer starvation. | 35254 Results are undefined if any of these functions are called with an uninitialized read-write lock. 35255 If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the 35256 signal handler the thread resumes waiting for the read-write lock for writing as if it was not 35257 interrupted. 35258 RETURN VALUE 35259 The pthread_rwlock_trywrlock( ) function shall return zero if the lock for writing on the read-write 35260 lock object referenced by rwlock is acquired. Otherwise, an error number shall be returned to 35261 indicate the error. 35262 If successful, the pthread_rwlock_wrlock( ) function shall return zero; otherwise, an error number 35263 shall be returned to indicate the error. 35264 ERRORS 35265 The pthread_rwlock_trywrlock( ) function shall fail if: 35266 [EBUSY] The read-write lock could not be acquired for writing because it was already 35267 locked for reading or writing. 35268 The pthread_rwlock_trywrlock( ) and pthread_rwlock_wrlock( ) functions may fail if: 35269 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35270 object. 35271 The pthread_rwlock_wrlock( ) function may fail if: 35272 [EDEADLK] The current thread already owns the read-write lock for writing or reading. 35273 These functions shall not return an error code of [EINTR]. 1612 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_trywrlock( ) 35274 EXAMPLES 35275 None. 35276 APPLICATION USAGE 35277 Applications using these functions may be subject to priority inversion, as discussed in the Base 35278 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 35279 RATIONALE 35280 None. 35281 FUTURE DIRECTIONS 35282 None. 35283 SEE ALSO 35284 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 35285 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), 35286 pthread_rwlock_unlock( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35287 CHANGE HISTORY 35288 First released in Issue 5. 35289 Issue 6 35290 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35291 * The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35292 now part of the Threads option (previously it was part of the Read-Write Locks option in 35293 IEEE Std 1003.1j-2000 and also part of the XSI extension). 35294 * The [EDEADLK] error is deleted as a pthread_rwlock_trywrlock( ) error. 35295 * The SEE ALSO section is updated. System Interfaces, Issue 6 1613 pthread_rwlock_unlock( ) System Interfaces 35296 NAME 35297 pthread_rwlock_unlock - unlock a read-write lock object 35298 SYNOPSIS 35299 THR #include 35300 int pthread_rwlock_unlock(pthread_rwlock_t *rwlock); 35301 35302 DESCRIPTION 35303 The pthread_rwlock_unlock( ) function shall release a lock held on the read-write lock object | 35304 referenced by rwlock. Results are undefined if the read-write lock rwlock is not held by the 35305 calling thread. 35306 If this function is called to release a read lock from the read-write lock object and there are other 35307 read locks currently held on this read-write lock object, the read-write lock object remains in the 35308 read locked state. If this function releases the last read lock for this read-write lock object, the 35309 read-write lock object shall be put in the unlocked state with no owners. 35310 If this function is called to release a write lock for this read-write lock object, the read-write lock 35311 object shall be put in the unlocked state. 35312 If there are threads blocked on the lock when it becomes available, the scheduling policy shall | 35313 TPS determine which thread(s) shall acquire the lock. If the Thread Execution Scheduling option is | 35314 supported, when threads executing with the scheduling policies SCHED_FIFO, SCHED_RR, or | 35315 SCHED_SPORADIC are waiting on the lock, they shall acquire the lock in priority order when | 35316 the lock becomes available. For equal priority threads, write locks shall take precedence over | 35317 read locks. If the Thread Execution Scheduling option is not supported, it is implementation- | 35318 defined whether write locks take precedence over read locks. 35319 Results are undefined if any of these functions are called with an uninitialized read-write lock. 35320 RETURN VALUE 35321 If successful, the pthread_rwlock_unlock( ) function shall return zero; otherwise, an error number 35322 shall be returned to indicate the error. 35323 ERRORS 35324 The pthread_rwlock_unlock( ) function may fail if: 35325 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 35326 object. 35327 [EPERM] The current thread does not hold a lock on the read-write lock. 35328 The pthread_rwlock_unlock( ) function shall not return an error code of [EINTR]. 35329 EXAMPLES 35330 None. 35331 APPLICATION USAGE 35332 None. 35333 RATIONALE 35334 None. 35335 FUTURE DIRECTIONS 35336 None. 1614 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlock_unlock( ) 35337 SEE ALSO 35338 pthread_rwlock_destroy( ), pthread_rwlock_init( ), pthread_rwlock_rdlock( ), 35339 pthread_rwlock_timedrdlock( ), pthread_rwlock_timedwrlock( ), pthread_rwlock_tryrdlock( ), 35340 pthread_rwlock_trywrlock( ), pthread_rwlock_wrlock( ), the Base Definitions volume of 35341 IEEE Std 1003.1-200x, 35342 CHANGE HISTORY 35343 First released in Issue 5. 35344 Issue 6 35345 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35346 * The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35347 now part of the Threads option (previously it was part of the Read-Write Locks option in 35348 IEEE Std 1003.1j-2000 and also part of the XSI extension). 35349 * The DESCRIPTION is updated as follows: 35350 - The conditions under which writers have precedence over readers are specified. 35351 - The concept of read-write lock owner is deleted. 35352 * The SEE ALSO section is updated. System Interfaces, Issue 6 1615 pthread_rwlock_wrlock( ) System Interfaces 35353 NAME 35354 pthread_rwlock_wrlock - lock a read-write lock object for writing 35355 SYNOPSIS 35356 THR #include 35357 int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); 35358 35359 DESCRIPTION 35360 Refer to pthread_rwlock_trywrlock( ). 1616 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlockattr_destroy( ) 35361 NAME 35362 pthread_rwlockattr_destroy, pthread_rwlockattr_init - destroy and initialize read-write lock 35363 attributes object 35364 SYNOPSIS 35365 THR #include 35366 int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); 35367 int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); 35368 35369 DESCRIPTION 35370 The pthread_rwlockattr_destroy( ) function shall destroy a read-write lock attributes object. A | 35371 destroyed attr attributes object can be reinitialized using pthread_rwlockattr_init( ); the results of | 35372 otherwise referencing the object after it has been destroyed are undefined. An implementation | 35373 may cause pthread_rwlockattr_destroy( ) to set the object referenced by attr to an invalid value. | 35374 The pthread_rwlockattr_init( ) function shall initialize a read-write lock attributes object attr with 35375 the default value for all of the attributes defined by the implementation. 35376 Results are undefined if pthread_rwlockattr_init( ) is called specifying an already initialized attr | 35377 attributes object. | 35378 After a read-write lock attributes object has been used to initialize one or more read-write locks, 35379 any function affecting the attributes object (including destruction) shall not affect any previously | 35380 initialized read-write locks. 35381 RETURN VALUE 35382 If successful, the pthread_rwlockattr_destroy( ) and pthread_rwlockattr_init( ) functions shall return 35383 zero; otherwise, an error number shall be returned to indicate the error. 35384 ERRORS 35385 The pthread_rwlockattr_destroy( ) function may fail if: 35386 [EINVAL] The value specified by attr is invalid. 35387 The pthread_rwlockattr_init( ) function shall fail if: 35388 [ENOMEM] Insufficient memory exists to initialize the read-write lock attributes object. 35389 These functions shall not return an error code of [EINTR]. 35390 EXAMPLES 35391 None. 35392 APPLICATION USAGE 35393 None. 35394 RATIONALE 35395 None. 35396 FUTURE DIRECTIONS 35397 None. 35398 SEE ALSO 35399 pthread_rwlock_init( ), pthread_rwlockattr_getpshared( ), pthread_rwlockattr_setpshared( ), the Base 35400 Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1617 pthread_rwlockattr_destroy( ) System Interfaces 35401 CHANGE HISTORY 35402 First released in Issue 5. 35403 Issue 6 35404 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35405 * The margin code in the SYNOPSIS is changed to THR to indicate that the functionality is 35406 now part of the Threads option (previously it was part of the Read-Write Locks option in 35407 IEEE Std 1003.1j-2000 and also part of the XSI extension). 35408 * The SEE ALSO section is updated. 1618 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlockattr_getpshared( ) 35409 NAME 35410 pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared - get and set process-shared 35411 attribute of read-write lock attributes object 35412 SYNOPSIS 35413 THR TSH #include 35414 int pthread_rwlockattr_getpshared( 35415 const pthread_rwlockattr_t *restrict attr, 35416 int *restrict pshared); 35417 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, 35418 int pshared); 35419 35420 DESCRIPTION 35421 The pthread_rwlockattr_getpshared( ) function shall obtain the value of the process-shared attribute 35422 from the initialized attributes object referenced by attr. The pthread_rwlockattr_setpshared( ) | 35423 function shall set the process-shared attribute in an initialized attributes object referenced by attr. | 35424 The process-shared attribute shall be set to PTHREAD_PROCESS_SHARED to permit a read- 35425 write lock to be operated upon by any thread that has access to the memory where the read- 35426 write lock is allocated, even if the read-write lock is allocated in memory that is shared by 35427 multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the read- 35428 write lock shall only be operated upon by threads created within the same process as the thread 35429 that initialized the read-write lock; if threads of differing processes attempt to operate on such a 35430 read-write lock, the behavior is undefined. The default value of the process-shared attribute shall 35431 be PTHREAD_PROCESS_PRIVATE. 35432 Additional attributes, their default values, and the names of the associated functions to get and 35433 set those attribute values are implementation-defined. 35434 RETURN VALUE 35435 Upon successful completion, the pthread_rwlockattr_getpshared( ) shall return zero and store the 35436 value of the process-shared attribute of attr into the object referenced by the pshared parameter. 35437 Otherwise, an error number shall be returned to indicate the error. 35438 If successful, the pthread_rwlockattr_setpshared( ) function shall return zero; otherwise, an error 35439 number shall be returned to indicate the error. 35440 ERRORS 35441 The pthread_rwlockattr_getpshared( ) and pthread_rwlockattr_setpshared( ) functions may fail if: 35442 [EINVAL] The value specified by attr is invalid. 35443 The pthread_rwlockattr_setpshared( ) function may fail if: 35444 [EINVAL] The new value specified for the attribute is outside the range of legal values 35445 for that attribute. 35446 These functions shall not return an error code of [EINTR]. System Interfaces, Issue 6 1619 pthread_rwlockattr_getpshared( ) System Interfaces 35447 EXAMPLES 35448 None. 35449 APPLICATION USAGE 35450 None. 35451 RATIONALE 35452 None. 35453 FUTURE DIRECTIONS 35454 None. 35455 SEE ALSO 35456 pthread_rwlock_init( ), pthread_rwlockattr_destroy( ), pthread_rwlockattr_init( ), the Base Definitions 35457 volume of IEEE Std 1003.1-200x, 35458 CHANGE HISTORY 35459 First released in Issue 5. 35460 Issue 6 35461 The following changes are made for alignment with IEEE Std 1003.1j-2000: 35462 * The margin code in the SYNOPSIS is changed to THR TSH to indicate that the functionality 35463 is now part of the Threads option (previously it was part of the Read-Write Locks option in 35464 IEEE Std 1003.1j-2000 and also part of the XSI extension). 35465 * The DESCRIPTION notes that additional attributes are implementation-defined. 35466 * The SEE ALSO section is updated. 35467 The restrict keyword is added to the pthread_rwlockattr_getpshared( ) prototype for alignment 35468 with the ISO/IEC 9899: 1999 standard. 1620 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_rwlockattr_init( ) 35469 NAME 35470 pthread_rwlockattr_init - initialize read-write lock attributes object 35471 SYNOPSIS 35472 XSI #include 35473 int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); 35474 35475 DESCRIPTION 35476 Refer to pthread_rwlockattr_destroy( ). System Interfaces, Issue 6 1621 pthread_rwlockattr_setpshared( ) System Interfaces 35477 NAME 35478 pthread_rwlockattr_setpshared - set process-shared attribute of read-write lock attributes 35479 object 35480 SYNOPSIS 35481 XSI #include 35482 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, 35483 int pshared); 35484 35485 DESCRIPTION 35486 Refer to pthread_rwlockattr_getpshared( ). 1622 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_self( ) 35487 NAME 35488 pthread_self - get calling thread's ID 35489 SYNOPSIS 35490 THR #include 35491 pthread_t pthread_self(void); 35492 35493 DESCRIPTION 35494 The pthread_self( ) function shall return the thread ID of the calling thread. 35495 RETURN VALUE 35496 Refer to the DESCRIPTION. 35497 ERRORS 35498 No errors are defined. 35499 The pthread_self( ) function shall not return an error code of [EINTR]. 35500 EXAMPLES 35501 None. 35502 APPLICATION USAGE 35503 None. 35504 RATIONALE 35505 The pthread_self( ) function provides a capability similar to the getpid( ) function for processes 35506 and the rationale is the same: the creation call does not provide the thread ID to the created 35507 thread. 35508 FUTURE DIRECTIONS 35509 None. 35510 SEE ALSO 35511 pthread_create( ), pthread_equal( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35512 35513 CHANGE HISTORY 35514 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 35515 Issue 6 35516 The pthread_self( ) function is marked as part of the Threads option. System Interfaces, Issue 6 1623 pthread_setcancelstate( ) System Interfaces 35517 NAME 35518 pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel - set cancelability state 35519 SYNOPSIS 35520 THR #include 35521 int pthread_setcancelstate(int state, int *oldstate); 35522 int pthread_setcanceltype(int type, int *oldtype); 35523 void pthread_testcancel(void); 35524 35525 DESCRIPTION 35526 The pthread_setcancelstate( ) function shall atomically both set the calling thread's cancelability 35527 state to the indicated state and return the previous cancelability state at the location referenced 35528 by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and 35529 PTHREAD_CANCEL_DISABLE. 35530 The pthread_setcanceltype( ) function shall atomically both set the calling thread's cancelability 35531 type to the indicated type and return the previous cancelability type at the location referenced by 35532 oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and 35533 PTHREAD_CANCEL_ASYNCHRONOUS. 35534 The cancelability state and type of any newly created threads, including the thread in which 35535 main( ) was first invoked, shall be PTHREAD_CANCEL_ENABLE and 35536 PTHREAD_CANCEL_DEFERRED respectively. 35537 The pthread_testcancel( ) function shall create a cancelation point in the calling thread. The 35538 pthread_testcancel( ) function shall have no effect if cancelability is disabled. 35539 RETURN VALUE 35540 If successful, the pthread_setcancelstate( ) and pthread_setcanceltype( ) functions shall return zero; 35541 otherwise, an error number shall be returned to indicate the error. 35542 ERRORS 35543 The pthread_setcancelstate( ) function may fail if: 35544 [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or 35545 PTHREAD_CANCEL_DISABLE. 35546 The pthread_setcanceltype( ) function may fail if: 35547 [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or 35548 PTHREAD_CANCEL_ASYNCHRONOUS. 35549 These functions shall not return an error code of [EINTR]. 35550 EXAMPLES 35551 None. 35552 APPLICATION USAGE 35553 None. 35554 RATIONALE 35555 The pthread_setcancelstate( ) and pthread_setcanceltype( ) functions control the points at which a | 35556 thread may be asynchronously canceled. For cancelation control to be usable in modular fashion, | 35557 some rules need to be followed. 35558 An object can be considered to be a generalization of a procedure. It is a set of procedures and 35559 global variables written as a unit and called by clients not known by the object. Objects may 35560 depend on other objects. 1624 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_setcancelstate( ) 35561 First, cancelability should only be disabled on entry to an object, never explicitly enabled. On 35562 exit from an object, the cancelability state should always be restored to its value on entry to the 35563 object. 35564 This follows from a modularity argument: if the client of an object (or the client of an object that 35565 uses that object) has disabled cancelability, it is because the client does not want to be concerned 35566 about cleaning up if the thread is canceled while executing some sequence of actions. If an object 35567 is called in such a state and it enables cancelability and a cancelation request is pending for that 35568 thread, then the thread is canceled, contrary to the wish of the client that disabled. 35569 Second, the cancelability type may be explicitly set to either deferred or asynchronous upon entry 35570 to an object. But as with the cancelability state, on exit from an object the cancelability type 35571 should always be restored to its value on entry to the object. 35572 Finally, only functions that are cancel-safe may be called from a thread that is asynchronously 35573 cancelable. 35574 FUTURE DIRECTIONS 35575 None. 35576 SEE ALSO 35577 pthread_cancel( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35578 CHANGE HISTORY 35579 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 35580 Issue 6 35581 The pthread_setcancelstate( ), pthread_setcanceltype( ), and pthread_testcancel( ) functions are marked 35582 as part of the Threads option. System Interfaces, Issue 6 1625 pthread_setconcurrency( ) System Interfaces 35583 NAME 35584 pthread_setconcurrency - set level of concurrency 35585 SYNOPSIS 35586 XSI #include 35587 int pthread_setconcurrency(int new_level); 35588 35589 DESCRIPTION 35590 Refer to pthread_getconcurrency( ). 1626 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_setschedparam( ) 35591 NAME 35592 pthread_setschedparam - dynamic thread scheduling parameters access (REALTIME 35593 THREADS) 35594 SYNOPSIS 35595 THR TPS #include 35596 int pthread_setschedparam(pthread_t thread, int policy, 35597 const struct sched_param *param); 35598 35599 DESCRIPTION | 35600 Refer to pthread_getschedparam( ). System Interfaces, Issue 6 1627 pthread_setschedprio( ) System Interfaces 35601 NAME | 35602 pthread_setschedprio - dynamic thread scheduling parameters access (REALTIME | 35603 THREADS) | 35604 SYNOPSIS | 35605 THR TPS #include | 35606 int pthread_setschedprio(pthread_t thread, int prio); | 35607 | 35608 DESCRIPTION | 35609 The pthread_setschedprio( ) function shall set the scheduling priority for the thread whose thread | 35610 ID is given by thread to the value given by prio. See Scheduling Policies (on page 494) for a | 35611 description on how this function call affects the ordering of the thread in the thread list for its | 35612 new priority. | 35613 If the pthread_setschedprio( ) function fails, the scheduling priority of the target thread shall not be | 35614 changed. | 35615 RETURN VALUE | 35616 If successful, the pthread_setschedprio( ) function shall return zero; otherwise, an error number | 35617 shall be returned to indicate the error. | 35618 ERRORS | 35619 The pthread_setschedprio( ) function may fail if: | 35620 [EINVAL] The value of prio is invalid for the scheduling policy of the specified thread. | 35621 [ENOTSUP] An attempt was made to set the priority to an unsupported value. | 35622 [EPERM] The caller does not have the appropriate permission to set the scheduling | 35623 policy of the specified thread. | 35624 [EPERM] The implementation does not allow the application to modify the priority to | 35625 the value specified. | 35626 [ESRCH] The value specified by thread does not refer to an existing thread. | 35627 The pthread_setschedprio( ) function shall not return an error code of [EINTR]. | 35628 EXAMPLES | 35629 None. | 35630 APPLICATION USAGE | 35631 None. | 35632 RATIONALE | 35633 The pthread_setschedprio( ) function provides a way for an application to temporarily raise its | 35634 priority and then lower it again, without having the undesired side effect of yielding to other | 35635 threads of the same priority. This is necessary if the application is to implement its own | 35636 strategies for bounding priority inversion, such as priority inheritance or priority ceilings. This | 35637 capability is especially important if the implementation does not support the Thread Priority | 35638 Protection or Thread Priority Inheritance options, but even if those options are supported it is | 35639 needed if the application is to bound priority inheritance for other resources, such as | 35640 semaphores. | 35641 The standard developers considered that while it might be preferable conceptually to solve this | 35642 problem by modifying the specification of pthread_setschedparam( ), it was too late to make such a | 35643 change, as there may be implementations that would need to be changed. Therefore, this new | 35644 function was introduced. | 1628 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_setschedprio( ) 35645 FUTURE DIRECTIONS | 35646 None. | 35647 SEE ALSO | 35648 pthread_getschedparam( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 35649 CHANGE HISTORY || 35650 First released in Issue 6. Included as a response to IEEE PASC Interpretation 1003.1 #96. | System Interfaces, Issue 6 1629 pthread_setspecific( ) System Interfaces 35651 NAME 35652 pthread_setspecific - thread-specific data management 35653 SYNOPSIS 35654 THR #include 35655 int pthread_setspecific(pthread_key_t key, const void *value); 35656 35657 DESCRIPTION 35658 Refer to pthread_getspecific( ). 1630 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_sigmask( ) 35659 NAME 35660 pthread_sigmask, sigprocmask - examine and change blocked signals 35661 SYNOPSIS 35662 #include 35663 THR int pthread_sigmask(int how, const sigset_t *restrict set, 35664 sigset_t *restrict oset); 35665 CX int sigprocmask(int how, const sigset_t *restrict set, | 35666 sigset_t *restrict oset); 35667 | 35668 DESCRIPTION 35669 THR The pthread_sigmask( ) function shall examine or change (or both) the calling thread's signal | 35670 mask, regardless of the number of threads in the process. The function shall be equivalent to 35671 sigprocmask( ), without the restriction that the call be made in a single-threaded process. 35672 In a single-threaded process, the sigprocmask( ) function shall examine or change (or both) the | 35673 signal mask of the calling thread. | 35674 If the argument set is not a null pointer, it points to a set of signals to be used to change the 35675 currently blocked set. 35676 The argument how indicates the way in which the set is changed, and the application shall 35677 ensure it consists of one of the following values: 35678 SIG_BLOCK The resulting set shall be the union of the current set and the signal set 35679 pointed to by set. 35680 SIG_SETMASK The resulting set shall be the signal set pointed to by set. 35681 SIG_UNBLOCK The resulting set shall be the intersection of the current set and the 35682 complement of the signal set pointed to by set. 35683 If the argument oset is not a null pointer, the previous mask shall be stored in the location | 35684 pointed to by oset. If set is a null pointer, the value of the argument how is not significant and the | 35685 process' signal mask shall be unchanged; thus the call can be used to enquire about currently | 35686 blocked signals. | 35687 If there are any pending unblocked signals after the call to sigprocmask( ), at least one of those 35688 signals shall be delivered before the call to sigprocmask( ) returns. 35689 It is not possible to block those signals which cannot be ignored. This shall be enforced by the 35690 system without causing an error to be indicated. 35691 If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS signals are generated while they are blocked, 35692 the result is undefined, unless the signal was generated by the kill( ) function, the sigqueue( ) 35693 function, or the raise( ) function. 35694 If sigprocmask( ) fails, the thread's signal mask shall not be changed. | 35695 The use of the sigprocmask( ) function is unspecified in a multi-threaded process. 35696 RETURN VALUE 35697 THR Upon successful completion pthread_sigmask( ) shall return 0; otherwise, it shall return the 35698 corresponding error number. 35699 Upon successful completion, sigprocmask( ) shall return 0; otherwise, -1 shall be returned, errno 35700 shall be set to indicate the error, and the process' signal mask shall be unchanged. System Interfaces, Issue 6 1631 pthread_sigmask( ) System Interfaces 35701 ERRORS 35702 THR The pthread_sigmask( )and sigprocmask( ) functions shall fail if: 35703 [EINVAL] The value of the how argument is not equal to one of the defined values. 35704 THR The pthread_sigmask( ) function shall not return an error code of [EINTR]. 35705 EXAMPLES 35706 None. 35707 APPLICATION USAGE 35708 None. 35709 RATIONALE 35710 When a process' signal mask is changed in a signal-catching function that is installed by 35711 sigaction( ), the restoration of the signal mask on return from the signal-catching function 35712 overrides that change (see sigaction( )). If the signal-catching function was installed with 35713 signal( ), it is unspecified whether this occurs. 35714 See kill( ) for a discussion of the requirement on delivery of signals. 35715 FUTURE DIRECTIONS 35716 None. 35717 SEE ALSO 35718 sigaction( ), sigaddset( ), sigdelset( ), sigemptyset( ), sigfillset( ), sigismember( ), sigpending( ), 35719 sigqueue( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35720 CHANGE HISTORY 35721 First released in Issue 3. 35722 Entry included for alignment with the POSIX.1-1988 standard. 35723 Issue 5 35724 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 35725 The pthread_sigmask( ) function is added for alignment with the POSIX Threads Extension. 35726 Issue 6 35727 The pthread_sigmask( ) function is marked as part of the Threads option. 35728 The SYNOPSIS for sigprocmask( ) is marked as a CX extension to note that the presence of this | 35729 function in the header is an extension to the ISO C standard. | 35730 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: | 35731 * The DESCRIPTION is updated to explicitly state the functions which may generate the 35732 signal. 35733 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 35734 The restrict keyword is added to the pthread_sigmask( ) and sigprocmask( ) prototypes for 35735 alignment with the ISO/IEC 9899: 1999 standard. 1632 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_spin_destroy( ) 35736 NAME 35737 pthread_spin_destroy, pthread_spin_init - destroy or initialize a spin lock object (ADVANCED 35738 REALTIME THREADS) 35739 SYNOPSIS 35740 THR SPI #include 35741 int pthread_spin_destroy(pthread_spinlock_t *lock); 35742 int pthread_spin_init(pthread_spinlock_t *lock, int pshared); 35743 35744 DESCRIPTION 35745 The pthread_spin_destroy( ) function shall destroy the spin lock referenced by lock and release any 35746 resources used by the lock. The effect of subsequent use of the lock is undefined until the lock is 35747 reinitialized by another call to pthread_spin_init( ). The results are undefined if 35748 pthread_spin_destroy( ) is called when a thread holds the lock, or if this function is called with an 35749 uninitialized thread spin lock. 35750 The pthread_spin_init( ) function shall allocate any resources required to use the spin lock 35751 referenced by lock and initialize the lock to an unlocked state. 35752 TSH If the Thread Process-Shared Synchronization option is supported and the value of pshared is 35753 PTHREAD_PROCESS_SHARED, the implementation shall permit the spin lock to be operated 35754 upon by any thread that has access to the memory where the spin lock is allocated, even if it is 35755 allocated in memory that is shared by multiple processes. 35756 If the Thread Process-Shared Synchronization option is supported and the value of pshared is 35757 PTHREAD_PROCESS_PRIVATE, or if the option is not supported, the spin lock shall only be 35758 operated upon by threads created within the same process as the thread that initialized the spin 35759 lock. If threads of differing processes attempt to operate on such a spin lock, the behavior is 35760 undefined. 35761 The results are undefined if pthread_spin_init( ) is called specifying an already initialized spin 35762 lock. The results are undefined if a spin lock is used without first being initialized. 35763 If the pthread_spin_init( ) function fails, the lock is not initialized and the contents of lock are 35764 undefined. 35765 Only the object referenced by lock may be used for performing synchronization. 35766 The result of referring to copies of that object in calls to pthread_spin_destroy( ), 35767 pthread_spin_lock( ), pthread_spin_trylock( ), or pthread_spin_unlock( ) is undefined. 35768 RETURN VALUE 35769 Upon successful completion, these functions shall return zero; otherwise, an error number shall 35770 be returned to indicate the error. 35771 ERRORS 35772 These functions may fail if: 35773 [EBUSY] The implementation has detected an attempt to initialize or destroy a spin 35774 lock while it is in use (for example, while being used in a pthread_spin_lock( ) 35775 call) by another thread. 35776 [EINVAL] The value specified by lock is invalid. 35777 The pthread_spin_init( ) function shall fail if: 35778 [EAGAIN] The system lacks the necessary resources to initialize another spin lock. System Interfaces, Issue 6 1633 pthread_spin_destroy( ) System Interfaces 35779 [ENOMEM] Insufficient memory exists to initialize the lock. 35780 These functions shall not return an error code of [EINTR]. 35781 EXAMPLES 35782 None. 35783 APPLICATION USAGE 35784 The pthread_spin_destroy( ) and pthread_spin_init( ) functions are part of the Spin Locks option 35785 and need not be provided on all implementations. 35786 RATIONALE 35787 None. 35788 FUTURE DIRECTIONS 35789 None. 35790 SEE ALSO 35791 pthread_spin_lock( ), pthread_spin_trylock( ), pthread_spin_unlock( ), the Base Definitions volume of 35792 IEEE Std 1003.1-200x, <> 35793 CHANGE HISTORY 35794 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 35795 In the SYNOPSIS, the inclusion of is no longer required. 1634 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_spin_init( ) 35796 NAME 35797 pthread_spin_init - initialize a spin lock object (ADVANCED REALTIME THREADS) 35798 SYNOPSIS 35799 THR SPI #include 35800 int pthread_spin_init(pthread_spinlock_t *lock, int pshared); 35801 35802 DESCRIPTION 35803 Refer to pthread_spin_destroy( ). System Interfaces, Issue 6 1635 pthread_spin_lock( ) System Interfaces 35804 NAME 35805 pthread_spin_lock, pthread_spin_trylock - lock a spin lock object (ADVANCED REALTIME 35806 THREADS) 35807 SYNOPSIS 35808 THR SPI #include 35809 int pthread_spin_lock(pthread_spinlock_t *lock); 35810 int pthread_spin_trylock(pthread_spinlock_t *lock); 35811 35812 DESCRIPTION 35813 The pthread_spin_lock( ) function shall lock the spin lock referenced by lock. The calling thread 35814 shall acquire the lock if it is not held by another thread. Otherwise, the thread shall spin (that is, | 35815 shall not return from the pthread_spin_lock( ) call) until the lock becomes available. The results | 35816 are undefined if the calling thread holds the lock at the time the call is made. The 35817 pthread_spin_trylock( ) function shall lock the spin lock referenced by lock if it is not held by any | 35818 thread. Otherwise, the function shall fail. | 35819 The results are undefined if any of these functions is called with an uninitialized spin lock. 35820 RETURN VALUE 35821 Upon successful completion, these functions shall return zero; otherwise, an error number shall 35822 be returned to indicate the error. 35823 ERRORS 35824 These functions may fail if: 35825 [EINVAL] The value specified by lock does not refer to an initialized spin lock object. 35826 The pthread_spin_lock( ) function may fail if: 35827 [EDEADLK] The calling thread already holds the lock. 35828 The pthread_spin_trylock( ) function shall fail if: 35829 [EBUSY] A thread currently holds the lock. 35830 These functions shall not return an error code of [EINTR]. 35831 EXAMPLES 35832 None. 35833 APPLICATION USAGE 35834 Applications using this function may be subject to priority inversion, as discussed in the Base 35835 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 35836 The pthread_spin_lock( ) and pthread_spin_trylock( ) functions are part of the Spin Locks option 35837 and need not be provided on all implementations. 35838 RATIONALE 35839 None. 35840 FUTURE DIRECTIONS 35841 None. 35842 SEE ALSO 35843 pthread_spin_init( ), pthread_spin_destroy( ), pthread_spin_unlock( ), the Base Definitions volume of 35844 IEEE Std 1003.1-200x, 1636 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_spin_lock( ) 35845 CHANGE HISTORY 35846 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 35847 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1637 pthread_spin_trylock( ) System Interfaces 35848 NAME 35849 pthread_spin_trylock - lock a spin lock object (ADVANCED REALTIME THREADS) 35850 SYNOPSIS 35851 THR SPI #include 35852 int pthread_spin_trylock(pthread_spinlock_t *lock); 35853 35854 DESCRIPTION 35855 Refer to pthread_spin_lock( ). 1638 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pthread_spin_unlock( ) 35856 NAME 35857 pthread_spin_unlock - unlock a spin lock object (ADVANCED REALTIME THREADS) 35858 SYNOPSIS 35859 THR SPI #include 35860 int pthread_spin_unlock(pthread_spinlock_t *lock); 35861 35862 DESCRIPTION 35863 The pthread_spin_unlock( ) function shall release the spin lock referenced by lock which was 35864 locked via the pthread_spin_lock( ) or pthread_spin_trylock( ) functions. The results are undefined if 35865 the lock is not held by the calling thread. If there are threads spinning on the lock when 35866 pthread_spin_unlock( ) is called, the lock becomes available and an unspecified spinning thread 35867 shall acquire the lock. 35868 The results are undefined if this function is called with an uninitialized thread spin lock. 35869 RETURN VALUE 35870 Upon successful completion, the pthread_spin_unlock( ) function shall return zero; otherwise, an 35871 error number shall be returned to indicate the error. 35872 ERRORS 35873 The pthread_spin_unlock( ) function may fail if: 35874 [EINVAL] An invalid argument was specified. 35875 [EPERM] The calling thread does not hold the lock. 35876 This function shall not return an error code of [EINTR]. 35877 EXAMPLES 35878 None. 35879 APPLICATION USAGE 35880 The pthread_spin_unlock( ) function is part of the Spin Locks option and need not be provided on 35881 all implementations. 35882 RATIONALE 35883 None. 35884 FUTURE DIRECTIONS 35885 None. 35886 SEE ALSO 35887 pthread_spin_init( ), pthread_spin_destroy( ), pthread_spin_lock( ), pthread_spin_trylock( ), the Base 35888 Definitions volume of IEEE Std 1003.1-200x, 35889 CHANGE HISTORY 35890 First released in Issue 6. Derived from IEEE Std 1003.1j-2000. 35891 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1639 pthread_testcancel( ) System Interfaces 35892 NAME 35893 pthread_testcancel - set cancelability state 35894 SYNOPSIS 35895 THR #include 35896 void pthread_testcancel(void); 35897 35898 DESCRIPTION 35899 Refer to pthread_setcancelstate( ). 1640 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ptsname( ) 35900 NAME 35901 ptsname - get name of the slave pseudo-terminal device 35902 SYNOPSIS 35903 XSI #include 35904 char *ptsname(int fildes); 35905 35906 DESCRIPTION 35907 The ptsname( ) function shall return the name of the slave pseudo-terminal device associated 35908 with a master pseudo-terminal device. The fildes argument is a file descriptor that refers to the 35909 master device. The ptsname( ) function shall return a pointer to a string containing the pathname | 35910 of the corresponding slave device. 35911 The ptsname( ) function need not be reentrant. A function that is not required to be reentrant is 35912 not required to be thread-safe. 35913 RETURN VALUE 35914 Upon successful completion, ptsname( ) shall return a pointer to a string which is the name of the 35915 pseudo-terminal slave device. Upon failure, ptsname( ) shall return a null pointer. This could 35916 occur if fildes is an invalid file descriptor or if the slave device name does not exist in the file 35917 system. 35918 ERRORS 35919 No errors are defined. 35920 EXAMPLES 35921 None. 35922 APPLICATION USAGE 35923 The value returned may point to a static data area that is overwritten by each call to ptsname( ). 35924 RATIONALE 35925 None. 35926 FUTURE DIRECTIONS 35927 None. 35928 SEE ALSO 35929 grantpt( ), open( ), ttyname( ), unlockpt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35930 35931 CHANGE HISTORY 35932 First released in Issue 4, Version 2. 35933 Issue 5 35934 Moved from X/OPEN UNIX extension to BASE. 35935 A note indicating that this function need not be reentrant is added to the DESCRIPTION. System Interfaces, Issue 6 1641 putc( ) System Interfaces 35936 NAME 35937 putc - put byte on a stream 35938 SYNOPSIS 35939 #include 35940 int putc(int c, FILE *stream); 35941 DESCRIPTION 35942 CX The functionality described on this reference page is aligned with the ISO C standard. Any 35943 conflict between the requirements described here and the ISO C standard is unintentional. This 35944 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 35945 The putc( ) function shall be equivalent to fputc( ), except that if it is implemented as a macro it 35946 may evaluate stream more than once, so the argument should never be an expression with side 35947 effects. 35948 RETURN VALUE 35949 Refer to fputc( ). 35950 ERRORS 35951 Refer to fputc( ). 35952 EXAMPLES 35953 None. 35954 APPLICATION USAGE 35955 Since it may be implemented as a macro, putc( ) may treat a stream argument with side effects | 35956 incorrectly. In particular, putc(c,*f++) does not necessarily work correctly. Therefore, use of this 35957 function is not recommended in such situations; fputc( ) should be used instead. 35958 RATIONALE 35959 None. 35960 FUTURE DIRECTIONS 35961 None. 35962 SEE ALSO 35963 fputc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35964 CHANGE HISTORY 35965 First released in Issue 1. Derived from Issue 1 of the SVID. 1642 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putc_unlocked( ) 35966 NAME 35967 putc_unlocked - stdio with explicit client locking 35968 SYNOPSIS 35969 TSF #include 35970 int putc_unlocked(int c, FILE *stream); 35971 35972 DESCRIPTION 35973 Refer to getc_unlocked( ). System Interfaces, Issue 6 1643 putchar( ) System Interfaces 35974 NAME 35975 putchar - put byte on stdout stream 35976 SYNOPSIS 35977 #include 35978 int putchar(int c); 35979 DESCRIPTION 35980 CX The functionality described on this reference page is aligned with the ISO C standard. Any 35981 conflict between the requirements described here and the ISO C standard is unintentional. This 35982 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 35983 The function call putchar(c) shall be equivalent to putc(c,stdout). 35984 RETURN VALUE 35985 Refer to fputc( ). 35986 ERRORS 35987 Refer to fputc( ). 35988 EXAMPLES 35989 None. 35990 APPLICATION USAGE 35991 None. 35992 RATIONALE 35993 None. 35994 FUTURE DIRECTIONS 35995 None. 35996 SEE ALSO 35997 putc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 35998 CHANGE HISTORY 35999 First released in Issue 1. Derived from Issue 1 of the SVID. 1644 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putchar_unlocked( ) 36000 NAME 36001 putchar_unlocked - stdio with explicit client locking 36002 SYNOPSIS 36003 TSF #include 36004 int putchar_unlocked(int c); 36005 36006 DESCRIPTION 36007 Refer to getc_unlocked( ). System Interfaces, Issue 6 1645 putenv( ) System Interfaces 36008 NAME 36009 putenv - change or add a value to environment 36010 SYNOPSIS 36011 XSI #include 36012 int putenv(char *string); 36013 36014 DESCRIPTION 36015 The putenv( ) function shall use the string argument to set environment variable values. The | 36016 string argument should point to a string of the form "name=value. The putenv( ) function shall | 36017 make the value of the environment variable name equal to value by altering an existing variable | 36018 or creating a new one. In either case, the string pointed to by string shall become part of the | 36019 environment, so altering the string shall change the environment. The space used by string is no | 36020 longer used once a new string-defining name is passed to putenv( ). 36021 The putenv( ) function need not be reentrant. A function that is not required to be reentrant is not 36022 required to be thread-safe. 36023 RETURN VALUE 36024 Upon successful completion, putenv( ) shall return 0; otherwise, it shall return a non-zero value 36025 and set errno to indicate the error. 36026 ERRORS 36027 The putenv( ) function may fail if: 36028 [ENOMEM] Insufficient memory was available. 36029 EXAMPLES 36030 Changing the Value of an Environment Variable 36031 The following example changes the value of the HOME environment variable to the value 36032 /usr/home. 36033 #include 36034 ... 36035 static char *var = "HOME=/usr/home"; 36036 int ret; 36037 ret = putenv(var); 36038 APPLICATION USAGE 36039 The putenv( ) function manipulates the environment pointed to by environ, and can be used in 36040 conjunction with getenv( ). 36041 This routine may use malloc( ) to enlarge the environment. 36042 A potential error is to call putenv( ) with an automatic variable as the argument, then return from 36043 the calling function while string is still part of the environment. 36044 The setenv( ) function is preferred over this function. 36045 RATIONALE 36046 The standard developers noted that putenv( ) is the only function available to add to the | 36047 environment without permitting memory leaks. | 1646 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putenv( ) 36048 FUTURE DIRECTIONS 36049 None. 36050 SEE ALSO 36051 exec, getenv( ), malloc( ), setenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 36052 CHANGE HISTORY 36053 First released in Issue 1. Derived from Issue 1 of the SVID. 36054 Issue 5 36055 The type of the argument to this function is changed from const char * to char *. This was 36056 indicated as a FUTURE DIRECTION in previous issues. 36057 A note indicating that this function need not be reentrant is added to the DESCRIPTION. System Interfaces, Issue 6 1647 putmsg( ) System Interfaces 36058 NAME 36059 putmsg, putpmsg - send a message on a STREAM (STREAMS) 36060 SYNOPSIS 36061 XSR #include 36062 int putmsg(int fildes, const struct strbuf *ctlptr, 36063 const struct strbuf *dataptr, int flags); 36064 int putpmsg(int fildes, const struct strbuf *ctlptr, 36065 const struct strbuf *dataptr, int band, int flags); 36066 36067 DESCRIPTION 36068 The putmsg( ) function shall create a message from a process buffer(s) and send the message to a 36069 STREAMS file. The message may contain either a data part, a control part, or both. The data and 36070 control parts are distinguished by placement in separate buffers, as described below. The 36071 semantics of each part are defined by the STREAMS module that receives the message. 36072 The putpmsg( ) function is equivalent o putmsg( ), except that the process can send messages in | 36073 different priority bands. Except where noted, all requirements on putmsg( ) also pertain to | 36074 putpmsg( ). 36075 The fildes argument specifies a file descriptor referencing an open STREAM. The ctlptr and 36076 dataptr arguments each point to a strbuf structure. 36077 The ctlptr argument points to the structure describing the control part, if any, to be included in 36078 the message. The buf member in the strbuf structure points to the buffer where the control 36079 information resides, and the len member indicates the number of bytes to be sent. The maxlen 36080 member is not used by putmsg( ). In a similar manner, the argument dataptr specifies the data, if 36081 any, to be included in the message. The flags argument indicates what type of message should be 36082 sent and is described further below. 36083 To send the data part of a message, the application shall ensure that dataptr is not a null pointer 36084 and the len member of dataptr is 0 or greater. To send the control part of a message, the 36085 application shall ensure that the corresponding values are set for ctlptr. No data (control) part 36086 shall be sent if either dataptr(ctlptr) is a null pointer or the len member of dataptr(ctlptr) is set to 36087 -1. 36088 For putmsg( ), if a control part is specified and flags is set to RS_HIPRI, a high priority message | 36089 shall be sent. If no control part is specified, and flags is set to RS_HIPRI, putmsg( ) shall fail and | 36090 set errno to [EINVAL]. If flags is set to 0, a normal message (priority band equal to 0) shall be | 36091 sent. If a control part and data part are not specified and flags is set to 0, no message shall be | 36092 sent and 0 shall be returned. | 36093 For putpmsg( ), the flags are different. The flags argument is a bitmask with the following 36094 mutually-exclusive flags defined: MSG_HIPRI and MSG_BAND. If flags is set to 0, putpmsg( ) | 36095 shall fail and set errno to [EINVAL]. If a control part is specified and flags is set to MSG_HIPRI | 36096 and band is set to 0, a high-priority message shall be sent. If flags is set to MSG_HIPRI and either | 36097 no control part is specified or band is set to a non-zero value, putpmsg( ) shall fail and set errno to | 36098 [EINVAL]. If flags is set to MSG_BAND, then a message shall be sent in the priority band | 36099 specified by band. If a control part and data part are not specified and flags is set to MSG_BAND, | 36100 no message shall be sent and 0 shall be returned. | 36101 The putmsg( ) function shall block if the STREAM write queue is full due to internal flow control | 36102 conditions, with the following exceptions: | 36103 * For high-priority messages, putmsg( ) shall not block on this condition and continues | 36104 processing the message. | 1648 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putmsg( ) 36105 * For other messages, putmsg( ) shall not block but shall fail when the write queue is full and | 36106 O_NONBLOCK is set. | 36107 The putmsg( ) function shall also block, unless prevented by lack of internal resources, while | 36108 waiting for the availability of message blocks in the STREAM, regardless of priority or whether | 36109 O_NONBLOCK has been specified. No partial message shall be sent. | 36110 RETURN VALUE 36111 Upon successful completion, putmsg( ) and putpmsg( ) shall return 0; otherwise, they shall return 36112 -1 and set errno to indicate the error. 36113 ERRORS 36114 The putmsg( ) and putpmsg( ) functions shall fail if: 36115 [EAGAIN] A non-priority message was specified, the O_NONBLOCK flag is set, and the 36116 STREAM write queue is full due to internal flow control conditions; or buffers 36117 could not be allocated for the message that was to be created. 36118 [EBADF] fildes is not a valid file descriptor open for writing. 36119 [EINTR] A signal was caught during putmsg( ). 36120 [EINVAL] An undefined value is specified in flags, or flags is set to RS_HIPRI or 36121 MSG_HIPRI and no control part is supplied, or the STREAM or multiplexer 36122 referenced by fildes is linked (directly or indirectly) downstream from a 36123 multiplexer, or flags is set to MSG_HIPRI and band is non-zero (for putpmsg( ) 36124 only). 36125 [ENOSR] Buffers could not be allocated for the message that was to be created due to 36126 insufficient STREAMS memory resources. 36127 [ENOSTR] A STREAM is not associated with fildes. 36128 [ENXIO] A hangup condition was generated downstream for the specified STREAM. 36129 [EPIPE] or [EIO] The fildes argument refers to a STREAMS-based pipe and the other end of the 36130 pipe is closed. A SIGPIPE signal is generated for the calling thread. 36131 [ERANGE] The size of the data part of the message does not fall within the range 36132 specified by the maximum and minimum packet sizes of the topmost 36133 STREAM module. This value is also returned if the control part of the message 36134 is larger than the maximum configured size of the control part of a message, 36135 or if the data part of a message is larger than the maximum configured size of 36136 the data part of a message. 36137 In addition, putmsg( ) and putpmsg( ) shall fail if the STREAM head had processed an 36138 asynchronous error before the call. In this case, the value of errno does not reflect the result of 36139 putmsg( ) or putpmsg( ), but reflects the prior error. | System Interfaces, Issue 6 1649 putmsg( ) System Interfaces 36140 EXAMPLES | 36141 Sending a High-Priority Message 36142 The value of fd is assumed to refer to an open STREAMS file. This call to putmsg( ) does the 36143 following: 36144 1. Creates a high-priority message with a control part and a data part, using the buffers 36145 pointed to by ctrlbuf and databuf, respectively. 36146 2. Sends the message to the STREAMS file identified by fd. 36147 #include 36148 #include 36149 ... 36150 int fd; 36151 char *ctrlbuf = "This is the control part"; 36152 char *databuf = "This is the data part"; 36153 struct strbuf ctrl; 36154 struct strbuf data; 36155 int ret; 36156 ctrl.buf = ctrlbuf; 36157 ctrl.len = strlen(ctrlbuf); 36158 data.buf = databuf; 36159 data.len = strlen(databuf); 36160 ret = putmsg(fd, &ctrl, &data, MSG_HIPRI); 36161 Using putpmsg( ) 36162 This example has the same effect as the previous example. In this example, however, the 36163 putpmsg( ) function creates and sends the message to the STREAMS file. | 36164 #include 36165 #include 36166 ... 36167 int fd; 36168 char *ctrlbuf = "This is the control part"; 36169 char *databuf = "This is the data part"; 36170 struct strbuf ctrl; 36171 struct strbuf data; 36172 int ret; 36173 ctrl.buf = ctrlbuf; 36174 ctrl.len = strlen(ctrlbuf); 36175 data.buf = databuf; 36176 data.len = strlen(databuf); 36177 ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI); 36178 APPLICATION USAGE 36179 None. 1650 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putmsg( ) 36180 RATIONALE 36181 None. 36182 FUTURE DIRECTIONS 36183 None. 36184 SEE ALSO 36185 getmsg( ), poll( ), read( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 36186 Section 2.6 (on page 488) 36187 CHANGE HISTORY 36188 First released in Issue 4, Version 2. 36189 Issue 5 36190 Moved from X/OPEN UNIX extension to BASE. 36191 The following text is removed from the DESCRIPTION: ``The STREAM head guarantees that the 36192 control part of a message generated by putmsg( ) is at least 64 bytes in length''. 36193 Issue 6 36194 This function is marked as part of the XSI STREAMS Option Group. 36195 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1651 putpmsg( ) System Interfaces 36196 NAME 36197 putpmsg - send a message on a STREAM (STREAMS) 36198 SYNOPSIS 36199 XSR #include 36200 int putpmsg(int fildes, const struct strbuf *ctlptr, 36201 const struct strbuf *dataptr, int band, int flags); 36202 36203 DESCRIPTION 36204 Refer to putmsg( ). 1652 Technical Standard (2001) (Draft April 16, 2001) System Interfaces puts( ) 36205 NAME 36206 puts - put a string on standard output 36207 SYNOPSIS 36208 #include 36209 int puts(const char *s); 36210 DESCRIPTION 36211 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36212 conflict between the requirements described here and the ISO C standard is unintentional. This 36213 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36214 The puts( ) function shall write the string pointed to by s, followed by a , to the 36215 standard output stream stdout. The terminating null byte shall not be written. 36216 CX The st_ctime and st_mtime fields of the file shall be marked for update between the successful 36217 execution of puts( ) and the next successful completion of a call to fflush( ) or fclose( ) on the same 36218 stream or a call to exit( ) or abort( ). 36219 RETURN VALUE 36220 Upon successful completion, puts( ) shall return a non-negative number. Otherwise, it shall 36221 CX return EOF, shall set an error indicator for the stream, and errno shall be set to indicate the error. 36222 ERRORS 36223 Refer to fputc( ). 36224 EXAMPLES 36225 Printing to Standard Output 36226 The following example gets the current time, converts it to a string using localtime( ) and 36227 asctime( ), and prints it to standard output using puts( ). It then prints the number of minutes to 36228 an event for which it is waiting. 36229 #include 36230 #include 36231 ... 36232 time_t now; 36233 int minutes_to_event; 36234 ... 36235 time(&now); 36236 printf("The time is "); 36237 puts(asctime(localtime(&now))); 36238 printf("There are %d minutes to the event.\n", 36239 minutes_to_event); 36240 ... 36241 APPLICATION USAGE 36242 The puts( ) function appends a , while fputs( ) does not. 36243 RATIONALE 36244 None. 36245 FUTURE DIRECTIONS 36246 None. System Interfaces, Issue 6 1653 puts( ) System Interfaces 36247 SEE ALSO 36248 fopen( ), fputs( ), putc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 36249 CHANGE HISTORY 36250 First released in Issue 1. Derived from Issue 1 of the SVID. 36251 Issue 6 36252 Extensions beyond the ISO C standard are now marked. 1654 Technical Standard (2001) (Draft April 16, 2001) System Interfaces pututxline( ) 36253 NAME 36254 pututxline - put an entry into user accounting database 36255 SYNOPSIS 36256 XSI #include 36257 struct utmpx *pututxline(const struct utmpx *utmpx); 36258 36259 DESCRIPTION 36260 Refer to endutxent( ). System Interfaces, Issue 6 1655 putwc( ) System Interfaces 36261 NAME 36262 putwc - put a wide character on a stream 36263 SYNOPSIS 36264 #include 36265 #include 36266 wint_t putwc(wchar_t wc, FILE *stream); 36267 DESCRIPTION 36268 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36269 conflict between the requirements described here and the ISO C standard is unintentional. This 36270 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36271 The putwc( ) function shall be equivalent to fputwc( ), except that if it is implemented as a macro 36272 it may evaluate stream more than once, so the argument should never be an expression with side 36273 effects. 36274 RETURN VALUE 36275 Refer to fputwc( ). 36276 ERRORS 36277 Refer to fputwc( ). 36278 EXAMPLES 36279 None. 36280 APPLICATION USAGE 36281 Since it may be implemented as a macro, putwc( ) may treat a stream argument with side effects | 36282 incorrectly. In particular, putwc(wc,*f++) need not work correctly. Therefore, use of this function 36283 is not recommended; fputwc( ) should be used instead. 36284 RATIONALE 36285 None. 36286 FUTURE DIRECTIONS 36287 None. 36288 SEE ALSO 36289 fputwc( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 36290 CHANGE HISTORY 36291 First released as a World-wide Portability Interface in Issue 4. 36292 Issue 5 36293 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the type of argument wc 36294 is changed from wint_t to wchar_t. 36295 The Optional Header (OH) marking is removed from . 1656 Technical Standard (2001) (Draft April 16, 2001) System Interfaces putwchar( ) 36296 NAME 36297 putwchar - put a wide character on stdout stream 36298 SYNOPSIS 36299 #include 36300 wint_t putwchar(wchar_t wc); 36301 DESCRIPTION 36302 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36303 conflict between the requirements described here and the ISO C standard is unintentional. This 36304 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36305 The function call putwchar(wc) shall be equivalent to putwc(wc,stdout). 36306 RETURN VALUE 36307 Refer to fputwc( ). 36308 ERRORS 36309 Refer to fputwc( ). 36310 EXAMPLES 36311 None. 36312 APPLICATION USAGE 36313 None. 36314 RATIONALE 36315 None. 36316 FUTURE DIRECTIONS 36317 None. 36318 SEE ALSO 36319 fputwc( ), putwc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 36320 CHANGE HISTORY 36321 First released in Issue 4. 36322 Issue 5 36323 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the type of argument wc 36324 is changed from wint_t to wchar_t. System Interfaces, Issue 6 1657 pwrite( ) System Interfaces 36325 NAME 36326 pwrite - write on a file 36327 SYNOPSIS 36328 #include 36329 XSI ssize_t pwrite(int fildes, const void *buf, size_t nbyte, 36330 off_t offset); 36331 36332 DESCRIPTION 36333 Refer to write( ). 1658 Technical Standard (2001) (Draft April 16, 2001) System Interfaces qsort( ) 36334 NAME 36335 qsort - sort a table of data 36336 SYNOPSIS 36337 #include 36338 void qsort(void *base, size_t nel, size_t width, | 36339 int (*compar)(const void *, const void *)); | 36340 DESCRIPTION 36341 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36342 conflict between the requirements described here and the ISO C standard is unintentional. This 36343 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36344 The qsort( ) function shall sort an array of nel objects, the initial element of which is pointed to by 36345 base. The size of each object, in bytes, is specified by the width argument. 36346 The contents of the array shall be sorted in ascending order according to a comparison function. 36347 The compar argument is a pointer to the comparison function, which is called with two 36348 arguments that point to the elements being compared. The application shall ensure that the 36349 function returns an integer less than, equal to, or greater than 0, if the first argument is 36350 considered respectively less than, equal to, or greater than the second. If two members compare 36351 as equal, their order in the sorted array is unspecified. 36352 RETURN VALUE 36353 The qsort( ) function shall not return a value. 36354 ERRORS 36355 No errors are defined. 36356 EXAMPLES 36357 None. 36358 APPLICATION USAGE 36359 The comparison function need not compare every byte, so arbitrary data may be contained in 36360 the elements in addition to the values being compared. 36361 RATIONALE 36362 None. 36363 FUTURE DIRECTIONS 36364 None. 36365 SEE ALSO 36366 The Base Definitions volume of IEEE Std 1003.1-200x, 36367 CHANGE HISTORY 36368 First released in Issue 1. Derived from Issue 1 of the SVID. 36369 Issue 6 36370 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1659 raise( ) System Interfaces 36371 NAME 36372 raise - send a signal to the executing process 36373 SYNOPSIS 36374 #include 36375 int raise(int sig); 36376 DESCRIPTION 36377 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36378 conflict between the requirements described here and the ISO C standard is unintentional. This 36379 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36380 CX The raise( ) function shall send the signal sig to the executing thread or process. If a signal 36381 handler is called, the raise( ) function shall not return until after the signal handler does. 36382 THR If the implementation supports the Threads option, the effect of the raise( ) function shall be | 36383 equivalent to calling: | 36384 pthread_kill(pthread_self(), sig); 36385 36386 CX Otherwise, the effect of the raise( ) function shall be equivalent to calling: | 36387 kill(getpid(), sig); 36388 36389 RETURN VALUE 36390 CX Upon successful completion, 0 shall be returned. Otherwise, a non-zero value shall be returned 36391 and errno shall be set to indicate the error. 36392 ERRORS 36393 The raise( ) function shall fail if: 36394 CX [EINVAL] The value of the sig argument is an invalid signal number. 36395 EXAMPLES 36396 None. 36397 APPLICATION USAGE 36398 None. 36399 RATIONALE 36400 The term ``thread'' is an extension to the ISO C standard. 36401 FUTURE DIRECTIONS 36402 None. 36403 SEE ALSO 36404 kill( ), sigaction( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 36405 36406 CHANGE HISTORY 36407 First released in Issue 4. Derived from the ANSI C standard. 36408 Issue 5 36409 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 1660 Technical Standard (2001) (Draft April 16, 2001) System Interfaces raise( ) 36410 Issue 6 36411 Extensions beyond the ISO C standard are now marked. 36412 The following new requirements on POSIX implementations derive from alignment with the 36413 Single UNIX Specification: 36414 * In the RETURN VALUE section, the requirement to set errno on error is added. 36415 * The [EINVAL] error condition is added. System Interfaces, Issue 6 1661 rand( ) System Interfaces 36416 NAME 36417 rand, rand_r, srand - pseudo-random number generator 36418 SYNOPSIS 36419 #include 36420 int rand(void); 36421 TSF int rand_r(unsigned *seed); 36422 void srand(unsigned seed); 36423 DESCRIPTION 36424 CX The functionality described on this reference page is aligned with the ISO C standard. Any 36425 conflict between the requirements described here and the ISO C standard is unintentional. This 36426 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 36427 The rand( ) function shall compute a sequence of pseudo-random integers in the range 0 to 36428 XSI {RAND_MAX} with a period of at least 232. 36429 CX The rand( ) function need not be reentrant. A function that is not required to be reentrant is not 36430 required to be thread-safe. 36431 TSF The rand_r( ) function shall compute a sequence of pseudo-random integers in the range 0 to 36432 {RAND_MAX}. (The value of the {RAND_MAX} macro shall be at least 32 767.) 36433 If rand_r( ) is called with the same initial value for the object pointed to by seed and that object is 36434 not modified between successive returns and calls to rand_r( ), the same sequence shall be 36435 generated. 36436 The srand( ) function uses the argument as a seed for a new sequence of pseudo-random 36437 numbers to be returned by subsequent calls to rand( ). If srand( ) is then called with the same 36438 seed value, the sequence of pseudo-random numbers shall be repeated. If rand( ) is called before 36439 any calls to srand( ) are made, the same sequence shall be generated as when srand( ) is first 36440 called with a seed value of 1. 36441 The implementation shall behave as if no function defined in this volume of 36442 IEEE Std 1003.1-200x calls rand( ) or srand( ). 36443 RETURN VALUE 36444 The rand( ) function shall return the next pseudo-random number in the sequence. 36445 TSF The rand_r( ) function shall return a pseudo-random integer. 36446 The srand( ) function shall not return a value. 36447 ERRORS 36448 No errors are defined. 36449 EXAMPLES 36450 Generating a Pseudo-Random Number Sequence 36451 The following example demonstrates how to generate a sequence of pseudo-random numbers. 36452 #include 36453 #include 36454 ... 36455 long count, i; 36456 char *keystr; 36457 int elementlen, len; 36458 char c; 1662 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rand( ) 36459 ... 36460 /* Initial random number generator. */ 36461 srand(1); 36462 /* Create keys using only lower case characters */ 36463 len = 0; 36464 for (i=0; i 36508 CHANGE HISTORY 36509 First released in Issue 1. Derived from Issue 1 of the SVID. 36510 Issue 5 36511 The rand_r( ) function is included for alignment with the POSIX Threads Extension. 36512 A note indicating that the rand( ) function need not be reentrant is added to the DESCRIPTION. 36513 Issue 6 36514 Extensions beyond the ISO C standard are now marked. 36515 The rand_r( ) function is marked as part of the Thread-Safe Functions option. 1664 Technical Standard (2001) (Draft April 16, 2001) System Interfaces random( ) 36516 NAME 36517 random - generate pseudo-random number 36518 SYNOPSIS 36519 XSI #include 36520 long random(void); 36521 36522 DESCRIPTION 36523 Refer to initstate( ). System Interfaces, Issue 6 1665 read( ) System Interfaces 36524 NAME 36525 pread, read - read from a file | 36526 SYNOPSIS 36527 #include 36528 XSI ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); 36529 ssize_t read(int fildes, void *buf, size_t nbyte); 36530 DESCRIPTION | 36531 The read( ) function shall attempt to read nbyte bytes from the file associated with the open file | 36532 descriptor, fildes, into the buffer pointed to by buf. The behavior of multiple concurrent reads on 36533 the same pipe, FIFO, or terminal device is unspecified. 36534 Before any action described below is taken, and if nbyte is zero, the read( ) function may detect 36535 and return errors as described below. In the absence of errors, or if error detection is not 36536 performed, the read( ) function shall return zero and have no other results. 36537 On files that support seeking (for example, a regular file), the read( ) shall start at a position in | 36538 the file given by the file offset associated with fildes. The file offset shall be incremented by the | 36539 number of bytes actually read. | 36540 Files that do not support seeking-for example, terminals-always read from the current 36541 position. The value of a file offset associated with such a file is undefined. 36542 No data transfer shall occur past the current end-of-file. If the starting position is at or after the 36543 end-of-file, 0 shall be returned. If the file refers to a device special file, the result of subsequent 36544 read( ) requests is implementation-defined. 36545 If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-defined. 36546 When attempting to read from an empty pipe or FIFO: 36547 * If no process has the pipe open for writing, read( ) shall return 0 to indicate end-of-file. 36548 * If some process has the pipe open for writing and O_NONBLOCK is set, read( ) shall return 36549 -1 and set errno to [EAGAIN]. 36550 * If some process has the pipe open for writing and O_NONBLOCK is clear, read( ) shall block 36551 the calling thread until some data is written or the pipe is closed by all processes that had the 36552 pipe open for writing. 36553 When attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and 36554 has no data currently available: 36555 * If O_NONBLOCK is set, read( ) shall return -1 and set errno to [EAGAIN]. 36556 * If O_NONBLOCK is clear, read( ) shall block the calling thread until some data becomes 36557 available. 36558 * The use of the O_NONBLOCK flag has no effect if there is some data available. 36559 The read( ) function reads data previously written to a file. If any portion of a regular file prior to 36560 the end-of-file has not been written, read( ) shall return bytes with value 0. For example, lseek( ) 36561 allows the file offset to be set beyond the end of existing data in the file. If data is later written at 36562 this point, subsequent reads in the gap between the previous end of data and the newly written 36563 data shall return bytes with value 0 until data is written into the gap. 36564 Upon successful completion, where nbyte is greater than 0, read( ) shall mark for update the 36565 st_atime field of the file, and shall return the number of bytes read. This number shall never be 36566 greater than nbyte. The value returned may be less than nbyte if the number of bytes left in the 1666 Technical Standard (2001) (Draft April 16, 2001) System Interfaces read( ) 36567 file is less than nbyte, if the read( ) request was interrupted by a signal, or if the file is a pipe or 36568 FIFO or special file and has fewer than nbyte bytes immediately available for reading. For 36569 example, a read( ) from a file associated with a terminal may return one typed line of data. 36570 If a read( ) is interrupted by a signal before it reads any data, it shall return -1 with errno set to 36571 [EINTR]. 36572 If a read( ) is interrupted by a signal after it has successfully read some data, it shall return the 36573 number of bytes read. 36574 For regular files, no data transfer shall occur past the offset maximum established in the open 36575 file description associated with fildes. 36576 If fildes refers to a socket, read( ) shall be equivalent to recv( ) with no flags set. | 36577 SIO If the O_DSYNC and O_RSYNC bits have been set, read I/O operations on the file descriptor | 36578 shall complete as defined by synchronized I/O data integrity completion. If the O_SYNC and | 36579 O_RSYNC bits have been set, read I/O operations on the file descriptor shall complete as | 36580 defined by synchronized I/O file integrity completion. | 36581 SHM If fildes refers to a shared memory object, the result of the read( ) function is unspecified. 36582 TYM If fildes refers to a typed memory object, the result of the read( ) function is unspecified. 36583 XSR A read( ) from a STREAMS file can read data in three different modes: byte-stream mode, 36584 message-nondiscard mode, and message-discard mode. The default shall be byte-stream mode. This | 36585 can be changed using the I_SRDOPT ioctl( ) request, and can be tested with the I_GRDOPT | 36586 ioctl( ). In byte-stream mode, read( ) shall retrieve data from the STREAM until as many bytes as 36587 were requested are transferred, or until there is no more data to be retrieved. Byte-stream mode 36588 ignores message boundaries. 36589 In STREAMS message-nondiscard mode, read( ) shall retrieve data until as many bytes as were 36590 requested are transferred, or until a message boundary is reached. If read( ) does not retrieve all 36591 the data in a message, the remaining data shall be left on the STREAM, and can be retrieved by 36592 the next read( ) call. Message-discard mode also retrieves data until as many bytes as were 36593 requested are transferred, or a message boundary is reached. However, unread data remaining 36594 in a message after the read( ) returns shall be discarded, and shall not be available for a 36595 subsequent read( ), getmsg( ), or getpmsg( ) call. | 36596 How read( ) handles zero-byte STREAMS messages is determined by the current read mode 36597 setting. In byte-stream mode, read( ) shall accept data until it has read nbyte bytes, or until there 36598 is no more data to read, or until a zero-byte message block is encountered. The read( ) function 36599 shall then return the number of bytes read, and place the zero-byte message back on the 36600 STREAM to be retrieved by the next read( ), getmsg( ), or getpmsg( ). In message-nondiscard mode | 36601 or message-discard mode, a zero-byte message shall return 0 and the message shall be removed 36602 from the STREAM. When a zero-byte message is read as the first message on a STREAM, the 36603 message shall be removed from the STREAM and 0 shall be returned, regardless of the read 36604 mode. 36605 A read( ) from a STREAMS file shall return the data in the message at the front of the STREAM 36606 head read queue, regardless of the priority band of the message. 36607 By default, STREAMs are in control-normal mode, in which a read( ) from a STREAMS file can 36608 only process messages that contain a data part but do not contain a control part. The read( ) shall 36609 fail if a message containing a control part is encountered at the STREAM head. This default 36610 action can be changed by placing the STREAM in either control-data mode or control-discard 36611 mode with the I_SRDOPT ioctl( ) command. In control-data mode, read( ) shall convert any 36612 control part to data and pass it to the application before passing any data part originally present System Interfaces, Issue 6 1667 read( ) System Interfaces 36613 in the same message. In control-discard mode, read( ) shall discard message control parts but 36614 return to the process any data part in the message. 36615 In addition, read( ) shall fail if the STREAM head had processed an asynchronous error before the | 36616 call. In this case, the value of errno shall not reflect the result of read( ), but reflects the prior error. | 36617 If a hangup occurs on the STREAM being read, read( ) shall continue to operate normally until 36618 the STREAM head read queue is empty. Thereafter, it shall return 0. 36619 XSI The pread( ) function shall be equivalent to read( ), except that it shall read from a given position | 36620 in the file without changing the file pointer. The first three arguments to pread( ) are the same as | 36621 read( ) with the addition of a fourth argument offset for the desired position inside the file. An 36622 attempt to perform a pread( ) on a file that is incapable of seeking shall result in an error. | 36623 RETURN VALUE 36624 XSI Upon successful completion, read( ) and pread( )shall return a non-negative integer indicating the | 36625 number of bytes actually read. Otherwise, the functions shall return -1 and set errno to indicate 36626 the error. 36627 ERRORS 36628 XSI The read( ) andpread( )functions shall fail if: | 36629 [EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the process would be 36630 delayed. 36631 [EBADF] The fildes argument is not a valid file descriptor open for reading. 36632 XSR [EBADMSG] The file is a STREAM file that is set to control-normal mode and the message 36633 waiting to be read includes a control part. 36634 [EINTR] The read operation was terminated due to the receipt of a signal, and no data 36635 was transferred. 36636 XSR [EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or 36637 indirectly) downstream from a multiplexer. 36638 [EIO] The process is a member of a background process attempting to read from its 36639 controlling terminal, the process is ignoring or blocking the SIGTTIN signal, 36640 or the process group is orphaned. This error may also be generated for 36641 implementation-defined reasons. 36642 XSI [EISDIR] The fildes argument refers to a directory and the implementation does not 36643 allow the directory to be read using read( ) or pread( ). The readdir( ) function | 36644 should be used instead. 36645 [EOVERFLOW] The file is a regular file, nbyte is greater than 0, the starting position is before 36646 the end-of-file, and the starting position is greater than or equal to the offset 36647 maximum established in the open file description associated with fildes. 36648 The read( ) function shall fail if: 36649 [EAGAIN] or [EWOULDBLOCK] 36650 The file descriptor is for a socket, is marked O_NONBLOCK, and no data is 36651 waiting to be received. 36652 [ECONNRESET] A read was attempted on a socket and the connection was forcibly closed by 36653 its peer. 36654 [ENOTCONN] A read was attempted on a socket that is not connected. 36655 [ETIMEDOUT] A read was attempted on a socket and a transmission timeout occurred. 1668 Technical Standard (2001) (Draft April 16, 2001) System Interfaces read( ) 36656 XSI The read( ) andpread( )functions may fail if: | 36657 [EIO] A physical I/O error has occurred. 36658 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 36659 [ENOMEM] Insufficient memory was available to fulfill the request. 36660 [ENXIO] A request was made of a nonexistent device, or the request was outside the 36661 capabilities of the device. 36662 The pread( ) function shall fail, and the file pointer shall remain unchanged, if: | 36663 XSI [EINVAL] The offset argument is invalid. The value is negative. 36664 XSI [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the | 36665 offset maximum associated with the file. 36666 XSI [ENXIO] A request was outside the capabilities of the device. 36667 XSI [ESPIPE] fildes is associated with a pipe or FIFO. 36668 EXAMPLES 36669 Reading Data into a Buffer 36670 The following example reads data from the file associated with the file descriptor fd into the 36671 buffer pointed to by buf. 36672 #include 36673 #include 36674 ... 36675 char buf[20]; 36676 size_t nbytes; 36677 ssize_t bytes_read; 36678 int fd; 36679 ... 36680 nbytes = sizeof(buf); 36681 bytes_read = read(fd, buf, nbytes); 36682 ... 36683 APPLICATION USAGE | 36684 None. 36685 RATIONALE 36686 This volume of IEEE Std 1003.1-200x does not specify the value of the file offset after an error is 36687 returned; there are too many cases. For programming errors, such as [EBADF], the concept is 36688 meaningless since no file is involved. For errors that are detected immediately, such as 36689 [EAGAIN], clearly the pointer should not change. After an interrupt or hardware error, however, 36690 an updated value would be very useful and is the behavior of many implementations. 36691 Note that a read( ) of zero bytes does not modify st_atime. A read( ) that requests more than zero 36692 bytes, but returns zero, shall modify st_atime. 36693 Implementations are allowed, but not required, to perform error checking for read( ) requests of 36694 zero bytes. System Interfaces, Issue 6 1669 read( ) System Interfaces 36695 Input and Output 36696 The use of I/O with large byte counts has always presented problems. Ideas such as lread( ) and 36697 lwrite( ) (using and returning longs) were considered at one time. The current solution is to use 36698 abstract types on the ISO C standard function to read( ) and write( ). The abstract types can be 36699 declared so that existing functions work, but can also be declared so that larger types can be 36700 represented in future implementations. It is presumed that whatever constraints limit the 36701 maximum range of size_t also limit portable I/O requests to the same range. This volume of 36702 IEEE Std 1003.1-200x also limits the range further by requiring that the byte count be limited so 36703 that a signed return value remains meaningful. Since the return type is also a (signed) abstract 36704 type, the byte count can be defined by the implementation to be larger than an int can hold. 36705 The standard developers considered adding atomicity requirements to a pipe or FIFO, but 36706 recognized that due to the nature of pipes and FIFOs there could be no guarantee of atomicity of 36707 reads of {PIPE_BUF} or any other size that would be an aid to applications portability. 36708 This volume of IEEE Std 1003.1-200x requires that no action be taken for read( ) or write( ) when 36709 nbyte is zero. This is not intended to take precedence over detection of errors (such as invalid 36710 buffer pointers or file descriptors). This is consistent with the rest of this volume of 36711 IEEE Std 1003.1-200x, but the phrasing here could be misread to require detection of the zero 36712 case before any other errors. A value of zero is to be considered a correct value, for which the 36713 semantics are a no-op. 36714 I/O is intended to be atomic to ordinary files and pipes and FIFOs. Atomic means that all the 36715 bytes from a single operation that started out together end up together, without interleaving 36716 from other I/O operations. It is a known attribute of terminals that this is not honored, and 36717 terminals are explicitly (and implicitly permanently) excepted, making the behavior unspecified. 36718 The behavior for other device types is also left unspecified, but the wording is intended to imply 36719 that future standards might choose to specify atomicity (or not). 36720 There were recommendations to add format parameters to read( ) and write( ) in order to handle 36721 networked transfers among heterogeneous file system and base hardware types. Such a facility 36722 may be required for support by the OSI presentation of layer services. However, it was 36723 determined that this should correspond with similar C-language facilities, and that is beyond the 36724 scope of this volume of IEEE Std 1003.1-200x. The concept was suggested to the developers of 36725 the ISO C standard for their consideration as a possible area for future work. 36726 In 4.3 BSD, a read( ) or write( ) that is interrupted by a signal before transferring any data does not 36727 by default return an [EINTR] error, but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, 36728 there is an additional function, select( ), whose purpose is to pause until specified activity (data 36729 to read, space to write, and so on) is detected on specified file descriptors. It is common in 36730 applications written for those systems for select( ) to be used before read( ) in situations (such as 36731 keyboard input) where interruption of I/O due to a signal is desired. 36732 The issue of which files or file types are interruptible is considered an implementation design 36733 issue. This is often affected primarily by hardware and reliability issues. 36734 There are no references to actions taken following an ``unrecoverable error''. It is considered 36735 beyond the scope of this volume of IEEE Std 1003.1-200x to describe what happens in the case of 36736 hardware errors. 36737 Previous versions of IEEE Std 1003.1-200x allowed two very different behaviors with regard to 36738 the handling of interrupts. In order to minimize the resulting confusion, it was decided that 36739 IEEE Std 1003.1-200x should support only one of these behaviors. Historical practice on AT&T- 36740 derived systems was to have read( ) and write( ) return -1 and set errno to [EINTR] when 36741 interrupted after some, but not all, of the data requested had been transferred. However, the U.S. 36742 Department of Commerce FIPS 151-1 and FIPS 151-2 require the historical BSD behavior, in 1670 Technical Standard (2001) (Draft April 16, 2001) System Interfaces read( ) 36743 which read( ) and write( ) return the number of bytes actually transferred before the interrupt. If 36744 -1 is returned when any data is transferred, it is difficult to recover from the error on a seekable 36745 device and impossible on a non-seekable device. Most new implementations support this 36746 behavior. The behavior required by IEEE Std 1003.1-200x is to return the number of bytes 36747 transferred. 36748 IEEE Std 1003.1-200x does not specify when an implementation that buffers read( )s actually 36749 moves the data into the user-supplied buffer, so an implementation may chose to do this at the 36750 latest possible moment. Therefore, an interrupt arriving earlier may not cause read( ) to return a 36751 partial byte count, but rather to return -1 and set errno to [EINTR]. 36752 Consideration was also given to combining the two previous options, and setting errno to 36753 [EINTR] while returning a short count. However, not only is there no existing practice that 36754 implements this, it is also contradictory to the idea that when errno is set, the function 36755 responsible shall return -1. 36756 FUTURE DIRECTIONS 36757 None. 36758 SEE ALSO 36759 fcntl( ), ioctl( ), lseek( ), open( ), pipe( ), readv( ), the Base Definitions volume of | 36760 IEEE Std 1003.1-200x, , , , the Base Definitions volume of 36761 IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface 36762 CHANGE HISTORY 36763 First released in Issue 1. Derived from Issue 1 of the SVID. 36764 Issue 5 36765 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 36766 Threads Extension. 36767 Large File Summit extensions are added. 36768 The pread( ) function is added. 36769 Issue 6 36770 The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are 36771 marked as part of the XSI STREAMS Option Group. 36772 The following new requirements on POSIX implementations derive from alignment with the 36773 Single UNIX Specification: 36774 * The DESCRIPTION now states that if read( ) is interrupted by a signal after it has successfully 36775 read some data, it returns the number of bytes read. In Issue 3, it was optional whether read( ) 36776 returned the number of bytes read, or whether it returned -1 with errno set to [EINTR]. This 36777 is a FIPS requirement. 36778 * In the DESCRIPTION, text is added to indicate that for regular files, no data transfer occurs 36779 past the offset maximum established in the open file description associated with fildes. This 36780 change is to support large files. 36781 * The [EOVERFLOW] mandatory error condition is added. 36782 * The [ENXIO] optional error condition is added. 36783 Text referring to sockets is added to the DESCRIPTION. 36784 The following changes were made to align with the IEEE P1003.1a draft standard: 36785 * The effect of reading zero bytes is clarified. System Interfaces, Issue 6 1671 read( ) System Interfaces 36786 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 36787 read( ) results are unspecified for typed memory objects. 36788 New RATIONALE is added to explain the atomicity requirements for input and output 36789 operations. 36790 The following error conditions are added for operations on sockets: [EAGAIN], 36791 [ECONNRESET], [ENOTCONN], and [ETIMEDOUT]. 36792 The [EIO] error is changed to ``may fail''. 36793 The following error conditions are added for operations on sockets: [ENOBUFS] and 36794 [ENOMEM]. | 36795 The readv( ) function is split out into a separate reference page. | 1672 Technical Standard (2001) (Draft April 16, 2001) System Interfaces readdir( ) 36796 NAME 36797 readdir, readdir_r - read directory 36798 SYNOPSIS 36799 #include 36800 struct dirent *readdir(DIR *dirp); 36801 TSF int readdir_r(DIR *restrict dirp, struct dirent *restrict entry, 36802 struct dirent **restrict result); 36803 36804 DESCRIPTION 36805 The type DIR, which is defined in the header, represents a directory stream, which is 36806 an ordered sequence of all the directory entries in a particular directory. Directory entries 36807 represent files; files may be removed from a directory or added to a directory asynchronously to 36808 the operation of readdir( ). 36809 The readdir( ) function shall return a pointer to a structure representing the directory entry at the 36810 current position in the directory stream specified by the argument dirp, and position the 36811 directory stream at the next entry. It shall return a null pointer upon reaching the end of the 36812 directory stream. The structure dirent defined in the header describes a directory | 36813 entry. 36814 The readdir( ) function shall not return directory entries containing empty names. If entries for 36815 dot or dot-dot exist, one entry shall be returned for dot and one entry shall be returned for dot- 36816 dot; otherwise, they shall not be returned. 36817 The pointer returned by readdir( ) points to data which may be overwritten by another call to 36818 readdir( ) on the same directory stream. This data is not overwritten by another call to readdir( ) 36819 on a different directory stream. 36820 If a file is removed from or added to the directory after the most recent call to opendir( ) or 36821 rewinddir( ), whether a subsequent call to readdir( ) returns an entry for that file is unspecified. 36822 The readdir( ) function may buffer several directory entries per actual read operation; readdir( ) 36823 shall mark for update the st_atime field of the directory each time the directory is actually read. 36824 After a call to fork( ), either the parent or child (but not both) may continue processing the 36825 XSI directory stream using readdir( ), rewinddir( ), or seekdir( ). If both the parent and child processes 36826 use these functions, the result is undefined. 36827 If the entry names a symbolic link, the value of the d_ino member is unspecified. 36828 The readdir( ) function need not be reentrant. A function that is not required to be reentrant is not 36829 required to be thread-safe. 36830 TSF The readdir_r( ) function shall initialize the dirent structure referenced by entry to represent the 36831 directory entry at the current position in the directory stream referred to by dirp, store a pointer 36832 to this structure at the location referenced by result, and position the directory stream at the next 36833 entry. 36834 The storage pointed to by entry shall be large enough for a dirent with an array of char d_name 36835 members containing at least {NAME_MAX} plus one elements. 36836 Upon successful return, the pointer returned at *result shall have the same value as the argument 36837 entry. Upon reaching the end of the directory stream, this pointer shall have the value NULL. 36838 The readdir_r( ) function shall not return directory entries containing empty names. System Interfaces, Issue 6 1673 readdir( ) System Interfaces 36839 If a file is removed from or added to the directory after the most recent call to opendir( ) or 36840 rewinddir( ), whether a subsequent call to readdir_r( ) returns an entry for that file is unspecified. 36841 The readdir_r( ) function may buffer several directory entries per actual read operation; the 36842 readdir_r( ) function shall mark for update the st_atime field of the directory each time the 36843 directory is actually read. 36844 Applications wishing to check for error situations should set errno to 0 before calling readdir( ). If 36845 errno is set to non-zero on return, an error occurred. 36846 RETURN VALUE 36847 Upon successful completion, readdir( ) shall return a pointer to an object of type struct dirent. 36848 When an error is encountered, a null pointer shall be returned and errno shall be set to indicate 36849 the error. When the end of the directory is encountered, a null pointer shall be returned and errno 36850 is not changed. 36851 TSF If successful, the readdir_r( ) function shall return zero; otherwise, an error number shall be 36852 returned to indicate the error. 36853 ERRORS 36854 The readdir( ) function shall fail if: 36855 [EOVERFLOW] One of the values in the structure to be returned cannot be represented 36856 correctly. 36857 The readdir( ) function may fail if: 36858 [EBADF] The dirp argument does not refer to an open directory stream. 36859 [ENOENT] The current position of the directory stream is invalid. 36860 The readdir_r( ) function may fail if: 36861 [EBADF] The dirp argument does not refer to an open directory stream. 36862 EXAMPLES 36863 The following sample code searches the current directory for the entry name: 36864 dirp = opendir("."); 36865 while (dirp) { 36866 errno = 0; 36867 if ((dp = readdir(dirp)) != NULL) { 36868 if (strcmp(dp->d_name, name) == 0) { 36869 closedir(dirp); 36870 return FOUND; 36871 } 36872 } else { 36873 if (errno == 0) { 36874 closedir(dirp); 36875 return NOT_FOUND; 36876 } 36877 closedir(dirp); 36878 return READ_ERROR; 36879 } 36880 } 36881 return OPEN_ERROR; 1674 Technical Standard (2001) (Draft April 16, 2001) System Interfaces readdir( ) 36882 APPLICATION USAGE 36883 The readdir( ) function should be used in conjunction with opendir( ), closedir( ), and rewinddir( ) to 36884 examine the contents of the directory. 36885 The readdir_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 36886 of possibly using a static data area that may be overwritten by each call. 36887 RATIONALE 36888 The returned value of readdir( ) merely represents a directory entry. No equivalence should be 36889 inferred. 36890 Historical implementations of readdir( ) obtain multiple directory entries on a single read 36891 operation, which permits subsequent readdir( ) operations to operate from the buffered 36892 information. Any wording that required each successful readdir( ) operation to mark the 36893 directory st_atime field for update would militate against the historical performance-oriented 36894 implementations. 36895 Since readdir( ) returns NULL when it detects an error and when the end of the directory is 36896 encountered, an application that needs to tell the difference must set errno to zero before the call 36897 and check it if NULL is returned. Since the function must not change errno in the second case | 36898 and must set it to a non-zero value in the first case, a zero errno after a call returning NULL 36899 indicates end of directory; otherwise, an error. 36900 Routines to deal with this problem more directly were proposed: 36901 int derror (dirp) 36902 DIR *dirp; 36903 void clearderr (dirp) 36904 DIR *dirp; 36905 The first would indicate whether an error had occurred, and the second would clear the error 36906 indication. The simpler method involving errno was adopted instead by requiring that readdir( ) 36907 not change errno when end-of-directory is encountered. 36908 An error or signal indicating that a directory has changed while open was considered but 36909 rejected. 36910 The thread-safe version of the directory reading function returns values in a user-supplied buffer 36911 instead of possibly using a static data area that may be overwritten by each call. Either the 36912 {NAME_MAX} compile-time constant or the corresponding pathconf( ) option can be used to 36913 determine the maximum sizes of returned pathnames. | 36914 FUTURE DIRECTIONS 36915 None. 36916 SEE ALSO 36917 closedir( ), lstat( ), opendir( ), rewinddir( ), symlink( ), the Base Definitions volume of 36918 IEEE Std 1003.1-200x, , 36919 CHANGE HISTORY 36920 First released in Issue 2. 36921 Issue 5 36922 Large File Summit extensions are added. 36923 The readdir_r( ) function is included for alignment with the POSIX Threads Extension. 36924 A note indicating that the readdir( ) function need not be reentrant is added to the 36925 DESCRIPTION. System Interfaces, Issue 6 1675 readdir( ) System Interfaces 36926 Issue 6 36927 The readdir_r( ) function is marked as part of the Thread-Safe Functions option. 36928 The Open Group Corrigendum U026/7 is applied, correcting the prototype for readdir_r( ). 36929 The Open Group Corrigendum U026/8 is applied, clarifying the wording of the successful 36930 return for the readdir_r( ) function. 36931 The following new requirements on POSIX implementations derive from alignment with the 36932 Single UNIX Specification: 36933 * The requirement to include has been removed. Although was 36934 required for conforming implementations of previous POSIX specifications, it was not 36935 required for UNIX applications. 36936 * A statement is added to the DESCRIPTION indicating the disposition of certain fields in 36937 struct dirent when an entry refers to a symbolic link. 36938 * The [EOVERFLOW] mandatory error condition is added. This change is to support large 36939 files. 36940 * The [ENOENT] optional error condition is added. 36941 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 36942 its avoidance of possibly using a static data area. 36943 The restrict keyword is added to the readdir_r( ) prototype for alignment with the 36944 ISO/IEC 9899: 1999 standard. 1676 Technical Standard (2001) (Draft April 16, 2001) System Interfaces readlink( ) 36945 NAME 36946 readlink - read the contents of a symbolic link 36947 SYNOPSIS 36948 #include 36949 ssize_t readlink(const char *restrict path, char *restrict buf, 36950 size_t bufsize); 36951 DESCRIPTION 36952 The readlink( ) function shall place the contents of the symbolic link referred to by path in the 36953 buffer buf which has size bufsize. If the number of bytes in the symbolic link is less than bufsize, 36954 the contents of the remainder of buf are unspecified. If the buf argument is not large enough to 36955 contain the link content, the first bufsize bytes shall be placed in buf. 36956 If the value of bufsize is greater than {SSIZE_MAX}, the result is implementation-defined. 36957 RETURN VALUE 36958 Upon successful completion, readlink( ) shall return the count of bytes placed in the buffer. 36959 Otherwise, it shall return a value of -1, leave the buffer unchanged, and set errno to indicate the 36960 error. 36961 ERRORS 36962 The readlink( ) function shall fail if: 36963 [EACCES] Search permission is denied for a component of the path prefix of path. 36964 [EINVAL] The path argument names a file that is not a symbolic link. 36965 [EIO] An I/O error occurred while reading from the file system. 36966 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 36967 argument. 36968 [ENAMETOOLONG] 36969 The length of the path argument exceeds {PATH_MAX} or a pathname | 36970 component is longer than {NAME_MAX}. | 36971 [ENOENT] A component of path does not name an existing file or path is an empty string. 36972 [ENOTDIR] A component of the path prefix is not a directory. 36973 The readlink( ) function may fail if: 36974 [EACCES] Read permission is denied for the directory. 36975 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 36976 resolution of the path argument. 36977 [ENAMETOOLONG] 36978 As a result of encountering a symbolic link in resolution of the path argument, | 36979 the length of the substituted pathname string exceeded {PATH_MAX}. | System Interfaces, Issue 6 1677 readlink( ) System Interfaces 36980 EXAMPLES 36981 Reading the Name of a Symbolic Link 36982 The following example shows how to read the name of a symbolic link named /modules/pass1. 36983 #include 36984 char buf[1024]; 36985 int len; 36986 ... 36987 if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1); 36988 buf[len] = '\0'; 36989 APPLICATION USAGE 36990 Conforming applications should not assume that the returned contents of the symbolic link are | 36991 null-terminated. 36992 RATIONALE 36993 Since IEEE Std 1003.1-200x does not require any association of file times with symbolic links, 36994 there is no requirement that file times be updated by readlink( ). The type associated with bufsiz 36995 is a size_t in order to be consistent with both the ISO C standard and the definition of read( ). 36996 The behavior specified for readlink( ) when bufsiz is zero represents historical practice. For this 36997 case, the standard developers considered a change whereby readlink( ) would return the number 36998 of non-null bytes contained in the symbolic link with the buffer buf remaining unchanged; 36999 however, since the stat structure member st_size value can be used to determine the size of 37000 buffer necessary to contain the contents of the symbolic link as returned by readlink( ), this 37001 proposal was rejected, and the historical practice retained. 37002 FUTURE DIRECTIONS 37003 None. 37004 SEE ALSO 37005 lstat( ), stat( ), symlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 37006 CHANGE HISTORY 37007 First released in Issue 4, Version 2. 37008 Issue 5 37009 Moved from X/OPEN UNIX extension to BASE. 37010 Issue 6 37011 The return type is changed to ssize_t, to align with the IEEE P1003.1a draft standard. 37012 The following new requirements on POSIX implementations derive from alignment with the 37013 Single UNIX Specification: 37014 * This function is made mandatory. 37015 * In this function it is possible for the return value to exceed the range of the type ssize_t (since 37016 size_t has a larger range of positive values than ssize_t). A sentence restricting the size of 37017 the size_t object is added to the description to resolve this conflict. 37018 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 37019 * The FUTURE DIRECTIONS section is changed to None. | 37020 The following changes were made to align with the IEEE P1003.1a draft standard: 37021 * The [ELOOP] optional error condition is added. 1678 Technical Standard (2001) (Draft April 16, 2001) System Interfaces readlink( ) 37022 The restrict keyword is added to the readlink( ) prototype for alignment with the 37023 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1679 readv( ) System Interfaces 37024 NAME | 37025 readv - read a vector | 37026 SYNOPSIS 37027 XSI #include 37028 ssize_t readv(int fildes, const struct iovec *iov, int iovcnt); 37029 37030 DESCRIPTION 37031 The readv( ) function shall be equivalent to read( ), except as described below. The readv( ) | 37032 function shall place the input data into the iovcnt buffers specified by the members of the iov | 37033 array: iov[0], iov[1], . . ., iov[iovcnt-1]. The iovcnt argument is valid if greater than 0 and less than | 37034 or equal to {IOV_MAX}. | 37035 Each iovec entry specifies the base address and length of an area in memory where data should | 37036 be placed. The readv( ) function shall always fill an area completely before proceeding to the | 37037 next. | 37038 Upon successful completion, readv( ) shall mark for update the st_atime field of the file. | 37039 RETURN VALUE | 37040 Refer to read( ). | 37041 ERRORS | 37042 Refer to read( ). | 37043 In addition, the readv( ) function shall fail if: | 37044 [EINVAL] The sum of the iov_len values in the iov array overflowed an ssize_t. | 37045 The readv( ) function may fail if: | 37046 [EINVAL] The iovcnt argument was less than or equal to 0, or greater than {IOV_MAX}. | 37047 EXAMPLES | 37048 Reading Data into an Array | 37049 The following example reads data from the file associated with the file descriptor fd into the | 37050 buffers specified by members of the iov array. | 37051 #include | 37052 #include | 37053 #include | 37054 ... | 37055 ssize_t bytes_read; | 37056 int fd; | 37057 char buf0[20]; | 37058 char buf1[30]; | 37059 char buf2[40]; | 37060 int iovcnt; | 37061 struct iovec iov[3]; | 37062 iov[0].iov_base = buf0; | 37063 iov[0].iov_len = sizeof(buf0); | 37064 iov[1].iov_base = buf1; | 37065 iov[1].iov_len = sizeof(buf1); | 37066 iov[2].iov_base = buf2; | 37067 iov[2].iov_len = sizeof(buf2); | 1680 Technical Standard (2001) (Draft April 16, 2001) System Interfaces readv( ) 37068 ... | 37069 iovcnt = sizeof(iov) / sizeof(struct iovec); | 37070 bytes_read = readv(fd, iov, iovcnt); | 37071 ... | 37072 APPLICATION USAGE | 37073 None. | 37074 RATIONALE | 37075 Refer to read( ). | 37076 FUTURE DIRECTIONS | 37077 None. | 37078 SEE ALSO | 37079 read( ), writev( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 37080 CHANGE HISTORY | 37081 First released in Issue 4, Version 2. | 37082 Issue 6 || 37083 Split out from the read( ) reference page. | System Interfaces, Issue 6 1681 realloc( ) System Interfaces 37084 NAME 37085 realloc - memory reallocator 37086 SYNOPSIS 37087 #include 37088 void *realloc(void *ptr, size_t size); 37089 DESCRIPTION 37090 CX The functionality described on this reference page is aligned with the ISO C standard. Any 37091 conflict between the requirements described here and the ISO C standard is unintentional. This 37092 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 37093 The realloc( ) function shall change the size of the memory object pointed to by ptr to the size 37094 specified by size. The contents of the object shall remain unchanged up to the lesser of the new 37095 and old sizes. If the new size of the memory object would require movement of the object, the 37096 space for the previous instantiation of the object is freed. If the new size is larger, the contents of 37097 the newly allocated portion of the object are unspecified. If size is 0 and ptr is not a null pointer, 37098 the object pointed to is freed. If the space cannot be allocated, the object shall remain unchanged. | 37099 If ptr is a null pointer, realloc( ) shall be equivalent to malloc( ) for the specified size. | 37100 If ptr does not match a pointer returned earlier by calloc( ), malloc( ), or realloc( ) or if the space has 37101 previously been deallocated by a call to free( ) or realloc( ), the behavior is undefined. 37102 The order and contiguity of storage allocated by successive calls to realloc( ) is unspecified. The | 37103 pointer returned if the allocation succeeds shall be suitably aligned so that it may be assigned to | 37104 a pointer to any type of object and then used to access such an object in the space allocated (until | 37105 the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object 37106 disjoint from any other object. The pointer returned shall point to the start (lowest byte address) | 37107 of the allocated space. If the space cannot be allocated, a null pointer shall be returned. | 37108 RETURN VALUE 37109 Upon successful completion with a size not equal to 0, realloc( ) shall return a pointer to the 37110 (possibly moved) allocated space. If size is 0, either a null pointer or a unique pointer that can be 37111 successfully passed to free( ) shall be returned. If there is not enough available memory, realloc( ) 37112 CX shall return a null pointer and set errno to [ENOMEM]. 37113 ERRORS 37114 The realloc( ) function shall fail if: 37115 CX [ENOMEM] Insufficient memory is available. 37116 EXAMPLES 37117 None. 37118 APPLICATION USAGE 37119 None. 37120 RATIONALE 37121 None. 37122 FUTURE DIRECTIONS 37123 None. 37124 SEE ALSO 37125 calloc( ), free( ), malloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1682 Technical Standard (2001) (Draft April 16, 2001) System Interfaces realloc( ) 37126 CHANGE HISTORY 37127 First released in Issue 1. Derived from Issue 1 of the SVID. 37128 Issue 6 37129 Extensions beyond the ISO C standard are now marked. 37130 The following new requirements on POSIX implementations derive from alignment with the 37131 Single UNIX Specification: 37132 * In the RETURN VALUE section, if there is not enough available memory, the setting of errno 37133 to [ENOMEM] is added. 37134 * The [ENOMEM] error condition is added. System Interfaces, Issue 6 1683 realpath( ) System Interfaces 37135 NAME 37136 realpath - resolve a pathname | 37137 SYNOPSIS 37138 XSI #include 37139 char *realpath(const char *restrict file_name, 37140 char *restrict resolved_name); 37141 37142 DESCRIPTION 37143 The realpath( ) function shall derive, from the pathname pointed to by file_name, an absolute | 37144 pathname that names the same file, whose resolution does not involve '.', '..', or symbolic | 37145 links. The generated pathname shall be stored as a null-terminated string, up to a maximum of | 37146 {PATH_MAX} bytes, in the buffer pointed to by resolved_name. 37147 RETURN VALUE 37148 Upon successful completion, realpath( ) shall return a pointer to the resolved name. Otherwise, 37149 realpath( ) shall return a null pointer and set errno to indicate the error, and the contents of the 37150 buffer pointed to by resolved_name are undefined. 37151 ERRORS 37152 The realpath( ) function shall fail if: 37153 [EACCES] Read or search permission was denied for a component of file_name. 37154 [EINVAL] Either the file_name or resolved_name argument is a null pointer. 37155 [EIO] An error occurred while reading from the file system. 37156 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 37157 argument. 37158 [ENAMETOOLONG] 37159 The length of the file_name argument exceeds {PATH_MAX} or a pathname | 37160 component is longer than {NAME_MAX}. | 37161 [ENOENT] A component of file_name does not name an existing file or file_name points to 37162 an empty string. 37163 [ENOTDIR] A component of the path prefix is not a directory. 37164 The realpath( ) function may fail if: 37165 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 37166 resolution of the path argument. 37167 [ENAMETOOLONG] 37168 Pathname resolution of a symbolic link produced an intermediate result | 37169 whose length exceeds {PATH_MAX}. 37170 [ENOMEM] Insufficient storage space is available. 1684 Technical Standard (2001) (Draft April 16, 2001) System Interfaces realpath( ) 37171 EXAMPLES 37172 Generating an Absolute Pathname | 37173 The following example generates an absolute pathname for the file identified by the symlinkpath | 37174 argument. The generated pathname is stored in the actualpath array. | 37175 #include 37176 ... 37177 char *symlinkpath = "/tmp/symlink/file"; 37178 char actualpath [PATH_MAX+1]; 37179 char *ptr; 37180 ptr = realpath(symlinkpath, actualpath); 37181 APPLICATION USAGE 37182 None. 37183 RATIONALE 37184 None. 37185 FUTURE DIRECTIONS 37186 None. 37187 SEE ALSO 37188 getcwd( ), sysconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 37189 CHANGE HISTORY 37190 First released in Issue 4, Version 2. 37191 Issue 5 37192 Moved from X/OPEN UNIX extension to BASE. 37193 Issue 6 37194 The restrict keyword is added to the realpath( ) prototype for alignment with the | 37195 ISO/IEC 9899: 1999 standard. 37196 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 37197 [ELOOP] error condition is added. System Interfaces, Issue 6 1685 recv( ) System Interfaces 37198 NAME 37199 recv - receive a message from a connected socket 37200 SYNOPSIS 37201 #include 37202 ssize_t recv(int socket, void *buffer, size_t length, int flags); 37203 DESCRIPTION 37204 The recv( ) function shall receive a message from a connection-mode or connectionless-mode 37205 socket. It is normally used with connected sockets because it does not permit the application to 37206 retrieve the source address of received data. 37207 The recv( ) function takes the following arguments: 37208 socket Specifies the socket file descriptor. 37209 buffer Points to a buffer where the message should be stored. 37210 length Specifies the length in bytes of the buffer pointed to by the buffer argument. 37211 flags Specifies the type of message reception. Values of this argument are formed by 37212 logically OR'ing zero or more of the following values: 37213 MSG_PEEK Peeks at an incoming message. The data is treated as unread and 37214 the next recv( ) or similar function shall still return this data. 37215 MSG_OOB Requests out-of-band data. The significance and semantics of 37216 out-of-band data are protocol-specific. 37217 MSG_WAITALL On SOCK_STREAM sockets this requests that the function block | 37218 until the full amount of data can be returned. The function may | 37219 return the smaller amount of data if the socket is a message- | 37220 based socket, if a signal is caught, if the connection is | 37221 terminated, if MSG_PEEK was specified, or if an error is pending | 37222 for the socket. | 37223 The recv( ) function shall return the length of the message written to the buffer pointed to by the 37224 buffer argument. For message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, 37225 the entire message shall be read in a single operation. If a message is too long to fit in the 37226 supplied buffer, and MSG_PEEK is not set in the flags argument, the excess bytes shall be 37227 discarded. For stream-based sockets, such as SOCK_STREAM, message boundaries shall be 37228 ignored. In this case, data shall be returned to the user as soon as it becomes available, and no | 37229 data shall be discarded. 37230 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 37231 message. 37232 If no messages are available at the socket and O_NONBLOCK is not set on the socket's file 37233 descriptor, recv( ) shall block until a message arrives. If no messages are available at the socket 37234 and O_NONBLOCK is set on the socket's file descriptor, recv( ) shall fail and set errno to 37235 [EAGAIN] or [EWOULDBLOCK]. 37236 RETURN VALUE 37237 Upon successful completion, recv( ) shall return the length of the message in bytes. If no 37238 messages are available to be received and the peer has performed an orderly shutdown, recv( ) 37239 shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error. 1686 Technical Standard (2001) (Draft April 16, 2001) System Interfaces recv( ) 37240 ERRORS 37241 The recv( ) function shall fail if: 37242 [EAGAIN] or [EWOULDBLOCK] 37243 The socket's file descriptor is marked O_NONBLOCK and no data is waiting 37244 to be received; or MSG_OOB is set and no out-of-band data is available and 37245 either the socket's file descriptor is marked O_NONBLOCK or the socket does 37246 not support blocking to await out-of-band data. 37247 [EBADF] The socket argument is not a valid file descriptor. 37248 [ECONNRESET] A connection was forcibly closed by a peer. 37249 [EINTR] The recv( ) function was interrupted by a signal that was caught, before any 37250 data was available. 37251 [EINVAL] The MSG_OOB flag is set and no out-of-band data is available. 37252 [ENOTCONN] A receive is attempted on a connection-mode socket that is not connected. 37253 [ENOTSOCK] The socket argument does not refer to a socket. 37254 [EOPNOTSUPP] The specified flags are not supported for this socket type or protocol. 37255 [ETIMEDOUT] The connection timed out during connection establishment, or due to a 37256 transmission timeout on active connection. 37257 The recv( ) function may fail if: 37258 [EIO] An I/O error occurred while reading from or writing to the file system. 37259 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 37260 [ENOMEM] Insufficient memory was available to fulfill the request. 37261 EXAMPLES 37262 None. 37263 APPLICATION USAGE 37264 The recv( ) function is equivalent to recvfrom( ) with a zero address_len argument, and to read( ) if | 37265 no flags are used. 37266 The select( ) and poll( ) functions can be used to determine when data is available to be received. 37267 RATIONALE 37268 None. 37269 FUTURE DIRECTIONS 37270 None. 37271 SEE ALSO 37272 poll( ), read( ), recvmsg( ), recvfrom( ), select( ), send( ), sendmsg( ), sendto( ), shutdown( ), socket( ), 37273 write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 37274 CHANGE HISTORY 37275 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1687 recvfrom( ) System Interfaces 37276 NAME 37277 recvfrom - receive a message from a socket 37278 SYNOPSIS 37279 #include 37280 ssize_t recvfrom(int socket, void *restrict buffer, size_t length, 37281 int flags, struct sockaddr *restrict address, 37282 socklen_t *restrict address_len); 37283 DESCRIPTION 37284 The recvfrom( ) function shall receive a message from a connection-mode or connectionless-mode 37285 socket. It is normally used with connectionless-mode sockets because it permits the application 37286 to retrieve the source address of received data. 37287 The recvfrom( ) function takes the following arguments: 37288 socket Specifies the socket file descriptor. 37289 buffer Points to the buffer where the message should be stored. 37290 length Specifies the length in bytes of the buffer pointed to by the buffer argument. 37291 flags Specifies the type of message reception. Values of this argument are formed 37292 by logically OR'ing zero or more of the following values: 37293 MSG_PEEK Peeks at an incoming message. The data is treated as unread 37294 and the next recvfrom( ) or similar function shall still return 37295 this data. 37296 MSG_OOB Requests out-of-band data. The significance and semantics 37297 of out-of-band data are protocol-specific. 37298 MSG_WAITALL On SOCK_STREAM sockets this requests that the function | 37299 block until the full amount of data can be returned. The | 37300 function may return the smaller amount of data if the socket | 37301 is a message-based socket, if a signal is caught, if the | 37302 connection is terminated, if MSG_PEEK was specified, or if | 37303 an error is pending for the socket. | 37304 address A null pointer, or points to a sockaddr structure in which the sending address 37305 is to be stored. The length and format of the address depend on the address 37306 family of the socket. 37307 address_len Specifies the length of the sockaddr structure pointed to by the address 37308 argument. 37309 The recvfrom( ) function shall return the length of the message written to the buffer pointed to by 37310 RS the buffer argument. For message-based sockets, such as SOCK_RAW, SOCK_DGRAM, and 37311 SOCK_SEQPACKET, the entire message shall be read in a single operation. If a message is too 37312 long to fit in the supplied buffer, and MSG_PEEK is not set in the flags argument, the excess 37313 bytes shall be discarded. For stream-based sockets, such as SOCK_STREAM, message 37314 boundaries shall be ignored. In this case, data shall be returned to the user as soon as it becomes | 37315 available, and no data shall be discarded. 37316 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 37317 message. 37318 Not all protocols provide the source address for messages. If the address argument is not a null 37319 pointer and the protocol provides the source address of messages, the source address of the | 1688 Technical Standard (2001) (Draft April 16, 2001) System Interfaces recvfrom( ) 37320 received message shall be stored in the sockaddr structure pointed to by the address argument, | 37321 and the length of this address shall be stored in the object pointed to by the address_len | 37322 argument. 37323 If the actual length of the address is greater than the length of the supplied sockaddr structure, 37324 the stored address shall be truncated. 37325 If the address argument is not a null pointer and the protocol does not provide the source address 37326 of messages, the value stored in the object pointed to by address is unspecified. 37327 If no messages are available at the socket and O_NONBLOCK is not set on the socket's file 37328 descriptor, recvfrom( ) shall block until a message arrives. If no messages are available at the | 37329 socket and O_NONBLOCK is set on the socket's file descriptor, recvfrom( ) shall fail and set errno | 37330 to [EAGAIN] or [EWOULDBLOCK]. 37331 RETURN VALUE 37332 Upon successful completion, recvfrom( ) shall return the length of the message in bytes. If no 37333 messages are available to be received and the peer has performed an orderly shutdown, 37334 recvfrom( ) shall return 0. Otherwise, the function shall return -1 and set errno to indicate the 37335 error. 37336 ERRORS 37337 The recvfrom( ) function shall fail if: 37338 [EAGAIN] or [EWOULDBLOCK] 37339 The socket's file descriptor is marked O_NONBLOCK and no data is waiting 37340 to be received; or MSG_OOB is set and no out-of-band data is available and 37341 either the socket's file descriptor is marked O_NONBLOCK or the socket does 37342 not support blocking to await out-of-band data. 37343 [EBADF] The socket argument is not a valid file descriptor. 37344 [ECONNRESET] A connection was forcibly closed by a peer. 37345 [EINTR] A signal interrupted recvfrom( ) before any data was available. 37346 [EINVAL] The MSG_OOB flag is set and no out-of-band data is available. 37347 [ENOTCONN] A receive is attempted on a connection-mode socket that is not connected. 37348 [ENOTSOCK] The socket argument does not refer to a socket. 37349 [EOPNOTSUPP] The specified flags are not supported for this socket type. 37350 [ETIMEDOUT] The connection timed out during connection establishment, or due to a 37351 transmission timeout on active connection. 37352 The recvfrom( ) function may fail if: 37353 [EIO] An I/O error occurred while reading from or writing to the file system. 37354 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 37355 [ENOMEM] Insufficient memory was available to fulfill the request. System Interfaces, Issue 6 1689 recvfrom( ) System Interfaces 37356 EXAMPLES 37357 None. 37358 APPLICATION USAGE 37359 The select( ) and poll( ) functions can be used to determine when data is available to be received. 37360 RATIONALE 37361 None. 37362 FUTURE DIRECTIONS 37363 None. 37364 SEE ALSO 37365 poll( ), read( ), recv( ), recvmsg( ), select( ) (on page 1742)1 send( ), sendmsg( ), sendto( ), shutdown( ), 37366 socket( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 37367 CHANGE HISTORY 37368 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1690 Technical Standard (2001) (Draft April 16, 2001) System Interfaces recvmsg( ) 37369 NAME 37370 recvmsg - receive a message from a socket 37371 SYNOPSIS 37372 #include 37373 ssize_t recvmsg(int socket, struct msghdr *message, int flags); 37374 DESCRIPTION 37375 The recvmsg( ) function shall receive a message from a connection-mode or connectionless-mode 37376 socket. It is normally used with connectionless-mode sockets because it permits the application 37377 to retrieve the source address of received data. 37378 The recvmsg( ) function takes the following arguments: 37379 socket Specifies the socket file descriptor. 37380 message Points to a msghdr structure, containing both the buffer to store the source 37381 address and the buffers for the incoming message. The length and format of 37382 the address depend on the address family of the socket. The msg_flags member 37383 is ignored on input, but may contain meaningful values on output. 37384 flags Specifies the type of message reception. Values of this argument are formed 37385 by logically OR'ing zero or more of the following values: 37386 MSG_OOB Requests out-of-band data. The significance and semantics 37387 of out-of-band data are protocol-specific. 37388 MSG_PEEK Peeks at the incoming message. 37389 MSG_WAITALL On SOCK_STREAM sockets this requests that the function | 37390 block until the full amount of data can be returned. The | 37391 function may return the smaller amount of data if the socket | 37392 is a message-based socket, if a signal is caught, if the | 37393 connection is terminated, if MSG_PEEK was specified, or if | 37394 an error is pending for the socket. | 37395 The recvmsg( ) function shall receive messages from unconnected or connected sockets and shall | 37396 return the length of the message. | 37397 The recvmsg( ) function shall return the total length of the message. For message-based sockets, 37398 such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message shall be read in a single 37399 operation. If a message is too long to fit in the supplied buffers, and MSG_PEEK is not set in the 37400 flags argument, the excess bytes shall be discarded, and MSG_TRUNC shall be set in the | 37401 msg_flags member of the msghdr structure. For stream-based sockets, such as SOCK_STREAM, 37402 message boundaries shall be ignored. In this case, data shall be returned to the user as soon as it | 37403 becomes available, and no data shall be discarded. | 37404 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 37405 message. 37406 If no messages are available at the socket and O_NONBLOCK is not set on the socket's file 37407 descriptor, recvmsg( ) shall block until a message arrives. If no messages are available at the 37408 socket and O_NONBLOCK is set on the socket's file descriptor, recvmsg( ) function shall fail and 37409 set errno to [EAGAIN] or [EWOULDBLOCK]. 37410 In the msghdr structure, the msg_name and msg_namelen members specify the source address if 37411 the socket is unconnected. If the socket is connected, the msg_name and msg_namelen members | 37412 shall be ignored. The msg_name member may be a null pointer if no names are desired or | 37413 required. The msg_iov and msg_iovlen fields are used to specify where the received data shall be System Interfaces, Issue 6 1691 recvmsg( ) System Interfaces 37414 stored. msg_iov points to an array of iovec structures; msg_iovlen shall be set to the dimension of 37415 this array. In each iovec structure, the iov_base field specifies a storage area and the iov_len field 37416 gives its size in bytes. Each storage area indicated by msg_iov is filled with received data in turn 37417 until all of the received data is stored or all of the areas have been filled. 37418 Upon successful completion, the msg_flags member of the message header shall be the bitwise- | 37419 inclusive OR of all of the following flags that indicate conditions detected for the received | 37420 message: | 37421 MSG_EOR End of record was received (if supported by the protocol). 37422 MSG_OOB Out-of-band data was received. 37423 MSG_TRUNC Normal data was truncated. 37424 MSG_CTRUNC Control data was truncated. 37425 RETURN VALUE 37426 Upon successful completion, recvmsg( ) shall return the length of the message in bytes. If no 37427 messages are available to be received and the peer has performed an orderly shutdown, 37428 recvmsg( ) shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error. 37429 ERRORS 37430 The recvmsg( ) function shall fail if: 37431 [EAGAIN] or [EWOULDBLOCK] 37432 The socket's file descriptor is marked O_NONBLOCK and no data is waiting 37433 to be received; or MSG_OOB is set and no out-of-band data is available and 37434 either the socket's file descriptor is marked O_NONBLOCK or the socket does 37435 not support blocking to await out-of-band data. 37436 [EBADF] The socket argument is not a valid open file descriptor. 37437 [ECONNRESET] A connection was forcibly closed by a peer. 37438 [EINTR] This function was interrupted by a signal before any data was available. 37439 [EINVAL] The sum of the iov_len values overflows a ssize_t, or the MSG_OOB flag is set 37440 and no out-of-band data is available. 37441 [EMSGSIZE] The msg_iovlen member of the msghdr structure pointed to by message is less 37442 than or equal to 0, or is greater than {IOV_MAX}. 37443 [ENOTCONN] A receive is attempted on a connection-mode socket that is not connected. 37444 [ENOTSOCK] The socket argument does not refer to a socket. 37445 [EOPNOTSUPP] The specified flags are not supported for this socket type. 37446 [ETIMEDOUT] The connection timed out during connection establishment, or due to a 37447 transmission timeout on active connection. 37448 The recvmsg( ) function may fail if: 37449 [EIO] An I/O error occurred while reading from or writing to the file system. 37450 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 37451 [ENOMEM] Insufficient memory was available to fulfill the request. 1692 Technical Standard (2001) (Draft April 16, 2001) System Interfaces recvmsg( ) 37452 EXAMPLES 37453 None. 37454 APPLICATION USAGE 37455 The select( ) and poll( ) functions can be used to determine when data is available to be received. 37456 RATIONALE 37457 None. 37458 FUTURE DIRECTIONS 37459 None. 37460 SEE ALSO 37461 poll( ), recv( ), recvfrom( ), select( ), send( ), sendmsg( ), sendto( ), shutdown( ), socket( ), the Base 37462 Definitions volume of IEEE Std 1003.1-200x, 37463 CHANGE HISTORY 37464 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1693 regcomp( ) System Interfaces 37465 NAME 37466 regcomp, regerror, regexec, regfree - regular expression matching 37467 SYNOPSIS 37468 #include 37469 int regcomp(regex_t *restrict preg, const char *restrict pattern, int cflags); 37470 size_t regerror(int errcode, const regex_t *restrict preg, 37471 char *restrict errbuf, size_t errbuf_size); 37472 int regexec(const regex_t *restrict preg, const char *restrict string, 37473 size_t nmatch, regmatch_t pmatch[restrict], int eflags); 37474 void regfree(regex_t *preg); 37475 DESCRIPTION 37476 These functions interpret basic and extended regular expressions as described in the Base 37477 Definitions volume of IEEE Std 1003.1-200x, Chapter 9, Regular Expressions. 37478 The regex_t structure is defined in and contains at least the following member: | 37479 ________________________________________________________________________ 37480 _Member Type Member Name Description _______________________________________________________________________ 37481 _ size_t re_nsub Number of parenthesized subexpressions. _______________________________________________________________________ 37482 The regmatch_t structure is defined in and contains at least the following members: | 37483 _______________________________________________________________________________ 37484 _ Member Type Member Name Description ______________________________________________________________________________ 37485 regoff_t rm_so Byte offset from start of string to start of substring. 37486 regoff_t rm_eo Byte offset from start of string of the first character 37487 after the end of substring. _ ______________________________________________________________________________ 37488 The regcomp( ) function shall compile the regular expression contained in the string pointed to by 37489 the pattern argument and place the results in the structure pointed to by preg. The cflags | 37490 argument is the bitwise-inclusive OR of zero or more of the following flags, which are defined in | 37491 the header: | 37492 REG_EXTENDED Use Extended Regular Expressions. 37493 REG_ICASE Ignore case in match. (See the Base Definitions volume of 37494 IEEE Std 1003.1-200x, Chapter 9, Regular Expressions.) 37495 REG_NOSUB Report only success/fail in regexec( ). 37496 REG_NEWLINE Change the handling of s, as described in the text. 37497 The default regular expression type for pattern is a Basic Regular Expression. The application can 37498 specify Extended Regular Expressions using the REG_EXTENDED cflags flag. 37499 If the REG_NOSUB flag was not set in cflags, then regcomp( ) shall set re_nsub to the number of 37500 parenthesized subexpressions (delimited by "\(\)" in basic regular expressions or "( )" in 37501 extended regular expressions) found in pattern. 37502 The regexec( ) function compares the null-terminated string specified by string with the compiled 37503 regular expression preg initialized by a previous call to regcomp( ). If it finds a match, regexec( ) 37504 shall return 0; otherwise, it shall return non-zero indicating either no match or an error. The 37505 eflags argument is the bitwise-inclusive OR of zero or more of the following flags, which are 37506 defined in the header: 1694 Technical Standard (2001) (Draft April 16, 2001) System Interfaces regcomp( ) 37507 REG_NOTBOL The first character of the string pointed to by string is not the beginning of the 37508 line. Therefore, the circumflex character (' '), when taken as a special 37509 character, shall not match the beginning of string. 37510 REG_NOTEOL The last character of the string pointed to by string is not the end of the line. 37511 Therefore, the dollar sign ('$'), when taken as a special character, shall not 37512 match the end of string. 37513 If nmatch is 0 or REG_NOSUB was set in the cflags argument to regcomp( ), then regexec( ) shall 37514 ignore the pmatch argument. Otherwise, the application shall ensure that the pmatch argument 37515 points to an array with at least nmatch elements, and regexec( ) shall fill in the elements of that 37516 array with offsets of the substrings of string that correspond to the parenthesized subexpressions 37517 of pattern: pmatch[i].rm_so shall be the byte offset of the beginning and pmatch[i].rm_eo shall be 37518 one greater than the byte offset of the end of substring i. (Subexpression i begins at the ith 37519 matched open parenthesis, counting from 1.) Offsets in pmatch[0] identify the substring that 37520 corresponds to the entire regular expression. Unused elements of pmatch up to pmatch[nmatch-1] 37521 shall be filled with -1. If there are more than nmatch subexpressions in pattern (pattern itself 37522 counts as a subexpression), then regexec( ) shall still do the match, but shall record only the first 37523 nmatch substrings. 37524 When matching a basic or extended regular expression, any given parenthesized subexpression 37525 of pattern might participate in the match of several different substrings of string, or it might not 37526 match any substring even though the pattern as a whole did match. The following rules shall be | 37527 used to determine which substrings to report in pmatch when matching regular expressions: | 37528 1. If subexpression i in a regular expression is not contained within another subexpression, 37529 and it participated in the match several times, then the byte offsets in pmatch[i] shall 37530 delimit the last such match. 37531 2. If subexpression i is not contained within another subexpression, and it did not participate 37532 in an otherwise successful match, the byte offsets in pmatch[i] shall be -1. A subexpression 37533 does not participate in the match when: 37534 '*' or "\{\}" appears immediately after the subexpression in a basic regular | 37535 expression, or '*', '?', or "{ }" appears immediately after the subexpression in an | 37536 extended regular expression, and the subexpression did not match (matched 0 times) | 37537 or: 37538 '|' is used in an extended regular expression to select this subexpression or another, | 37539 and the other subexpression matched. | 37540 3. If subexpression i is contained within another subexpression j, and i is not contained 37541 within any other subexpression that is contained within j, and a match of subexpression j 37542 is reported in pmatch[j], then the match or non-match of subexpression i reported in 37543 pmatch[i] shall be as described in 1. and 2. above, but within the substring reported in 37544 pmatch[j] rather than the whole string. The offsets in pmatch[i] are still relative to the start 37545 of string. | 37546 4. If subexpression i is contained in subexpression j, and the byte offsets in pmatch[j] are -1, 37547 then the pointers in pmatch[i] shall also be -1. 37548 5. If subexpression i matched a zero-length string, then both byte offsets in pmatch[i] shall be 37549 the byte offset of the character or null terminator immediately following the zero-length 37550 string. 37551 If, when regexec( ) is called, the locale is different from when the regular expression was 37552 compiled, the result is undefined. System Interfaces, Issue 6 1695 regcomp( ) System Interfaces 37553 If REG_NEWLINE is not set in cflags, then a in pattern or string shall be treated as an 37554 ordinary character. If REG_NEWLINE is set, then shall be treated as an ordinary 37555 character except as follows: 37556 1. A in string shall not be matched by a period outside a bracket expression or by 37557 any form of a non-matching list (see the Base Definitions volume of IEEE Std 1003.1-200x, 37558 Chapter 9, Regular Expressions). 37559 2. A circumflex (' ') in pattern, when used to specify expression anchoring (see the Base 37560 Definitions volume of IEEE Std 1003.1-200x, Section 9.3.8, BRE Expression Anchoring), 37561 shall match the zero-length string immediately after a in string, regardless of 37562 the setting of REG_NOTBOL. 37563 3. A dollar sign ('$') in pattern, when used to specify expression anchoring, shall match the 37564 zero-length string immediately before a in string, regardless of the setting of 37565 REG_NOTEOL. 37566 The regfree( ) function frees any memory allocated by regcomp( ) associated with preg. 37567 The following constants are defined as error return values: 37568 REG_NOMATCH regexec( ) failed to match. 37569 REG_BADPAT Invalid regular expression. 37570 REG_ECOLLATE Invalid collating element referenced. 37571 REG_ECTYPE Invalid character class type referenced. 37572 REG_EESCAPE Trailing '\' in pattern. 37573 REG_ESUBREG Number in "\digit" invalid or in error. 37574 REG_EBRACK "[]" imbalance. 37575 REG_EPAREN "\(\)" or "()" imbalance. 37576 REG_EBRACE "\{\}" imbalance. 37577 REG_BADBR Content of "\{\}" invalid: not a number, number too large, more than 37578 two numbers, first larger than second. 37579 REG_ERANGE Invalid endpoint in range expression. 37580 REG_ESPACE Out of memory. 37581 REG_BADRPT '?', '*', or '+' not preceded by valid regular expression. 37582 The regerror( ) function provides a mapping from error codes returned by regcomp( ) and 37583 regexec( ) to unspecified printable strings. It generates a string corresponding to the value of the 37584 errcode argument, which the application shall ensure is the last non-zero value returned by 37585 regcomp( ) or regexec( ) with the given value of preg. If errcode is not such a value, the content of 37586 the generated string is unspecified. 37587 If preg is a null pointer, but errcode is a value returned by a previous call to regexec( ) or regcomp( ), 37588 the regerror( ) still generates an error string corresponding to the value of errcode, but it might not 37589 be as detailed under some implementations. 37590 If the errbuf_size argument is not 0, regerror( ) shall place the generated string into the buffer of 37591 size errbuf_size bytes pointed to by errbuf. If the string (including the terminating null) cannot fit 37592 in the buffer, regerror( ) shall truncate the string and null-terminates the result. 1696 Technical Standard (2001) (Draft April 16, 2001) System Interfaces regcomp( ) 37593 If errbuf_size is 0, regerror( ) shall ignore the errbuf argument, and return the size of the buffer 37594 needed to hold the generated string. 37595 If the preg argument to regexec( ) or regfree( ) is not a compiled regular expression returned by 37596 regcomp( ), the result is undefined. A preg is no longer treated as a compiled regular expression 37597 after it is given to regfree( ). 37598 RETURN VALUE 37599 Upon successful completion, the regcomp( ) function shall return 0. Otherwise, it shall return an 37600 integer value indicating an error as described in , and the content of preg is undefined. 37601 If a code is returned, the interpretation shall be as given in . 37602 If regcomp( ) detects an invalid RE, it may return REG_BADPAT, or it may return one of the error 37603 codes that more precisely describes the error. 37604 Upon successful completion, the regexec( ) function shall return 0. Otherwise, it shall return 37605 REG_NOMATCH to indicate no match. 37606 Upon successful completion, the regerror( ) function shall return the number of bytes needed to 37607 hold the entire generated string, including the null termination. If the return value is greater than 37608 errbuf_size, the string returned in the buffer pointed to by errbuf has been truncated. 37609 The regfree( ) function shall not return a value. 37610 ERRORS 37611 No errors are defined. 37612 EXAMPLES 37613 #include 37614 /* 37615 * Match string against the extended regular expression in 37616 * pattern, treating errors as no match. 37617 * 37618 * Return 1 for match, 0 for no match. 37619 */ 37620 int 37621 match(const char *string, char *pattern) 37622 { 37623 int status; 37624 regex_t re; 37625 if (regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) != 0) { 37626 return(0); /* Report error. */ 37627 } 37628 status = regexec(&re, string, (size_t) 0, NULL, 0); 37629 regfree(&re); 37630 if (status != 0) { 37631 return(0); /* Report error. */ 37632 } 37633 return(1); 37634 } 37635 The following demonstrates how the REG_NOTBOL flag could be used with regexec( ) to find all 37636 substrings in a line that match a pattern supplied by a user. (For simplicity of the example, very 37637 little error checking is done.) System Interfaces, Issue 6 1697 regcomp( ) System Interfaces 37638 (void) regcomp (&re, pattern, 0); 37639 /* This call to regexec() finds the first match on the line. */ 37640 error = regexec (&re, &buffer[0], 1, &pm, 0); 37641 while (error == 0) { /* While matches found. */ 37642 /* Substring found between pm.rm_so and pm.rm_eo. */ 37643 /* This call to regexec() finds the next match. */ 37644 error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); 37645 } 37646 APPLICATION USAGE 37647 An application could use: 37648 regerror(code,preg,(char *)NULL,(size_t)0) 37649 to find out how big a buffer is needed for the generated string, malloc( ) a buffer to hold the 37650 string, and then call regerror( ) again to get the string. Alternatively, it could allocate a fixed, 37651 static buffer that is big enough to hold most strings, and then use malloc( ) to allocate a larger 37652 buffer if it finds that this is too small. 37653 To match a pattern as described in the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 37654 2.13, Pattern Matching Notation, use the fnmatch( ) function. 37655 RATIONALE 37656 The regmatch( ) function must fill in all nmatch elements of pmatch, where nmatch and pmatch are 37657 supplied by the application, even if some elements of pmatch do not correspond to 37658 subexpressions in pattern. The application writer should note that there is probably no reason 37659 for using a value of nmatch that is larger than preg->re_nsub+1. 37660 The REG_NEWLINE flag supports a use of RE matching that is needed in some applications like 37661 text editors. In such applications, the user supplies an RE asking the application to find a line 37662 that matches the given expression. An anchor in such an RE anchors at the beginning or end of 37663 any line. Such an application can pass a sequence of -separated lines to regexec( ) as a 37664 single long string and specify REG_NEWLINE to regcomp( ) to get the desired behavior. The 37665 application must ensure that there are no explicit s in pattern if it wants to ensure that 37666 any match occurs entirely within a single line. 37667 The REG_NEWLINE flag affects the behavior of regexec( ), but it is in the cflags parameter to 37668 regcomp( ) to allow flexibility of implementation. Some implementations will want to generate 37669 the same compiled RE in regcomp( ) regardless of the setting of REG_NEWLINE and have 37670 regexec( ) handle anchors differently based on the setting of the flag. Other implementations will 37671 generate different compiled REs based on the REG_NEWLINE. 37672 The REG_ICASE flag supports the operations taken by the grep -i option and the historical 37673 implementations of ex and vi. Including this flag will make it easier for application code to be 37674 written that does the same thing as these utilities. 37675 The substrings reported in pmatch[ ] are defined using offsets from the start of the string rather 37676 than pointers. Since this is a new interface, there should be no impact on historical 37677 implementations or applications, and offsets should be just as easy to use as pointers. The 37678 change to offsets was made to facilitate future extensions in which the string to be searched is 37679 presented to regexec( ) in blocks, allowing a string to be searched that is not all in memory at 37680 once. 37681 A new type regoff_t is used for the elements of pmatch[ ] to ensure that the application can 37682 represent either the largest possible array in memory (important for an application conforming 37683 to the Shell and Utilities volume of IEEE Std 1003.1-200x) or the largest possible file (important 37684 for an application using the extension where a file is searched in chunks). 1698 Technical Standard (2001) (Draft April 16, 2001) System Interfaces regcomp( ) 37685 The standard developers rejected the inclusion of a regsub( ) function that would be used to do 37686 substitutions for a matched RE. While such a routine would be useful to some applications, its 37687 utility would be much more limited than the matching function described here. Both RE parsing 37688 and substitution are possible to implement without support other than that required by the 37689 ISO C standard, but matching is much more complex than substituting. The only difficult part of 37690 substitution, given the information supplied by regexec( ), is finding the next character in a string 37691 when there can be multi-byte characters. That is a much larger issue, and one that needs a more 37692 general solution. 37693 The errno variable has not been used for error returns to avoid filling the errno name space for 37694 this feature. 37695 The interface is defined so that the matched substrings rm_sp and rm_ep are in a separate 37696 regmatch_t structure instead of in regex_t. This allows a single compiled RE to be used 37697 simultaneously in several contexts; in main( ) and a signal handler, perhaps, or in multiple 37698 threads of lightweight processes. (The preg argument to regexec( ) is declared with type const, so 37699 the implementation is not permitted to use the structure to store intermediate results.) It also 37700 allows an application to request an arbitrary number of substrings from an RE. The number of 37701 subexpressions in the RE is reported in re_nsub in preg. With this change to regexec( ), 37702 consideration was given to dropping the REG_NOSUB flag since the user can now specify this 37703 with a zero nmatch argument to regexec( ). However, keeping REG_NOSUB allows an 37704 implementation to use a different (perhaps more efficient) algorithm if it knows in regcomp( ) 37705 that no subexpressions need be reported. The implementation is only required to fill in pmatch if 37706 nmatch is not zero and if REG_NOSUB is not specified. Note that the size_t type, as defined in 37707 the ISO C standard, is unsigned, so the description of regexec( ) does not need to address 37708 negative values of nmatch. 37709 REG_NOTBOL was added to allow an application to do repeated searches for the same pattern 37710 in a line. If the pattern contains a circumflex character that should match the beginning of a line, 37711 then the pattern should only match when matched against the beginning of the line. Without 37712 the REG_NOTBOL flag, the application could rewrite the expression for subsequent matches, 37713 but in the general case this would require parsing the expression. The need for REG_NOTEOL is 37714 not as clear; it was added for symmetry. 37715 The addition of the regerror( ) function addresses the historical need for conforming application | 37716 programs to have access to error information more than ``Function failed to compile/match your 37717 RE for unknown reasons''. 37718 This interface provides for two different methods of dealing with error conditions. The specific 37719 error codes (REG_EBRACE, for example), defined in , allow an application to recover 37720 from an error if it is so able. Many applications, especially those that use patterns supplied by a 37721 user, will not try to deal with specific error cases, but will just use regerror( ) to obtain a human- 37722 readable error message to present to the user. 37723 The regerror( ) function uses a scheme similar to confstr( ) to deal with the problem of allocating 37724 memory to hold the generated string. The scheme used by strerror( ) in the ISO C standard was 37725 considered unacceptable since it creates difficulties for multi-threaded applications. 37726 The preg argument is provided to regerror( ) to allow an implementation to generate a more 37727 descriptive message than would be possible with errcode alone. An implementation might, for 37728 example, save the character offset of the offending character of the pattern in a field of preg, and 37729 then include that in the generated message string. The implementation may also ignore preg. 37730 A REG_FILENAME flag was considered, but omitted. This flag caused regexec( ) to match 37731 patterns as described in the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 2.13, 37732 Pattern Matching Notation instead of REs. This service is now provided by the fnmatch( ) System Interfaces, Issue 6 1699 regcomp( ) System Interfaces 37733 function. 37734 Notice that there is a difference in philosophy between the ISO POSIX-2: 1993 standard and 37735 IEEE Std 1003.1-200x in how to handle a bad regular expression. The ISO POSIX-2: 1993 standard 37736 says that many bad constructs produce undefined results, or that the interpretation is undefined. 37737 IEEE Std 1003.1-200x, however, says that the interpretation of such REs is unspecified. The term 37738 ``undefined'' means that the action by the application is an error, of similar severity to passing a 37739 bad pointer to a function. 37740 The regcomp( ) and regexec( ) functions are required to accept any null-terminated string as the 37741 pattern argument. If the meaning of the string is undefined, the behavior of the function is 37742 unspecified. IEEE Std 1003.1-200x does not specify how the functions will interpret the pattern; 37743 they might return error codes, or they might do pattern matching in some completely 37744 unexpected way, but they should not do something like abort the process. 37745 FUTURE DIRECTIONS 37746 None. 37747 SEE ALSO 37748 fnmatch( ), glob( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 37749 CHANGE HISTORY 37750 First released in Issue 4. Derived from the ISO POSIX-2 standard. 37751 Issue 5 37752 Moved from POSIX2 C-language Binding to BASE. 37753 Issue 6 37754 In the SYNOPSIS, the optional include of the header is removed. 37755 The following new requirements on POSIX implementations derive from alignment with the 37756 Single UNIX Specification: 37757 * The requirement to include has been removed. Although was 37758 required for conforming implementations of previous POSIX specifications, it was not 37759 required for UNIX applications. 37760 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 37761 The REG_ENOSYS constant is removed. 37762 The restrict keyword is added to the regcomp( ), regerror( ), and regexec( ) prototypes for 37763 alignment with the ISO/IEC 9899: 1999 standard. 1700 Technical Standard (2001) (Draft April 16, 2001) System Interfaces remainder( ) 37764 NAME 37765 remainder, remainderf, remainderl - remainder function 37766 SYNOPSIS 37767 #include 37768 double remainder(double x, double y); 37769 float remainderf(float x, float y); 37770 long double remainderl(long double x, long double y); 37771 DESCRIPTION 37772 CX The functionality described on this reference page is aligned with the ISO C standard. Any 37773 conflict between the requirements described here and the ISO C standard is unintentional. This 37774 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 37775 These functions shall return the floating-point remainder r=x-ny when y is non-zero. The value 37776 n is the integral value nearest the exact value x/y. When | n-x/y |=1 2, the value n is chosen to 37777 be even. 37778 The behavior of remainder( ) shall be independent of the rounding mode. 37779 RETURN VALUE 37780 Upon successful completion, these functions shall return the floating-point remainder r=x-ny 37781 when y is non-zero. 37782 MX If x or y is NaN, a NaN shall be returned. 37783 If x is infinite or y is 0 and the other is non-NaN, a domain error shall occur, and either a NaN (if 37784 supported), or an implementation-defined value shall be returned. 37785 ERRORS 37786 These functions shall fail if: 37787 MX Domain Error The x argument is ±Inf, or the y argument is ±0 and the other argument is 37788 non-NaN. 37789 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 37790 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 37791 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 37792 shall be raised. | 37793 EXAMPLES 37794 None. 37795 APPLICATION USAGE 37796 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 37797 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 37798 RATIONALE 37799 None. 37800 FUTURE DIRECTIONS 37801 None. 37802 SEE ALSO 37803 abs( ), div( ), feclearexcept( ), fetestexcept( ), ldiv( ), the Base Definitions volume of | 37804 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 37805 System Interfaces, Issue 6 1701 remainder( ) System Interfaces 37806 CHANGE HISTORY 37807 First released in Issue 4, Version 2. 37808 Issue 5 37809 Moved from X/OPEN UNIX extension to BASE. 37810 Issue 6 37811 The remainder( ) function is no longer marked as an extension. 37812 The remainderf( ) and remainderl( ) functions are added for alignment with the ISO/IEC 9899: 1999 37813 standard. 37814 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 37815 revised to align with the ISO/IEC 9899: 1999 standard. 37816 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 37817 marked. 1702 Technical Standard (2001) (Draft April 16, 2001) System Interfaces remove( ) 37818 NAME 37819 remove - remove a file 37820 SYNOPSIS 37821 #include 37822 int remove(const char *path); 37823 DESCRIPTION 37824 CX The functionality described on this reference page is aligned with the ISO C standard. Any 37825 conflict between the requirements described here and the ISO C standard is unintentional. This 37826 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 37827 The remove( ) function shall cause the file named by the pathname pointed to by path to be no | 37828 longer accessible by that name. A subsequent attempt to open that file using that name shall fail, 37829 unless it is created anew. 37830 CX If path does not name a directory, remove(path) shall be equivalent to unlink(path). 37831 If path names a directory, remove(path) shall be equivalent to rmdir(path). 37832 RETURN VALUE 37833 CX Refer to rmdir( ) or unlink( ). 37834 ERRORS 37835 CX Refer to rmdir( ) or unlink( ). 37836 EXAMPLES 37837 Removing Access to a File 37838 The following example shows how to remove access to a file named /home/cnd/old_mods. 37839 #include 37840 int status; 37841 ... 37842 status = remove("/home/cnd/old_mods"); 37843 APPLICATION USAGE 37844 None. 37845 RATIONALE 37846 None. 37847 FUTURE DIRECTIONS 37848 None. 37849 SEE ALSO 37850 rmdir( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 37851 CHANGE HISTORY 37852 First released in Issue 3. 37853 Entry included for alignment with the POSIX.1-1988 standard and the ISO C standard. 37854 Issue 6 37855 Extensions beyond the ISO C standard are now marked. 37856 The following new requirements on POSIX implementations derive from alignment with the 37857 Single UNIX Specification: System Interfaces, Issue 6 1703 remove( ) System Interfaces 37858 * The DESCRIPTION, RETURN VALUE, and ERRORS sections are updated so that if path is 37859 not a directory, remove( ) is equivalent to unlink( ), and if it is a directory, it is equivalent to 37860 rmdir( ). 1704 Technical Standard (2001) (Draft April 16, 2001) System Interfaces remque( ) 37861 NAME 37862 remque - remove an element from a queue 37863 SYNOPSIS 37864 XSI #include 37865 void remque(void *element); 37866 37867 DESCRIPTION 37868 Refer to insque( ). System Interfaces, Issue 6 1705 remquo( ) System Interfaces 37869 NAME 37870 remquo, remquof, remquol - remainder functions 37871 SYNOPSIS 37872 #include 37873 double remquo(double x, double y, int *quo); 37874 float remquof(float x, float y, int *quo); 37875 long double remquol(long double x, long double y, int *quo); 37876 DESCRIPTION 37877 CX The functionality described on this reference page is aligned with the ISO C standard. Any 37878 conflict between the requirements described here and the ISO C standard is unintentional. This 37879 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 37880 The remquo( ), remquof( ), and remquol( ) functions shall compute the same remainder as the 37881 remainder( ), remainderf( ), and remainderl( ) functions, respectively. In the object pointed to by 37882 quo, they store a value whose sign is the sign of x/y and whose magnitude is congruent modulo 37883 2n to the magnitude of the integral quotient of x/y, where n is an implementation-defined 37884 integer greater than or equal to 3. 37885 An application wishing to check for error situations should set errno to zero and call 37886 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 37887 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 37888 zero, an error has occurred. 37889 RETURN VALUE 37890 These functions shall return x REM y. 37891 MX If x or y is NaN, a NaN shall be returned. 37892 If x is ±Inf or y is zero and the other argument is non-NaN, a domain error shall occur, and either 37893 a NaN (if supported), or an implementation-defined value shall be returned. 37894 ERRORS 37895 These functions shall fail if: 37896 MX Domain Error The x argument is ±Inf, or the y argument is ±0 and the other argument is 37897 non-NaN. 37898 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 37899 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 37900 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 37901 shall be raised. | 37902 EXAMPLES 37903 None. 37904 APPLICATION USAGE 37905 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 37906 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 37907 RATIONALE 37908 These functions are intended for implementing argument reductions which can exploit a few 37909 low-order bits of the quotient. Note that x may be so large in magnitude relative to y that an 37910 exact representation of the quotient is not practical. 1706 Technical Standard (2001) (Draft April 16, 2001) System Interfaces remquo( ) 37911 FUTURE DIRECTIONS 37912 None. 37913 SEE ALSO 37914 feclearexcept( ), fetestexcept( ), remainder( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 37915 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 37916 CHANGE HISTORY 37917 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1707 rename( ) System Interfaces 37918 NAME 37919 rename - rename a file 37920 SYNOPSIS 37921 #include 37922 int rename(const char *old, const char *new); 37923 DESCRIPTION 37924 CX The functionality described on this reference page is aligned with the ISO C standard. Any 37925 conflict between the requirements described here and the ISO C standard is unintentional. This 37926 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 37927 The rename( ) function shall change the name of a file. The old argument points to the pathname | 37928 of the file to be renamed. The new argument points to the new pathname of the file. | 37929 CX If either the old or new argument names a symbolic link, rename( ) shall operate on the symbolic | 37930 link itself, and shall not resolve the last component of the argument. If the old argument and the | 37931 new argument resolve to the same existing file, rename( ) shall return successfully and perform no | 37932 other action. 37933 If the old argument points to the pathname of a file that is not a directory, the new argument shall | 37934 not point to the pathname of a directory. If the link named by the new argument exists, it shall be | 37935 removed and old renamed to new. In this case, a link named new shall remain visible to other 37936 processes throughout the renaming operation and refer either to the file referred to by new or old 37937 before the operation began. Write access permission is required for both the directory containing 37938 old and the directory containing new. 37939 If the old argument points to the pathname of a directory, the new argument shall not point to the | 37940 pathname of a file that is not a directory. If the directory named by the new argument exists, it | 37941 shall be removed and old renamed to new. In this case, a link named new shall exist throughout 37942 the renaming operation and shall refer either to the directory referred to by new or old before the 37943 operation began. If new names an existing directory, it shall be required to be an empty directory. 37944 If the old argument points to a pathname of a symbolic link, the symbolic link shall be renamed. | 37945 If the new argument points to a pathname of a symbolic link, the symbolic link shall be removed. | 37946 The new pathname shall not contain a path prefix that names old. Write access permission is | 37947 required for the directory containing old and the directory containing new. If the old argument | 37948 points to the pathname of a directory, write access permission may be required for the directory | 37949 named by old, and, if it exists, the directory named by new. 37950 If the link named by the new argument exists and the file's link count becomes 0 when it is 37951 removed and no process has the file open, the space occupied by the file shall be freed and the 37952 file shall no longer be accessible. If one or more processes have the file open when the last link is 37953 removed, the link shall be removed before rename( ) returns, but the removal of the file contents 37954 shall be postponed until all references to the file are closed. 37955 Upon successful completion, rename( ) shall mark for update the st_ctime and st_mtime fields of 37956 the parent directory of each file. 37957 If the rename( ) function fails for any reason other than [EIO], any file named by new shall be 37958 unaffected. 37959 RETURN VALUE 37960 CX Upon successful completion, rename( ) shall return 0; otherwise, -1 shall be returned,errno shall 37961 be set to indicate the error, and neither the file named by old nor the file named by new shall be 37962 changed or created. 1708 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rename( ) 37963 ERRORS 37964 The rename( ) function shall fail if: 37965 CX [EACCES] A component of either path prefix denies search permission; or one of the 37966 directories containing old or new denies write permissions; or, write 37967 permission is required and is denied for a directory pointed to by the old or 37968 new arguments. 37969 CX [EBUSY] The directory named by old or new is currently in use by the system or another 37970 process, and the implementation considers this an error. 37971 CX [EEXIST] or [ENOTEMPTY] 37972 The link named by new is a directory that is not an empty directory. 37973 CX [EINVAL] The new directory pathname contains a path prefix that names the old | 37974 directory. 37975 CX [EIO] A physical I/O error has occurred. 37976 CX [EISDIR] The new argument points to a directory and the old argument points to a file 37977 that is not a directory. 37978 CX [ELOOP] A loop exists in symbolic links encountered during resolution of the path 37979 argument. 37980 CX [EMLINK] The file named by old is a directory, and the link count of the parent directory 37981 of new would exceed {LINK_MAX}. 37982 CX [ENAMETOOLONG] 37983 The length of the old or new argument exceeds {PATH_MAX} or a pathname | 37984 component is longer than {NAME_MAX}. | 37985 CX [ENOENT] The link named by old does not name an existing file, or either old or new 37986 points to an empty string. 37987 CX [ENOSPC] The directory that would contain new cannot be extended. 37988 CX [ENOTDIR] A component of either path prefix is not a directory; or the old argument 37989 names a directory and new argument names a non-directory file. 37990 XSI [EPERM] or [EACCES] 37991 The S_ISVTX flag is set on the directory containing the file referred to by old 37992 and the caller is not the file owner, nor is the caller the directory owner, nor 37993 does the caller have appropriate privileges; or new refers to an existing file, the 37994 S_ISVTX flag is set on the directory containing this file, and the caller is not 37995 the file owner, nor is the caller the directory owner, nor does the caller have 37996 appropriate privileges. 37997 CX [EROFS] The requested operation requires writing in a directory on a read-only file 37998 system. 37999 CX [EXDEV] The links named by new and old are on different file systems and the 38000 implementation does not support links between file systems. 38001 The rename( ) function may fail if: 38002 XSI [EBUSY] The file named by the old or new arguments is a named STREAM. 38003 CX [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 38004 resolution of the path argument. System Interfaces, Issue 6 1709 rename( ) System Interfaces 38005 CX [ENAMETOOLONG] 38006 As a result of encountering a symbolic link in resolution of the path argument, | 38007 the length of the substituted pathname string exceeded {PATH_MAX}. | 38008 CX [ETXTBSY] The file to be renamed is a pure procedure (shared text) file that is being 38009 executed. 38010 EXAMPLES 38011 Renaming a File 38012 The following example shows how to rename a file named /home/cnd/mod1 to 38013 /home/cnd/mod2. 38014 #include 38015 int status; 38016 ... 38017 status = rename("/home/cnd/mod1", "/home/cnd/mod2"); 38018 APPLICATION USAGE 38019 Some implementations mark for update the st_ctime field of renamed files and some do not. | 38020 Applications which make use of the st_ctime field may behave differently with respect to | 38021 renamed files unless they are designed to allow for either behavior. | 38022 RATIONALE 38023 This rename( ) function is equivalent for regular files to that defined by the ISO C standard. Its 38024 inclusion here expands that definition to include actions on directories and specifies behavior 38025 when the new parameter names a file that already exists. That specification requires that the 38026 action of the function be atomic. 38027 One of the reasons for introducing this function was to have a means of renaming directories 38028 while permitting implementations to prohibit the use of link( ) and unlink( ) with directories, 38029 thus constraining links to directories to those made by mkdir( ). 38030 The specification that if old and new refer to the same file is intended to guarantee that: 38031 rename("x", "x"); 38032 does not remove the file. 38033 Renaming dot or dot-dot is prohibited in order to prevent cyclical file system paths. 38034 See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir( ) and [EBUSY] in 38035 unlink( ). For a discussion of [EXDEV], see link( ). 38036 FUTURE DIRECTIONS 38037 None. 38038 SEE ALSO 38039 link( ), rmdir( ), symlink( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38040 38041 CHANGE HISTORY 38042 First released in Issue 3. 38043 Entry included for alignment with the POSIX.1-1988 standard. 1710 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rename( ) 38044 Issue 5 38045 The [EBUSY] error is added to the ``may fail'' part of the ERRORS section. 38046 Issue 6 38047 Extensions beyond the ISO C standard are now marked. 38048 The following new requirements on POSIX implementations derive from alignment with the | 38049 Single UNIX Specification: 38050 * The [EIO] mandatory error condition is added. 38051 * The [ELOOP] mandatory error condition is added. 38052 * A second [ENAMETOOLONG] is added as an optional error condition. 38053 * The [ETXTBSY] optional error condition is added. 38054 The following changes were made to align with the IEEE P1003.1a draft standard: 38055 * Details are added regarding the treatment of symbolic links. 38056 * The [ELOOP] optional error condition is added. 38057 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1711 rewind( ) System Interfaces 38058 NAME 38059 rewind - reset file position indicator in a stream 38060 SYNOPSIS 38061 #include 38062 void rewind(FILE *stream); 38063 DESCRIPTION 38064 CX The functionality described on this reference page is aligned with the ISO C standard. Any 38065 conflict between the requirements described here and the ISO C standard is unintentional. This 38066 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 38067 The call: 38068 rewind(stream) 38069 shall be equivalent to: 38070 (void) fseek(stream, 0L, SEEK_SET) 38071 except that rewind( ) shall also clear the error indicator. | 38072 CX Since rewind( ) does not return a value, an application wishing to detect errors should clear errno, | 38073 then call rewind( ), and if errno is non-zero, assume an error has occurred. 38074 RETURN VALUE 38075 The rewind( ) function shall not return a value. 38076 ERRORS 38077 CX Refer to fseek( ) with the exception of [EINVAL] which does not apply. 38078 EXAMPLES 38079 None. 38080 APPLICATION USAGE 38081 None. 38082 RATIONALE 38083 None. 38084 FUTURE DIRECTIONS 38085 None. 38086 SEE ALSO 38087 fseek( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38088 CHANGE HISTORY 38089 First released in Issue 1. Derived from Issue 1 of the SVID. 38090 Issue 6 38091 Extensions beyond the ISO C standard are now marked. 1712 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rewinddir( ) 38092 NAME 38093 rewinddir - reset position of directory stream to the beginning of a directory 38094 SYNOPSIS 38095 #include 38096 void rewinddir(DIR *dirp); 38097 DESCRIPTION 38098 The rewinddir( ) function shall reset the position of the directory stream to which dirp refers to 38099 the beginning of the directory. It shall also cause the directory stream to refer to the current state 38100 of the corresponding directory, as a call to opendir( ) would have done. If dirp does not refer to a 38101 directory stream, the effect is undefined. 38102 After a call to the fork( ) function, either the parent or child (but not both) may continue 38103 XSI processing the directory stream using readdir( ), rewinddir( ), or seekdir( ). If both the parent and 38104 child processes use these functions, the result is undefined. 38105 RETURN VALUE 38106 The rewinddir( ) function shall not return a value. 38107 ERRORS 38108 No errors are defined. 38109 EXAMPLES 38110 None. 38111 APPLICATION USAGE 38112 The rewinddir( ) function should be used in conjunction with opendir( ), readdir( ), and closedir( ) to 38113 examine the contents of the directory. This method is recommended for portability. 38114 RATIONALE 38115 None. 38116 FUTURE DIRECTIONS 38117 None. 38118 SEE ALSO 38119 closedir( ), opendir( ), readdir( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38120 38121 CHANGE HISTORY 38122 First released in Issue 2. 38123 Issue 6 38124 In the SYNOPSIS, the optional include of the header is removed. 38125 The following new requirements on POSIX implementations derive from alignment with the 38126 Single UNIX Specification: 38127 * The requirement to include has been removed. Although was 38128 required for conforming implementations of previous POSIX specifications, it was not 38129 required for UNIX applications. System Interfaces, Issue 6 1713 rindex( ) System Interfaces 38130 NAME 38131 rindex - character string operations (LEGACY) 38132 SYNOPSIS 38133 XSI #include 38134 char *rindex(const char *s, int c); 38135 38136 DESCRIPTION 38137 The rindex( ) function shall be equivalent to strrchr( ). | 38138 RETURN VALUE 38139 Refer to strrchr( ). 38140 ERRORS 38141 Refer to strrchr( ). 38142 EXAMPLES 38143 None. 38144 APPLICATION USAGE 38145 strrchr( ) is preferred over this function. 38146 For maximum portability, it is recommended to replace the function call to rindex( ) as follows: 38147 #define rindex(a,b) strrchr((a),(b)) 38148 RATIONALE 38149 None. 38150 FUTURE DIRECTIONS 38151 This function may be withdrawn in a future version. 38152 SEE ALSO 38153 strrchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38154 CHANGE HISTORY 38155 First released in Issue 4, Version 2. 38156 Issue 5 38157 Moved from X/OPEN UNIX extension to BASE. 38158 Issue 6 38159 This function is marked LEGACY. 1714 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rint( ) 38160 NAME 38161 rint, rintf, rintl - round-to-nearest integral value 38162 SYNOPSIS 38163 #include 38164 double rint(double x); 38165 float rintf(float x); 38166 long double rintl(long double x); 38167 DESCRIPTION 38168 CX The functionality described on this reference page is aligned with the ISO C standard. Any 38169 conflict between the requirements described here and the ISO C standard is unintentional. This 38170 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 38171 These functions shall return the integral value (represented as a double) nearest x in the 38172 direction of the current rounding mode. The current rounding mode is implementation-defined. 38173 If the current rounding mode rounds toward negative infinity, then rint( ) shall be equivalent to | 38174 floor( ). If the current rounding mode rounds toward positive infinity, then rint( ) shall be | 38175 equivalent to ceil( ). | 38176 These functions differ from the nearbyint( ), nearbyintf( ), and nearbyintl( ) functions only in that 38177 they may raise the inexact floating-point exception if the result differs in value from the 38178 argument. 38179 An application wishing to check for error situations should set errno to zero and call 38180 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 38181 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 38182 zero, an error has occurred. 38183 RETURN VALUE 38184 Upon successful completion, these functions shall return the integer (represented as a double 38185 precision number) nearest x in the direction of the current rounding mode. 38186 MX If x is NaN, a NaN shall be returned. 38187 If x is ±0, or ±Inf, x shall be returned. 38188 XSI If the correct value would cause overflow, a range error shall occur and rint( ), rintf( ), and rintl( ) 38189 shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 38190 ERRORS 38191 These functions shall fail if: 38192 XSI Range Error The result would cause an overflow. 38193 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38194 then errno shall be set to [ERANGE]. If the integer expression | 38195 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 38196 floating-point exception shall be raised. | System Interfaces, Issue 6 1715 rint( ) System Interfaces 38197 EXAMPLES 38198 None. 38199 APPLICATION USAGE 38200 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 38201 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 38202 RATIONALE 38203 None. 38204 FUTURE DIRECTIONS 38205 None. 38206 SEE ALSO 38207 abs( ), ceil( ), feclearexcept( ), fetestexcept( ), nearbyint( ), floor( ), isnan( ), the Base Definitions volume | 38208 of IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 38209 38210 CHANGE HISTORY 38211 First released in Issue 4, Version 2. 38212 Issue 5 38213 Moved from X/OPEN UNIX extension to BASE. 38214 Issue 6 38215 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 38216 * The rintf( ) and rintl( ) functions are added. 38217 * The rint( ) function is no longer marked as an extension. 38218 * The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 38219 revised to align with the ISO/IEC 9899: 1999 standard. 38220 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 38221 marked. 1716 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rmdir( ) 38222 NAME 38223 rmdir - remove a directory 38224 SYNOPSIS 38225 #include 38226 int rmdir(const char *path); 38227 DESCRIPTION 38228 The rmdir( ) function shall remove a directory whose name is given by path. The directory shall | 38229 be removed only if it is an empty directory. | 38230 If the directory is the root directory or the current working directory of any process, it is 38231 unspecified whether the function succeeds, or whether it shall fail and set errno to [EBUSY]. 38232 If path names a symbolic link, then rmdir( ) shall fail and set errno to [ENOTDIR]. 38233 If the path argument refers to a path whose final component is either dot or dot-dot, rmdir( ) shall 38234 fail. 38235 If the directory's link count becomes 0 and no process has the directory open, the space occupied 38236 by the directory shall be freed and the directory shall no longer be accessible. If one or more 38237 processes have the directory open when the last link is removed, the dot and dot-dot entries, if 38238 present, shall be removed before rmdir( ) returns and no new entries may be created in the 38239 directory, but the directory shall not be removed until all references to the directory are closed. 38240 If the directory is not an empty directory, rmdir( ) shall fail and set errno to [EEXIST] or 38241 [ENOTEMPTY]. 38242 Upon successful completion, the rmdir( ) function shall mark for update the st_ctime and 38243 st_mtime fields of the parent directory. 38244 RETURN VALUE 38245 Upon successful completion, the function rmdir( ) shall return 0. Otherwise, -1 shall be returned, 38246 and errno set to indicate the error. If -1 is returned, the named directory shall not be changed. 38247 ERRORS 38248 The rmdir( ) function shall fail if: 38249 [EACCES] Search permission is denied on a component of the path prefix, or write 38250 permission is denied on the parent directory of the directory to be removed. 38251 [EBUSY] The directory to be removed is currently in use by the system or some process 38252 and the implementation considers this to be an error. 38253 [EEXIST] or [ENOTEMPTY] 38254 The path argument names a directory that is not an empty directory, or there 38255 are hard links to the directory other than dot or a single entry in dot-dot. 38256 [EINVAL] The path argument contains a last component that is dot. 38257 [EIO] A physical I/O error has occurred. 38258 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 38259 argument. 38260 [ENAMETOOLONG] 38261 The length of the path argument exceeds {PATH_MAX} or a pathname | 38262 component is longer than | 38263 NAME_MAX System Interfaces, Issue 6 1717 rmdir( ) System Interfaces 38264 [ENOENT] A component of path does not name an existing file, or the path argument 38265 names a nonexistent directory or points to an empty string. 38266 [ENOTDIR] A component of path is not a directory. 38267 XSI [EPERM] or [EACCES] 38268 The S_ISVTX flag is set on the parent directory of the directory to be removed 38269 and the caller is not the owner of the directory to be removed, nor is the caller 38270 the owner of the parent directory, nor does the caller have the appropriate 38271 privileges. 38272 [EROFS] The directory entry to be removed resides on a read-only file system. 38273 The rmdir( ) function may fail if: 38274 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 38275 resolution of the path argument. 38276 [ENAMETOOLONG] 38277 As a result of encountering a symbolic link in resolution of the path argument, | 38278 the length of the substituted pathname string exceeded {PATH_MAX}. | 38279 EXAMPLES 38280 Removing a Directory 38281 The following example shows how to remove a directory named /home/cnd/mod1. 38282 #include 38283 int status; 38284 ... 38285 status = rmdir("/home/cnd/mod1"); 38286 APPLICATION USAGE 38287 None. 38288 RATIONALE 38289 The rmdir( ) and rename( ) functions originated in 4.2 BSD, and they used [ENOTEMPTY] for the 38290 condition when the directory to be removed does not exist or new already exists. When the 1984 38291 /usr/group standard was published, it contained [EEXIST] instead. When these functions were 38292 adopted into System V, the 1984 /usr/group standard was used as a reference. Therefore, several 38293 existing applications and implementations support/use both forms, and no agreement could be 38294 reached on either value. All implementations are required to supply both [EEXIST] and 38295 [ENOTEMPTY] in with distinct values, so that applications can use both values in C- 38296 language case statements. 38297 The meaning of deleting pathname/dot is unclear, because the name of the file (directory) in the 38298 parent directory to be removed is not clear, particularly in the presence of multiple links to a 38299 directory. 38300 IEEE Std 1003.1-200x was silent with regard to the behavior of rmdir( ) when there are multiple 38301 hard links to the directory being removed. The requirement to set errno to [EEXIST] or 38302 [ENOTEMPTY] clarifies the behavior in this case. 38303 If the process' current working directory is being removed, that should be an allowed error. | 38304 Virtually all existing implementations detect [ENOTEMPTY] or the case of dot-dot. The text in 38305 Section 2.3 (on page 471) about returning any one of the possible errors permits that behavior to 38306 continue. The [ELOOP] error may be returned if more than {SYMLOOP_MAX} symbolic links 1718 Technical Standard (2001) (Draft April 16, 2001) System Interfaces rmdir( ) 38307 are encountered during resolution of the path argument. 38308 FUTURE DIRECTIONS 38309 None. 38310 SEE ALSO 38311 mkdir( ), remove( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38312 CHANGE HISTORY 38313 First released in Issue 3. 38314 Entry included for alignment with the POSIX.1-1988 standard. 38315 Issue 6 38316 The following new requirements on POSIX implementations derive from alignment with the | 38317 Single UNIX Specification: 38318 * The DESCRIPTION is updated to indicate the results of naming a symbolic link in path. 38319 * The [EIO] mandatory error condition is added. 38320 * The [ELOOP] mandatory error condition is added. 38321 * A second [ENAMETOOLONG] is added as an optional error condition. 38322 The following changes were made to align with the IEEE P1003.1a draft standard: 38323 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1719 round( ) System Interfaces 38324 NAME 38325 round, roundf, roundl - round to nearest integer value in floating-point format 38326 SYNOPSIS 38327 #include 38328 double round(double x); 38329 float roundf(float x); 38330 long double roundl(long double x); 38331 DESCRIPTION 38332 CX The functionality described on this reference page is aligned with the ISO C standard. Any 38333 conflict between the requirements described here and the ISO C standard is unintentional. This 38334 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 38335 These functions shall round their argument to the nearest integer value in floating-point format, 38336 rounding halfway cases away from zero, regardless of the current rounding direction. 38337 An application wishing to check for error situations should set errno to zero and call 38338 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 38339 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 38340 zero, an error has occurred. 38341 RETURN VALUE 38342 Upon successful completion, these functions shall return the rounded integer value. 38343 MX If x is NaN, a NaN shall be returned. 38344 If x is ±0, or ±Inf, x shall be returned. 38345 XSI If the correct value would cause overflow, a range error shall occur and round( ), roundf( ), and 38346 roundl( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, 38347 respectively. 38348 ERRORS 38349 These functions may fail if: 38350 XSI Range Error The result overflows. 38351 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38352 then errno shall be set to [ERANGE]. If the integer expression | 38353 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 38354 floating-point exception shall be raised. | 38355 EXAMPLES 38356 None. 38357 APPLICATION USAGE 38358 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 38359 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 38360 RATIONALE 38361 None. 38362 FUTURE DIRECTIONS 38363 None. 1720 Technical Standard (2001) (Draft April 16, 2001) System Interfaces round( ) 38364 SEE ALSO 38365 feclearexcept( ), fetestexcept( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section 4.18, | 38366 Treatment of Error Conditions for Mathematical Functions, | 38367 CHANGE HISTORY 38368 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1721 scalb( ) System Interfaces 38369 NAME 38370 scalb - load exponent of a radix-independent floating-point number 38371 SYNOPSIS 38372 OB XSI #include 38373 double scalb(double x, double n); 38374 38375 DESCRIPTION 38376 The scalb( ) function shall compute x rn, where r is the radix of the machine's floating-point | 38377 arithmetic. When r is 2, scalb( ) shall be equivalent to ldexp( ). The value of r is FLT_RADIX | 38378 which is defined in . 38379 An application wishing to check for error situations should set errno to zero and call 38380 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 38381 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 38382 zero, an error has occurred. 38383 RETURN VALUE 38384 Upon successful completion, the scalb( ) function shall return x rn. | 38385 If x or n is NaN, a NaN shall be returned. 38386 If n is zero, x shall be returned. 38387 If x is ±Inf and n is not -Inf, x shall be returned. 38388 If x is ±0 and n is not +Inf, x shall be returned. 38389 If x is ±0 and n is +Inf, a domain error shall occur, and either a NaN (if supported), or an 38390 implementation-defined value shall be returned. 38391 If x is ±Inf and n is -Inf, a domain error shall occur, and either a NaN (if supported), or an 38392 implementation-defined value shall be returned. 38393 If the result would cause an overflow, a range error shall occur and ±HUGE_VAL (according to 38394 the sign of x) shall be returned. 38395 If the correct value would cause underflow, and is representable, a range error may occur and 38396 the correct value shall be returned. 38397 If the correct value would cause underflow, and is not representable, a range error may occur, 38398 and 0.0 shall be returned. 38399 ERRORS 38400 The scalb( ) function shall fail if: 38401 Domain Error If x is zero and n is +Inf, or x is Inf and n is -Inf. 38402 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38403 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 38404 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 38405 shall be raised. | 38406 Range Error The result would overflow. 38407 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38408 then errno shall be set to [ERANGE]. If the integer expression | 38409 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 38410 floating-point exception shall be raised. | 1722 Technical Standard (2001) (Draft April 16, 2001) System Interfaces scalb( ) 38411 The scalb( ) function may fail if: 38412 Range Error The result underflows. 38413 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38414 then errno shall be set to [ERANGE]. If the integer expression | 38415 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 38416 floating-point exception shall be raised. | 38417 EXAMPLES 38418 None. 38419 APPLICATION USAGE 38420 Applications should use either scalbln( ), scalblnf( ), or scalblnl( ) in preference to this function. 38421 IEEE Std 1003.1-200x only defines the behavior for the scalb( ) function when the n argument is 38422 an integer, a NaN, or Inf. The behavior of other values for the n argument is unspecified. 38423 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 38424 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 38425 RATIONALE 38426 None. 38427 FUTURE DIRECTIONS 38428 None. 38429 SEE ALSO 38430 feclearexcept( ), fetestexcept( ), ilogb( ), ldexp( ), logb( ), scalbln( ), the Base Definitions volume of | 38431 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 38432 , 38433 CHANGE HISTORY 38434 First released in Issue 4, Version 2. 38435 Issue 5 38436 Moved from X/OPEN UNIX extension to BASE. 38437 The DESCRIPTION is updated to indicate how an application should check for an error. This 38438 text was previously published in the APPLICATION USAGE section. 38439 Issue 6 38440 This function is marked obsolescent. 38441 Although this function is not part of the ISO/IEC 9899: 1999 standard, the RETURN VALUE and 38442 ERROR sections are updated to align with the error handling in ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1723 scalbln( ) System Interfaces 38443 NAME 38444 scalbln, scalblnf, scalblnl, scalbn, scalbnf, scalbnl, - compute exponent using FLT_RADIX 38445 SYNOPSIS 38446 #include 38447 double scalbln(double x, long n); 38448 float scalblnf(float x, long n); 38449 long double scalblnl(long double x, long n); 38450 double scalbn(double x, int n); 38451 float scalbnf(float x, int n); 38452 long double scalbnl(long double x, int n); 38453 DESCRIPTION 38454 CX The functionality described on this reference page is aligned with the ISO C standard. Any 38455 conflict between the requirements described here and the ISO C standard is unintentional. This 38456 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 38457 These functions shall compute x * FLT_RADIXn efficiently, not normally by computing 38458 FLT_RADIXn explicitly. 38459 An application wishing to check for error situations should set errno to zero and call 38460 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 38461 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 38462 zero, an error has occurred. 38463 RETURN VALUE 38464 Upon successful completion, these functions shall return x * FLT_RADIXn. 38465 If the result would cause overflow, a range error shall occur and these functions shall return 38466 ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL (according to the sign of x) as appropriate for 38467 the return type of the function. 38468 If the correct value would cause underflow, and is not representable, a range error may occur, 38469 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 38470 MX If x is NaN, a NaN shall be returned. 38471 If x is ±0, or ±Inf, x shall be returned. 38472 If n is 0, x shall be returned. 38473 If the correct value would cause underflow, and is representable, a range error may occur and 38474 the correct value shall be returned. 38475 ERRORS 38476 These functions shall fail if: 38477 Range Error The result overflows. 38478 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38479 then errno shall be set to [ERANGE]. If the integer expression | 38480 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 38481 floating-point exception shall be raised. | 38482 These functions may fail if: 38483 Range Error The result underflows. 38484 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 38485 then errno shall be set to [ERANGE]. If the integer expression | 1724 Technical Standard (2001) (Draft April 16, 2001) System Interfaces scalbln( ) 38486 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 38487 floating-point exception shall be raised. | 38488 EXAMPLES 38489 None. 38490 APPLICATION USAGE 38491 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 38492 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 38493 RATIONALE 38494 These functions are named so as to avoid conflicting with the historical definition of the scalb( ) 38495 function from the Single UNIX Specification. The difference is that the scalb( ) function has 38496 second argument of double instead of int. The scalb( ) function is not part of ISO C standard. | 38497 The three functions whose second type is long are provided because the factor required to scale | 38498 from the smallest positive floating-point value to the largest finite one, on many 38499 implementations, is too large to represent in the minimum-width int format. 38500 FUTURE DIRECTIONS 38501 None. 38502 SEE ALSO 38503 feclearexcept( ), fetestexcept( ), scalb( ), the Base Definitions volume of IEEE Std 1003.1-200x, Section | 38504 4.18, Treatment of Error Conditions for Mathematical Functions, | 38505 CHANGE HISTORY 38506 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1725 scalbn( ) System Interfaces 38507 NAME 38508 scalbn, scalbnf, scalbnl, - compute exponent using FLT_RADIX 38509 SYNOPSIS 38510 #include 38511 double scalbn(double x, int n); 38512 float scalbnf(float x, int n); 38513 long double scalbnl(long double x, int n); 38514 DESCRIPTION 38515 Refer to scalbln( ). 1726 Technical Standard (2001) (Draft April 16, 2001) System Interfaces scanf( ) 38516 NAME 38517 scanf - convert formatted input 38518 SYNOPSIS 38519 #include 38520 int scanf(const char *restrict format, ... ); 38521 DESCRIPTION 38522 Refer to fscanf( ). System Interfaces, Issue 6 1727 sched_get_priority_max( ) System Interfaces 38523 NAME 38524 sched_get_priority_max, sched_get_priority_min - get priority limits (REALTIME) 38525 SYNOPSIS 38526 PS #include 38527 int sched_get_priority_max(int policy); 38528 int sched_get_priority_min(int policy); 38529 38530 DESCRIPTION 38531 The sched_get_priority_max( ) and sched_get_priority_min( ) functions shall return the appropriate 38532 maximum or minimum, respectively, for the scheduling policy specified by policy. 38533 The value of policy shall be one of the scheduling policy values defined in . 38534 RETURN VALUE 38535 If successful, the sched_get_priority_max( ) and sched_get_priority_min( ) functions shall return the 38536 appropriate maximum or minimum values, respectively. If unsuccessful, they shall return a 38537 value of -1 and set errno to indicate the error. 38538 ERRORS 38539 The sched_get_priority_max( ) and sched_get_priority_min( ) functions shall fail if: 38540 [EINVAL] The value of the policy parameter does not represent a defined scheduling 38541 policy. 38542 EXAMPLES 38543 None. 38544 APPLICATION USAGE 38545 None. 38546 RATIONALE 38547 None. 38548 FUTURE DIRECTIONS 38549 None. 38550 SEE ALSO 38551 sched_getparam( ), sched_setparam( ), sched_getscheduler( ), sched_rr_get_interval( ), 38552 sched_setscheduler( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38553 CHANGE HISTORY 38554 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38555 Issue 6 38556 These functions are marked as part of the Process Scheduling option. 38557 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38558 implementation does not support the Process Scheduling option. 38559 The [ESRCH] error condition has been removed since these functions do not take a pid 38560 argument. 1728 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sched_getparam( ) 38561 NAME 38562 sched_getparam - get scheduling parameters (REALTIME) 38563 SYNOPSIS 38564 PS #include 38565 int sched_getparam(pid_t pid, struct sched_param *param); 38566 38567 DESCRIPTION 38568 The sched_getparam( ) function shall return the scheduling parameters of a process specified by 38569 pid in the sched_param structure pointed to by param. 38570 If a process specified by pid exists, and if the calling process has permission, the scheduling 38571 parameters for the process whose process ID is equal to pid shall be returned. 38572 If pid is zero, the scheduling parameters for the calling process shall be returned. The behavior of 38573 the sched_getparam( ) function is unspecified if the value of pid is negative. 38574 RETURN VALUE 38575 Upon successful completion, the sched_getparam( ) function shall return zero. If the call to 38576 sched_getparam( ) is unsuccessful, the function shall return a value of -1 and set errno to indicate 38577 the error. 38578 ERRORS 38579 The sched_getparam( ) function shall fail if: 38580 [EPERM] The requesting process does not have permission to obtain the scheduling 38581 parameters of the specified process. 38582 [ESRCH] No process can be found corresponding to that specified by pid. 38583 EXAMPLES 38584 None. 38585 APPLICATION USAGE 38586 None. 38587 RATIONALE 38588 None. 38589 FUTURE DIRECTIONS 38590 None. 38591 SEE ALSO 38592 sched_getscheduler( ), sched_setparam( ), sched_setscheduler( ), the Base Definitions volume of 38593 IEEE Std 1003.1-200x, 38594 CHANGE HISTORY 38595 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38596 Issue 6 38597 The sched_getparam( ) function is marked as part of the Process Scheduling option. 38598 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38599 implementation does not support the Process Scheduling option. System Interfaces, Issue 6 1729 sched_getscheduler( ) System Interfaces 38600 NAME 38601 sched_getscheduler - get scheduling policy (REALTIME) 38602 SYNOPSIS 38603 PS #include 38604 int sched_getscheduler(pid_t pid); 38605 38606 DESCRIPTION 38607 The sched_getscheduler( ) function shall return the scheduling policy of the process specified by 38608 pid. If the value of pid is negative, the behavior of the sched_getscheduler( ) function is 38609 unspecified. 38610 The values that can be returned by sched_getscheduler( ) are defined in the header. | 38611 If a process specified by pid exists, and if the calling process has permission, the scheduling 38612 policy shall be returned for the process whose process ID is equal to pid. 38613 If pid is zero, the scheduling policy shall be returned for the calling process. 38614 RETURN VALUE 38615 Upon successful completion, the sched_getscheduler( ) function shall return the scheduling policy 38616 of the specified process. If unsuccessful, the function shall return -1 and set errno to indicate the 38617 error. 38618 ERRORS 38619 The sched_getscheduler( ) function shall fail if: 38620 [EPERM] The requesting process does not have permission to determine the scheduling 38621 policy of the specified process. 38622 [ESRCH] No process can be found corresponding to that specified by pid. 38623 EXAMPLES 38624 None. 38625 APPLICATION USAGE 38626 None. 38627 RATIONALE 38628 None. 38629 FUTURE DIRECTIONS 38630 None. 38631 SEE ALSO 38632 sched_getparam( ), sched_setparam( ), sched_setscheduler( ), the Base Definitions volume of 38633 IEEE Std 1003.1-200x, 38634 CHANGE HISTORY 38635 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38636 Issue 6 38637 The sched_getscheduler( ) function is marked as part of the Process Scheduling option. 38638 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38639 implementation does not support the Process Scheduling option. 1730 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sched_rr_get_interval( ) 38640 NAME 38641 sched_rr_get_interval - get execution time limits (REALTIME) 38642 SYNOPSIS 38643 PS #include 38644 int sched_rr_get_interval(pid_t pid, struct timespec *interval); 38645 38646 DESCRIPTION 38647 The sched_rr_get_interval( ) function shall update the timespec structure referenced by the 38648 interval argument to contain the current execution time limit (that is, time quantum) for the 38649 process specified by pid. If pid is zero, the current execution time limit for the calling process 38650 shall be returned. 38651 RETURN VALUE 38652 If successful, the sched_rr_get_interval( ) function shall return zero. Otherwise, it shall return a 38653 value of -1 and set errno to indicate the error. 38654 ERRORS 38655 The sched_rr_get_interval( ) function shall fail if: 38656 [ESRCH] No process can be found corresponding to that specified by pid. 38657 EXAMPLES 38658 None. 38659 APPLICATION USAGE 38660 None. 38661 RATIONALE 38662 None. 38663 FUTURE DIRECTIONS 38664 None. 38665 SEE ALSO 38666 sched_getparam( ), sched_get_priority_max( ), sched_getscheduler( ), sched_setparam( ), 38667 sched_setscheduler( ), the Base Definitions volume of IEEE Std 1003.1-200x, 38668 CHANGE HISTORY 38669 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38670 Issue 6 38671 The sched_rr_get_interval( ) function is marked as part of the Process Scheduling option. 38672 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38673 implementation does not support the Process Scheduling option. System Interfaces, Issue 6 1731 sched_setparam( ) System Interfaces 38674 NAME 38675 sched_setparam - set scheduling parameters (REALTIME) 38676 SYNOPSIS 38677 PS #include 38678 int sched_setparam(pid_t pid, const struct sched_param *param); 38679 38680 DESCRIPTION 38681 The sched_setparam( ) function shall set the scheduling parameters of the process specified by pid 38682 to the values specified by the sched_param structure pointed to by param. The value of the 38683 sched_priority member in the sched_param structure shall be any integer within the inclusive 38684 priority range for the current scheduling policy of the process specified by pid. Higher 38685 numerical values for the priority represent higher priorities. If the value of pid is negative, the 38686 behavior of the sched_setparam( ) function is unspecified. 38687 If a process specified by pid exists, and if the calling process has permission, the scheduling 38688 parameters shall be set for the process whose process ID is equal to pid. 38689 If pid is zero, the scheduling parameters shall be set for the calling process. 38690 The conditions under which one process has permission to change the scheduling parameters of 38691 another process are implementation-defined. 38692 Implementations may require the requesting process to have the appropriate privilege to set its 38693 own scheduling parameters or those of another process. 38694 The target process, whether it is running or not running, shall be moved to the tail of the thread 38695 list for its priority. 38696 If the priority of the process specified by the pid argument is set higher than that of the lowest 38697 priority running process and if the specified process is ready to run, the process specified by the 38698 pid argument shall preempt a lowest priority running process. Similarly, if the process calling | 38699 sched_setparam( ) sets its own priority lower than that of one or more other non-empty process 38700 lists, then the process that is the head of the highest priority list shall also preempt the calling | 38701 process. Thus, in either case, the originating process might not receive notification of the | 38702 completion of the requested priority change until the higher priority process has executed. 38703 SS If the scheduling policy of the target process is SCHED_SPORADIC, the value specified by the 38704 sched_ss_low_priority member of the param argument shall be any integer within the inclusive 38705 priority range for the sporadic server policy. The sched_ss_repl_period and sched_ss_init_budget 38706 members of the param argument shall represent the time parameters to be used by the sporadic 38707 server scheduling policy for the target process. The sched_ss_max_repl member of the param 38708 argument shall represent the maximum number of replenishments that are allowed to be 38709 pending simultaneously for the process scheduled under this scheduling policy. 38710 The specified sched_ss_repl_period shall be greater than or equal to the specified 38711 sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. 38712 The value of sched_ss_max_repl shall be within the inclusive range [1,{SS_REPL_MAX}] for the 38713 function to succeed; if not, the function shall fail. 38714 If the scheduling policy of the target process is either SCHED_FIFO or SCHED_RR, the 38715 sched_ss_low_priority, sched_ss_repl_period, and sched_ss_init_budget members of the param 38716 argument shall have no effect on the scheduling behavior. If the scheduling policy of this process 38717 is not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC, the effects of these members are 38718 implementation-defined; this case includes the SCHED_OTHER policy. 1732 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sched_setparam( ) 38719 If the current scheduling policy for the process specified by pid is not SCHED_FIFO, 38720 SS SCHED_RR, or SCHED_SPORADIC, the result is implementation-defined; this case includes the | 38721 SCHED_OTHER policy. 38722 The effect of this function on individual threads is dependent on the scheduling contention 38723 scope of the threads: 38724 * For threads with system scheduling contention scope, these functions shall have no effect on | 38725 their scheduling. | 38726 * For threads with process scheduling contention scope, the threads' scheduling parameters 38727 shall not be affected. However, the scheduling of these threads with respect to threads in 38728 other processes may be dependent on the scheduling parameters of their process, which are 38729 governed using these functions. 38730 If an implementation supports a two-level scheduling model in which library threads are 38731 multiplexed on top of several kernel-scheduled entities, then the underlying kernel-scheduled 38732 entities for the system contention scope threads shall not be affected by these functions. 38733 The underlying kernel-scheduled entities for the process contention scope threads shall have 38734 their scheduling parameters changed to the value specified in param. Kernel scheduled entities 38735 for use by process contention scope threads that are created after this call completes shall inherit | 38736 their scheduling policy and associated scheduling parameters from the process. | 38737 This function is not atomic with respect to other threads in the process. Threads may continue to | 38738 execute while this function call is in the process of changing the scheduling policy for the | 38739 underlying kernel-scheduled entities used by the process contention scope threads. | 38740 RETURN VALUE 38741 If successful, the sched_setparam( ) function shall return zero. 38742 If the call to sched_setparam( ) is unsuccessful, the priority shall remain unchanged, and the 38743 function shall return a value of -1 and set errno to indicate the error. 38744 ERRORS 38745 The sched_setparam( ) function shall fail if: 38746 [EINVAL] One or more of the requested scheduling parameters is outside the range 38747 defined for the scheduling policy of the specified pid. 38748 [EPERM] The requesting process does not have permission to set the scheduling 38749 parameters for the specified process, or does not have the appropriate 38750 privilege to invoke sched_setparam( ). 38751 [ESRCH] No process can be found corresponding to that specified by pid. 38752 EXAMPLES 38753 None. 38754 APPLICATION USAGE 38755 None. 38756 RATIONALE 38757 None. 38758 FUTURE DIRECTIONS 38759 None. System Interfaces, Issue 6 1733 sched_setparam( ) System Interfaces 38760 SEE ALSO 38761 sched_getparam( ), sched_getscheduler( ), sched_setscheduler( ), the Base Definitions volume of 38762 IEEE Std 1003.1-200x, 38763 CHANGE HISTORY 38764 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38765 Issue 6 38766 The sched_setparam( ) function is marked as part of the Process Scheduling option. 38767 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38768 implementation does not support the Process Scheduling option. 38769 The following new requirements on POSIX implementations derive from alignment with the 38770 Single UNIX Specification: 38771 * In the DESCRIPTION, the effect of this function on a thread's scheduling parameters is 38772 added. 38773 * Sections describing two-level scheduling and atomicity of the function are added. 38774 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999. 38775 IEEE PASC Interpretation 1003.1 #100 is applied. 1734 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sched_setscheduler( ) 38776 NAME 38777 sched_setscheduler - set scheduling policy and parameters (REALTIME) 38778 SYNOPSIS 38779 PS #include 38780 int sched_setscheduler(pid_t pid, int policy, 38781 const struct sched_param *param); 38782 38783 DESCRIPTION 38784 The sched_setscheduler( ) function shall set the scheduling policy and scheduling parameters of 38785 the process specified by pid to policy and the parameters specified in the sched_param structure 38786 pointed to by param, respectively. The value of the sched_priority member in the sched_param 38787 structure shall be any integer within the inclusive priority range for the scheduling policy 38788 specified by policy. If the value of pid is negative, the behavior of the sched_setscheduler( ) 38789 function is unspecified. 38790 The possible values for the policy parameter are defined in the header. | 38791 If a process specified by pid exists, and if the calling process has permission, the scheduling 38792 policy and scheduling parameters shall be set for the process whose process ID is equal to pid. 38793 If pid is zero, the scheduling policy and scheduling parameters shall be set for the calling 38794 process. 38795 The conditions under which one process has the appropriate privilege to change the scheduling 38796 parameters of another process are implementation-defined. 38797 Implementations may require that the requesting process have permission to set its own 38798 scheduling parameters or those of another process. Additionally, implementation-defined 38799 restrictions may apply as to the appropriate privileges required to set a process' own scheduling 38800 policy, or another process' scheduling policy, to a particular value. 38801 The sched_setscheduler( ) function shall be considered successful if it succeeds in setting the | 38802 scheduling policy and scheduling parameters of the process specified by pid to the values 38803 specified by policy and the structure pointed to by param, respectively. 38804 SS If the scheduling policy specified by policy is SCHED_SPORADIC, the value specified by the 38805 sched_ss_low_priority member of the param argument shall be any integer within the inclusive 38806 priority range for the sporadic server policy. The sched_ss_repl_period and sched_ss_init_budget 38807 members of the param argument shall represent the time parameters used by the sporadic server 38808 scheduling policy for the target process. The sched_ss_max_repl member of the param argument 38809 shall represent the maximum number of replenishments that are allowed to be pending 38810 simultaneously for the process scheduled under this scheduling policy. 38811 The specified sched_ss_repl_period shall be greater than or equal to the specified 38812 sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. 38813 The value of sched_ss_max_repl shall be within the inclusive range [1,{SS_REPL_MAX}] for the 38814 function to succeed; if not, the function shall fail. 38815 If the scheduling policy specified by policy is either SCHED_FIFO or SCHED_RR, the 38816 sched_ss_low_priority, sched_ss_repl_period, and sched_ss_init_budget members of the param 38817 argument shall have no effect on the scheduling behavior. 38818 The effect of this function on individual threads is dependent on the scheduling contention 38819 scope of the threads: System Interfaces, Issue 6 1735 sched_setscheduler( ) System Interfaces 38820 * For threads with system scheduling contention scope, these functions shall have no effect on | 38821 their scheduling. | 38822 * For threads with process scheduling contention scope, the threads' scheduling policy and 38823 associated parameters shall not be affected. However, the scheduling of these threads with 38824 respect to threads in other processes may be dependent on the scheduling parameters of their 38825 process, which are governed using these functions. 38826 If an implementation supports a two-level scheduling model in which library threads are 38827 multiplexed on top of several kernel-scheduled entities, then the underlying kernel-scheduled 38828 entities for the system contention scope threads shall not be affected by these functions. 38829 The underlying kernel-scheduled entities for the process contention scope threads shall have 38830 their scheduling policy and associated scheduling parameters changed to the values specified in 38831 policy and param, respectively. Kernel scheduled entities for use by process contention scope | 38832 threads that are created after this call completes shall inherit their scheduling policy and | 38833 associated scheduling parameters from the process. | 38834 This function is not atomic with respect to other threads in the process. Threads may continue to | 38835 execute while this function call is in the process of changing the scheduling policy and | 38836 associated scheduling parameters for the underlying kernel-scheduled entities used by the | 38837 process contention scope threads. | 38838 RETURN VALUE 38839 Upon successful completion, the function shall return the former scheduling policy of the 38840 specified process. If the sched_setscheduler( ) function fails to complete successfully, the policy 38841 and scheduling paramenters shall remain unchanged, and the function shall return a value of -1 38842 and set errno to indicate the error. 38843 ERRORS 38844 The sched_setscheduler( ) function shall fail if: 38845 [EINVAL] The value of the policy parameter is invalid, or one or more of the parameters 38846 contained in param is outside the valid range for the specified scheduling 38847 policy. 38848 [EPERM] The requesting process does not have permission to set either or both of the 38849 scheduling parameters or the scheduling policy of the specified process. 38850 [ESRCH] No process can be found corresponding to that specified by pid. 38851 EXAMPLES 38852 None. 38853 APPLICATION USAGE 38854 None. 38855 RATIONALE 38856 None. 38857 FUTURE DIRECTIONS 38858 None. 38859 SEE ALSO 38860 sched_getparam( ), sched_getscheduler( ), sched_setparam( ), the Base Definitions volume of 38861 IEEE Std 1003.1-200x, 1736 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sched_setscheduler( ) 38862 CHANGE HISTORY 38863 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 38864 Issue 6 38865 The sched_setscheduler( ) function is marked as part of the Process Scheduling option. 38866 The [ENOSYS] error condition has been removed as stubs need not be provided if an 38867 implementation does not support the Process Scheduling option. 38868 The following new requirements on POSIX implementations derive from alignment with the 38869 Single UNIX Specification: 38870 * In the DESCRIPTION, the effect of this function on a thread's scheduling parameters is 38871 added. 38872 * Sections describing two-level scheduling and atomicity of the function are added. 38873 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std 1003.1d-1999. System Interfaces, Issue 6 1737 sched_yield( ) System Interfaces 38874 NAME 38875 sched_yield - yield processor 38876 SYNOPSIS 38877 PS|THR #include 38878 int sched_yield(void); 38879 38880 DESCRIPTION 38881 The sched_yield( ) function shall force the running thread to relinquish the processor until it again 38882 becomes the head of its thread list. It takes no arguments. 38883 RETURN VALUE 38884 The sched_yield( ) function shall return 0 if it completes successfully; otherwise, it shall return a 38885 value of -1 and set errno to indicate the error. 38886 ERRORS 38887 No errors are defined. 38888 EXAMPLES 38889 None. 38890 APPLICATION USAGE 38891 None. 38892 RATIONALE 38893 None. 38894 FUTURE DIRECTIONS 38895 None. 38896 SEE ALSO 38897 The Base Definitions volume of IEEE Std 1003.1-200x, 38898 CHANGE HISTORY 38899 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the 38900 POSIX Threads Extension. 38901 Issue 6 38902 The sched_yield( ) function is now marked as part of the Process Scheduling and Threads options. 1738 Technical Standard (2001) (Draft April 16, 2001) System Interfaces seed48( ) 38903 NAME 38904 seed48 - seed uniformly distributed pseudo-random non-negative long integer generator 38905 SYNOPSIS 38906 XSI #include 38907 unsigned short *seed48(unsigned short seed16v[3]); 38908 38909 DESCRIPTION 38910 Refer to drand48( ). System Interfaces, Issue 6 1739 seekdir( ) System Interfaces 38911 NAME 38912 seekdir - set position of directory stream 38913 SYNOPSIS 38914 XSI #include 38915 void seekdir(DIR *dirp, long loc); 38916 38917 DESCRIPTION 38918 The seekdir( ) function shall set the position of the next readdir( ) operation on the directory 38919 stream specified by dirp to the position specified by loc. The value of loc should have been 38920 returned from an earlier call to telldir( ). The new position reverts to the one associated with the 38921 directory stream when telldir( ) was performed. 38922 If the value of loc was not obtained from an earlier call to telldir( ), or if a call to rewinddir( ) 38923 occurred between the call to telldir( ) and the call to seekdir( ), the results of subsequent calls to 38924 readdir( ) are unspecified. 38925 RETURN VALUE 38926 The seekdir( ) function shall not return a value. 38927 ERRORS 38928 No errors are defined. 38929 EXAMPLES 38930 None. 38931 APPLICATION USAGE 38932 None. 38933 RATIONALE 38934 The original standard developers perceived that there were restrictions on the use of the 38935 seekdir( ) and telldir( ) functions related to implementation details, and for that reason these 38936 functions need not be supported on all POSIX-conforming systems. They are required on 38937 implementations supporting the XSI extension. 38938 One of the perceived problems of implementation is that returning to a given point in a directory 38939 is quite difficult to describe formally, in spite of its intuitive appeal, when systems that use B- 38940 trees, hashing functions, or other similar mechanisms to order their directories are considered. 38941 The definition of seekdir( ) and telldir( ) does not specify whether, when using these interfaces, a 38942 given directory entry will be seen at all, or more than once. 38943 On systems not supporting these functions, their capability can sometimes be accomplished by 38944 saving a filename found by readdir( ) and later using rewinddir( ) and a loop on readdir( ) to 38945 relocate the position from which the filename was saved. 38946 FUTURE DIRECTIONS 38947 None. 38948 SEE ALSO 38949 opendir( ), readdir( ), telldir( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 38950 , 38951 CHANGE HISTORY 38952 First released in Issue 2. 1740 Technical Standard (2001) (Draft April 16, 2001) System Interfaces seekdir( ) 38953 Issue 6 38954 In the SYNOPSIS, the inclusion of is no longer required. System Interfaces, Issue 6 1741 select( ) System Interfaces 38955 NAME 38956 select - synchronous I/O multiplexing 38957 SYNOPSIS 38958 #include 38959 int select(int nfds, fd_set *restrict readfds, 38960 fd_set *restrict writefds, fd_set *restrict errorfds, 38961 struct timeval *restrict timeout); 38962 38963 DESCRIPTION 38964 Refer to pselect( ). 1742 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_close( ) 38965 NAME 38966 sem_close - close a named semaphore (REALTIME) 38967 SYNOPSIS 38968 SEM #include 38969 int sem_close(sem_t *sem); 38970 38971 DESCRIPTION 38972 The sem_close( ) function shall indicate that the calling process is finished using the named | 38973 semaphore indicated by sem. The effects of calling sem_close( ) for an unnamed semaphore (one 38974 created by sem_init( )) are undefined. The sem_close( ) function shall deallocate (that is, make 38975 available for reuse by a subsequent sem_open( ) by this process) any system resources allocated 38976 by the system for use by this process for this semaphore. The effect of subsequent use of the 38977 semaphore indicated by sem by this process is undefined. If the semaphore has not been 38978 removed with a successful call to sem_unlink( ), then sem_close( ) has no effect on the state of the 38979 semaphore. If the sem_unlink( ) function has been successfully invoked for name after the most 38980 recent call to sem_open( ) with O_CREAT for this semaphore, then when all processes that have 38981 opened the semaphore close it, the semaphore is no longer accessible. 38982 RETURN VALUE 38983 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 38984 returned and errno set to indicate the error. 38985 ERRORS 38986 The sem_close( ) function shall fail if: 38987 [EINVAL] The sem argument is not a valid semaphore descriptor. 38988 EXAMPLES 38989 None. 38990 APPLICATION USAGE 38991 The sem_close( ) function is part of the Semaphores option and need not be available on all 38992 implementations. 38993 RATIONALE 38994 None. 38995 FUTURE DIRECTIONS 38996 None. 38997 SEE ALSO 38998 semctl( ), semget( ), semop( ), sem_init( ), sem_open( ), sem_unlink( ), the Base Definitions volume of 38999 IEEE Std 1003.1-200x, 39000 CHANGE HISTORY 39001 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39002 Issue 6 39003 The sem_close( ) function is marked as part of the Semaphores option. 39004 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39005 implementation does not support the Semaphores option. System Interfaces, Issue 6 1743 sem_destroy( ) System Interfaces 39006 NAME 39007 sem_destroy - destroy an unnamed semaphore (REALTIME) 39008 SYNOPSIS 39009 SEM #include 39010 int sem_destroy(sem_t *sem); 39011 39012 DESCRIPTION 39013 The sem_destroy( ) function shall destroy the unnamed semaphore indicated by sem. Only a | 39014 semaphore that was created using sem_init( ) may be destroyed using sem_destroy( ); the effect of 39015 calling sem_destroy( ) with a named semaphore is undefined. The effect of subsequent use of the 39016 semaphore sem is undefined until sem is reinitialized by another call to sem_init( ). | 39017 It is safe to destroy an initialized semaphore upon which no threads are currently blocked. The 39018 effect of destroying a semaphore upon which other threads are currently blocked is undefined. 39019 RETURN VALUE 39020 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 39021 returned and errno set to indicate the error. 39022 ERRORS 39023 The sem_destroy( ) function shall fail if: 39024 [EINVAL] The sem argument is not a valid semaphore. 39025 The sem_destroy( ) function may fail if: 39026 [EBUSY] There are currently processes blocked on the semaphore. 39027 EXAMPLES 39028 None. 39029 APPLICATION USAGE 39030 The sem_destroy( ) function is part of the Semaphores option and need not be available on all 39031 implementations. 39032 RATIONALE 39033 None. 39034 FUTURE DIRECTIONS 39035 None. 39036 SEE ALSO 39037 semctl( ), semget( ), semop( ), sem_init( ), sem_open( ), the Base Definitions volume of 39038 IEEE Std 1003.1-200x, 39039 CHANGE HISTORY 39040 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39041 Issue 6 39042 The sem_destroy( ) function is marked as part of the Semaphores option. 39043 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39044 implementation does not support the Semaphores option. 1744 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_getvalue( ) 39045 NAME 39046 sem_getvalue - get the value of a semaphore (REALTIME) 39047 SYNOPSIS 39048 SEM #include 39049 int sem_getvalue(sem_t *restrict sem, int *restrict sval); 39050 39051 DESCRIPTION 39052 The sem_getvalue( ) function shall update the location referenced by the sval argument to have 39053 the value of the semaphore referenced by sem without affecting the state of the semaphore. The 39054 updated value represents an actual semaphore value that occurred at some unspecified time 39055 during the call, but it need not be the actual value of the semaphore when it is returned to the 39056 calling process. 39057 If sem is locked, then the value returned by sem_getvalue( ) is either zero or a negative number 39058 whose absolute value represents the number of processes waiting for the semaphore at some 39059 unspecified time during the call. 39060 RETURN VALUE 39061 Upon successful completion, the sem_getvalue( ) function shall return a value of zero. Otherwise, 39062 it shall return a value of -1 and set errno to indicate the error. 39063 ERRORS 39064 The sem_getvalue( ) function shall fail if: 39065 [EINVAL] The sem argument does not refer to a valid semaphore. 39066 EXAMPLES 39067 None. 39068 APPLICATION USAGE 39069 The sem_getvalue( ) function is part of the Semaphores option and need not be available on all 39070 implementations. 39071 RATIONALE 39072 None. 39073 FUTURE DIRECTIONS 39074 None. 39075 SEE ALSO 39076 semctl( ), semget( ), semop( ), sem_post( ), sem_timedwait( ), sem_trywait( ), sem_wait( ), the Base 39077 Definitions volume of IEEE Std 1003.1-200x, 39078 CHANGE HISTORY 39079 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39080 Issue 6 39081 The sem_getvalue( ) function is marked as part of the Semaphores option. 39082 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39083 implementation does not support the Semaphores option. 39084 The sem_timedwait( ) function is added to the SEE ALSO section for alignment with 39085 IEEE Std 1003.1d-1999. 39086 The restrict keyword is added to the sem_getvalue( ) prototype for alignment with the 39087 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1745 sem_init( ) System Interfaces 39088 NAME 39089 sem_init - initialize an unnamed semaphore (REALTIME) 39090 SYNOPSIS 39091 SEM #include 39092 int sem_init(sem_t *sem, int pshared, unsigned value); 39093 39094 DESCRIPTION 39095 The sem_init( ) function shall initialize the unnamed semaphore referred to by sem. The value of | 39096 the initialized semaphore shall be value. Following a successful call to sem_init( ), the semaphore 39097 may be used in subsequent calls to sem_wait( ), sem_trywait( ), sem_post( ), and sem_destroy( ). 39098 This semaphore shall remain usable until the semaphore is destroyed. 39099 If the pshared argument has a non-zero value, then the semaphore is shared between processes; 39100 in this case, any process that can access the semaphore sem can use sem for performing 39101 sem_wait( ), sem_trywait( ), sem_post( ), and sem_destroy( ) operations. 39102 Only sem itself may be used for performing synchronization. The result of referring to copies of 39103 sem in calls to sem_wait( ), sem_trywait( ), sem_post( ), and sem_destroy( ), is undefined. 39104 If the pshared argument is zero, then the semaphore is shared between threads of the process; any 39105 thread in this process can use sem for performing sem_wait( ), sem_trywait( ), sem_post( ), and 39106 sem_destroy( ) operations. The use of the semaphore by threads other than those created in the 39107 same process is undefined. 39108 Attempting to initialize an already initialized semaphore results in undefined behavior. 39109 RETURN VALUE 39110 Upon successful completion, the sem_init( ) function shall initialize the semaphore in sem. 39111 Otherwise, it shall return -1 and set errno to indicate the error. 39112 ERRORS 39113 The sem_init( ) function shall fail if: 39114 [EINVAL] The value argument exceeds {SEM_VALUE_MAX}. 39115 [ENOSPC] A resource required to initialize the semaphore has been exhausted, or the 39116 limit on semaphores ({SEM_NSEMS_MAX}) has been reached. 39117 [EPERM] The process lacks the appropriate privileges to initialize the semaphore. 39118 EXAMPLES 39119 None. 39120 APPLICATION USAGE 39121 The sem_init( ) function is part of the Semaphores option and need not be available on all 39122 implementations. 39123 RATIONALE 39124 Although this volume of IEEE Std 1003.1-200x fails to specify a successful return value, it is 39125 likely that a later version may require the implementation to return a value of zero if the call to 39126 sem_init( ) is successful. 39127 FUTURE DIRECTIONS 39128 None. 1746 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_init( ) 39129 SEE ALSO 39130 sem_destroy( ), sem_post( ), sem_timedwait( ), sem_trywait( ), sem_wait( ), the Base Definitions 39131 volume of IEEE Std 1003.1-200x, 39132 CHANGE HISTORY 39133 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39134 Issue 6 39135 The sem_init( ) function is marked as part of the Semaphores option. 39136 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39137 implementation does not support the Semaphores option. 39138 The sem_timedwait( ) function is added to the SEE ALSO section for alignment with 39139 IEEE Std 1003.1d-1999. System Interfaces, Issue 6 1747 sem_open( ) System Interfaces 39140 NAME 39141 sem_open - initialize and open a named semaphore (REALTIME) 39142 SYNOPSIS 39143 SEM #include 39144 sem_t *sem_open(const char *name, int oflag, ...); 39145 39146 DESCRIPTION 39147 The sem_open( ) function shall establish a connection between a named semaphore and a process. 39148 Following a call to sem_open( ) with semaphore name name, the process may reference the 39149 semaphore associated with name using the address returned from the call. This semaphore may 39150 be used in subsequent calls to sem_wait( ), sem_trywait( ), sem_post( ), and sem_close( ). The 39151 semaphore remains usable by this process until the semaphore is closed by a successful call to 39152 sem_close( ), _exit( ), or one of the exec functions. 39153 The oflag argument controls whether the semaphore is created or merely accessed by the call to 39154 sem_open( ). The following flag bits may be set in oflag: 39155 O_CREAT This flag is used to create a semaphore if it does not already exist. If O_CREAT is 39156 set and the semaphore already exists, then O_CREAT has no effect, except as noted 39157 under O_EXCL. Otherwise, sem_open( ) creates a named semaphore. The O_CREAT 39158 flag requires a third and a fourth argument: mode, which is of type mode_t, and 39159 value, which is of type unsigned. The semaphore is created with an initial value of 39160 value. Valid initial values for semaphores are less than or equal to 39161 {SEM_VALUE_MAX}. 39162 The user ID of the semaphore is set to the effective user ID of the process; the 39163 group ID of the semaphore is set to a system default group ID or to the effective 39164 group ID of the process. The permission bits of the semaphore are set to the value 39165 of the mode argument except those set in the file mode creation mask of the 39166 process. When bits in mode other than the file permission bits are specified, the 39167 effect is unspecified. 39168 After the semaphore named name has been created by sem_open( ) with the 39169 O_CREAT flag, other processes can connect to the semaphore by calling 39170 sem_open( ) with the same value of name. 39171 O_EXCL If O_EXCL and O_CREAT are set, sem_open( ) fails if the semaphore name exists. 39172 The check for the existence of the semaphore and the creation of the semaphore if 39173 it does not exist are atomic with respect to other processes executing sem_open( ) 39174 with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the 39175 effect is undefined. 39176 If flags other than O_CREAT and O_EXCL are specified in the oflag parameter, the 39177 effect is unspecified. 39178 The name argument points to a string naming a semaphore object. It is unspecified whether the 39179 name appears in the file system and is visible to functions that take pathnames as arguments. | 39180 The name argument conforms to the construction rules for a pathname. If name begins with the | 39181 slash character, then processes calling sem_open( ) with the same value of name shall refer to the 39182 same semaphore object, as long as that name has not been removed. If name does not begin with 39183 the slash character, the effect is implementation-defined. The interpretation of slash characters 39184 other than the leading slash character in name is implementation-defined. 39185 If a process makes multiple successful calls to sem_open( ) with the same value for name, the | 39186 same semaphore address shall be returned for each such successful call, provided that there | 1748 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_open( ) 39187 have been no calls to sem_unlink( ) for this semaphore. | 39188 References to copies of the semaphore produce undefined results. 39189 RETURN VALUE 39190 Upon successful completion, the sem_open( ) function shall return the address of the semaphore. 39191 Otherwise, it shall return a value of SEM_FAILED and set errno to indicate the error. The symbol 39192 SEM_FAILED is defined in the header. No successful return from sem_open( ) 39193 shall return the value SEM_FAILED. 39194 ERRORS 39195 If any of the following conditions occur, the sem_open( ) function shall return SEM_FAILED and 39196 set errno to the corresponding value: 39197 [EACCES] The named semaphore exists and the permissions specified by oflag are 39198 denied, or the named semaphore does not exist and permission to create the 39199 named semaphore is denied. 39200 [EEXIST] O_CREAT and O_EXCL are set and the named semaphore already exists. 39201 [EINTR] The sem_open( ) operation was interrupted by a signal. 39202 [EINVAL] The sem_open( ) operation is not supported for the given name, or O_CREAT 39203 was specified in oflag and value was greater than {SEM_VALUE_MAX}. 39204 [EMFILE] Too many semaphore descriptors or file descriptors are currently in use by 39205 this process. 39206 [ENAMETOOLONG] 39207 The length of the name argument exceeds {PATH_MAX} or a pathname | 39208 component is longer than {NAME_MAX}. | 39209 [ENFILE] Too many semaphores are currently open in the system. 39210 [ENOENT] O_CREAT is not set and the named semaphore does not exist. 39211 [ENOSPC] There is insufficient space for the creation of the new named semaphore. 39212 EXAMPLES 39213 None. 39214 APPLICATION USAGE 39215 The sem_open( ) function is part of the Semaphores option and need not be available on all 39216 implementations. 39217 RATIONALE 39218 An earlier version of this volume of IEEE Std 1003.1-200x required an error return value of -1 39219 with the type sem_t * for the sem_open( ) function, which is not guaranteed to be portable across 39220 implementations. The revised text provides the symbolic error code SEM_FAILED to eliminate 39221 the type conflict. 39222 FUTURE DIRECTIONS 39223 None. 39224 SEE ALSO 39225 semctl( ), semget( ), semop( ), sem_close( ), sem_post( ), sem_timedwait( ), sem_trywait( ), sem_unlink( ), 39226 sem_wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1749 sem_open( ) System Interfaces 39227 CHANGE HISTORY 39228 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39229 Issue 6 39230 The sem_open( ) function is marked as part of the Semaphores option. 39231 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39232 implementation does not support the Semaphores option. 39233 The sem_timedwait( ) function is added to the SEE ALSO section for alignment with 39234 IEEE Std 1003.1d-1999. 1750 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_post( ) 39235 NAME 39236 sem_post - unlock a semaphore (REALTIME) 39237 SYNOPSIS 39238 SEM #include 39239 int sem_post(sem_t *sem); 39240 39241 DESCRIPTION 39242 The sem_post( ) function shall unlock the semaphore referenced by sem by performing a 39243 semaphore unlock operation on that semaphore. 39244 If the semaphore value resulting from this operation is positive, then no threads were blocked 39245 waiting for the semaphore to become unlocked; the semaphore value is simply incremented. 39246 If the value of the semaphore resulting from this operation is zero, then one of the threads 39247 blocked waiting for the semaphore shall be allowed to return successfully from its call to 39248 PS sem_wait( ). If the Process Scheduling option is supported, the thread to be unblocked shall be 39249 chosen in a manner appropriate to the scheduling policies and parameters in effect for the 39250 blocked threads. In the case of the schedulers SCHED_FIFO and SCHED_RR, the highest 39251 priority waiting thread shall be unblocked, and if there is more than one highest priority thread 39252 blocked waiting for the semaphore, then the highest priority thread that has been waiting the 39253 longest shall be unblocked. If the Process Scheduling option is not defined, the choice of a thread 39254 to unblock is unspecified. 39255 SS If the Process Sporadic Server option is supported, and the scheduling policy is 39256 SCHED_SPORADIC, the semantics are as per SCHED_FIFO above. 39257 The sem_post( ) function shall be reentrant with respect to signals and may be invoked from a 39258 signal-catching function. 39259 RETURN VALUE 39260 If successful, the sem_post( ) function shall return zero; otherwise, the function shall return -1 39261 and set errno to indicate the error. 39262 ERRORS 39263 The sem_post( ) function shall fail if: 39264 [EINVAL] The sem argument does not refer to a valid semaphore. 39265 EXAMPLES 39266 None. 39267 APPLICATION USAGE 39268 The sem_post( ) function is part of the Semaphores option and need not be available on all 39269 implementations. 39270 RATIONALE 39271 None. 39272 FUTURE DIRECTIONS 39273 None. 39274 SEE ALSO 39275 semctl( ), semget( ), semop( ), sem_timedwait( ), sem_trywait( ), sem_wait( ), the Base Definitions 39276 volume of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1751 sem_post( ) System Interfaces 39277 CHANGE HISTORY 39278 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39279 Issue 6 39280 The sem_post( ) function is marked as part of the Semaphores option. 39281 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39282 implementation does not support the Semaphores option. 39283 The sem_timedwait( ) function is added to the SEE ALSO section for alignment with 39284 IEEE Std 1003.1d-1999. 39285 SCHED_SPORADIC is added to the list of scheduling policies for which the thread that is to be 39286 unblocked is specified for alignment with IEEE Std 1003.1d-1999. 1752 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_timedwait( ) 39287 NAME 39288 sem_timedwait - lock a semaphore (ADVANCED REALTIME) 39289 SYNOPSIS 39290 SEM TMO #include 39291 #include 39292 int sem_timedwait(sem_t *restrict sem, 39293 const struct timespec *restrict abs_timeout); 39294 39295 DESCRIPTION 39296 The sem_timedwait( ) function shall lock the semaphore referenced by sem as in the sem_wait( ) 39297 function. However, if the semaphore cannot be locked without waiting for another process or 39298 thread to unlock the semaphore by performing a sem_post( ) function, this wait shall be 39299 terminated when the specified timeout expires. 39300 The timeout shall expire when the absolute time specified by abs_timeout passes, as measured by 39301 the clock on which timeouts are based (that is, when the value of that clock equals or exceeds 39302 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 39303 of the call. 39304 TMR If the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock. If | 39305 the Timers option is not supported, the timeout shall be based on the system clock as returned | 39306 by the time( ) function. The resolution of the timeout shall be the resolution of the clock on which | 39307 it is based. The timespec data type is defined as a structure in the header. | 39308 Under no circumstance shall the function fail with a timeout if the semaphore can be locked 39309 immediately. The validity of the abs_timeout need not be checked if the semaphore can be locked 39310 immediately. 39311 RETURN VALUE 39312 The sem_timedwait( ) function shall return zero if the calling process successfully performed the 39313 semaphore lock operation on the semaphore designated by sem. If the call was unsuccessful, the 39314 state of the semaphore shall be unchanged, and the function shall return a value of -1 and set 39315 errno to indicate the error. 39316 ERRORS 39317 The sem_timedwait( ) function shall fail if: 39318 [EINVAL] The sem argument does not refer to a valid semaphore. 39319 [EINVAL] The process or thread would have blocked, and the abs_timeout parameter 39320 specified a nanoseconds field value less than zero or greater than or equal to 39321 1 000 million. 39322 [ETIMEDOUT] The semaphore could not be locked before the specified timeout expired. 39323 The sem_timedwait( ) function may fail if: 39324 [EDEADLK] A deadlock condition was detected. 39325 [EINTR] A signal interrupted this function. System Interfaces, Issue 6 1753 sem_timedwait( ) System Interfaces 39326 EXAMPLES 39327 None. 39328 APPLICATION USAGE 39329 Applications using these functions may be subject to priority inversion, as discussed in the Base 39330 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 39331 The sem_timedwait( ) function is part of the Semaphores and Timeouts options and need not be 39332 provided on all implementations. 39333 RATIONALE 39334 None. 39335 FUTURE DIRECTIONS 39336 None. 39337 SEE ALSO 39338 sem_post( ), sem_trywait( ), sem_wait( ), semctl( ), semget( ), semop( ), time( ), the Base Definitions 39339 volume of IEEE Std 1003.1-200x, , 39340 CHANGE HISTORY 39341 First released in Issue 6. Derived from IEEE Std 1003.1d-1999. 1754 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_trywait( ) 39342 NAME 39343 sem_trywait, sem_wait - lock a semaphore (REALTIME) 39344 SYNOPSIS 39345 SEM #include 39346 int sem_trywait(sem_t *sem); 39347 int sem_wait(sem_t *sem); 39348 39349 DESCRIPTION 39350 The sem_trywait( ) function shall lock the semaphore referenced by sem only if the semaphore is 39351 currently not locked; that is, if the semaphore value is currently positive. Otherwise, shall does 39352 not lock the semaphore. 39353 The sem_wait( ) function shall lock the semaphore referenced by sem by performing a semaphore 39354 lock operation on that semaphore. If the semaphore value is currently zero, then the calling 39355 thread shall not return from the call to sem_wait( ) until it either locks the semaphore or the call is 39356 interrupted by a signal. 39357 Upon successful return, the state of the semaphore shall be locked and shall remain locked until 39358 the sem_post( ) function is executed and returns successfully. 39359 The sem_wait( ) function is interruptible by the delivery of a signal. 39360 RETURN VALUE 39361 The sem_trywait( ) and sem_wait( ) functions shall return zero if the calling process successfully 39362 performed the semaphore lock operation on the semaphore designated by sem. If the call was 39363 unsuccessful, the state of the semaphore shall be unchanged, and the function shall return a 39364 value of -1 and set errno to indicate the error. 39365 ERRORS 39366 The sem_trywait( ) and sem_wait( ) functions shall fail if: 39367 [EAGAIN] The semaphore was already locked, so it cannot be immediately locked by the 39368 sem_trywait( ) operation (sem_trywait( ) only). 39369 [EINVAL] The sem argument does not refer to a valid semaphore. 39370 The sem_trywait( ) and sem_wait( ) functions may fail if: 39371 [EDEADLK] A deadlock condition was detected. 39372 [EINTR] A signal interrupted this function. 39373 EXAMPLES 39374 None. 39375 APPLICATION USAGE 39376 Applications using these functions may be subject to priority inversion, as discussed in the Base 39377 Definitions volume of IEEE Std 1003.1-200x, Section 3.285, Priority Inversion. 39378 The sem_trywait( ) and sem_wait( ) functions are part of the Semaphores option and need not be 39379 provided on all implementations. 39380 RATIONALE 39381 None. System Interfaces, Issue 6 1755 sem_trywait( ) System Interfaces 39382 FUTURE DIRECTIONS 39383 None. 39384 SEE ALSO 39385 semctl( ), semget( ), semop( ), sem_post( ), sem_timedwait( ), the Base Definitions volume of 39386 IEEE Std 1003.1-200x, 39387 CHANGE HISTORY 39388 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39389 Issue 6 39390 The sem_trywait( ) and sem_wait( ) functions are marked as part of the Semaphores option. 39391 The [ENOSYS] error condition has been removed as stubs need not be provided if an 39392 implementation does not support the Semaphores option. 39393 The sem_timedwait( ) function is added to the SEE ALSO section for alignment with 39394 IEEE Std 1003.1d-1999. 1756 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_unlink( ) 39395 NAME 39396 sem_unlink - remove a named semaphore (REALTIME) 39397 SYNOPSIS 39398 SEM #include 39399 int sem_unlink(const char *name); 39400 39401 DESCRIPTION 39402 The sem_unlink( ) function shall remove the semaphore named by the string name. If the 39403 semaphore named by name is currently referenced by other processes, then sem_unlink( ) shall 39404 have no effect on the state of the semaphore. If one or more processes have the semaphore open 39405 when sem_unlink( ) is called, destruction of the semaphore is postponed until all references to the 39406 semaphore have been destroyed by calls to sem_close( ), _exit( ), or exec. Calls to sem_open( ) to 39407 recreate or reconnect to the semaphore refer to a new semaphore after sem_unlink( ) is called. The 39408 sem_unlink( ) call shall not block until all references have been destroyed; it shall return | 39409 immediately. 39410 RETURN VALUE 39411 Upon successful completion, the sem_unlink( ) function shall return a value of 0. Otherwise, the 39412 semaphore shall not be changed and the function shall return a value of -1 and set errno to 39413 indicate the error. 39414 ERRORS 39415 The sem_unlink( ) function shall fail if: 39416 [EACCES] Permission is denied to unlink the named semaphore. 39417 [ENAMETOOLONG] 39418 The length of the name argument exceeds {PATH_MAX} or a pathname | 39419 component is longer than {NAME_MAX}. | 39420 [ENOENT] The named semaphore does not exist. 39421 EXAMPLES 39422 None. 39423 APPLICATION USAGE 39424 The sem_unlink( ) function is part of the Semaphores option and need not be available on all 39425 implementations. 39426 RATIONALE 39427 None. 39428 FUTURE DIRECTIONS 39429 None. 39430 SEE ALSO 39431 semctl( ), semget( ), semop( ), sem_close( ), sem_open( ), the Base Definitions volume of 39432 IEEE Std 1003.1-200x, 39433 CHANGE HISTORY 39434 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 39435 Issue 6 39436 The sem_unlink( ) function is marked as part of the Semaphores option. | System Interfaces, Issue 6 1757 sem_unlink( ) System Interfaces 39437 The [ENOSYS] error condition has been removed as stubs need not be provided if an | 39438 implementation does not support the Semaphores option. 1758 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sem_wait( ) 39439 NAME 39440 sem_wait - lock a semaphore (REALTIME) 39441 SYNOPSIS 39442 SEM #include 39443 int sem_wait(sem_t *sem); 39444 39445 DESCRIPTION 39446 Refer to sem_trywait( ). System Interfaces, Issue 6 1759 semctl( ) System Interfaces 39447 NAME 39448 semctl - XSI semaphore control operations 39449 SYNOPSIS 39450 XSI #include 39451 int semctl(int semid, int semnum, int cmd, ...); 39452 39453 DESCRIPTION 39454 The semctl( ) function operates on XSI semaphores (see the Base Definitions volume of | 39455 IEEE Std 1003.1-200x, Section 4.15, Semaphore). It is unspecified whether this function | 39456 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 39457 page 491). 39458 The semctl( ) function provides a variety of semaphore control operations as specified by cmd. 39459 The fourth argument is optional and depends upon the operation requested. If required, it is of 39460 type union semun, which the application shall explicitly declare: 39461 union semun { 39462 int val; 39463 struct semid_ds *buf; 39464 unsigned short *array; 39465 } arg; 39466 The following semaphore control operations as specified by cmd are executed with respect to the 39467 semaphore specified by semid and semnum. The level of permission required for each operation 39468 is shown with each command; see Section 2.7 (on page 489). The symbolic names for the values 39469 of cmd are defined in the header: | 39470 GETVAL Return the value of semval; see . Requires read permission. 39471 SETVAL Set the value of semval to arg.val, where arg is the value of the fourth argument 39472 to semctl( ). When this command is successfully executed, the semadj value 39473 corresponding to the specified semaphore in all processes is cleared. Requires 39474 alter permission; see Section 2.7 (on page 489). 39475 GETPID Return the value of sempid. Requires read permission. 39476 GETNCNT Return the value of semncnt. Requires read permission. 39477 GETZCNT Return the value of semzcnt. Requires read permission. 39478 The following values of cmd operate on each semval in the set of semaphores: 39479 GETALL Return the value of semval for each semaphore in the semaphore set and place 39480 into the array pointed to by arg.array, where arg is the fourth argument to 39481 semctl( ). Requires read permission. 39482 SETALL Set the value of semval for each semaphore in the semaphore set according to 39483 the array pointed to by arg.array, where arg is the fourth argument to semctl( ). 39484 When this command is successfully executed, the semadj values corresponding 39485 to each specified semaphore in all processes are cleared. Requires alter 39486 permission. 39487 The following values of cmd are also available: 39488 IPC_STAT Place the current value of each member of the semid_ds data structure 39489 associated with semid into the structure pointed to by arg.buf, where arg is the 39490 fourth argument to semctl( ). The contents of this structure are defined in 1760 Technical Standard (2001) (Draft April 16, 2001) System Interfaces semctl( ) 39491 . Requires read permission. 39492 IPC_SET Set the value of the following members of the semid_ds data structure 39493 associated with semid to the corresponding value found in the structure 39494 pointed to by arg.buf, where arg is the fourth argument to semctl( ): 39495 sem_perm.uid 39496 sem_perm.gid 39497 sem_perm.mode 39498 The mode bits specified in Section 2.7.1 (on page 490) are copied into the 39499 corresponding bits of the sem_perm.mode associated with semid. The stored 39500 values of any other bits are unspecified. 39501 This command can only be executed by a process that has an effective user ID 39502 equal to either that of a process with appropriate privileges or to the value of 39503 sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with 39504 semid. 39505 IPC_RMID Remove the semaphore identifier specified by semid from the system and 39506 destroy the set of semaphores and semid_ds data structure associated with it. 39507 This command can only be executed by a process that has an effective user ID 39508 equal to either that of a process with appropriate privileges or to the value of 39509 sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with 39510 semid. 39511 RETURN VALUE 39512 If successful, the value returned by semctl( ) depends on cmd as follows: 39513 GETVAL The value of semval. 39514 GETPID The value of sempid. 39515 GETNCNT The value of semncnt. 39516 GETZCNT The value of semzcnt. 39517 All others 0. 39518 Otherwise, semctl( ) shall return -1 and set errno to indicate the error. 39519 ERRORS 39520 The semctl( ) function shall fail if: 39521 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page 39522 489). 39523 [EINVAL] The value of semid is not a valid semaphore identifier, or the value of semnum 39524 is less than 0 or greater than or equal to sem_nsems, or the value of cmd is not a 39525 valid command. 39526 [EPERM] The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID 39527 of the calling process is not equal to that of a process with appropriate 39528 privileges and it is not equal to the value of sem_perm.cuid or sem_perm.uid in 39529 the data structure associated with semid. 39530 [ERANGE] The argument cmd is equal to SETVAL or SETALL and the value to which 39531 semval is to be set is greater than the system-imposed maximum. System Interfaces, Issue 6 1761 semctl( ) System Interfaces 39532 EXAMPLES 39533 None. 39534 APPLICATION USAGE 39535 The fourth parameter in the SYNOPSIS section is now specified as "..." in order to avoid a 39536 clash with the ISO C standard when referring to the union semun (as defined in Issue 3) and for 39537 backward compatibility. 39538 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 39539 Application developers who need to use IPC should design their applications so that modules 39540 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 39541 alternative interfaces. 39542 RATIONALE 39543 None. 39544 FUTURE DIRECTIONS 39545 None. 39546 SEE ALSO 39547 semget( ), semop( ), sem_close( ), sem_destroy( ), sem_getvalue( ), sem_init( ), sem_open( ), sem_post( ), 39548 sem_unlink( ), sem_wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 39549 Section 2.7 (on page 489) 39550 CHANGE HISTORY 39551 First released in Issue 2. Derived from Issue 2 of the SVID. 39552 Issue 5 39553 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 39554 DIRECTIONS to the APPLICATION USAGE section. 1762 Technical Standard (2001) (Draft April 16, 2001) System Interfaces semget( ) 39555 NAME 39556 semget - get set of XSI semaphores 39557 SYNOPSIS 39558 XSI #include 39559 int semget(key_t key, int nsems, int semflg); 39560 39561 DESCRIPTION 39562 The semget( ) function operates on XSI semaphores (see the Base Definitions volume of | 39563 IEEE Std 1003.1-200x, Section 4.15, Semaphore). It is unspecified whether this function | 39564 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 39565 page 491). 39566 The semget( ) function shall return the semaphore identifier associated with key. 39567 A semaphore identifier with its associated semid_ds data structure and its associated set of 39568 nsems semaphores (see ) is created for key if one of the following is true: 39569 * The argument key is equal to IPC_PRIVATE. 39570 * The argument key does not already have a semaphore identifier associated with it and (semflg 39571 &IPC_CREAT) is non-zero. 39572 Upon creation, the semid_ds data structure associated with the new semaphore identifier is 39573 initialized as follows: 39574 * In the operation permissions structure sem_perm.cuid, sem_perm.uid, sem_perm.cgid, and 39575 sem_perm.gid shall be set equal to the effective user ID and effective group ID, respectively, of | 39576 the calling process. 39577 * The low-order 9 bits of sem_perm.mode shall be set equal to the low-order 9 bits of semflg. | 39578 * The variable sem_nsems shall be set equal to the value of nsems. | 39579 * The variable sem_otime shall be set equal to 0 and sem_ctime shall be set equal to the current | 39580 time. | 39581 * The data structure associated with each semaphore in the set shall not be initialized. The | 39582 semctl( ) function with the command SETVAL or SETALL can be used to initialize each 39583 semaphore. 39584 RETURN VALUE 39585 Upon successful completion, semget( ) shall return a non-negative integer, namely a semaphore 39586 identifier; otherwise, it shall return -1 and set errno to indicate the error. 39587 ERRORS 39588 The semget( ) function shall fail if: 39589 [EACCES] A semaphore identifier exists for key, but operation permission as specified by 39590 the low-order 9 bits of semflg would not be granted; see Section 2.7 (on page 39591 489). 39592 [EEXIST] A semaphore identifier exists for the argument key but ((semflg &IPC_CREAT) 39593 &&(semflg &IPC_EXCL)) is non-zero. 39594 [EINVAL] The value of nsems is either less than or equal to 0 or greater than the system- 39595 imposed limit, or a semaphore identifier exists for the argument key, but the 39596 number of semaphores in the set associated with it is less than nsems and 39597 nsems is not equal to 0. System Interfaces, Issue 6 1763 semget( ) System Interfaces 39598 [ENOENT] A semaphore identifier does not exist for the argument key and (semflg 39599 &IPC_CREAT) is equal to 0. 39600 [ENOSPC] A semaphore identifier is to be created but the system-imposed limit on the 39601 maximum number of allowed semaphores system-wide would be exceeded. 39602 EXAMPLES 39603 Creating a Semaphore Identifier 39604 The following example gets a unique semaphore key using the ftok( ) function, then gets a 39605 semaphore ID associated with that key using the semget( ) function (the first call also tests to 39606 make sure the semaphore exists). If the semaphore does not exist, the program creates it, as 39607 shown by the second call to semget( ). In creating the semaphore for the queuing process, the 39608 program attempts to create one semaphore with read/write permission for all. It also uses the 39609 IPC_EXCL flag, which forces semget( ) to fail if the semaphore already exists. 39610 After creating the semaphore, the program uses a call to semop( ) to initialize it to the values in 39611 the sbuf array. The number of processes that can execute concurrently without queuing is 39612 initially set to 2. The final call to semget( ) creates a semaphore identifier that can be used later in 39613 the program. 39614 #include 39615 #include 39616 #include 39617 #include 39618 #include 39619 #include 39620 #include 39621 #include 39622 #include 39623 #include 39624 #include 39625 ... 39626 key_t semkey; 39627 int semid, pfd, fv; 39628 struct sembuf sbuf; 39629 char *lgn; 39630 char filename[PATH_MAX+1]; 39631 struct stat outstat; 39632 struct passwd *pw; 39633 ... 39634 /* Get unique key for semaphore. */ 39635 if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { 39636 perror("IPC error: ftok"); exit(1); 39637 } 39638 /* Get semaphore ID associated with this key. */ 39639 if ((semid = semget(semkey, 0, 0)) == -1) { 39640 /* Semaphore does not exist - Create. */ 39641 if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | 39642 S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) 39643 { 39644 /* Initialize the semaphore. */ 39645 sbuf.sem_num = 0; 1764 Technical Standard (2001) (Draft April 16, 2001) System Interfaces semget( ) 39646 sbuf.sem_op = 2; /* This is the number of runs without queuing. */ 39647 sbuf.sem_flg = 0; 39648 if (semop(semid, &sbuf, 1) == -1) { 39649 perror("IPC error: semop"); exit(1); 39650 } 39651 } 39652 else if (errno == EEXIST) { 39653 if ((semid = semget(semkey, 0, 0)) == -1) { 39654 perror("IPC error 1: semget"); exit(1); 39655 } 39656 } 39657 else { 39658 perror("IPC error 2: semget"); exit(1); 39659 } 39660 } 39661 ... 39662 APPLICATION USAGE 39663 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 39664 Application developers who need to use IPC should design their applications so that modules 39665 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 39666 alternative interfaces. 39667 RATIONALE 39668 None. 39669 FUTURE DIRECTIONS 39670 None. 39671 SEE ALSO 39672 semctl( ), semop( ), sem_close( ), sem_destroy( ), sem_getvalue( ), sem_init( ), sem_open( ), sem_post( ), 39673 sem_unlink( ), sem_wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 39674 Section 2.7 (on page 489). 39675 CHANGE HISTORY 39676 First released in Issue 2. Derived from Issue 2 of the SVID. 39677 Issue 5 39678 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 39679 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1765 semop( ) System Interfaces 39680 NAME 39681 semop - XSI semaphore operations 39682 SYNOPSIS 39683 XSI #include 39684 int semop(int semid, struct sembuf *sops, size_t nsops); 39685 39686 DESCRIPTION 39687 The semop( ) function operates on XSI semaphores (see the Base Definitions volume of | 39688 IEEE Std 1003.1-200x, Section 4.15, Semaphore). It is unspecified whether this function | 39689 interoperates with the realtime interprocess communication facilities defined in Section 2.8 (on 39690 page 491). 39691 The semop( ) function shall perform atomically a user-defined array of semaphore operations on | 39692 the set of semaphores associated with the semaphore identifier specified by the argument semid. | 39693 The argument sops is a pointer to a user-defined array of semaphore operation structures. The 39694 implementation shall not modify elements of this array unless the application uses 39695 implementation-defined extensions. 39696 The argument nsops is the number of such structures in the array. 39697 Each structure, sembuf, includes the following members: 39698 ______________________________________________________ 39699 _ Member Type Member Name Description _____________________________________________________ 39700 short sem_num Semaphore number. 39701 short sem_op Semaphore operation. 39702 _ short sem_flg Operation flags. _____________________________________________________ 39703 Each semaphore operation specified by sem_op is performed on the corresponding semaphore 39704 specified by semid and sem_num. 39705 The variable sem_op specifies one of three semaphore operations: 39706 1. If sem_op is a negative integer and the calling process has alter permission, one of the 39707 following shall occur: 39708 * If semval(see ) is greater than or equal to the absolute value of sem_op, the 39709 absolute value of sem_op is subtracted from semval. Also, if (sem_flg &SEM_UNDO) is 39710 non-zero, the absolute value of sem_op shall be added to the calling process' semadj | 39711 value for the specified semaphore. 39712 * If semval is less than the absolute value of sem_op and (sem_flg &IPC_NOWAIT) is non- 39713 zero, semop( ) shall return immediately. 39714 * If semval is less than the absolute value of sem_op and (sem_flg &IPC_NOWAIT) is 0, 39715 semop( ) shall increment the semncnt associated with the specified semaphore and 39716 suspend execution of the calling thread until one of the following conditions occurs: 39717 - The value of semval becomes greater than or equal to the absolute value of sem_op. 39718 When this occurs, the value of semncnt associated with the specified semaphore | 39719 shall be decremented, the absolute value of sem_op shall be subtracted from semval | 39720 and, if (sem_flg &SEM_UNDO) is non-zero, the absolute value of sem_op shall be | 39721 added to the calling process' semadj value for the specified semaphore. | 39722 - The semid for which the calling thread is awaiting action is removed from the 39723 system. When this occurs, errno shall be set equal to [EIDRM] and -1 shall be 1766 Technical Standard (2001) (Draft April 16, 2001) System Interfaces semop( ) 39724 returned. 39725 - The calling thread receives a signal that is to be caught. When this occurs, the value 39726 of semncnt associated with the specified semaphore shall be decremented, and the | 39727 calling thread shall resume execution in the manner prescribed in sigaction( ). | 39728 2. If sem_op is a positive integer and the calling process has alter permission, the value of 39729 sem_op shall be added to semval and, if (sem_flg &SEM_UNDO) is non-zero, the value of | 39730 sem_op shall be subtracted from the calling process' semadj value for the specified | 39731 semaphore. 39732 3. If sem_op is 0 and the calling process has read permission, one of the following shall occur: 39733 * If semval is 0, semop( ) shall return immediately. 39734 * If semval is non-zero and (sem_flg &IPC_NOWAIT) is non-zero, semop( ) shall return 39735 immediately. 39736 * If semval is non-zero and (sem_flg &IPC_NOWAIT) is 0, semop( ) shall increment the | 39737 semzcnt associated with the specified semaphore and suspend execution of the calling | 39738 thread until one of the following occurs: 39739 - The value of semval becomes 0, at which time the value of semzcnt associated with | 39740 the specified semaphore shall be decremented. | 39741 - The semid for which the calling thread is awaiting action is removed from the 39742 system. When this occurs, errno shall be set equal to [EIDRM] and -1 shall be 39743 returned. 39744 - The calling thread receives a signal that is to be caught. When this occurs, the value 39745 of semzcnt associated with the specified semaphore shall be decremented, and the | 39746 calling thread shall resume execution in the manner prescribed in sigaction( ). | 39747 Upon successful completion, the value of sempid for each semaphore specified in the array 39748 pointed to by sops shall be set equal to the process ID of the calling process. 39749 RETURN VALUE 39750 Upon successful completion, semop( ) shall return 0; otherwise, it shall return -1 and set errno to 39751 indicate the error. 39752 ERRORS 39753 The semop( ) function shall fail if: 39754 [E2BIG] The value of nsops is greater than the system-imposed maximum. 39755 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page 39756 489). 39757 [EAGAIN] The operation would result in suspension of the calling process but (sem_flg 39758 &IPC_NOWAIT) is non-zero. 39759 [EFBIG] The value of sem_num is less than 0 or greater than or equal to the number of 39760 semaphores in the set associated with semid. 39761 [EIDRM] The semaphore identifier semid is removed from the system. 39762 [EINTR] The semop( ) function was interrupted by a signal. 39763 [EINVAL] The value of semid is not a valid semaphore identifier, or the number of 39764 individual semaphores for which the calling process requests a SEM_UNDO 39765 would exceed the system-imposed limit. System Interfaces, Issue 6 1767 semop( ) System Interfaces 39766 [ENOSPC] The limit on the number of individual processes requesting a SEM_UNDO 39767 would be exceeded. 39768 [ERANGE] An operation would cause a semval to overflow the system-imposed limit, or 39769 an operation would cause a semadj value to overflow the system-imposed 39770 limit. 39771 EXAMPLES 39772 Setting Values in Semaphores 39773 The following example sets the values of the two semaphores associated with the semid 39774 identifier to the values contained in the sb array. 39775 #include 39776 ... 39777 int semid; 39778 struct sembuf sb[2]; 39779 int nsops = 2; 39780 int result; 39781 /* Adjust value of semaphore in the semaphore array semid. */ 39782 sb[0].sem_num = 0; 39783 sb[0].sem_op = -1; 39784 sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT; 39785 sb[1].sem_num = 1; 39786 sb[1].sem_op = 1; 39787 sb[1].sem_flg = 0; 39788 result = semop(semid, sb, nsops); 39789 Creating a Semaphore Identifier 39790 The following example gets a unique semaphore key using the ftok( ) function, then gets a 39791 semaphore ID associated with that key using the semget( ) function (the first call also tests to 39792 make sure the semaphore exists). If the semaphore does not exist, the program creates it, as 39793 shown by the second call to semget( ). In creating the semaphore for the queuing process, the 39794 program attempts to create one semaphore with read/write permission for all. It also uses the 39795 IPC_EXCL flag, which forces semget( ) to fail if the semaphore already exists. 39796 After creating the semaphore, the program uses a call to semop( ) to initialize it to the values in 39797 the sbuf array. The number of processes that can execute concurrently without queuing is 39798 initially set to 2. The final call to semget( ) creates a semaphore identifier that can be used later in 39799 the program. 39800 The final call to semop( ) acquires the semaphore and waits until it is free; the SEM_UNDO 39801 option releases the semaphore when the process exits, waiting until there are less than two 39802 processes running concurrently. 39803 #include 39804 #include 39805 #include 39806 #include 39807 #include 39808 #include 39809 #include 39810 #include 1768 Technical Standard (2001) (Draft April 16, 2001) System Interfaces semop( ) 39811 #include 39812 #include 39813 #include 39814 ... 39815 key_t semkey; 39816 int semid, pfd, fv; 39817 struct sembuf sbuf; 39818 char *lgn; 39819 char filename[PATH_MAX+1]; 39820 struct stat outstat; 39821 struct passwd *pw; 39822 ... 39823 /* Get unique key for semaphore. */ 39824 if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { 39825 perror("IPC error: ftok"); exit(1); 39826 } 39827 /* Get semaphore ID associated with this key. */ 39828 if ((semid = semget(semkey, 0, 0)) == -1) { 39829 /* Semaphore does not exist - Create. */ 39830 if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | 39831 S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) 39832 { 39833 /* Initialize the semaphore. */ 39834 sbuf.sem_num = 0; 39835 sbuf.sem_op = 2; /* This is the number of runs without queuing. */ 39836 sbuf.sem_flg = 0; 39837 if (semop(semid, &sbuf, 1) == -1) { 39838 perror("IPC error: semop"); exit(1); 39839 } 39840 } 39841 else if (errno == EEXIST) { 39842 if ((semid = semget(semkey, 0, 0)) == -1) { 39843 perror("IPC error 1: semget"); exit(1); 39844 } 39845 } 39846 else { 39847 perror("IPC error 2: semget"); exit(1); 39848 } 39849 } 39850 ... 39851 sbuf.sem_num = 0; 39852 sbuf.sem_op = -1; 39853 sbuf.sem_flg = SEM_UNDO; 39854 if (semop(semid, &sbuf, 1) == -1) { 39855 perror("IPC Error: semop"); exit(1); 39856 } 39857 APPLICATION USAGE 39858 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 39859 Application developers who need to use IPC should design their applications so that modules 39860 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 39861 alternative interfaces. System Interfaces, Issue 6 1769 semop( ) System Interfaces 39862 RATIONALE 39863 None. 39864 FUTURE DIRECTIONS 39865 None. 39866 SEE ALSO 39867 exec, exit( ), fork( ), semctl( ), semget( ), sem_close( ), sem_destroy( ), sem_getvalue( ), sem_init( ), 39868 sem_open( ), sem_post( ), sem_unlink( ), sem_wait( ), the Base Definitions volume of 39869 IEEE Std 1003.1-200x, , , , Section 2.7 (on page 489) 39870 CHANGE HISTORY 39871 First released in Issue 2. Derived from Issue 2 of the SVID. 39872 Issue 5 39873 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 39874 DIRECTIONS to a new APPLICATION USAGE section. 1770 Technical Standard (2001) (Draft April 16, 2001) System Interfaces send( ) 39875 NAME 39876 send - send a message on a socket 39877 SYNOPSIS 39878 #include 39879 ssize_t send(int socket, const void *buffer, size_t length, int flags); 39880 DESCRIPTION 39881 The send( ) function shall initiate transmission of a message from the specified socket to its peer. 39882 The send( ) function shall send a message only when the socket is connected (including when the | 39883 peer of a connectionless socket has been set via connect( )). 39884 The send( ) functions takes the following arguments: 39885 socket Specifies the socket file descriptor. 39886 buffer Points to the buffer containing the message to send. 39887 length Specifies the length of the message in bytes. 39888 flags Specifies the type of message transmission. Values of this argument are 39889 formed by logically OR'ing zero or more of the following flags: 39890 MSG_EOR Terminates a record (if supported by the protocol). 39891 MSG_OOB Sends out-of-band data on sockets that support out-of-band 39892 communications. The significance and semantics of out-of- 39893 band data are protocol-specific. 39894 The length of the message to be sent is specified by the length argument. If the message is too 39895 long to pass through the underlying protocol, send( ) shall fail and no data shall be transmitted. 39896 Successful completion of a call to send( ) does not guarantee delivery of the message. A return 39897 value of -1 indicates only locally-detected errors. 39898 If space is not available at the sending socket to hold the message to be transmitted, and the 39899 socket file descriptor does not have O_NONBLOCK set, send( ) shall block until space is 39900 available. If space is not available at the sending socket to hold the message to be transmitted, 39901 and the socket file descriptor does have O_NONBLOCK set, send( ) shall fail. The select( ) and 39902 poll( ) functions can be used to determine when it is possible to send more data. 39903 The socket in use may require the process to have appropriate privileges to use the send( ) 39904 function. 39905 RETURN VALUE 39906 Upon successful completion, send( ) shall return the number of bytes sent. Otherwise, -1 shall be 39907 returned and errno set to indicate the error. 39908 ERRORS 39909 The send( ) function shall fail if: 39910 [EAGAIN] or [EWOULDBLOCK] 39911 The socket's file descriptor is marked O_NONBLOCK and the requested 39912 operation would block. 39913 [EBADF] The socket argument is not a valid file descriptor. 39914 [ECONNRESET] A connection was forcibly closed by a peer. 39915 [EDESTADDRREQ] 39916 The socket is not connection-mode and no peer address is set. System Interfaces, Issue 6 1771 send( ) System Interfaces 39917 [EINTR] A signal interrupted send( ) before any data was transmitted. 39918 [EMSGSIZE] The message is too large be sent all at once, as the socket requires. 39919 [ENOTCONN] The socket is not connected or otherwise has not had the peer pre-specified. 39920 [ENOTSOCK] The socket argument does not refer to a socket. 39921 [EOPNOTSUPP] The socket argument is associated with a socket that does not support one or 39922 more of the values set in flags. 39923 [EPIPE] The socket is shut down for writing, or the socket is connection-mode and is 39924 no longer connected. In the latter case, and if the socket is of type 39925 SOCK_STREAM, the SIGPIPE signal is generated to the calling thread. 39926 The send( ) function may fail if: 39927 [EACCES] The calling process does not have the appropriate privileges. 39928 [EIO] An I/O error occurred while reading from or writing to the file system. 39929 [ENETDOWN] The local network interface used to reach the destination is down. 39930 [ENETUNREACH] 39931 No route to the network is present. 39932 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 39933 EXAMPLES 39934 None. 39935 APPLICATION USAGE 39936 The send( ) function is equivalent to sendto( ) with a null pointer dest_len argument, and to write( ) | 39937 if no flags are used. 39938 RATIONALE 39939 None. 39940 FUTURE DIRECTIONS 39941 None. 39942 SEE ALSO 39943 connect( ), getsockopt( ), poll( ), recv( ), recvfrom( ), recvmsg( ), select( ), sendmsg( ), sendto( ), 39944 setsockopt( ), shutdown( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 39945 39946 CHANGE HISTORY 39947 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 1772 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sendmsg( ) 39948 NAME 39949 sendmsg - send a message on a socket using a message structure 39950 SYNOPSIS 39951 #include 39952 ssize_t sendmsg(int socket, const struct msghdr *message, int flags); 39953 DESCRIPTION 39954 The sendmsg( ) function shall send a message through a connection-mode or connectionless- 39955 mode socket. If the socket is connectionless-mode, the message shall be sent to the address 39956 specified by msghdr. If the socket is connection-mode, the destination address in msghdr shall | 39957 be ignored. | 39958 The sendmsg( ) function takes the following arguments: 39959 socket Specifies the socket file descriptor. 39960 message Points to a msghdr structure, containing both the destination address and the 39961 buffers for the outgoing message. The length and format of the address 39962 depend on the address family of the socket. The msg_flags member is ignored. 39963 flags Specifies the type of message transmission. The application may specify 0 or 39964 the following flag: 39965 MSG_EOR Terminates a record (if supported by the protocol). 39966 MSG_OOB Sends out-of-band data on sockets that support out-of- 39967 bound data. The significance and semantics of out-of-band 39968 data are protocol-specific. 39969 The msg_iov and msg_iovlen fields of message specify zero or more buffers containing the data to 39970 be sent. msg_iov points to an array of iovec structures; msg_iovlen shall be set to the dimension of 39971 this array. In each iovec structure, the iov_base field specifies a storage area and the iov_len field 39972 gives its size in bytes. Some of these sizes can be zero. The data from each storage area indicated 39973 by msg_iov is sent in turn. 39974 Successful completion of a call to sendmsg( ) does not guarantee delivery of the message. A 39975 return value of -1 indicates only locally-detected errors. 39976 If space is not available at the sending socket to hold the message to be transmitted and the 39977 socket file descriptor does not have O_NONBLOCK set, sendmsg( ) function shall block until | 39978 space is available. If space is not available at the sending socket to hold the message to be | 39979 transmitted and the socket file descriptor does have O_NONBLOCK set, sendmsg( ) function | 39980 shall fail. 39981 If the socket protocol supports broadcast and the specified address is a broadcast address for the 39982 socket protocol, sendmsg( ) shall fail if the SO_BROADCAST option is not set for the socket. 39983 The socket in use may require the process to have appropriate privileges to use the sendmsg( ) 39984 function. 39985 RETURN VALUE 39986 Upon successful completion, sendmsg( ) shall return the number of bytes sent. Otherwise, -1 39987 shall be returned and errno set to indicate the error. 39988 ERRORS 39989 The sendmsg( ) function shall fail if: 39990 [EAGAIN] or [EWOULDBLOCK] 39991 The socket's file descriptor is marked O_NONBLOCK and the requested System Interfaces, Issue 6 1773 sendmsg( ) System Interfaces 39992 operation would block. 39993 [EAFNOSUPPORT] 39994 Addresses in the specified address family cannot be used with this socket. 39995 [EBADF] The socket argument is not a valid file descriptor. 39996 [ECONNRESET] A connection was forcibly closed by a peer. 39997 [EINTR] A signal interrupted sendmsg( ) before any data was transmitted. 39998 [EINVAL] The sum of the iov_len values overflows an ssize_t. 39999 [EMSGSIZE] The message is too large to be sent all at once (as the socket requires), or the 40000 msg_iovlen member of the msghdr structure pointed to by message is less than 40001 or equal to 0 or is greater than {IOV_MAX}. 40002 [ENOTCONN] The socket is connection-mode but is not connected. 40003 [ENOTSOCK] The socket argument does not refer a socket. 40004 [EOPNOTSUPP] The socket argument is associated with a socket that does not support one or 40005 more of the values set in flags. 40006 [EPIPE] The socket is shut down for writing, or the socket is connection-mode and is 40007 no longer connected. In the latter case, and if the socket is of type 40008 SOCK_STREAM, the SIGPIPE signal is generated to the calling thread. 40009 If the address family of the socket is AF_UNIX, then sendmsg( ) shall fail if: 40010 [EIO] An I/O error occurred while reading from or writing to the file system. 40011 [ELOOP] A loop exists in symbolic links encountered during resolution of the pathname | 40012 in the socket address. | 40013 [ENAMETOOLONG] 40014 A component of a pathname exceeded {NAME_MAX} characters, or an entire | 40015 pathname exceeded {PATH_MAX} characters. | 40016 [ENOENT] A component of the pathname does not name an existing file or the path name | 40017 is an empty string. 40018 [ENOTDIR] A component of the path prefix of the pathname in the socket address is not a | 40019 directory. 40020 The sendmsg( ) function may fail if: 40021 [EACCES] Search permission is denied for a component of the path prefix; or write 40022 access to the named socket is denied. 40023 [EDESTADDRREQ] 40024 The socket is not connection-mode and does not have its peer address set, and 40025 no destination address was specified. 40026 [EHOSTUNREACH] 40027 The destination host cannot be reached (probably because the host is down or 40028 a remote router cannot reach it). 40029 [EIO] An I/O error occurred while reading from or writing to the file system. 40030 [EISCONN] A destination address was specified and the socket is already connected. 40031 [ENETDOWN] The local network interface used to reach the destination is down. 1774 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sendmsg( ) 40032 [ENETUNREACH] 40033 No route to the network is present. 40034 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 40035 [ENOMEM] Insufficient memory was available to fulfill the request. 40036 If the address family of the socket is AF_UNIX, then sendmsg( ) may fail if: 40037 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 40038 resolution of the pathname in the socket address. | 40039 [ENAMETOOLONG] 40040 Pathname resolution of a symbolic link produced an intermediate result | 40041 whose length exceeds {PATH_MAX}. 40042 EXAMPLES 40043 Done. 40044 APPLICATION USAGE 40045 The select( ) and poll( ) functions can be used to determine when it is possible to send more data. 40046 RATIONALE 40047 None. 40048 FUTURE DIRECTIONS 40049 None. 40050 SEE ALSO 40051 getsockopt( ), poll( ), recv( ), recvfrom( ), recvmsg( ), select( ), send( ), sendto( ), setsockopt( ), 40052 shutdown( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40053 CHANGE HISTORY 40054 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 40055 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 40056 [ELOOP] error condition is added. System Interfaces, Issue 6 1775 sendto( ) System Interfaces 40057 NAME 40058 sendto - send a message on a socket 40059 SYNOPSIS 40060 #include 40061 ssize_t sendto(int socket, const void *message, size_t length, 40062 int flags, const struct sockaddr *dest_addr, 40063 socklen_t dest_len); 40064 DESCRIPTION 40065 The sendto( ) function shall send a message through a connection-mode or connectionless-mode 40066 socket. If the socket is connectionless-mode, the message shall be sent to the address specified by 40067 dest_addr. If the socket is connection-mode, dest_addr shall be ignored. | 40068 The sendto( ) function takes the following arguments: 40069 socket Specifies the socket file descriptor. 40070 message Points to a buffer containing the message to be sent. 40071 length Specifies the size of the message in bytes. 40072 flags Specifies the type of message transmission. Values of this argument are 40073 formed by logically OR'ing zero or more of the following flags: 40074 MSG_EOR Terminates a record (if supported by the protocol). 40075 MSG_OOB Sends out-of-band data on sockets that support out-of-band 40076 data. The significance and semantics of out-of-band data are 40077 protocol-specific. 40078 dest_addr Points to a sockaddr structure containing the destination address. The length 40079 and format of the address depend on the address family of the socket. 40080 dest_len Specifies the length of the sockaddr structure pointed to by the dest_addr 40081 argument. 40082 If the socket protocol supports broadcast and the specified address is a broadcast address for the 40083 socket protocol, sendto( ) shall fail if the SO_BROADCAST option is not set for the socket. 40084 The dest_addr argument specifies the address of the target. The length argument specifies the 40085 length of the message. 40086 Successful completion of a call to sendto( ) does not guarantee delivery of the message. A return 40087 value of -1 indicates only locally-detected errors. 40088 If space is not available at the sending socket to hold the message to be transmitted and the 40089 socket file descriptor does not have O_NONBLOCK set, sendto( ) shall block until space is | 40090 available. If space is not available at the sending socket to hold the message to be transmitted | 40091 and the socket file descriptor does have O_NONBLOCK set, sendto( ) shall fail. 40092 The socket in use may require the process to have appropriate privileges to use the sendto( ) 40093 function. 40094 RETURN VALUE 40095 Upon successful completion, sendto( ) shall return the number of bytes sent. Otherwise, -1 shall 40096 be returned and errno set to indicate the error. 1776 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sendto( ) 40097 ERRORS 40098 The sendto( ) function shall fail if: 40099 [EAFNOSUPPORT] 40100 Addresses in the specified address family cannot be used with this socket. 40101 [EAGAIN] or [EWOULDBLOCK] 40102 The socket's file descriptor is marked O_NONBLOCK and the requested 40103 operation would block. 40104 [EBADF] The socket argument is not a valid file descriptor. 40105 [ECONNRESET] A connection was forcibly closed by a peer. 40106 [EINTR] A signal interrupted sendto( ) before any data was transmitted. 40107 [EMSGSIZE] The message is too large to be sent all at once, as the socket requires. 40108 [ENOTCONN] The socket is connection-mode but is not connected. 40109 [ENOTSOCK] The socket argument does not refer to a socket. 40110 [EOPNOTSUPP] The socket argument is associated with a socket that does not support one or 40111 more of the values set in flags. 40112 [EPIPE] The socket is shut down for writing, or the socket is connection-mode and is 40113 no longer connected. In the latter case, and if the socket is of type 40114 SOCK_STREAM, the SIGPIPE signal is generated to the calling thread. 40115 If the address family of the socket is AF_UNIX, then sendto( ) shall fail if: 40116 [EIO] An I/O error occurred while reading from or writing to the file system. 40117 [ELOOP] A loop exists in symbolic links encountered during resolution of the pathname | 40118 in the socket address. | 40119 [ENAMETOOLONG] 40120 A component of a pathname exceeded {NAME_MAX} characters, or an entire | 40121 pathname exceeded {PATH_MAX} characters. | 40122 [ENOENT] A component of the pathname does not name an existing file or the pathname | 40123 is an empty string. | 40124 [ENOTDIR] A component of the path prefix of the pathname in the socket address is not a | 40125 directory. 40126 The sendto( ) function may fail if: 40127 [EACCES] Search permission is denied for a component of the path prefix; or write 40128 access to the named socket is denied. 40129 [EDESTADDRREQ] 40130 The socket is not connection-mode and does not have its peer address set, and 40131 no destination address was specified. 40132 [EHOSTUNREACH] 40133 The destination host cannot be reached (probably because the host is down or 40134 a remote router cannot reach it). 40135 [EINVAL] The dest_len argument is not a valid length for the address family. 40136 [EIO] An I/O error occurred while reading from or writing to the file system. System Interfaces, Issue 6 1777 sendto( ) System Interfaces 40137 [EISCONN] A destination address was specified and the socket is already connected. This 40138 error may or may not be returned for connection mode sockets. 40139 [ENETDOWN] The local network interface used to reach the destination is down. 40140 [ENETUNREACH] 40141 No route to the network is present. 40142 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 40143 [ENOMEM] Insufficient memory was available to fulfill the request. 40144 If the address family of the socket is AF_UNIX, then sendto( ) may fail if: 40145 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during | 40146 resolution of the pathname in the socket address. | 40147 [ENAMETOOLONG] 40148 Pathname resolution of a symbolic link produced an intermediate result | 40149 whose length exceeds {PATH_MAX}. 40150 EXAMPLES 40151 None. 40152 APPLICATION USAGE 40153 The select( ) and poll( ) functions can be used to determine when it is possible to send more data. 40154 RATIONALE 40155 None. 40156 FUTURE DIRECTIONS 40157 None. 40158 SEE ALSO 40159 getsockopt( ), poll( ), recv( ), recvfrom( ), recvmsg( ), select( ), send( ), sendmsg( ), setsockopt( ), 40160 shutdown( ), socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40161 CHANGE HISTORY 40162 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 40163 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 40164 [ELOOP] error condition is added. 1778 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setbuf( ) 40165 NAME 40166 setbuf - assign buffering to a stream 40167 SYNOPSIS 40168 #include 40169 void setbuf(FILE *restrict stream, char *restrict buf); 40170 DESCRIPTION 40171 CX The functionality described on this reference page is aligned with the ISO C standard. Any 40172 conflict between the requirements described here and the ISO C standard is unintentional. This 40173 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 40174 Except that it returns no value, the function call: 40175 setbuf(stream, buf) 40176 shall be equivalent to: 40177 setvbuf(stream, buf, _IOFBF, BUFSIZ) 40178 if buf is not a null pointer, or to: 40179 setvbuf(stream, buf, _IONBF, BUFSIZ) 40180 if buf is a null pointer. 40181 RETURN VALUE 40182 The setbuf( ) function shall not return a value. 40183 ERRORS 40184 No errors are defined. 40185 EXAMPLES 40186 None. 40187 APPLICATION USAGE 40188 A common source of error is allocating buffer space as an ``automatic'' variable in a code block, 40189 and then failing to close the stream in the same block. 40190 With setbuf( ), allocating a buffer of BUFSIZ bytes does not necessarily imply that all of BUFSIZ 40191 bytes are used for the buffer area. 40192 RATIONALE 40193 None. 40194 FUTURE DIRECTIONS 40195 None. 40196 SEE ALSO 40197 fopen( ), setvbuf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40198 CHANGE HISTORY 40199 First released in Issue 1. Derived from Issue 1 of the SVID. 40200 Issue 6 40201 The prototype for setbuf( ) is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1779 setcontext( ) System Interfaces 40202 NAME 40203 setcontext - set current user context 40204 SYNOPSIS 40205 XSI #include 40206 int setcontext(const ucontext_t *ucp); 40207 40208 DESCRIPTION 40209 Refer to getcontext( ). 1780 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setegid( ) 40210 NAME 40211 setegid - set effective group ID 40212 SYNOPSIS 40213 #include 40214 int setegid(gid_t gid); 40215 DESCRIPTION 40216 If gid is equal to the real group ID or the saved set-group-ID, or if the process has appropriate 40217 privileges, setegid( ) shall set the effective group ID of the calling process to gid; the real group 40218 ID, saved set-group-ID, and any supplementary group IDs shall remain unchanged. 40219 The setegid( ) function shall not affect the supplementary group list in any way. 40220 RETURN VALUE 40221 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 40222 indicate the error. 40223 ERRORS 40224 The setegid( ) function shall fail if: 40225 [EINVAL] The value of the gid argument is invalid and is not supported by the 40226 implementation. 40227 [EPERM] The process does not have appropriate privileges and gid does not match the 40228 real group ID or the saved set-group-ID. 40229 EXAMPLES 40230 None. 40231 APPLICATION USAGE 40232 None. 40233 RATIONALE 40234 Refer to the RATIONALE section in setuid( ). 40235 FUTURE DIRECTIONS 40236 None. 40237 SEE ALSO 40238 exec, getegid( ), geteuid( ), getgid( ), getuid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the 40239 Base Definitions volume of IEEE Std 1003.1-200x, , 40240 CHANGE HISTORY 40241 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. System Interfaces, Issue 6 1781 setenv( ) System Interfaces 40242 NAME 40243 setenv - add or change environment variable 40244 SYNOPSIS 40245 CX #include | 40246 int setenv(const char *envname, const char *envval, int overwrite); 40247 | 40248 DESCRIPTION 40249 The setenv( ) function shall update or add a variable in the environment of the calling process. | 40250 The envname argument points to a string containing the name of an environment variable to be | 40251 added or altered. The environment variable shall be set to the value to which envval points. The 40252 function shall fail if envname points to a string which contains an '=' character. If the 40253 environment variable named by envname already exists and the value of overwrite is non-zero, 40254 the function shall return success and the environment shall be updated. If the environment 40255 variable named by envname already exists and the value of overwrite is zero, the function shall 40256 return success and the environment shall remain unchanged. 40257 If the application modifies environ or the pointers to which it points, the behavior of setenv( ) is 40258 undefined. The setenv( ) function shall update the list of pointers to which environ points. 40259 The strings described by envname and envval are copied by this function. 40260 The setenv( ) function need not be reentrant. A function that is not required to be reentrant is not 40261 required to be thread-safe. 40262 RETURN VALUE 40263 Upon successful completion, zero shall be returned. Otherwise, -1 shall be returned, errno set to 40264 indicate the error, and the environment shall be unchanged. 40265 ERRORS 40266 The setenv( ) function shall fail if: 40267 [EINVAL] The name argument is a null pointer, points to an empty string, or points to a 40268 string containing an '=' character. 40269 [ENOMEM] Insufficient memory was available to add a variable or its value to the 40270 environment. 40271 EXAMPLES 40272 None. 40273 APPLICATION USAGE 40274 None. 40275 RATIONALE 40276 Unanticipated results may occur if setenv( ) changes the external variable environ. In particular, 40277 if the optional envp argument to main( ) is present, it is not changed, and thus may point to an 40278 obsolete copy of the environment (as may any other copy of environ). However, other than the 40279 aforementioned restriction, the developers of IEEE Std 1003.1-200x intended that the traditional 40280 method of walking through the environment by way of the environ pointer must be supported. 40281 It was decided that setenv( ) should be required by this revision because it addresses a piece of 40282 missing functionality, and does not impose a significant burden on the implementor. 40283 There was considerable debate as to whether the System V putenv( ) function or the BSD setenv( ) 40284 function should be required as a mandatory function. The setenv( ) function was chosen because 40285 it permitted the implementation of unsetenv( ) function to delete environmental variables, 40286 without specifying an additional interface. The putenv( ) function is available as an XSI 1782 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setenv( ) 40287 extension. 40288 The standard developers considered requiring that setenv( ) indicate an error when a call to it 40289 would result in exceeding {ARG_MAX}. The requirement was rejected since the condition might 40290 be temporary, with the application eventually reducing the environment size. The ultimate 40291 success or failure depends on the size at the time of a call to exec, which returns an indication of 40292 this error condition. 40293 FUTURE DIRECTIONS 40294 None. 40295 SEE ALSO 40296 getenv( ), unsetenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 40297 , 40298 CHANGE HISTORY 40299 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. System Interfaces, Issue 6 1783 seteuid( ) System Interfaces 40300 NAME 40301 seteuid - set effective user ID 40302 SYNOPSIS 40303 #include 40304 int seteuid(uid_t uid); 40305 DESCRIPTION 40306 If uid is equal to the real user ID or the saved set-user-ID, or if the process has appropriate 40307 privileges, seteuid( ) shall set the effective user ID of the calling process to uid; the real user ID 40308 and saved set-user-ID shall remain unchanged. 40309 The seteuid( ) function shall not affect the supplementary group list in any way. 40310 RETURN VALUE 40311 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 40312 indicate the error. 40313 ERRORS 40314 The seteuid( ) function shall fail if: 40315 [EINVAL] The value of the uid argument is invalid and is not supported by the 40316 implementation. 40317 [EPERM] The process does not have appropriate privileges and uid does not match the 40318 real group ID or the saved set-group-ID. 40319 EXAMPLES 40320 None. 40321 APPLICATION USAGE 40322 None. 40323 RATIONALE 40324 Refer to the RATIONALE section in setuid( ). 40325 FUTURE DIRECTIONS 40326 None. 40327 SEE ALSO 40328 exec, getegid( ), geteuid( ), getgid( ), getuid( ), setegid( ), setgid( ), setregid( ), setreuid( ), setuid( ), the 40329 Base Definitions volume of IEEE Std 1003.1-200x, , 40330 CHANGE HISTORY 40331 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 1784 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setgid( ) 40332 NAME 40333 setgid - set-group-ID 40334 SYNOPSIS 40335 #include 40336 int setgid(gid_t gid); 40337 DESCRIPTION 40338 If the process has appropriate privileges, setgid( ) shall set the real group ID, effective group ID, 40339 and the saved set-group-ID of the calling process to gid. 40340 If the process does not have appropriate privileges, but gid is equal to the real group ID or the 40341 saved set-group-ID, setgid( ) shall set the effective group ID to gid; the real group ID and saved 40342 set-group-ID shall remain unchanged. 40343 The setgid( ) function shall not affect the supplementary group list in any way. 40344 Any supplementary group IDs of the calling process shall remain unchanged. 40345 RETURN VALUE 40346 Upon successful completion, 0 is returned. Otherwise, -1 shall be returned and errno set to 40347 indicate the error. 40348 ERRORS 40349 The setgid( ) function shall fail if: 40350 [EINVAL] The value of the gid argument is invalid and is not supported by the 40351 implementation. 40352 [EPERM] The process does not have appropriate privileges and gid does not match the 40353 real group ID or the saved set-group-ID. 40354 EXAMPLES 40355 None. 40356 APPLICATION USAGE 40357 None. 40358 RATIONALE 40359 Refer to the RATIONALE section in setuid( ). 40360 FUTURE DIRECTIONS 40361 None. 40362 SEE ALSO 40363 exec, getegid( ), geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setregid( ), setreuid( ), setuid( ), the 40364 Base Definitions volume of IEEE Std 1003.1-200x, , 40365 CHANGE HISTORY 40366 First released in Issue 1. Derived from Issue 1 of the SVID. 40367 Issue 6 40368 In the SYNOPSIS, the optional include of the header is removed. 40369 The following new requirements on POSIX implementations derive from alignment with the 40370 Single UNIX Specification: 40371 * The requirement to include has been removed. Although was 40372 required for conforming implementations of previous POSIX specifications, it was not 40373 required for UNIX applications. System Interfaces, Issue 6 1785 setgid( ) System Interfaces 40374 * Functionality associated with _POSIX_SAVED_IDS is now mandated. This is a FIPS 40375 requirement. 40376 The following changes were made to align with the IEEE P1003.1a draft standard: 40377 * The effects of setgid( ) in processes without appropriate privileges are changed 40378 * A requirement that the supplementary group list is not affected is added. 1786 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setgrent( ) 40379 NAME 40380 setgrent - reset group database to first entry 40381 SYNOPSIS 40382 XSI #include 40383 void setgrent(void); 40384 40385 DESCRIPTION 40386 Refer to endgrent( ). System Interfaces, Issue 6 1787 sethostent( ) System Interfaces 40387 NAME 40388 sethostent - network host database functions 40389 SYNOPSIS 40390 #include 40391 void sethostent(int stayopen); 40392 DESCRIPTION 40393 Refer to endhostent( ). 1788 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setitimer( ) 40394 NAME 40395 setitimer - set value of interval timer 40396 SYNOPSIS 40397 XSI #include 40398 int setitimer(int which, const struct itimerval *restrict value, 40399 struct itimerval *restrict ovalue); 40400 40401 DESCRIPTION 40402 Refer to getitimer( ). System Interfaces, Issue 6 1789 setjmp( ) System Interfaces 40403 NAME 40404 setjmp - set jump point for a non-local goto 40405 SYNOPSIS 40406 #include 40407 int setjmp(jmp_buf env); 40408 DESCRIPTION 40409 CX The functionality described on this reference page is aligned with the ISO C standard. Any 40410 conflict between the requirements described here and the ISO C standard is unintentional. This 40411 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 40412 A call to setjmp( ), shall save the calling environment in its env argument for later use by 40413 longjmp( ). 40414 It is unspecified whether setjmp( ) is a macro or a function. If a macro definition is suppressed in 40415 order to access an actual function, or a program defines an external identifier with the name 40416 setjmp, the behavior is undefined. 40417 An application shall ensure that an invocation of setjmp( ) appears in one of the following 40418 contexts only: 40419 * The entire controlling expression of a selection or iteration statement 40420 * One operand of a relational or equality operator with the other operand an integral constant 40421 expression, with the resulting expression being the entire controlling expression of a 40422 selection or iteration statement 40423 * The operand of a unary '!' operator with the resulting expression being the entire 40424 controlling expression of a selection or iteration 40425 * The entire expression of an expression statement (possibly cast to void) 40426 If the invocation appears in any other context, the behavior is undefined. 40427 RETURN VALUE 40428 If the return is from a direct invocation, setjmp( ) shall return 0. If the return is from a call to 40429 longjmp( ), setjmp( ) shall return a non-zero value. 40430 ERRORS 40431 No errors are defined. 40432 EXAMPLES 40433 None. 40434 APPLICATION USAGE 40435 In general, sigsetjmp( ) is more useful in dealing with errors and interrupts encountered in a low- 40436 level subroutine of a program. 40437 RATIONALE 40438 None. 40439 FUTURE DIRECTIONS 40440 None. 40441 SEE ALSO 40442 longjmp( ), sigsetjmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1790 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setjmp( ) 40443 CHANGE HISTORY 40444 First released in Issue 1. Derived from Issue 1 of the SVID. 40445 Issue 6 40446 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 1791 setkey( ) System Interfaces 40447 NAME 40448 setkey - set encoding key (CRYPT) 40449 SYNOPSIS 40450 XSI #include 40451 void setkey(const char *key); 40452 40453 DESCRIPTION 40454 The setkey( ) function provides access to an implementation-defined encoding algorithm. The | 40455 argument of setkey( ) is an array of length 64 bytes containing only the bytes with numerical | 40456 value of 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is 40457 ignored; this gives a 56-bit key which is used by the algorithm. This is the key that shall be used 40458 with the algorithm to encode a string block passed to encrypt( ). 40459 The setkey( ) function shall not change the setting of errno if successful. An application wishing to 40460 check for error situations should set errno to 0 before calling setkey( ). If errno is non-zero on 40461 return, an error has occurred. 40462 The setkey( ) function need not be reentrant. A function that is not required to be reentrant is not 40463 required to be thread-safe. 40464 RETURN VALUE 40465 No values are returned. 40466 ERRORS 40467 The setkey( ) function shall fail if: 40468 [ENOSYS] The functionality is not supported on this implementation. 40469 EXAMPLES 40470 None. 40471 APPLICATION USAGE 40472 Decoding need not be implemented in all environments. This is related to government | 40473 restrictions in some countries on encryption and decryption routines. Historical practice has | 40474 been to ship a different version of the encryption library without the decryption feature in the | 40475 routines supplied. Thus the exported version of encrypt( ) does encoding but not decoding. | 40476 RATIONALE 40477 None. 40478 FUTURE DIRECTIONS 40479 None. 40480 SEE ALSO 40481 crypt( ), encrypt( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40482 CHANGE HISTORY 40483 First released in Issue 1. Derived from Issue 1 of the SVID. 40484 Issue 5 40485 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 1792 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setlocale( ) 40486 NAME 40487 setlocale - set program locale 40488 SYNOPSIS 40489 #include 40490 char *setlocale(int category, const char *locale); 40491 DESCRIPTION 40492 CX The functionality described on this reference page is aligned with the ISO C standard. Any 40493 conflict between the requirements described here and the ISO C standard is unintentional. This 40494 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 40495 The setlocale( ) function selects the appropriate piece of the program's locale, as specified by the 40496 category and locale arguments, and may be used to change or query the program's entire locale or 40497 portions thereof. The value LC_ALL for category names the program's entire locale; other values 40498 for category name only a part of the program's locale: 40499 LC_COLLATE Affects the behavior of regular expressions and the collation functions. 40500 LC_CTYPE Affects the behavior of regular expressions, character classification, character 40501 conversion functions, and wide-character functions. 40502 CX LC_MESSAGES Affects what strings are expected by commands and utilities as affirmative or 40503 negative responses. 40504 XSI It also affects what strings are given by commands and utilities as affirmative 40505 or negative responses, and the content of messages. 40506 LC_MONETARY Affects the behavior of functions that handle monetary values. 40507 LC_NUMERIC Affects the behavior of functions that handle numeric values. 40508 LC_TIME Affects the behavior of the time conversion functions. 40509 The locale argument is a pointer to a character string containing the required setting of category. 40510 The contents of this string are implementation-defined. In addition, the following preset values 40511 of locale are defined for all settings of category: 40512 CX "POSIX" Specifies the minimal environment for C-language translation called POSIX 40513 locale. If setlocale( ) is not invoked, the POSIX locale is the default at entry to 40514 main( ). 40515 "C" Equivalent to "POSIX". | 40516 CX " " Specifies an implementation-defined native environment. This corresponds to | 40517 the value of the associated environment variables, LC_* and LANG; see the | 40518 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale and the 40519 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment 40520 Variables. | 40521 A null pointer Used to direct setlocale( ) to query the current internationalized environment 40522 and return the name of the locale( ). 40523 THR The locale state is common to all threads within a process. 40524 RETURN VALUE 40525 Upon successful completion, setlocale( ) shall return the string associated with the specified 40526 category for the new locale. Otherwise, setlocale( ) shall return a null pointer and the program's 40527 locale is not changed. System Interfaces, Issue 6 1793 setlocale( ) System Interfaces 40528 A null pointer for locale causes setlocale( ) to return a pointer to the string associated with the 40529 category for the program's current locale. The program's locale shall not be changed. 40530 The string returned by setlocale( ) is such that a subsequent call with that string and its associated 40531 category shall restore that part of the program's locale. The application shall not modify the string 40532 returned which may be overwritten by a subsequent call to setlocale( ). 40533 ERRORS 40534 No errors are defined. 40535 EXAMPLES 40536 None. 40537 APPLICATION USAGE 40538 The following code illustrates how a program can initialize the international environment for 40539 one language, while selectively modifying the program's locale such that regular expressions 40540 and string operations can be applied to text recorded in a different language: 40541 setlocale(LC_ALL, "De"); 40542 setlocale(LC_COLLATE, "Fr@dict"); 40543 Internationalized programs must call setlocale( ) to initiate a specific language operation. This can 40544 be done by calling setlocale( ) as follows: 40545 setlocale(LC_ALL, ""); 40546 Changing the setting of LC_MESSAGES has no effect on catalogs that have already been opened 40547 by calls to catopen( ). 40548 RATIONALE 40549 The ISO C standard defines a collection of functions to support internationalization. One of the 40550 most significant aspects of these functions is a facility to set and query the international 40551 environment. The international environment is a repository of information that affects the 40552 behavior of certain functionality, namely: 40553 1. Character handling 40554 2. Collating 40555 3. Date/time formatting 40556 4. Numeric editing 40557 5. Monetary formatting 40558 6. Messaging 40559 The setlocale( ) function provides the application developer with the ability to set all or portions, 40560 called categories, of the international environment. These categories correspond to the areas of 40561 functionality, mentioned above. The syntax for setlocale( ) is as follows: 40562 char *setlocale(int category, const char *locale); 40563 where category is the name of one of following categories, namely: | 40564 LC_COLLATE | 40565 LC_CTYPE | 40566 LC_MESSAGES | 40567 LC_MONETARY | 40568 LC_NUMERIC | 40569 LC_TIME | 1794 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setlocale( ) 40570 In addition, a special value called LC_ALL directs setlocale( ) to set all categories. 40571 There are two primary uses of setlocale( ): 40572 1. Querying the international environment to find out what it is set to 40573 2. Setting the international environment, or locale, to a specific value 40574 The behavior of setlocale( ) in these two areas is described below. Since it is difficult to describe 40575 the behavior in words, examples are used to illustrate the behavior of specific uses. 40576 To query the international environment, setlocale( ) is invoked with a specific category and the 40577 NULL pointer as the locale. The NULL pointer is a special directive to setlocale( ) that tells it to 40578 query rather than set the international environment. The following syntax is used to query the 40579 name of the international environment: 40580 setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \ 40581 LC_NUMERIC, LC_TIME},(char *) NULL); 40582 The setlocale( ) function shall return the string corresponding to the current international 40583 environment. This value may be used by a subsequent call to setlocale( ) to reset the international 40584 environment to this value. However, it should be noted that the return value from setlocale( ) 40585 may be a pointer to a static area within the function and is not guaranteed to remain unchanged 40586 (that is, it may be modified by a subsequent call to setlocale( )). Therefore, if the purpose of 40587 calling setlocale( ) is to save the value of the current international environment so it can be 40588 changed and reset later, the return value should be copied to an array of char in the calling 40589 program. 40590 There are three ways to set the international environment with setlocale( ): 40591 setlocale(category, string) 40592 This usage sets a specific category in the international environment to a specific value 40593 corresponding to the value of the string. A specific example is provided below: 40594 setlocale(LC_ALL, "fr_FR.ISO-8859-1"); 40595 In this example, all categories of the international environment are set to the locale 40596 corresponding to the string "fr_FR.ISO-8859-1", or to the French language as spoken in 40597 France using the ISO/IEC 8859-1: 1998 standard codeset. 40598 If the string does not correspond to a valid locale, setlocale( ) shall return a NULL pointer 40599 and the international environment is not changed. Otherwise, setlocale( ) shall return the 40600 name of the locale just set. 40601 setlocale(category, "C") 40602 The ISO C standard states that one locale must exist on all conforming implementations. 40603 The name of the locale is C and corresponds to a minimal international environment needed 40604 to support the C programming language. 40605 setlocale(category, "") 40606 This sets a specific category to an implementation-defined default. This corresponds to the 40607 value of the environment variables. 40608 FUTURE DIRECTIONS 40609 None. 40610 SEE ALSO 40611 exec, isalnum( ), isalpha( ), isblank( ), iscntrl( ), isdigit( ), isgraph( ), islower( ), isprint( ), ispunct( ), 40612 isspace( ), isupper( ), iswalnum( ), iswalpha( ), iswblank( ), iswcntrl( ), iswctype( ), iswdigit( ), 40613 iswgraph( ), iswlower( ), iswprint( ), iswpunct( ), iswspace( ), iswupper( ), iswxdigit( ), isxdigit( ), System Interfaces, Issue 6 1795 setlocale( ) System Interfaces 40614 localeconv( ), mblen( ), mbstowcs( ), mbtowc( ), nl_langinfo ( ), printf( ), scanf( ), setlocale( ), strcoll( ), 40615 strerror( ), strfmon( ), strtod( ), strxfrm( ), tolower( ), toupper( ), towlower( ), towupper( ), wcscoll( ), 40616 wcstod( ), wcstombs( ), wcsxfrm( ), wctomb( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40617 , 40618 CHANGE HISTORY 40619 First released in Issue 3. 40620 Issue 5 40621 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 40622 Issue 6 40623 Extensions beyond the ISO C standard are now marked. 40624 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 1796 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setlogmask( ) 40625 NAME 40626 setlogmask - set log priority mask 40627 SYNOPSIS 40628 XSI #include 40629 int setlogmask(int maskpri); 40630 40631 DESCRIPTION 40632 Refer to closelog( ). System Interfaces, Issue 6 1797 setnetent( ) System Interfaces 40633 NAME 40634 setnetent - network database function 40635 SYNOPSIS 40636 #include 40637 void setnetent(int stayopen); 40638 DESCRIPTION 40639 Refer to endnetent( ). 1798 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setpgid( ) 40640 NAME 40641 setpgid - set process group ID for job control 40642 SYNOPSIS 40643 #include 40644 int setpgid(pid_t pid, pid_t pgid); 40645 DESCRIPTION 40646 The setpgid( ) function shall either join an existing process group or create a new process group | 40647 within the session of the calling process. The process group ID of a session leader shall not 40648 change. Upon successful completion, the process group ID of the process with a process ID that 40649 matches pid shall be set to pgid. As a special case, if pid is 0, the process ID of the calling process 40650 shall be used. Also, if pgid is 0, the process group ID of the indicated process shall be used. 40651 RETURN VALUE 40652 Upon successful completion, setpgid( ) shall return 0; otherwise, -1 shall be returned and errno 40653 shall be set to indicate the error. 40654 ERRORS 40655 The setpgid( ) function shall fail if: 40656 [EACCES] The value of the pid argument matches the process ID of a child process of the 40657 calling process and the child process has successfully executed one of the exec 40658 functions. 40659 [EINVAL] The value of the pgid argument is less than 0, or is not a value supported by 40660 the implementation. 40661 [EPERM] The process indicated by the pid argument is a session leader. 40662 [EPERM] The value of the pid argument matches the process ID of a child process of the 40663 calling process and the child process is not in the same session as the calling 40664 process. 40665 [EPERM] The value of the pgid argument is valid but does not match the process ID of 40666 the process indicated by the pid argument and there is no process with a 40667 process group ID that matches the value of the pgid argument in the same 40668 session as the calling process. 40669 [ESRCH] The value of the pid argument does not match the process ID of the calling 40670 process or of a child process of the calling process. 40671 EXAMPLES 40672 None. 40673 APPLICATION USAGE 40674 None. 40675 RATIONALE 40676 The setpgid( ) function shall group processes together for the purpose of signaling, placement in | 40677 foreground or background, and other job control actions. 40678 The setpgid( ) function is similar to the setpgrp( ) function of 4.2 BSD, except that 4.2 BSD allowed 40679 the specified new process group to assume any value. This presents certain security problems 40680 and is more flexible than necessary to support job control. 40681 To provide tighter security, setpgid( ) only allows the calling process to join a process group 40682 already in use inside its session or create a new process group whose process group ID was 40683 equal to its process ID. System Interfaces, Issue 6 1799 setpgid( ) System Interfaces 40684 When a job control shell spawns a new job, the processes in the job must be placed into a new 40685 process group via setpgid( ). There are two timing constraints involved in this action: 40686 1. The new process must be placed in the new process group before the appropriate program 40687 is launched via one of the exec functions. 40688 2. The new process must be placed in the new process group before the shell can correctly 40689 send signals to the new process group. 40690 To address these constraints, the following actions are performed. The new processes call 40691 setpgid( ) to alter their own process groups after fork( ) but before exec. This satisfies the first 40692 constraint. Under 4.3 BSD, the second constraint is satisfied by the synchronization property of 40693 vfork( ); that is, the shell is suspended until the child has completed the exec, thus ensuring that 40694 the child has completed the setpgid( ). A new version of fork( ) with this same synchronization 40695 property was considered, but it was decided instead to merely allow the parent shell process to 40696 adjust the process group of its child processes via setpgid( ). Both timing constraints are now 40697 satisfied by having both the parent shell and the child attempt to adjust the process group of the 40698 child process; it does not matter which succeeds first. 40699 Since it would be confusing to an application to have its process group change after it began | 40700 executing (that is, after exec), and because the child process would already have adjusted its 40701 process group before this, the [EACCES] error was added to disallow this. 40702 One non-obvious use of setpgid( ) is to allow a job control shell to return itself to its original 40703 process group (the one in effect when the job control shell was executed). A job control shell 40704 does this before returning control back to its parent when it is terminating or suspending itself as 40705 a way of restoring its job control ``state'' back to what its parent would expect. (Note that the 40706 original process group of the job control shell typically matches the process group of its parent, 40707 but this is not necessarily always the case.) 40708 FUTURE DIRECTIONS 40709 None. 40710 SEE ALSO 40711 exec, getpgrp( ), setsid( ), tcsetpgrp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 40712 , 40713 CHANGE HISTORY 40714 First released in Issue 3. 40715 Entry included for alignment with the POSIX.1-1988 standard. 40716 Issue 6 40717 In the SYNOPSIS, the optional include of the header is removed. 40718 The following new requirements on POSIX implementations derive from alignment with the 40719 Single UNIX Specification: 40720 * The requirement to include has been removed. Although was 40721 required for conforming implementations of previous POSIX specifications, it was not 40722 required for UNIX applications. 40723 * The setpgid( ) function is mandatory since _POSIX_JOB_CONTROL is required to be defined 40724 in this issue. This is a FIPS requirement. 1800 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setpgrp( ) 40725 NAME 40726 setpgrp - set process group ID 40727 SYNOPSIS 40728 XSI #include 40729 pid_t setpgrp(void); 40730 40731 DESCRIPTION 40732 If the calling process is not already a session leader, setpgrp( ) sets the process group ID of the 40733 calling process to the process ID of the calling process. If setpgrp( ) creates a new session, then 40734 the new session has no controlling terminal. 40735 The setpgrp( ) function has no effect when the calling process is a session leader. 40736 RETURN VALUE 40737 Upon completion, setpgrp( ) shall return the process group ID. 40738 ERRORS 40739 No errors are defined. 40740 EXAMPLES 40741 None. 40742 APPLICATION USAGE 40743 None. 40744 RATIONALE 40745 None. 40746 FUTURE DIRECTIONS 40747 None. 40748 SEE ALSO 40749 exec, fork( ), getpid( ), getsid( ), kill( ), setpgid( ), setsid( ), the Base Definitions volume of 40750 IEEE Std 1003.1-200x, 40751 CHANGE HISTORY 40752 First released in Issue 4, Version 2. 40753 Issue 5 40754 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1801 setpriority( ) System Interfaces 40755 NAME 40756 setpriority - set the nice value 40757 SYNOPSIS 40758 XSI #include 40759 int setpriority(int which, id_t who, int nice); 40760 40761 DESCRIPTION 40762 Refer to getpriority( ). 1802 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setprotoent( ) 40763 NAME 40764 setprotoent - network protocol database functions 40765 SYNOPSIS 40766 #include 40767 void setprotoent(int stayopen); 40768 DESCRIPTION 40769 Refer to endprotoent( ). System Interfaces, Issue 6 1803 setpwent( ) System Interfaces 40770 NAME 40771 setpwent - user database function 40772 SYNOPSIS 40773 XSI #include 40774 void setpwent(void); 40775 40776 DESCRIPTION 40777 Refer to endpwent( ). 1804 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setregid( ) 40778 NAME 40779 setregid - set real and effective group IDs 40780 SYNOPSIS 40781 XSI #include 40782 int setregid(gid_t rgid, gid_t egid); 40783 40784 DESCRIPTION 40785 The setregid( ) function shall set the real and effective group IDs of the calling process. | 40786 If rgid is -1, the real group ID shall not be changed; if egid is -1, the effective group ID shall not 40787 be changed. 40788 The real and effective group IDs may be set to different values in the same call. 40789 Only a process with appropriate privileges can set the real group ID and the effective group ID 40790 to any valid value. 40791 A non-privileged process can set either the real group ID to the saved set-group-ID from one of 40792 the exec family of functions, or the effective group ID to the saved set-group-ID or the real group 40793 ID. 40794 Any supplementary group IDs of the calling process remain unchanged. 40795 RETURN VALUE 40796 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 40797 indicate the error, and neither of the group IDs are changed. 40798 ERRORS 40799 The setregid( ) function shall fail if: 40800 [EINVAL] The value of the rgid or egid argument is invalid or out-of-range. 40801 [EPERM] The process does not have appropriate privileges and a change other than 40802 changing the real group ID to the saved set-group-ID, or changing the 40803 effective group ID to the real group ID or the saved set-group-ID, was 40804 requested. 40805 EXAMPLES 40806 None. 40807 APPLICATION USAGE 40808 If a set-group-ID process sets its effective group ID to its real group ID, it can still set its effective 40809 group ID back to the saved set-group-ID. 40810 RATIONALE 40811 None. 40812 FUTURE DIRECTIONS 40813 None. 40814 SEE ALSO 40815 exec, getegid( ), geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setreuid( ), setuid( ), the 40816 Base Definitions volume of IEEE Std 1003.1-200x, 40817 CHANGE HISTORY 40818 First released in Issue 4, Version 2. System Interfaces, Issue 6 1805 setregid( ) System Interfaces 40819 Issue 5 40820 Moved from X/OPEN UNIX extension to BASE. 40821 The DESCRIPTION is updated to indicate that the saved set-group-ID can be set by any of the 40822 exec family of functions, not just execev( ). 1806 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setreuid( ) 40823 NAME 40824 setreuid - set real and effective user IDs 40825 SYNOPSIS 40826 XSI #include 40827 int setreuid(uid_t ruid, uid_t euid); 40828 40829 DESCRIPTION 40830 The setreuid( ) function shall set the real and effective user IDs of the current process to the | 40831 values specified by the ruid and euid arguments. If ruid or euid is -1, the corresponding effective | 40832 or real user ID of the current process shall be left unchanged. | 40833 A process with appropriate privileges can set either ID to any value. An unprivileged process 40834 can only set the effective user ID if the euid argument is equal to either the real, effective, or 40835 saved user ID of the process. 40836 It is unspecified whether a process without appropriate privileges is permitted to change the real 40837 user ID to match the current real, effective, or saved set-user-ID of the process. 40838 RETURN VALUE 40839 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 40840 indicate the error. 40841 ERRORS 40842 The setreuid( ) function shall fail if: 40843 [EINVAL] The value of the ruid or euid argument is invalid or out-of-range. 40844 [EPERM] The current process does not have appropriate privileges, and either an 40845 attempt was made to change the effective user ID to a value other than the 40846 real user ID or the saved set-user-ID or an attempt was made to change the 40847 real user ID to a value not permitted by the implementation. 40848 EXAMPLES 40849 Setting the Effective User ID to the Real User ID 40850 The following example sets the effective user ID of the calling process to the real user ID, so that 40851 files created later will be owned by the current user. 40852 #include 40853 #include 40854 ... 40855 setreuid(getuid(), getuid()); 40856 ... 40857 APPLICATION USAGE 40858 None. 40859 RATIONALE 40860 None. 40861 FUTURE DIRECTIONS 40862 None. System Interfaces, Issue 6 1807 setreuid( ) System Interfaces 40863 SEE ALSO 40864 getegid( ), geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setuid( ), the Base 40865 Definitions volume of IEEE Std 1003.1-200x, 40866 CHANGE HISTORY 40867 First released in Issue 4, Version 2. 40868 Issue 5 40869 Moved from X/OPEN UNIX extension to BASE. 1808 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setrlimit( ) 40870 NAME 40871 setrlimit - control maximum resource consumption 40872 SYNOPSIS 40873 XSI #include 40874 int setrlimit(int resource, const struct rlimit *rlp); 40875 40876 DESCRIPTION 40877 Refer to getrlimit( ). System Interfaces, Issue 6 1809 setservent( ) System Interfaces 40878 NAME 40879 setservent - network services database functions 40880 SYNOPSIS 40881 #include 40882 void setservent(int stayopen); 40883 DESCRIPTION 40884 Refer to endservent( ). 1810 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setsid( ) 40885 NAME 40886 setsid - create session and set process group ID 40887 SYNOPSIS 40888 #include 40889 pid_t setsid(void); 40890 DESCRIPTION 40891 The setsid( ) function shall create a new session, if the calling process is not a process group 40892 leader. Upon return the calling process shall be the session leader of this new session, shall be 40893 the process group leader of a new process group, and shall have no controlling terminal. The 40894 process group ID of the calling process shall be set equal to the process ID of the calling process. 40895 The calling process shall be the only process in the new process group and the only process in 40896 the new session. 40897 RETURN VALUE 40898 Upon successful completion, setsid( ) shall return the value of the new process group ID of the 40899 calling process. Otherwise, it shall return (pid_t)-1 and set errno to indicate the error. 40900 ERRORS 40901 The setsid( ) function shall fail if: 40902 [EPERM] The calling process is already a process group leader, or the process group ID 40903 of a process other than the calling process matches the process ID of the 40904 calling process. 40905 EXAMPLES 40906 None. 40907 APPLICATION USAGE 40908 None. 40909 RATIONALE 40910 The setsid( ) function is similar to the setpgrp( ) function of System V. System V, without job 40911 control, groups processes into process groups and creates new process groups via setpgrp( ); only 40912 one process group may be part of a login session. 40913 Job control allows multiple process groups within a login session. In order to limit job control 40914 actions so that they can only affect processes in the same login session, this volume of 40915 IEEE Std 1003.1-200x adds the concept of a session that is created via setsid( ). The setsid( ) 40916 function also creates the initial process group contained in the session. Additional process 40917 groups can be created via the setpgid( ) function. A System V process group would correspond to 40918 a POSIX System Interfaces session containing a single POSIX process group. Note that this 40919 function requires that the calling process not be a process group leader. The usual way to ensure 40920 this is true is to create a new process with fork( ) and have it call setsid( ). The fork( ) function 40921 guarantees that the process ID of the new process does not match any existing process group ID. 40922 FUTURE DIRECTIONS 40923 None. 40924 SEE ALSO 40925 getsid( ), setpgid( ), setpgrp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 40926 System Interfaces, Issue 6 1811 setsid( ) System Interfaces 40927 CHANGE HISTORY 40928 First released in Issue 3. 40929 Entry included for alignment with the POSIX.1-1988 standard. 40930 Issue 6 40931 In the SYNOPSIS, the optional include of the header is removed. 40932 The following new requirements on POSIX implementations derive from alignment with the 40933 Single UNIX Specification: 40934 * The requirement to include has been removed. Although was 40935 required for conforming implementations of previous POSIX specifications, it was not 40936 required for UNIX applications. 1812 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setsockopt( ) 40937 NAME 40938 setsockopt - set the socket options 40939 SYNOPSIS 40940 #include 40941 int setsockopt(int socket, int level, int option_name, 40942 const void *option_value, socklen_t option_len); 40943 DESCRIPTION 40944 The setsockopt( ) function shall set the option specified by the option_name argument, at the | 40945 protocol level specified by the level argument, to the value pointed to by the option_value 40946 argument for the socket associated with the file descriptor specified by the socket argument. 40947 The level argument specifies the protocol level at which the option resides. To set options at the 40948 socket level, specify the level argument as SOL_SOCKET. To set options at other levels, supply 40949 the appropriate level identifier for the protocol controlling the option. For example, to indicate 40950 that an option is interpreted by the TCP (Transport Control Protocol), set level to IPPROTO_TCP 40951 as defined in the header. 40952 The option_name argument specifies a single option to set. The option_name argument and any 40953 specified options are passed uninterpreted to the appropriate protocol module for 40954 interpretations. The header defines the socket-level options. The options are as 40955 follows: 40956 SO_DEBUG Turns on recording of debugging information. This option enables or 40957 disables debugging in the underlying protocol modules. This option takes 40958 an int value. This is a Boolean option. 40959 SO_BROADCAST Permits sending of broadcast messages, if this is supported by the 40960 protocol. This option takes an int value. This is a Boolean option. 40961 SO_REUSEADDR Specifies that the rules used in validating addresses supplied to bind( ) 40962 should allow reuse of local addresses, if this is supported by the protocol. 40963 This option takes an int value. This is a Boolean option. 40964 SO_KEEPALIVE Keeps connections active by enabling the periodic transmission of 40965 messages, if this is supported by the protocol. This option takes an int 40966 value. 40967 If the connected socket fails to respond to these messages, the connection 40968 is broken and threads writing to that socket are notified with a SIGPIPE 40969 signal. 40970 This is a Boolean option. 40971 SO_LINGER Lingers on a close( ) if data is present. This option controls the action 40972 taken when unsent messages queue on a socket and close( ) is performed. | 40973 If SO_LINGER is set, the system shall block the process during close( ) | 40974 until it can transmit the data or until the time expires. If SO_LINGER is 40975 not specified, and close( ) is issued, the system handles the call in a way 40976 that allows the process to continue as quickly as possible. This option 40977 takes a linger structure, as defined in the header, to 40978 specify the state of the option and linger interval. 40979 SO_OOBINLINE Leaves received out-of-band data (data marked urgent) inline. This 40980 option takes an int value. This is a Boolean option. System Interfaces, Issue 6 1813 setsockopt( ) System Interfaces 40981 SO_SNDBUF Sets send buffer size. This option takes an int value. 40982 SO_RCVBUF Sets receive buffer size. This option takes an int value. 40983 SO_DONTROUTE Requests that outgoing messages bypass the standard routing facilities. 40984 The destination shall be on a directly-connected network, and messages 40985 are directed to the appropriate network interface according to the 40986 destination address. The effect, if any, of this option depends on what 40987 protocol is in use. This option takes an int value. This is a Boolean option. 40988 SO_RCVLOWAT Sets the minimum number of bytes to process for socket input operations. 40989 The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a 40990 larger value, blocking receive calls normally wait until they have received 40991 the smaller of the low water mark value or the requested amount. (They 40992 may return less than the low water mark if an error occurs, a signal is 40993 caught, or the type of data next in the receive queue is different from that | 40994 returned; for example, out-of-band data.) This option takes an int value. | 40995 Note that not all implementations allow this option to be set. 40996 SO_RCVTIMEO Sets the timeout value that specifies the maximum amount of time an 40997 input function waits until it completes. It accepts a timeval structure with 40998 the number of seconds and microseconds specifying the limit on how 40999 long to wait for an input operation to complete. If a receive operation has 41000 blocked for this much time without receiving additional data, it shall 41001 return with a partial count or errno set to [EAGAIN] or 41002 [EWOULDBLOCK] if no data is received. The default for this option is 41003 zero, which indicates that a receive operation shall not time out. This 41004 option takes a timeval structure. Note that not all implementations allow 41005 this option to be set. 41006 SO_SNDLOWAT Sets the minimum number of bytes to process for socket output 41007 operations. Non-blocking output operations shall process no data if flow 41008 control does not allow the smaller of the send low water mark value or 41009 the entire request to be processed. This option takes an int value. Note 41010 that not all implementations allow this option to be set. 41011 SO_SNDTIMEO Sets the timeout value specifying the amount of time that an output 41012 function blocks because flow control prevents data from being sent. If a 41013 send operation has blocked for this time, it shall return with a partial 41014 count or with errno set to [EAGAIN] or [EWOULDBLOCK] if no data is 41015 sent. The default for this option is zero, which indicates that a send 41016 operation shall not time out. This option stores a timeval structure. Note 41017 that not all implementations allow this option to be set. 41018 For Boolean options, 0 indicates that the option is disabled and 1 indicates that the option is 41019 enabled. 41020 Options at other protocol levels vary in format and name. 41021 RETURN VALUE 41022 Upon successful completion, setsockopt( ) shall return 0. Otherwise, -1 shall be returned and errno 41023 set to indicate the error. 41024 ERRORS 41025 The setsockopt( ) function shall fail if: 41026 [EBADF] The socket argument is not a valid file descriptor. 1814 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setsockopt( ) 41027 [EDOM] The send and receive timeout values are too big to fit into the timeout fields in 41028 the socket structure. 41029 [EINVAL] The specified option is invalid at the specified socket level or the socket has 41030 been shut down. 41031 [EISCONN] The socket is already connected, and a specified option cannot be set while the 41032 socket is connected. 41033 [ENOPROTOOPT] 41034 The option is not supported by the protocol. 41035 [ENOTSOCK] The socket argument does not refer to a socket. 41036 The setsockopt( ) function may fail if: 41037 [ENOMEM] There was insufficient memory available for the operation to complete. 41038 [ENOBUFS] Insufficient resources are available in the system to complete the call. 41039 EXAMPLES 41040 None. 41041 APPLICATION USAGE 41042 The setsockopt( ) function provides an application program with the means to control socket 41043 behavior. An application program can use setsockopt( ) to allocate buffer space, control timeouts, 41044 or permit socket data broadcasts. The header defines the socket-level options 41045 available to setsockopt( ). 41046 Options may exist at multiple protocol levels. The SO_ options are always present at the 41047 uppermost socket level. 41048 RATIONALE 41049 None. 41050 FUTURE DIRECTIONS 41051 None. 41052 SEE ALSO 41053 Section 2.10 (on page 508), bind( ), endprotoent( ), getsockopt( ), socket( ), the Base Definitions 41054 volume of IEEE Std 1003.1-200x, , 41055 CHANGE HISTORY 41056 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1815 setstate( ) System Interfaces 41057 NAME 41058 setstate - switch pseudo-random number generator state arrays 41059 SYNOPSIS 41060 XSI #include 41061 char *setstate(const char *state); 41062 41063 DESCRIPTION 41064 Refer to initstate( ). 1816 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setuid( ) 41065 NAME 41066 setuid - set user ID 41067 SYNOPSIS 41068 #include 41069 int setuid(uid_t uid); 41070 DESCRIPTION 41071 If the process has appropriate privileges, setuid( ) shall set the real user ID, effective user ID, and 41072 the saved set-user-ID of the calling process to uid. 41073 If the process does not have appropriate privileges, but uid is equal to the real user ID or the 41074 saved set-user-ID, setuid( ) shall set the effective user ID to uid; the real user ID and saved set- 41075 user-ID shall remain unchanged. 41076 The setuid( ) function shall not affect the supplementary group list in any way. 41077 RETURN VALUE 41078 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 41079 indicate the error. 41080 ERRORS 41081 The setuid( ) function shall fail, return -1, and set errno to the corresponding value if one or more 41082 of the following are true: 41083 [EINVAL] The value of the uid argument is invalid and not supported by the 41084 implementation. 41085 [EPERM] The process does not have appropriate privileges and uid does not match the 41086 real user ID or the saved set-user-ID. 41087 EXAMPLES 41088 None. 41089 APPLICATION USAGE 41090 None. 41091 RATIONALE 41092 The various behaviors of the setuid( ) and setgid( ) functions when called by non-privileged 41093 processes reflect the behavior of different historical implementations. For portability, it is 41094 recommended that new non-privileged applications use the seteuid( ) and setegid( ) functions 41095 instead. 41096 The saved set-user-ID capability allows a program to regain the effective user ID established at 41097 the last exec call. Similarly, the saved set-group-ID capability allows a program to regain the 41098 effective group ID established at the last exec call. These capabilities are derived from System V. 41099 Without them, a program might have to run as superuser in order to perform the same | 41100 functions, because superuser can write on the user's files. This is a problem because such a | 41101 program can write on any user's files, and so must be carefully written to emulate the | 41102 permissions of the calling process properly. In System V, these capabilities have traditionally 41103 been implemented only via the setuid( ) and setgid( ) functions for non-privileged processes. The 41104 fact that the behavior of those functions was different for privileged processes made them 41105 difficult to use. The POSIX.1-1990 standard defined the setuid( ) function to behave differently 41106 for privileged and unprivileged users. When the caller had the appropriate privilege, the 41107 function set the calling process' real user ID, effective user ID, and saved set-user ID on | 41108 implementations that supported it. When the caller did not have the appropriate privilege, the 41109 function set only the effective user ID, subject to permission checks. The former use is generally 41110 needed for utilities like login and su, which are not conforming applications and thus outside the | System Interfaces, Issue 6 1817 setuid( ) System Interfaces 41111 scope of IEEE Std 1003.1-200x. These utilities wish to change the user ID irrevocably to a new | 41112 value, generally that of an unprivileged user. The latter use is needed for conforming | 41113 applications that are installed with the set-user-ID bit and need to perform operations using the | 41114 real user ID. 41115 IEEE Std 1003.1-200x augments the latter functionality with a mandatory feature named 41116 _POSIX_SAVED_IDS. This feature permits a set-user-ID application to switch its effective user 41117 ID back and forth between the values of its exec-time real user ID and effective user ID. 41118 Unfortunately, the POSIX.1-1990 standard did not permit a conforming application using this | 41119 feature to work properly when it happened to be executed with the (implementation-defined) | 41120 appropriate privilege. Furthermore, the application did not even have a means to tell whether it | 41121 had this privilege. Since the saved set-user-ID feature is quite desirable for applications, as | 41122 evidenced by the fact that NIST required it in FIPS 151-2, it has been mandated by 41123 IEEE Std 1003.1-200x. However, there are implementors who have been reluctant to support it 41124 given the limitation described above. 41125 The 4.3BSD system handles the problem by supporting separate functions: setuid( ) (which 41126 always sets both the real and effective user IDs, like setuid( ) in IEEE Std 1003.1-200x for 41127 privileged users), and seteuid( ) (which always sets just the effective user ID, like setuid( ) in 41128 IEEE Std 1003.1-200x for non-privileged users). This separation of functionality into distinct 41129 functions seems desirable. 4.3BSD does not support the saved set-user-ID feature. It supports 41130 similar functionality of switching the effective user ID back and forth via setreuid( ), which 41131 permits reversing the real and effective user IDs. This model seems less desirable than the saved 41132 set-user-ID because the real user ID changes as a side effect. The current 4.4BSD includes saved 41133 effective IDs and uses them for seteuid( ) and setegid( ) as described above. The setreuid( ) and 41134 setregid( ) functions will be deprecated or removed. 41135 The solution here is: 41136 * Require that all implementations support the functionality of the saved set-user-ID, which is 41137 set by the exec functions and by privileged calls to setuid( ). 41138 * Add the seteuid( ) and setegid( ) functions as portable alternatives to setuid( ) and setgid( ) for 41139 non-privileged and privileged processes. 41140 Historical systems have provided two mechanisms for a set-user-ID process to change its 41141 effective user ID to be the same as its real user ID in such a way that it could return to the 41142 original effective user ID: the use of the setuid( ) function in the presence of a saved set-user-ID, 41143 or the use of the BSD setreuid( ) function, which was able to swap the real and effective user IDs. 41144 The changes included in IEEE Std 1003.1-200x provide a new mechanism using seteuid( ) in 41145 conjunction with a saved set-user-ID. Thus, all implementations with the new seteuid( ) 41146 mechanism will have a saved set-user-ID for each process, and most of the behavior controlled 41147 by _POSIX_SAVED_IDS has been changed to agree with the case where the option was defined. 41148 The kill( ) function is an exception. Implementors of the new seteuid( ) mechanism will generally 41149 be required to maintain compatibility with the older mechanisms previously supported by their 41150 systems. However, compatibility with this use of setreuid( ) and with the _POSIX_SAVED_IDS 41151 behavior of kill( ) is unfortunately complicated. If an implementation with a saved set-user-ID 41152 allows a process to use setreuid( ) to swap its real and effective user IDs, but were to leave the 41153 saved set-user-ID unmodified, the process would then have an effective user ID equal to the 41154 original real user ID, and both real and saved set-user-ID would be equal to the original effective 41155 user ID. In that state, the real user would be unable to kill the process, even though the effective 41156 user ID of the process matches that of the real user, if the kill( ) behavior of _POSIX_SAVED_IDS 41157 was used. This is obviously not acceptable. The alternative choice, which is used in at least one 41158 implementation, is to change the saved set-user-ID to the effective user ID during most calls to 41159 setreuid( ). The standard developers considered that alternative to be less correct than the 1818 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setuid( ) 41160 retention of the old behavior of kill( ) in such systems. Current conforming applications shall 41161 accommodate either behavior from kill( ), and there appears to be no strong reason for kill( ) to 41162 check the saved set-user-ID rather than the effective user ID. 41163 FUTURE DIRECTIONS 41164 None. 41165 SEE ALSO 41166 exec, getegid( ), geteuid( ), getgid( ), getuid( ), setegid( ), seteuid( ), setgid( ), setregid( ), setreuid( ), the 41167 Base Definitions volume of IEEE Std 1003.1-200x, , 41168 CHANGE HISTORY 41169 First released in Issue 1. Derived from Issue 1 of the SVID. 41170 Issue 6 41171 In the SYNOPSIS, the optional include of the header is removed. 41172 The following new requirements on POSIX implementations derive from alignment with the 41173 Single UNIX Specification: 41174 * The requirement to include has been removed. Although was 41175 required for conforming implementations of previous POSIX specifications, it was not 41176 required for UNIX applications. 41177 * The functionality associated with _POSIX_SAVED_IDS is now mandatory. This is a FIPS 41178 requirement. 41179 The following changes were made to align with the IEEE P1003.1a draft standard: 41180 * The effects of setuid( ) in processes without appropriate privileges are changed. 41181 * A requirement that the supplementary group list is not affected is added. System Interfaces, Issue 6 1819 setutxent( ) System Interfaces 41182 NAME 41183 setutxent - reset user accounting database to first entry 41184 SYNOPSIS 41185 XSI #include 41186 void setutxent(void); 41187 41188 DESCRIPTION 41189 Refer to endutxent( ). 1820 Technical Standard (2001) (Draft April 16, 2001) System Interfaces setvbuf( ) 41190 NAME 41191 setvbuf - assign buffering to a stream 41192 SYNOPSIS 41193 #include 41194 int setvbuf(FILE *restrict stream, char *restrict buf, int type, 41195 size_t size); 41196 DESCRIPTION 41197 CX The functionality described on this reference page is aligned with the ISO C standard. Any 41198 conflict between the requirements described here and the ISO C standard is unintentional. This 41199 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 41200 The setvbuf( ) function may be used after the stream pointed to by stream is associated with an 41201 open file but before any other operation (other than an unsuccessful call to setvbuf( )) is 41202 performed on the stream. The argument type determines how stream shall be buffered, as 41203 follows: 41204 * {_IOFBF} shall cause input/output to be fully buffered. 41205 * {_IOLBF} shall cause input/output to be line buffered. 41206 * {_IONBF} shall cause input/output to be unbuffered. 41207 If buf is not a null pointer, the array it points to may be used instead of a buffer allocated by 41208 setvbuf( ) and the argument size specifies the size of the array; otherwise, size may determine the 41209 size of a buffer allocated by the setvbuf( ) function. The contents of the array at any time are | 41210 unspecified. | 41211 For information about streams, see Section 2.5 (on page 484). 41212 RETURN VALUE 41213 Upon successful completion, setvbuf( ) shall return 0. Otherwise, it shall return a non-zero value 41214 CX if an invalid value is given for type or if the request cannot be honored, and may set errno to 41215 indicate the error. 41216 ERRORS 41217 The setvbuf( ) function may fail if: 41218 CX [EBADF] The file descriptor underlying stream is not valid. 41219 EXAMPLES 41220 None. 41221 APPLICATION USAGE 41222 A common source of error is allocating buffer space as an ``automatic'' variable in a code block, 41223 and then failing to close the stream in the same block. 41224 With setvbuf( ), allocating a buffer of size bytes does not necessarily imply that all of size bytes are 41225 used for the buffer area. 41226 Applications should note that many implementations only provide line buffering on input from 41227 terminal devices. 41228 RATIONALE 41229 None. System Interfaces, Issue 6 1821 setvbuf( ) System Interfaces 41230 FUTURE DIRECTIONS 41231 None. 41232 SEE ALSO 41233 fopen( ), setbuf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 41234 CHANGE HISTORY 41235 First released in Issue 1. Derived from Issue 1 of the SVID. 41236 Issue 6 41237 Extensions beyond the ISO C standard are now marked. 41238 The setvbuf( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 1822 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shm_open( ) 41239 NAME 41240 shm_open - open a shared memory object (REALTIME) 41241 SYNOPSIS 41242 SHM #include 41243 int shm_open(const char *name, int oflag, mode_t mode); 41244 41245 DESCRIPTION 41246 The shm_open( ) function shall establish a connection between a shared memory object and a file 41247 descriptor. It shall create an open file description that refers to the shared memory object and a 41248 file descriptor that refers to that open file description. The file descriptor is used by other 41249 functions to refer to that shared memory object. The name argument points to a string naming a 41250 shared memory object. It is unspecified whether the name appears in the file system and is 41251 visible to other functions that take pathnames as arguments. The name argument conforms to the | 41252 construction rules for a pathname. If name begins with the slash character, then processes calling | 41253 shm_open( ) with the same value of name refer to the same shared memory object, as long as that 41254 name has not been removed. If name does not begin with the slash character, the effect is 41255 implementation-defined. The interpretation of slash characters other than the leading slash 41256 character in name is implementation-defined. 41257 If successful, shm_open( ) shall return a file descriptor for the shared memory object that is the 41258 lowest numbered file descriptor not currently open for that process. The open file description is 41259 new, and therefore the file descriptor does not share it with any other processes. It is unspecified 41260 whether the file offset is set. The FD_CLOEXEC file descriptor flag associated with the new file 41261 descriptor is set. 41262 The file status flags and file access modes of the open file description are according to the value 41263 of oflag. The oflag argument is the bitwise-inclusive OR of the following flags defined in the 41264 header. Applications specify exactly one of the first two values (access modes) below 41265 in the value of oflag: 41266 O_RDONLY Open for read access only. 41267 O_RDWR Open for read or write access. 41268 Any combination of the remaining flags may be specified in the value of oflag: 41269 O_CREAT If the shared memory object exists, this flag has no effect, except as noted 41270 under O_EXCL below. Otherwise, the shared memory object is created; the 41271 user ID of the shared memory object shall be set to the effective user ID of the 41272 process; the group ID of the shared memory object is set to a system default 41273 group ID or to the effective group ID of the process. The permission bits of the 41274 shared memory object shall be set to the value of the mode argument except 41275 those set in the file mode creation mask of the process. When bits in mode 41276 other than the file permission bits are set, the effect is unspecified. The mode 41277 argument does not affect whether the shared memory object is opened for 41278 reading, for writing, or for both. The shared memory object has a size of zero. 41279 O_EXCL If O_EXCL and O_CREAT are set, shm_open( ) fails if the shared memory 41280 object exists. The check for the existence of the shared memory object and the 41281 creation of the object if it does not exist is atomic with respect to other 41282 processes executing shm_open( ) naming the same shared memory object with 41283 O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the 41284 result is undefined. System Interfaces, Issue 6 1823 shm_open( ) System Interfaces 41285 O_TRUNC If the shared memory object exists, and it is successfully opened O_RDWR, 41286 the object shall be truncated to zero length and the mode and owner shall be 41287 unchanged by this function call. The result of using O_TRUNC with 41288 O_RDONLY is undefined. 41289 When a shared memory object is created, the state of the shared memory object, including all 41290 data associated with the shared memory object, persists until the shared memory object is 41291 unlinked and all other references are gone. It is unspecified whether the name and shared 41292 memory object state remain valid after a system reboot. 41293 RETURN VALUE 41294 Upon successful completion, the shm_open( ) function shall return a non-negative integer 41295 representing the lowest numbered unused file descriptor. Otherwise, it shall return -1 and set 41296 errno to indicate the error. 41297 ERRORS 41298 The shm_open( ) function shall fail if: 41299 [EACCES] The shared memory object exists and the permissions specified by oflag are 41300 denied, or the shared memory object does not exist and permission to create 41301 the shared memory object is denied, or O_TRUNC is specified and write 41302 permission is denied. 41303 [EEXIST] O_CREAT and O_EXCL are set and the named shared memory object already 41304 exists. 41305 [EINTR] The shm_open( ) operation was interrupted by a signal. 41306 [EINVAL] The shm_open( ) operation is not supported for the given name. 41307 [EMFILE] Too many file descriptors are currently in use by this process. 41308 [ENAMETOOLONG] 41309 The length of the name argument exceeds {PATH_MAX} or a pathname | 41310 component is longer than {NAME_MAX}. | 41311 [ENFILE] Too many shared memory objects are currently open in the system. 41312 [ENOENT] O_CREAT is not set and the named shared memory object does not exist. 41313 [ENOSPC] There is insufficient space for the creation of the new shared memory object. 41314 EXAMPLES 41315 None. 41316 APPLICATION USAGE 41317 None. 41318 RATIONALE 41319 When the Memory Mapped Files option is supported, the normal open( ) call is used to obtain a 41320 descriptor to a file to be mapped according to existing practice with mmap( ). When the Shared 41321 Memory Objects option is supported, the shm_open( ) function shall obtain a descriptor to the | 41322 shared memory object to be mapped. | 41323 There is ample precedent for having a file descriptor represent several types of objects. In the 41324 POSIX.1-1990 standard, a file descriptor can represent a file, a pipe, a FIFO, a tty, or a directory. 41325 Many implementations simply have an operations vector, which is indexed by the file descriptor 41326 type and does very different operations. Note that in some cases the file descriptor passed to 41327 generic operations on file descriptors are returned by open( ) or creat( ) and in some cases 41328 returned by alternate functions, such as pipe( ). The latter technique is used by shm_open( ). 1824 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shm_open( ) 41329 Note that such shared memory objects can actually be implemented as mapped files. In both 41330 cases, the size can be set after the open using ftruncate( ). The shm_open( ) function itself does not 41331 create a shared object of a specified size because this would duplicate an extant function that set 41332 the size of an object referenced by a file descriptor. 41333 On implementations where memory objects are implemented using the existing file system, the 41334 shm_open( ) function may be implemented using a macro that invokes open( ), and the 41335 shm_unlink( ) function may be implemented using a macro that invokes unlink( ). 41336 For implementations without a permanent file system, the definition of the name of the memory 41337 objects is allowed not to survive a system reboot. Note that this allows systems with a 41338 permanent file system to implement memory objects as data structures internal to the 41339 implementation as well. 41340 On implementations that choose to implement memory objects using memory directly, a 41341 shm_open( ) followed by a ftruncate( ) and close( ) can be used to preallocate a shared memory 41342 area and to set the size of that preallocation. This may be necessary for systems without virtual 41343 memory hardware support in order to ensure that the memory is contiguous. 41344 The set of valid open flags to shm_open( ) was restricted to O_RDONLY, O_RDWR, O_CREAT, 41345 and O_TRUNC because these could be easily implemented on most memory mapping systems. 41346 This volume of IEEE Std 1003.1-200x is silent on the results if the implementation cannot supply 41347 the requested file access because of implementation-defined reasons, including hardware ones. 41348 The error conditions [EACCES] and [ENOTSUP] are provided to inform the application that the 41349 implementation cannot complete a request. 41350 [EACCES] indicates for implementation-defined reasons, probably hardware-related, that the 41351 implementation cannot comply with a requested mode because it conflicts with another 41352 requested mode. An example might be that an application desires to open a memory object two 41353 times, mapping different areas with different access modes. If the implementation cannot map a 41354 single area into a process space in two places, which would be required if different access modes 41355 were required for the two areas, then the implementation may inform the application at the time 41356 of the second open. 41357 [ENOTSUP] indicates for implementation-defined reasons, probably hardware-related, that the 41358 implementation cannot comply with a requested mode at all. An example would be that the 41359 hardware of the implementation cannot support write-only shared memory areas. 41360 On all implementations, it may be desirable to restrict the location of the memory objects to 41361 specific file systems for performance (such as a RAM disk) or implementation-defined reasons 41362 (shared memory supported directly only on certain file systems). The shm_open( ) function may 41363 be used to enforce these restrictions. There are a number of methods available to the application 41364 to determine an appropriate name of the file or the location of an appropriate directory. One 41365 way is from the environment via getenv( ). Another would be from a configuration file. 41366 This volume of IEEE Std 1003.1-200x specifies that memory objects have initial contents of zero 41367 when created. This is consistent with current behavior for both files and newly allocated 41368 memory. For those implementations that use physical memory, it would be possible that such 41369 implementations could simply use available memory and give it to the process uninitialized. 41370 This, however, is not consistent with standard behavior for the uninitialized data area, the stack, 41371 and of course, files. Finally, it is highly desirable to set the allocated memory to zero for security 41372 reasons. Thus, initializing memory objects to zero is required. System Interfaces, Issue 6 1825 shm_open( ) System Interfaces 41373 FUTURE DIRECTIONS 41374 None. 41375 SEE ALSO 41376 close( ), dup( ), exec, fcntl( ), mmap( ), shmat( ), shmctl( ), shmdt( ), shm_unlink( ), umask( ), the Base 41377 Definitions volume of IEEE Std 1003.1-200x, , 41378 CHANGE HISTORY 41379 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 41380 Issue 6 41381 The shm_open( ) function is marked as part of the Shared Memory Objects option. 41382 The [ENOSYS] error condition has been removed as stubs need not be provided if an 41383 implementation does not support the Shared Memory Objects option. 1826 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shm_unlink( ) 41384 NAME 41385 shm_unlink - remove a shared memory object (REALTIME) 41386 SYNOPSIS 41387 SHM #include 41388 int shm_unlink(const char *name); 41389 41390 DESCRIPTION 41391 The shm_unlink( ) function shall remove the name of the shared memory object named by the 41392 string pointed to by name. 41393 If one or more references to the shared memory object exist when the object is unlinked, the 41394 name shall be removed before shm_unlink( ) returns, but the removal of the memory object 41395 contents shall be postponed until all open and map references to the shared memory object have 41396 been removed. 41397 Even if the object continues to exist after the last shm_unlink( ), reuse of the name shall 41398 subsequently cause shm_open( ) to behave as if no shared memory object of this name exists (that 41399 is, shm_open( ) will fail if O_CREAT is not set, or will create a new shared memory object if 41400 O_CREAT is set). 41401 RETURN VALUE 41402 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 41403 returned and errno set to indicate the error. If -1 is returned, the named shared memory object 41404 shall not be changed by this function call. 41405 ERRORS 41406 The shm_unlink( ) function shall fail if: 41407 [EACCES] Permission is denied to unlink the named shared memory object. 41408 [ENAMETOOLONG] 41409 The length of the name argument exceeds {PATH_MAX} or a pathname | 41410 component is longer than {NAME_MAX}. | 41411 [ENOENT] The named shared memory object does not exist. 41412 EXAMPLES 41413 None. 41414 APPLICATION USAGE 41415 Names of memory objects that were allocated with open( ) are deleted with unlink( ) in the usual 41416 fashion. Names of memory objects that were allocated with shm_open( ) are deleted with 41417 shm_unlink( ). Note that the actual memory object is not destroyed until the last close and 41418 unmap on it have occurred if it was already in use. 41419 RATIONALE 41420 None. 41421 FUTURE DIRECTIONS 41422 None. 41423 SEE ALSO 41424 close( ), mmap( ), munmap( ), shmat( ), shmctl( ), shmdt( ), shm_open( ), the Base Definitions volume 41425 of IEEE Std 1003.1-200x, System Interfaces, Issue 6 1827 shm_unlink( ) System Interfaces 41426 CHANGE HISTORY 41427 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 41428 Issue 6 41429 The shm_unlink( ) function is marked as part of the Shared Memory Objects option. 41430 In the DESCRIPTION, text is added to clarify that reusing the same name after a shm_unlink( ) 41431 will not attach to the old shared memory object. 41432 The [ENOSYS] error condition has been removed as stubs need not be provided if an 41433 implementation does not support the Shared Memory Objects option. 1828 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shmat( ) 41434 NAME 41435 shmat - XSI shared memory attach operation 41436 SYNOPSIS 41437 XSI #include 41438 void *shmat(int shmid, const void *shmaddr, int shmflg); 41439 41440 DESCRIPTION 41441 The shmat( ) function operates on XSI shared memory (see the Base Definitions volume of 41442 IEEE Std 1003.1-200x, Section 3.340, Shared Memory Object). It is unspecified whether this 41443 function interoperates with the realtime interprocess communication facilities defined in Section 41444 2.8 (on page 491). 41445 The shmat( ) function attaches the shared memory segment associated with the shared memory 41446 identifier specified by shmid to the address space of the calling process. The segment is attached 41447 at the address specified by one of the following criteria: 41448 * If shmaddr is a null pointer, the segment is attached at the first available address as selected 41449 by the system. 41450 * If shmaddr is not a null pointer and (shmflg &SHM_RND) is non-zero, the segment is attached 41451 at the address given by (shmaddr -((uintptr_t)shmaddr %SHMLBA)). The character '%' is the 41452 C-language remainder operator. 41453 * If shmaddr is not a null pointer and (shmflg &SHM_RND) is 0, the segment is attached at the 41454 address given by shmaddr. 41455 * The segment is attached for reading if (shmflg &SHM_RDONLY) is non-zero and the calling 41456 process has read permission; otherwise, if it is 0 and the calling process has read and write 41457 permission, the segment is attached for reading and writing. 41458 RETURN VALUE 41459 Upon successful completion, shmat( ) shall increment the value of shm_nattch in the data 41460 structure associated with the shared memory ID of the attached shared memory segment and 41461 return the segment's start address. 41462 Otherwise, the shared memory segment shall not be attached, shmat( ) shall return -1, and errno 41463 shall be set to indicate the error. 41464 ERRORS 41465 The shmat( ) function shall fail if: 41466 [EACCES] Operation permission is denied to the calling process; see Section 2.7 (on page 41467 489). 41468 [EINVAL] The value of shmid is not a valid shared memory identifier, the shmaddr is not a 41469 null pointer, and the value of (shmaddr -((uintptr_t)shmaddr %SHMLBA)) is an 41470 illegal address for attaching shared memory; or the shmaddr is not a null 41471 pointer, (shmflg &SHM_RND) is 0, and the value of shmaddr is an illegal 41472 address for attaching shared memory. 41473 [EMFILE] The number of shared memory segments attached to the calling process 41474 would exceed the system-imposed limit. 41475 [ENOMEM] The available data space is not large enough to accommodate the shared 41476 memory segment. System Interfaces, Issue 6 1829 shmat( ) System Interfaces 41477 EXAMPLES 41478 None. 41479 APPLICATION USAGE 41480 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 41481 Application developers who need to use IPC should design their applications so that modules 41482 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 41483 alternative interfaces. 41484 RATIONALE 41485 None. 41486 FUTURE DIRECTIONS 41487 None. 41488 SEE ALSO 41489 exec, exit( ), fork( ), shmctl( ), shmdt( ), shmget( ), shm_open( ), shm_unlink( ), the Base Definitions 41490 volume of IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 41491 CHANGE HISTORY 41492 First released in Issue 2. Derived from Issue 2 of the SVID. 41493 Issue 5 41494 Moved from SHARED MEMORY to BASE. 41495 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 41496 DIRECTIONS to a new APPLICATION USAGE section. 41497 Issue 6 41498 The Open Group Corrigendum U021/13 is applied. 1830 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shmctl( ) 41499 NAME 41500 shmctl - XSI shared memory control operations 41501 SYNOPSIS 41502 XSI #include 41503 int shmctl(int shmid, int cmd, struct shmid_ds *buf); 41504 41505 DESCRIPTION 41506 The shmctl( ) function operates on XSI shared memory (see the Base Definitions volume of 41507 IEEE Std 1003.1-200x, Section 3.340, Shared Memory Object). It is unspecified whether this 41508 function interoperates with the realtime interprocess communication facilities defined in Section 41509 2.8 (on page 491). 41510 The shmctl( ) function provides a variety of shared memory control operations as specified by 41511 cmd. The following values for cmd are available: 41512 IPC_STAT Place the current value of each member of the shmid_ds data structure 41513 associated with shmid into the structure pointed to by buf. The contents of the 41514 structure are defined in . 41515 IPC_SET Set the value of the following members of the shmid_ds data structure 41516 associated with shmid to the corresponding value found in the structure 41517 pointed to by buf: 41518 shm_perm.uid 41519 shm_perm.gid 41520 shm_perm.mode Low-order nine bits. 41521 IPC_SET can only be executed by a process that has an effective user ID equal 41522 to either that of a process with appropriate privileges or to the value of 41523 shm_perm.cuid or shm_perm.uid in the shmid_ds data structure associated with 41524 shmid. 41525 IPC_RMID Remove the shared memory identifier specified by shmid from the system and 41526 destroy the shared memory segment and shmid_ds data structure associated 41527 with it. IPC_RMID can only be executed by a process that has an effective user 41528 ID equal to either that of a process with appropriate privileges or to the value 41529 of shm_perm.cuid or shm_perm.uid in the shmid_ds data structure associated 41530 with shmid. 41531 RETURN VALUE 41532 Upon successful completion, shmctl( ) shall return 0; otherwise, it shall return -1 and set errno to 41533 indicate the error. 41534 ERRORS 41535 The shmctl( ) function shall fail if: 41536 [EACCES] The argument cmd is equal to IPC_STAT and the calling process does not have 41537 read permission; see Section 2.7 (on page 489). 41538 [EINVAL] The value of shmid is not a valid shared memory identifier, or the value of cmd 41539 is not a valid command. 41540 [EPERM] The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID 41541 of the calling process is not equal to that of a process with appropriate 41542 privileges and it is not equal to the value of shm_perm.cuid or shm_perm.uid in 41543 the data structure associated with shmid. System Interfaces, Issue 6 1831 shmctl( ) System Interfaces 41544 The shmctl( ) function may fail if: 41545 [EOVERFLOW] The cmd argument is IPC_STAT and the gid or uid value is too large to be 41546 stored in the structure pointed to by the buf argument. 41547 EXAMPLES 41548 None. 41549 APPLICATION USAGE 41550 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 41551 Application developers who need to use IPC should design their applications so that modules 41552 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 41553 alternative interfaces. 41554 RATIONALE 41555 None. 41556 FUTURE DIRECTIONS 41557 None. 41558 SEE ALSO 41559 shmat( ), shmdt( ), shmget( ), shm_open( ), shm_unlink( ), the Base Definitions volume of 41560 IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 41561 CHANGE HISTORY 41562 First released in Issue 2. Derived from Issue 2 of the SVID. 41563 Issue 5 41564 Moved from SHARED MEMORY to BASE. 41565 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 41566 DIRECTIONS to a new APPLICATION USAGE section. 1832 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shmdt( ) 41567 NAME 41568 shmdt - XSI shared memory detach operation 41569 SYNOPSIS 41570 XSI #include 41571 int shmdt(const void *shmaddr); 41572 41573 DESCRIPTION 41574 The shmdt( ) function operates on XSI shared memory (see the Base Definitions volume of 41575 IEEE Std 1003.1-200x, Section 3.340, Shared Memory Object). It is unspecified whether this 41576 function interoperates with the realtime interprocess communication facilities defined in Section 41577 2.8 (on page 491). 41578 The shmdt( ) function detaches the shared memory segment located at the address specified by 41579 shmaddr from the address space of the calling process. 41580 RETURN VALUE 41581 Upon successful completion, shmdt( ) shall decrement the value of shm_nattch in the data 41582 structure associated with the shared memory ID of the attached shared memory segment and 41583 return 0. 41584 Otherwise, the shared memory segment shall not be detached, shmdt( ) shall return -1, and errno 41585 shall be set to indicate the error. 41586 ERRORS 41587 The shmdt( ) function shall fail if: 41588 [EINVAL] The value of shmaddr is not the data segment start address of a shared 41589 memory segment. 41590 EXAMPLES 41591 None. 41592 APPLICATION USAGE 41593 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 41594 Application developers who need to use IPC should design their applications so that modules 41595 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 41596 alternative interfaces. 41597 RATIONALE 41598 None. 41599 FUTURE DIRECTIONS 41600 None. 41601 SEE ALSO 41602 exec, exit( ), fork( ), shmat( ), shmctl( ), shmget( ), shm_open( ), shm_unlink( ), the Base Definitions 41603 volume of IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 41604 CHANGE HISTORY 41605 First released in Issue 2. Derived from Issue 2 of the SVID. 41606 Issue 5 41607 Moved from SHARED MEMORY to BASE. 41608 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 41609 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1833 shmget( ) System Interfaces 41610 NAME 41611 shmget - get XSI shared memory segment 41612 SYNOPSIS 41613 XSI #include 41614 int shmget(key_t key, size_t size, int shmflg); 41615 41616 DESCRIPTION 41617 The shmget( ) function operates on XSI shared memory (see the Base Definitions volume of 41618 IEEE Std 1003.1-200x, Section 3.340, Shared Memory Object). It is unspecified whether this 41619 function interoperates with the realtime interprocess communication facilities defined in Section 41620 2.8 (on page 491). 41621 The shmget( ) function shall return the shared memory identifier associated with key. 41622 A shared memory identifier, associated data structure, and shared memory segment of at least 41623 size bytes (see ) are created for key if one of the following is true: 41624 * The argument key is equal to IPC_PRIVATE. 41625 * The argument key does not already have a shared memory identifier associated with it and 41626 (shmflg &IPC_CREAT) is non-zero. 41627 Upon creation, the data structure associated with the new shared memory identifier shall be 41628 initialized as follows: 41629 * The values of shm_perm.cuid, shm_perm.uid, shm_perm.cgid, and shm_perm.gid are set equal to 41630 the effective user ID and effective group ID, respectively, of the calling process. 41631 * The low-order nine bits of shm_perm.mode are set equal to the low-order nine bits of shmflg. 41632 The value of shm_segsz is set equal to the value of size. 41633 * The values of shm_lpid, shm_nattch, shm_atime, and shm_dtime are set equal to 0. 41634 * The value of shm_ctime is set equal to the current time. 41635 When the shared memory segment is created, it shall be initialized with all zero values. 41636 RETURN VALUE 41637 Upon successful completion, shmget( ) shall return a non-negative integer, namely a shared 41638 memory identifier; otherwise, it shall return -1 and set errno to indicate the error. 41639 ERRORS 41640 The shmget( ) function shall fail if: 41641 [EACCES] A shared memory identifier exists for key but operation permission as 41642 specified by the low-order nine bits of shmflg would not be granted; see 41643 Section 2.7 (on page 489). 41644 [EEXIST] A shared memory identifier exists for the argument key but (shmflg 41645 &IPC_CREAT) &&(shmflg &IPC_EXCL) is non-zero. | 41646 [EINVAL] A shared memory segment is to be created and the value of size is less than | 41647 the system-imposed minimum or greater than the system-imposed maximum. | 41648 [EINVAL] No shared memory segment is to be created and a shared memory segment | 41649 exists for key but the size of the segment associated with it is less than size and | 41650 size is not 0. 1834 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shmget( ) 41651 [ENOENT] A shared memory identifier does not exist for the argument key and (shmflg 41652 &IPC_CREAT) is 0. 41653 [ENOMEM] A shared memory identifier and associated shared memory segment shall be 41654 created, but the amount of available physical memory is not sufficient to fill 41655 the request. 41656 [ENOSPC] A shared memory identifier is to be created, but the system-imposed limit on 41657 the maximum number of allowed shared memory identifiers system-wide 41658 would be exceeded. 41659 EXAMPLES 41660 None. 41661 APPLICATION USAGE 41662 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 41663 Application developers who need to use IPC should design their applications so that modules 41664 using the IPC routines described in Section 2.7 (on page 489) can be easily modified to use the 41665 alternative interfaces. 41666 RATIONALE 41667 None. 41668 FUTURE DIRECTIONS 41669 None. 41670 SEE ALSO 41671 shmat( ), shmctl( ), shmdt( ), shm_open( ), shm_unlink( ), the Base Definitions volume of 41672 IEEE Std 1003.1-200x, , Section 2.7 (on page 489) 41673 CHANGE HISTORY 41674 First released in Issue 2. Derived from Issue 2 of the SVID. 41675 Issue 5 41676 Moved from SHARED MEMORY to BASE. 41677 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 41678 DIRECTIONS to a new APPLICATION USAGE section. System Interfaces, Issue 6 1835 shutdown( ) System Interfaces 41679 NAME 41680 shutdown - shut down socket send and receive operations 41681 SYNOPSIS 41682 #include 41683 int shutdown(int socket, int how); 41684 DESCRIPTION 41685 The shutdown( ) function shall cause all or part of a full-duplex connection on the socket 41686 associated with the file descriptor socket to be shut down. 41687 The shutdown( ) function takes the following arguments: 41688 socket Specifies the file descriptor of the socket. 41689 how Specifies the type of shutdown. The values are as follows: 41690 SHUT_RD Disables further receive operations. 41691 SHUT_WR Disables further send operations. 41692 SHUT_RDWR Disables further send and receive operations. 41693 The shutdown( ) function disables subsequent send and/or receive operations on a socket, 41694 depending on the value of the how argument. 41695 RETURN VALUE 41696 Upon successful completion, shutdown( ) shall return 0; otherwise, -1 shall be returned and errno 41697 set to indicate the error. 41698 ERRORS 41699 The shutdown( ) function shall fail if: 41700 [EBADF] The socket argument is not a valid file descriptor. 41701 [EINVAL] The how argument is invalid. 41702 [ENOTCONN] The socket is not connected. 41703 [ENOTSOCK] The socket argument does not refer to a socket. 41704 The shutdown( ) function may fail if: 41705 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 41706 EXAMPLES 41707 None. 41708 APPLICATION USAGE 41709 None. 41710 RATIONALE 41711 None. 41712 FUTURE DIRECTIONS 41713 None. 41714 SEE ALSO 41715 getsockopt( ), read( ), recv( ), recvfrom( ), recvmsg( ), select( ), send( ), sendto( ), setsockopt( ), socket( ), 41716 write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1836 Technical Standard (2001) (Draft April 16, 2001) System Interfaces shutdown( ) 41717 CHANGE HISTORY 41718 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1837 sigaction( ) System Interfaces 41719 NAME 41720 sigaction - examine and change signal action 41721 SYNOPSIS 41722 CX #include | 41723 int sigaction(int sig, const struct sigaction *restrict act, 41724 struct sigaction *restrict oact); 41725 | 41726 DESCRIPTION 41727 The sigaction( ) function allows the calling process to examine and/or specify the action to be 41728 associated with a specific signal. The argument sig specifies the signal; acceptable values are 41729 defined in . 41730 The structure sigaction, used to describe an action to be taken, is defined in the | 41731 header to include at least the following members: 41732 _______________________________________________________________________________ 41733 _ Member Type Member Name Description ______________________________________________________________________________ 41734 void(*) (int) sa_handler SIG_DFL, SIG_IGN, or pointer to a function. 41735 sigset_t sa_mask Additional set of signals to be blocked 41736 during execution of signal-catching 41737 function. 41738 int sa_flags Special flags to affect behavior of signal. 41739 void(*) (int, 41740 _ siginfo_t *, void *) sa_sigaction Signal-catching function. ______________________________________________________________________________ 41741 The storage occupied by sa_handler and sa_sigaction may overlap, and a conforming application 41742 shall not use both simultaneously. 41743 If the argument act is not a null pointer, it points to a structure specifying the action to be 41744 associated with the specified signal. If the argument oact is not a null pointer, the action 41745 previously associated with the signal is stored in the location pointed to by the argument oact. If 41746 the argument act is a null pointer, signal handling is unchanged; thus, the call can be used to 41747 enquire about the current handling of a given signal. The SIGKILL and SIGSTOP signals shall 41748 not be added to the signal mask using this mechanism; this restriction shall be enforced by the 41749 system without causing an error to be indicated. 41750 If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of the sigaction structure, the 41751 XSI|RTS sa_handler field identifies the action to be associated with the specified signal. If the 41752 SA_SIGINFO flag is set in the sa_flags field, and the implementation supports the Realtime 41753 Signals Extension option or the X/Open System Interfaces Extension option, the sa_sigaction 41754 field specifies a signal-catching function. If the SA_SIGINFO bit is cleared and the sa_handler 41755 field specifies a signal-catching function, or if the SA_SIGINFO bit is set, the sa_mask field 41756 identifies a set of signals that shall be added to the signal mask of the thread before the signal- 41757 catching function is invoked. If the sa_handler field specifies a signal-catching function, the 41758 sa_mask field identifies a set of signals that shall be added to the process' signal mask before the 41759 signal-catching function is invoked. 41760 The sa_flags field can be used to modify the behavior of the specified signal. 41761 The following flags, defined in the header, can be set in sa_flags: 41762 XSI SA_NOCLDSTOP Do not generate SIGCHLD when children stop or stopped children | 41763 continue. | 1838 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigaction( ) 41764 If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and 41765 the implementation supports the SIGCHLD signal, then a SIGCHLD 41766 signal shall be generated for the calling process whenever any of its child | 41767 XSI processes stop and a SIGCHLD signal may be generated for the calling | 41768 process whnever any of its stopped child processes are continued. If sig is | 41769 SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then the 41770 implementation shall not generate a SIGCHLD signal in this way. 41771 XSI SA_ONSTACK If set and an alternate signal stack has been declared with sigaltstack( ) or 41772 sigstack( ), the signal shall be delivered to the calling process on that stack. 41773 Otherwise, the signal shall be delivered on the current stack. 41774 XSI SA_RESETHAND If set, the disposition of the signal shall be reset to SIG_DFL and the 41775 SA_SIGINFO flag shall be cleared on entry to the signal handler. 41776 Note: SIGILL and SIGTRAP cannot be automatically reset when delivered; 41777 the system silently enforces this restriction. 41778 Otherwise, the disposition of the signal shall not be modified on entry to 41779 the signal handler. 41780 In addition, if this flag is set, sigaction( ) behaves as if the SA_NODEFER 41781 flag were also set. 41782 XSI SA_RESTART This flag affects the behavior of interruptible functions; that is, those 41783 specified to fail with errno set to [EINTR]. If set, and a function specified 41784 as interruptible is interrupted by this signal, the function shall restart and 41785 shall not fail with [EINTR] unless otherwise specified. If the flag is not 41786 set, interruptible functions interrupted by this signal shall fail with errno 41787 set to [EINTR]. 41788 SA_SIGINFO If cleared and the signal is caught, the signal-catching function shall be 41789 entered as: 41790 void func(int signo); 41791 where signo is the only argument to the signal catching function. In this 41792 case, the application shall use the sa_handler member to describe the 41793 signal catching function and the application shall not modify the 41794 sa_sigaction member. 41795 XSI|RTS If SA_SIGINFO is set and the signal is caught, the signal-catching 41796 function shall be entered as: 41797 void func(int signo, siginfo_t *info, void *context); 41798 where two additional arguments are passed to the signal catching 41799 function. The second argument shall point to an object of type siginfo_t 41800 explaining the reason why the signal was generated; the third argument 41801 can be cast to a pointer to an object of type ucontext_t to refer to the 41802 receiving process' context that was interrupted when the signal was 41803 delivered. In this case, the application shall use the sa_sigaction member 41804 to describe the signal catching function and the application shall not 41805 modify the sa_handler member. 41806 The si_signo member contains the system-generated signal number. 41807 XSI The si_errno member may contain implementation-defined additional 41808 error information; if non-zero, it contains an error number identifying the 41809 condition that caused the signal to be generated. | System Interfaces, Issue 6 1839 sigaction( ) System Interfaces 41810 XSI|RTS The si_code member contains a code identifying the cause of the signal. | 41811 XSI If the value of si_code is less than or equal to 0, then the signal was | 41812 generated by a process and si_pid and si_uid, respectively, indicate the 41813 process ID and the real user ID of the sender. The header 41814 description contains information about the signal specific contents of the 41815 elements of the siginfo_t type. 41816 XSI SA_NOCLDWAIT If set, and sig equals SIGCHLD, child processes of the calling processes 41817 shall not be transformed into zombie processes when they terminate. If 41818 the calling process subsequently waits for its children, and the process 41819 has no unwaited-for children that were transformed into zombie 41820 processes, it shall block until all of its children terminate, and wait( ), 41821 waitid( ), and waitpid( ) shall fail and set errno to [ECHILD]. Otherwise, 41822 terminating child processes shall be transformed into zombie processes, 41823 unless SIGCHLD is set to SIG_IGN. 41824 XSI SA_NODEFER If set and sig is caught, sig shall not be added to the process' signal mask 41825 on entry to the signal handler unless it is included in sa_mask. Otherwise, 41826 sig shall always be added to the process' signal mask on entry to the 41827 signal handler. 41828 When a signal is caught by a signal-catching function installed by sigaction( ), a new signal mask 41829 is calculated and installed for the duration of the signal-catching function (or until a call to either 41830 sigprocmask( ) or sigsuspend( ) is made). This mask is formed by taking the union of the current 41831 XSI signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or 41832 SA_RESETHAND is set, and then including the signal being delivered. If and when the user's 41833 signal handler returns normally, the original signal mask is restored. 41834 Once an action is installed for a specific signal, it shall remain installed until another action is 41835 XSI explicitly requested (by another call to sigaction( )), until the SA_RESETHAND flag causes 41836 resetting of the handler,or until one of the exec functions is called. 41837 If the previous action for sig had been established by signal( ), the values of the fields returned in 41838 the structure pointed to by oact are unspecified, and in particular oact->sa_handler is not 41839 necessarily the same value passed to signal( ). However, if a pointer to the same structure or a 41840 copy thereof is passed to a subsequent call to sigaction( ) via the act argument, handling of the 41841 signal shall be as if the original call to signal( ) were repeated. 41842 If sigaction( ) fails, no new signal handler is installed. 41843 It is unspecified whether an attempt to set the action for a signal that cannot be caught or 41844 ignored to SIG_DFL is ignored or causes an error to be returned with errno set to [EINVAL]. 41845 If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when 41846 it is already pending is implementation-defined; the signal-catching function shall be invoked 41847 RTS with a single argument. If the implementation supports the Realtime Signals Extension option, 41848 and if SA_SIGINFO is set in sa_flags, then subsequent occurrences of sig generated by sigqueue( ) 41849 or as a result of any signal-generating function that supports the specification of an application- 41850 defined value (when sig is already pending) shall be queued in FIFO order until delivered or 41851 accepted; the signal-catching function shall be invoked with three arguments. The application 41852 specified value is passed to the signal-catching function as the si_value member of the siginfo_t 41853 structure. 41854 The result of the use of sigaction( ) and a sigwait( ) function concurrently within a process on the 41855 same signal is unspecified. 1840 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigaction( ) 41856 RETURN VALUE 41857 Upon successful completion, sigaction( ) shall return 0; otherwise, -1 shall be returned, errno shall 41858 be set to indicate the error, and no new signal-catching function shall be installed. 41859 ERRORS 41860 The sigaction( ) function shall fail if: 41861 [EINVAL] The sig argument is not a valid signal number or an attempt is made to catch a 41862 signal that cannot be caught or ignore a signal that cannot be ignored. 41863 [ENOTSUP] The SA_SIGINFO bit flag is set in the sa_flags field of the sigaction structure, 41864 and the implementation does not support either the Realtime Signals 41865 Extension option, or the X/Open System Interfaces Extension option. 41866 The sigaction( ) function may fail if: 41867 [EINVAL] An attempt was made to set the action to SIG_DFL for a signal that cannot be 41868 caught or ignored (or both). 41869 EXAMPLES 41870 None. 41871 APPLICATION USAGE 41872 The sigaction( ) function supersedes the signal( ) function, and should be used in preference. In 41873 particular, sigaction( ) and signal( ) should not be used in the same process to control the same 41874 signal. The behavior of reentrant functions, as defined in the DESCRIPTION, is as specified by 41875 this volume of IEEE Std 1003.1-200x, regardless of invocation from a signal-catching function. 41876 This is the only intended meaning of the statement that reentrant functions may be used in 41877 signal-catching functions without restrictions. Applications must still consider all effects of such 41878 functions on such things as data structures, files, and process state. In particular, application 41879 writers need to consider the restrictions on interactions when interrupting sleep( ) and 41880 interactions among multiple handles for a file description. The fact that any specific function is 41881 listed as reentrant does not necessarily mean that invocation of that function from a signal- 41882 catching function is recommended. 41883 In order to prevent errors arising from interrupting non-reentrant function calls, applications 41884 should protect calls to these functions either by blocking the appropriate signals or through the 41885 use of some programmatic semaphore (see semget( ), sem_init( ), sem_open( ), and so on). Note in 41886 particular that even the ``safe'' functions may modify errno; the signal-catching function, if not 41887 executing as an independent thread, may want to save and restore its value. Naturally, the same 41888 principles apply to the reentrancy of application routines and asynchronous data access. Note 41889 that longjmp( ) and siglongjmp( ) are not in the list of reentrant functions. This is because the code 41890 executing after longjmp( ) and siglongjmp( ) can call any unsafe functions with the same danger as 41891 calling those unsafe functions directly from the signal handler. Applications that use longjmp( ) 41892 and siglongjmp( ) from within signal handlers require rigorous protection in order to be portable. 41893 Many of the other functions that are excluded from the list are traditionally implemented using 41894 either malloc( ) or free( ) functions or the standard I/O library, both of which traditionally use | 41895 data structures in a non-reentrant manner. Since any combination of different functions using a | 41896 common data structure can cause reentrancy problems, this volume of IEEE Std 1003.1-200x 41897 does not define the behavior when any unsafe function is called in a signal handler that 41898 interrupts an unsafe function. 41899 If the signal occurs other than as the result of calling abort( ), kill( ), or raise( ), the behavior is 41900 undefined if the signal handler calls any function in the standard library other than one of the 41901 functions listed in the table above or refers to any object with static storage duration other than 41902 by assigning a value to a static storage duration variable of type volatile sig_atomic_t. 41903 Furthermore, if such a call fails, the value of errno is unspecified. | System Interfaces, Issue 6 1841 sigaction( ) System Interfaces 41904 Usually, the signal is executed on the stack that was in effect before the signal was delivered. An 41905 alternate stack may be specified to receive a subset of the signals being caught. 41906 When the signal handler returns, the receiving process resumes execution at the point it was 41907 interrupted unless the signal handler makes other arrangements. If longjmp( ) or _longjmp( ) is 41908 used to leave the signal handler, then the signal mask must be explicitly restored by the process. 41909 This volume of IEEE Std 1003.1-200x defines the third argument of a signal handling function 41910 when SA_SIGINFO is set as a void * instead of a ucontext_t *, but without requiring type 41911 checking. New applications should explicitly cast the third argument of the signal handling 41912 function to ucontext_t *. 41913 The BSD optional four argument signal handling function is not supported by this volume of 41914 IEEE Std 1003.1-200x. The BSD declaration would be: 41915 void handler(int sig, int code, struct sigcontext *scp, 41916 char *addr); 41917 where sig is the signal number, code is additional information on certain signals, scp is a pointer 41918 to the sigcontext structure, and addr is additional address information. Much the same 41919 information is available in the objects pointed to by the second argument of the signal handler 41920 specified when SA_SIGINFO is set. 41921 RATIONALE 41922 Although this volume of IEEE Std 1003.1-200x requires that signals that cannot be ignored shall 41923 not be added to the signal mask when a signal-catching function is entered, there is no explicit 41924 requirement that subsequent calls to sigaction( ) reflect this in the information returned in the oact 41925 argument. In other words, if SIGKILL is included in the sa_mask field of act, it is unspecified 41926 whether or not a subsequent call to sigaction( ) returns with SIGKILL included in the sa_mask 41927 field of oact. 41928 The SA_NOCLDSTOP flag, when supplied in the act->sa_flags parameter, allows overloading 41929 SIGCHLD with the System V semantics that each SIGCLD signal indicates a single terminated | 41930 child. Most conforming applications that catch SIGCHLD are expected to install signal-catching | 41931 functions that repeatedly call the waitpid( ) function with the WNOHANG flag set, acting on 41932 each child for which status is returned, until waitpid( ) returns zero. If stopped children are not of 41933 interest, the use of the SA_NOCLDSTOP flag can prevent the overhead from invoking the 41934 signal-catching routine when they stop. 41935 Some historical implementations also define other mechanisms for stopping processes, such as 41936 the ptrace( ) function. These implementations usually do not generate a SIGCHLD signal when 41937 processes stop due to this mechanism; however, that is beyond the scope of this volume of 41938 IEEE Std 1003.1-200x. 41939 This volume of IEEE Std 1003.1-200x requires that calls to sigaction( ) that supply a NULL act 41940 argument succeed, even in the case of signals that cannot be caught or ignored (that is, SIGKILL 41941 or SIGSTOP). The System V signal( ) and BSD sigvec( ) functions return [EINVAL] in these cases 41942 and, in this respect, their behavior varies from sigaction( ). 41943 This volume of IEEE Std 1003.1-200x requires that sigaction( ) properly save and restore a signal 41944 action set up by the ISO C standard signal( ) function. However, there is no guarantee that the 41945 reverse is true, nor could there be given the greater amount of information conveyed by the 41946 sigaction structure. Because of this, applications should avoid using both functions for the same 41947 signal in the same process. Since this cannot always be avoided in case of general-purpose 41948 library routines, they should always be implemented with sigaction( ). 41949 It was intended that the signal( ) function should be implementable as a library routine using 41950 sigaction( ). 1842 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigaction( ) 41951 The POSIX Realtime Extension extends the sigaction( ) function as specified by the POSIX.1-1990 41952 standard to allow the application to request on a per-signal basis via an additional signal action 41953 flag that the extra parameters, including the application-defined signal value, if any, be passed 41954 to the signal-catching function. 41955 FUTURE DIRECTIONS 41956 None. | 41957 SEE ALSO 41958 Section 2.4 (on page 478), bsd_signal( ), kill( ), _longjmp( ), longjmp( ), raise( ), semget( ), sem_init( ), 41959 sem_open( ), sigaddset( ), sigaltstack( ), sigdelset( ), sigemptyset( ), sigfillset( ), sigismember( ), signal( ), 41960 sigprocmask( ), sigsuspend( ), wait( ), waitid( ), waitpid( ), the Base Definitions volume of 41961 IEEE Std 1003.1-200x, , 41962 CHANGE HISTORY 41963 First released in Issue 3. 41964 Entry included for alignment with the POSIX.1-1988 standard. 41965 Issue 5 41966 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and POSIX 41967 Threads Extension. 41968 In the DESCRIPTION, the second argument to func when SA_SIGINFO is set is no longer 41969 permitted to be NULL, and the description of permitted siginfo_t contents is expanded by 41970 reference to . 41971 Since the X/OPEN UNIX Extension functionality is now folded into the BASE, the [ENOTSUP] | 41972 error is deleted. 41973 Issue 6 41974 The Open Group Corrigendum U028/7 is applied. In the paragraph entitled ``Signal Effects on 41975 Other Functions'', a reference to sigpending( ) is added. 41976 In the DESCRIPTION, the text ``Signal Generation and Delivery'', ``Signal Actions'', and ``Signal | 41977 Effects on Other Functions'' are moved to a separate section of this volume of | 41978 IEEE Std 1003.1-200x. 41979 Text describing functionality from the Realtime Signals option is marked. 41980 The following changes are made for alignment with the ISO POSIX-1: 1996 standard: 41981 * The [ENOTSUP] error condition is added. 41982 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 41983 The restrict keyword is added to the sigaction( ) prototype for alignment with the 41984 ISO/IEC 9899: 1999 standard. 41985 References to the wait3( ) function are removed. | 41986 The SYNOPSIS is marked CX since the presence of this function in the header is an | 41987 extension over the ISO C standard. | System Interfaces, Issue 6 1843 sigaddset( ) System Interfaces 41988 NAME 41989 sigaddset - add a signal to a signal set 41990 SYNOPSIS 41991 CX #include | 41992 int sigaddset(sigset_t *set, int signo); 41993 | 41994 DESCRIPTION 41995 The sigaddset( ) function adds the individual signal specified by the signo to the signal set pointed 41996 to by set. 41997 Applications shall call either sigemptyset( ) or sigfillset( ) at least once for each object of type 41998 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 41999 nonetheless supplied as an argument to any of pthread_sigmask( ), sigaction( ), sigaddset( ), 42000 sigdelset( ), sigismember( ), sigpending( ), sigprocmask( ), sigsuspend( ), sigtimedwait( ), sigwait( ), or 42001 sigwaitinfo ( ), the results are undefined. 42002 RETURN VALUE 42003 Upon successful completion, sigaddset( ) shall return 0; otherwise, it shall return -1 and set errno 42004 to indicate the error. 42005 ERRORS 42006 The sigaddset( ) function may fail if: 42007 [EINVAL] The value of the signo argument is an invalid or unsupported signal number. 42008 EXAMPLES 42009 None. 42010 APPLICATION USAGE 42011 None. 42012 RATIONALE 42013 None. 42014 FUTURE DIRECTIONS 42015 None. 42016 SEE ALSO 42017 Section 2.4 (on page 478), sigaction( ), sigdelset( ), sigemptyset( ), sigfillset( ), sigismember( ), 42018 sigpending( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42019 42020 CHANGE HISTORY 42021 First released in Issue 3. 42022 Entry included for alignment with the POSIX.1-1988 standard. 42023 Issue 5 42024 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 42025 previous issues. 42026 Issue 6 42027 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 42028 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42029 extension over the ISO C standard. | 1844 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigaltstack( ) 42030 NAME 42031 sigaltstack - set and get signal alternate stack context 42032 SYNOPSIS 42033 XSI #include 42034 int sigaltstack(const stack_t *restrict ss, stack_t *restrict oss); 42035 42036 DESCRIPTION 42037 The sigaltstack( ) function allows a process to define and examine the state of an alternate stack 42038 for signal handlers. Signals that have been explicitly declared to execute on the alternate stack 42039 shall be delivered on the alternate stack. 42040 If ss is not a null pointer, it points to a stack_t structure that specifies the alternate signal stack 42041 that shall take effect upon return from sigaltstack( ). The ss_flags member specifies the new stack 42042 state. If it is set to SS_DISABLE, the stack is disabled and ss_sp and ss_size are ignored. 42043 Otherwise, the stack shall be enabled, and the ss_sp and ss_size members specify the new address 42044 and size of the stack. 42045 The range of addresses starting at ss_sp up to but not including ss_sp+ss_size, is available to the 42046 implementation for use as the stack. This function makes no assumptions regarding which end 42047 is the stack base and in which direction the stack grows as items are pushed. 42048 If oss is not a null pointer, on successful completion it shall point to a stack_t structure that 42049 specifies the alternate signal stack that was in effect prior to the call to sigaltstack( ). The ss_sp 42050 and ss_size members specify the address and size of that stack. The ss_flags member specifies the 42051 stack's state, and may contain one of the following values: 42052 SS_ONSTACK The process is currently executing on the alternate signal stack. Attempts to 42053 modify the alternate signal stack while the process is executing on it fail. This 42054 flag shall not be modified by processes. 42055 SS_DISABLE The alternate signal stack is currently disabled. 42056 The value SIGSTKSZ is a system default specifying the number of bytes that would be used to 42057 cover the usual case when manually allocating an alternate stack area. The value MINSIGSTKSZ 42058 is defined to be the minimum stack size for a signal handler. In computing an alternate stack 42059 size, a program should add that amount to its stack requirements to allow for the system 42060 implementation overhead. The constants SS_ONSTACK, SS_DISABLE, SIGSTKSZ, and 42061 MINSIGSTKSZ are defined in . 42062 After a successful call to one of the exec functions, there are no alternate signal stacks in the new 42063 process image. 42064 In some implementations, a signal (whether or not indicated to execute on the alternate stack) 42065 shall always execute on the alternate stack if it is delivered while another signal is being caught 42066 using the alternate stack. 42067 Use of this function by library threads that are not bound to kernel-scheduled entities results in 42068 undefined behavior. 42069 RETURN VALUE 42070 Upon successful completion, sigaltstack( ) shall return 0; otherwise, it shall return -1 and set errno 42071 to indicate the error. System Interfaces, Issue 6 1845 sigaltstack( ) System Interfaces 42072 ERRORS 42073 The sigaltstack( ) function shall fail if: 42074 [EINVAL] The ss argument is not a null pointer, and the ss_flags member pointed to by ss 42075 contains flags other than SS_DISABLE. 42076 [ENOMEM] The size of the alternate stack area is less than MINSIGSTKSZ. 42077 [EPERM] An attempt was made to modify an active stack. 42078 EXAMPLES 42079 Allocating Memory for an Alternate Stack 42080 The following example illustrates a method for allocating memory for an alternate stack. 42081 #include 42082 ... 42083 if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) 42084 /* Error return. */ 42085 sigstk.ss_size = SIGSTKSZ; 42086 sigstk.ss_flags = 0; 42087 if (sigaltstack(&sigstk,(stack_t *)0) < 0) 42088 perror("sigaltstack"); 42089 APPLICATION USAGE 42090 On some implementations, stack space is automatically extended as needed. On those 42091 implementations, automatic extension is typically not available for an alternate stack. If the stack 42092 overflows, the behavior is undefined. 42093 RATIONALE 42094 None. 42095 FUTURE DIRECTIONS 42096 None. 42097 SEE ALSO 42098 Section 2.4 (on page 478), sigaction( ), sigsetjmp( ), the Base Definitions volume of 42099 IEEE Std 1003.1-200x, 42100 CHANGE HISTORY 42101 First released in Issue 4, Version 2. 42102 Issue 5 42103 Moved from X/OPEN UNIX extension to BASE. 42104 The last sentence of the DESCRIPTION was included as an APPLICATION USAGE note in 42105 previous issues. 42106 Issue 6 42107 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 42108 The restrict keyword is added to the sigaltstack( ) prototype for alignment with the 42109 ISO/IEC 9899: 1999 standard. 1846 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigdelset( ) 42110 NAME 42111 sigdelset - delete a signal from a signal set 42112 SYNOPSIS 42113 CX #include | 42114 int sigdelset(sigset_t *set, int signo); 42115 | 42116 DESCRIPTION 42117 The sigdelset( ) function deletes the individual signal specified by signo from the signal set 42118 pointed to by set. 42119 Applications should call either sigemptyset( ) or sigfillset( ) at least once for each object of type 42120 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 42121 nonetheless supplied as an argument to any of pthread_sigmask( ), sigaction( ), sigaddset( ), 42122 sigdelset( ), sigismember( ), sigpending( ), sigprocmask( ), sigsuspend( ), sigtimedwait( ), sigwait( ), or 42123 sigwaitinfo ( ), the results are undefined. 42124 RETURN VALUE 42125 Upon successful completion, sigdelset( ) shall return 0; otherwise, it shall return -1 and set errno 42126 to indicate the error. 42127 ERRORS 42128 The sigdelset( ) function may fail if: 42129 [EINVAL] The signo argument is not a valid signal number, or is an unsupported signal 42130 number. 42131 EXAMPLES 42132 None. 42133 APPLICATION USAGE 42134 None. 42135 RATIONALE 42136 None. 42137 FUTURE DIRECTIONS 42138 None. 42139 SEE ALSO 42140 Section 2.4 (on page 478), sigaction( ), sigaddset( ), sigemptyset( ), sigfillset( ), sigismember( ), 42141 sigpending( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42142 42143 CHANGE HISTORY 42144 First released in Issue 3. 42145 Entry included for alignment with the POSIX.1-1988 standard. 42146 Issue 5 42147 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 42148 previous issues. | 42149 Issue 6 | 42150 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42151 extension over the ISO C standard. | System Interfaces, Issue 6 1847 sigemptyset( ) System Interfaces 42152 NAME 42153 sigemptyset - initialize and empty a signal set 42154 SYNOPSIS 42155 CX #include | 42156 int sigemptyset(sigset_t *set); 42157 | 42158 DESCRIPTION 42159 The sigemptyset( ) function initializes the signal set pointed to by set, such that all signals defined 42160 in IEEE Std 1003.1-200x are excluded. 42161 RETURN VALUE 42162 Upon successful completion, sigemptyset( ) shall return 0; otherwise, it shall return -1 and set 42163 errno to indicate the error. 42164 ERRORS 42165 No errors are defined. 42166 EXAMPLES 42167 None. 42168 APPLICATION USAGE 42169 None. 42170 RATIONALE 42171 The implementation of the sigemptyset( ) (or sigfillset( )) function could quite trivially clear (or 42172 set) all the bits in the signal set. Alternatively, it would be reasonable to initialize part of the 42173 structure, such as a version field, to permit binary-compatibility between releases where the size 42174 of the set varies. For such reasons, either sigemptyset( ) or sigfillset( ) must be called prior to any 42175 other use of the signal set, even if such use is read-only (for example, as an argument to 42176 sigpending( )). This function is not intended for dynamic allocation. 42177 The sigfillset( ) and sigemptyset( ) functions require that the resulting signal set include (or 42178 exclude) all the signals defined in this volume of IEEE Std 1003.1-200x. Although it is outside the 42179 scope of this volume of IEEE Std 1003.1-200x to place this requirement on signals that are 42180 implemented as extensions, it is recommended that implementation-defined signals also be 42181 affected by these functions. However, there may be a good reason for a particular signal not to 42182 be affected. For example, blocking or ignoring an implementation-defined signal may have 42183 undesirable side effects, whereas the default action for that signal is harmless. In such a case, it 42184 would be preferable for such a signal to be excluded from the signal set returned by sigfillset( ). 42185 In early proposals there was no distinction between invalid and unsupported signals (the names 42186 of optional signals that were not supported by an implementation were not defined by that 42187 implementation). The [EINVAL] error was thus specified as a required error for invalid signals. 42188 With that distinction, it is not necessary to require implementations of these functions to 42189 determine whether an optional signal is actually supported, as that could have a significant 42190 performance impact for little value. The error could have been required for invalid signals and 42191 optional for unsupported signals, but this seemed unnecessarily complex. Thus, the error is 42192 optional in both cases. 42193 FUTURE DIRECTIONS 42194 None. 1848 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigemptyset( ) 42195 SEE ALSO 42196 Section 2.4 (on page 478), sigaction( ), sigaddset( ), sigdelset( ), sigfillset( ), sigismember( ), 42197 sigpending( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42198 42199 CHANGE HISTORY 42200 First released in Issue 3. 42201 Entry included for alignment with the POSIX.1-1988 standard. | 42202 Issue 6 | 42203 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42204 extension over the ISO C standard. | System Interfaces, Issue 6 1849 sigfillset( ) System Interfaces 42205 NAME 42206 sigfillset - initialize and fill a signal set 42207 SYNOPSIS 42208 CX #include | 42209 int sigfillset(sigset_t *set); 42210 | 42211 DESCRIPTION 42212 The sigfillset( ) function shall initialize the signal set pointed to by set, such that all signals 42213 defined in this volume of IEEE Std 1003.1-200x are included. 42214 RETURN VALUE 42215 Upon successful completion, sigfillset( ) shall return 0; otherwise, it shall return -1 and set errno 42216 to indicate the error. 42217 ERRORS 42218 No errors are defined. 42219 EXAMPLES 42220 None. 42221 APPLICATION USAGE 42222 None. 42223 RATIONALE 42224 Refer to sigemptyset( ) (on page 1848). 42225 FUTURE DIRECTIONS 42226 None. 42227 SEE ALSO 42228 Section 2.4 (on page 478), sigaction( ), sigaddset( ), sigdelset( ), sigemptyset( ), sigismember( ), 42229 sigpending( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42230 42231 CHANGE HISTORY 42232 First released in Issue 3. 42233 Entry included for alignment with the POSIX.1-1988 standard. | 42234 Issue 6 | 42235 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42236 extension over the ISO C standard. | 1850 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sighold( ) 42237 NAME 42238 sighold, sigignore, sigpause, sigrelse, sigset - signal management 42239 SYNOPSIS 42240 XSI #include 42241 int sighold(int sig); 42242 int sigignore(int sig); 42243 int sigpause(int sig); 42244 int sigrelse(int sig); 42245 void (*sigset(int sig, void (*disp)(int)))(int); 42246 42247 DESCRIPTION 42248 Use of any of these functions is unspecified in a multi-threaded process. 42249 The sighold( ), sigignore( ), sigpause( ), sigrelse( ), and sigset( ) functions provide simplified signal 42250 management. 42251 The sigset( ) function shall modify signal dispositions. The sig argument specifies the signal, | 42252 which may be any signal except SIGKILL and SIGSTOP. The disp argument specifies the signal's 42253 disposition, which may be SIG_DFL, SIG_IGN, or the address of a signal handler. If sigset( ) is 42254 used, and disp is the address of a signal handler, the system shall add sig to the calling process' 42255 signal mask before executing the signal handler; when the signal handler returns, the system 42256 shall restore the calling process' signal mask to its state prior to the delivery of the signal. In 42257 addition, if sigset( ) is used, and disp is equal to SIG_HOLD, sig shall be added to the calling 42258 process' signal mask and sig's disposition shall remain unchanged. If sigset( ) is used, and disp is 42259 not equal to SIG_HOLD, sig shall be removed from the calling process' signal mask. 42260 The sighold( ) function shall add sig to the calling process' signal mask. | 42261 The sigrelse( ) function shall remove sig from the calling process' signal mask. | 42262 The sigignore( ) function shall set the disposition of sig to SIG_IGN. | 42263 The sigpause( ) function shall remove sig from the calling process' signal mask and suspend the | 42264 calling process until a signal is received. The sigpause( ) function shall restore the process' signal | 42265 mask to its original state before returning. | 42266 If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the calling processes 42267 shall not be transformed into zombie processes when they terminate. If the calling process 42268 subsequently waits for its children, and the process has no unwaited-for children that were 42269 transformed into zombie processes, it shall block until all of its children terminate, and wait( ), 42270 waitid( ), and waitpid( ) shall fail and set errno to [ECHILD]. 42271 RETURN VALUE 42272 Upon successful completion, sigset( ) shall return SIG_HOLD if the signal had been blocked and 42273 the signal's previous disposition if it had not been blocked. Otherwise, SIG_ERR shall be 42274 returned and errno set to indicate the error. 42275 The sigpause( ) function shall suspend execution of the thread until a signal is received, 42276 whereupon it shall return -1 and set errno to [EINTR]. 42277 For all other functions, upon successful completion, 0 shall be returned. Otherwise, -1 shall be 42278 returned and errno set to indicate the error. System Interfaces, Issue 6 1851 sighold( ) System Interfaces 42279 ERRORS 42280 These functions shall fail if: 42281 [EINVAL] The sig argument is an illegal signal number. 42282 The sigset( ) and sigignore( ) functions shall fail if: 42283 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a 42284 signal that cannot be ignored. 42285 EXAMPLES 42286 None. 42287 APPLICATION USAGE 42288 The sigaction( ) function provides a more comprehensive and reliable mechanism for controlling 42289 signals; new applications should use sigaction( ) rather than sigset( ). 42290 The sighold( ) function, in conjunction with sigrelse( ) or sigpause( ), may be used to establish 42291 critical regions of code that require the delivery of a signal to be temporarily deferred. 42292 The sigsuspend( ) function should be used in preference to sigpause( ) for broader portability. 42293 RATIONALE 42294 None. 42295 FUTURE DIRECTIONS 42296 None. 42297 SEE ALSO 42298 Section 2.4 (on page 478), exec, pause( ), sigaction( ), signal( ), sigsuspend( ), waitid( ), the Base 42299 Definitions volume of IEEE Std 1003.1-200x, 42300 CHANGE HISTORY 42301 First released in Issue 4 Version 2. 42302 Issue 5 42303 Moved from X/OPEN UNIX extension to BASE. 42304 The DESCRIPTION is updated to indicate that the sigpause( ) function restores the process' 42305 signal mask to its original state before returning. 42306 The RETURN VALUE section is updated to indicate that the sigpause( ) function suspends 42307 execution of the process until a signal is received, whereupon it returns -1 and sets errno to 42308 [EINTR]. 42309 Issue 6 42310 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 42311 References to the wait3( ) function are removed. 42312 The XSI functions are split out into their own reference page. 1852 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigignore( ) 42313 NAME 42314 sigignore - signal management 42315 SYNOPSIS 42316 XSI #include 42317 int sigignore(int sig); 42318 42319 DESCRIPTION 42320 Refer to sighold( ). System Interfaces, Issue 6 1853 siginterrupt( ) System Interfaces 42321 NAME 42322 siginterrupt - allow signals to interrupt functions 42323 SYNOPSIS 42324 XSI #include 42325 int siginterrupt(int sig, int flag); 42326 42327 DESCRIPTION 42328 The siginterrupt( ) function shall change the restart behavior when a function is interrupted by | 42329 the specified signal. The function siginterrupt(sig, flag) has an effect as if implemented as: 42330 siginterrupt(int sig, int flag) { 42331 int ret; 42332 struct sigaction act; 42333 (void) sigaction(sig, NULL, &act); 42334 if (flag) 42335 act.sa_flags &= SA_RESTART; 42336 else 42337 act.sa_flags |= SA_RESTART; 42338 ret = sigaction(sig, &act, NULL); 42339 return ret; 42340 } 42341 RETURN VALUE 42342 Upon successful completion, siginterrupt( ) shall return 0; otherwise, -1 shall be returned and 42343 errno set to indicate the error. 42344 ERRORS 42345 The siginterrupt( ) function shall fail if: 42346 [EINVAL] The sig argument is not a valid signal number. 42347 EXAMPLES 42348 None. 42349 APPLICATION USAGE 42350 The siginterrupt( ) function supports programs written to historical system interfaces. A | 42351 conforming application, when being written or rewritten, should use sigaction( ) with the | 42352 SA_RESTART flag instead of siginterrupt( ). 42353 RATIONALE 42354 None. 42355 FUTURE DIRECTIONS 42356 None. 42357 SEE ALSO 42358 Section 2.4 (on page 478), sigaction( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42359 42360 CHANGE HISTORY 42361 First released in Issue 4, Version 2. 1854 Technical Standard (2001) (Draft April 16, 2001) System Interfaces siginterrupt( ) 42362 Issue 5 42363 Moved from X/OPEN UNIX extension to BASE. System Interfaces, Issue 6 1855 sigismember( ) System Interfaces 42364 NAME 42365 sigismember - test for a signal in a signal set 42366 SYNOPSIS 42367 CX #include | 42368 int sigismember(const sigset_t *set, int signo); 42369 | 42370 DESCRIPTION 42371 The sigismember( ) function shall test whether the signal specified by signo is a member of the set 42372 pointed to by set. 42373 Applications should call either sigemptyset( ) or sigfillset( ) at least once for each object of type 42374 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 42375 nonetheless supplied as an argument to any of pthread_sigmask( ), sigaction( ), sigaddset( ), 42376 sigdelset( ), sigismember( ), sigpending( ), sigprocmask( ), sigsuspend( ), sigtimedwait( ), sigwait( ), or 42377 sigwaitinfo ( ), the results are undefined. 42378 RETURN VALUE 42379 Upon successful completion, sigismember( ) shall return 1 if the specified signal is a member of 42380 the specified set, or 0 if it is not. Otherwise, it shall return -1 and set errno to indicate the error. 42381 ERRORS 42382 The sigismember( ) function may fail if: 42383 [EINVAL] The signo argument is not a valid signal number, or is an unsupported signal 42384 number. 42385 EXAMPLES 42386 None. 42387 APPLICATION USAGE 42388 None. 42389 RATIONALE 42390 None. 42391 FUTURE DIRECTIONS 42392 None. 42393 SEE ALSO 42394 Section 2.4 (on page 478), sigaction( ), sigaddset( ), sigdelset( ), sigfillset( ), sigemptyset( ), 42395 sigpending( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42396 42397 CHANGE HISTORY 42398 First released in Issue 3. 42399 Entry included for alignment with the POSIX.1-1988 standard. 42400 Issue 5 42401 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 42402 previous issues. | 42403 Issue 6 | 42404 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42405 extension over the ISO C standard. | 1856 Technical Standard (2001) (Draft April 16, 2001) System Interfaces siglongjmp( ) 42406 NAME 42407 siglongjmp - non-local goto with signal handling 42408 SYNOPSIS 42409 CX #include | 42410 void siglongjmp(sigjmp_buf env, int val); 42411 | 42412 DESCRIPTION 42413 The siglongjmp( ) function shall be equivalent to the longjmp( ) function, except as follows: 42414 * References to setjmp( ) shall be equivalent to sigsetjmp( ). 42415 * The siglongjmp( ) function shall restore the saved signal mask if and only if the env argument 42416 was initialized by a call to sigsetjmp( ) with a non-zero savemask argument. 42417 RETURN VALUE 42418 After siglongjmp( ) is completed, program execution shall continue as if the corresponding 42419 invocation of sigsetjmp( ) had just returned the value specified by val. The siglongjmp( ) function 42420 shall not cause sigsetjmp( ) to return 0; if val is 0, sigsetjmp( ) shall return the value 1. 42421 ERRORS 42422 No errors are defined. 42423 EXAMPLES 42424 None. 42425 APPLICATION USAGE 42426 The distinction between setjmp( ) or longjmp( ) and sigsetjmp( ) or siglongjmp( ) is only significant 42427 for programs which use sigaction( ), sigprocmask( ), or sigsuspend( ). 42428 RATIONALE 42429 None. 42430 FUTURE DIRECTIONS 42431 None. 42432 SEE ALSO 42433 longjmp( ), setjmp( ), sigprocmask( ), sigsetjmp( ), sigsuspend( ), the Base Definitions volume of 42434 IEEE Std 1003.1-200x, 42435 CHANGE HISTORY 42436 First released in Issue 3. 42437 Entry included for alignment with the ISO POSIX-1 standard. 42438 Issue 5 42439 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 42440 Issue 6 42441 The DESCRIPTION is rewritten in terms of longjmp( ). | 42442 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42443 extension over the ISO C standard. | System Interfaces, Issue 6 1857 signal( ) System Interfaces 42444 NAME 42445 signal - signal management 42446 SYNOPSIS 42447 #include 42448 void (*signal(int sig, void (*func)(int)))(int); 42449 DESCRIPTION 42450 CX The functionality described on this reference page is aligned with the ISO C standard. Any 42451 conflict between the requirements described here and the ISO C standard is unintentional. This 42452 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 42453 CX Use of this function is unspecified in a multi-threaded process. 42454 The signal( ) function chooses one of three ways in which receipt of the signal number sig is to be 42455 subsequently handled. If the value of func is SIG_DFL, default handling for that signal shall 42456 occur. If the value of func is SIG_IGN, the signal shall be ignored. Otherwise, the application 42457 shall ensure that func points to a function to be called when that signal occurs. An invocation of 42458 such a function because of a signal, or (recursively) of any further functions called by that 42459 invocation (other than functions in the standard library), is called a ``signal handler''. 42460 When a signal occurs, and func points to a function, it is implementation-defined whether the 42461 equivalent of a: 42462 signal(sig, SIG_DFL); 42463 is executed or the implementation prevents some implementation-defined set of signals (at least 42464 including sig) from occurring until the current signal handling has completed. (If the value of sig 42465 is SIGILL, the implementation may alternatively define that no action is taken.) Next the 42466 equivalent of: 42467 (*func)(sig); 42468 is executed. If and when the function returns, if the value of sig was SIGFPE, SIGILL, or 42469 SIGSEGV or any other implementation-defined value corresponding to a computational 42470 exception, the behavior is undefined. Otherwise, the program shall resume execution at the 42471 CX point it was interrupted. If the signal occurs as the result of calling the abort( ), raise( ), kill( ), | 42472 pthread_kill ( ), or sigqueue( )function, the signal handler shall not call the raise( ) function. | 42473 CX If the signal occurs other than as the result of calling abort( ), raise( ), kill( ), pthread_kill ( ), or | 42474 sigqueue( ), the behavior is undefined if the signal handler refers to any object with static storage | 42475 duration other than by assigning a value to an object declared as volatile sig_atomic_t, or if the 42476 signal handler calls any function in the standard library other than one of the functions listed in 42477 Section 2.4 (on page 478). Furthermore, if such a call fails, the value of errno is unspecified. | 42478 At program start-up, the equivalent of: 42479 signal(sig, SIG_IGN); 42480 is executed for some signals, and the equivalent of: 42481 signal(sig, SIG_DFL); 42482 CX is executed for all other signals (see exec). 42483 RETURN VALUE 42484 If the request can be honored, signal( ) shall return the value of func for the most recent call to 42485 signal( ) for the specified signal sig. Otherwise, SIG_ERR shall be returned and a positive value 42486 shall be stored in errno. 1858 Technical Standard (2001) (Draft April 16, 2001) System Interfaces signal( ) 42487 ERRORS 42488 The signal( ) function shall fail if: 42489 CX [EINVAL] The sig argument is not a valid signal number or an attempt is made to catch a 42490 signal that cannot be caught or ignore a signal that cannot be ignored. 42491 The signal( ) function may fail if: 42492 CX [EINVAL] An attempt was made to set the action to SIG_DFL for a signal that cannot be 42493 caught or ignored (or both). 42494 EXAMPLES 42495 None. 42496 APPLICATION USAGE 42497 The sigaction( ) function provides a more comprehensive and reliable mechanism for controlling 42498 signals; new applications should use sigaction( ) rather than signal( ). 42499 RATIONALE 42500 None. 42501 FUTURE DIRECTIONS 42502 None. 42503 SEE ALSO 42504 Section 2.4 (on page 478), exec, pause( ), sigaction( ), sigsuspend( ), waitid( ), the Base Definitions 42505 volume of IEEE Std 1003.1-200x, 42506 CHANGE HISTORY 42507 First released in Issue 1. Derived from Issue 1 of the SVID. 42508 Issue 5 42509 Moved from X/OPEN UNIX extension to BASE. 42510 The DESCRIPTION is updated to indicate that the sigpause( ) function restores the process' 42511 signal mask to its original state before returning. 42512 The RETURN VALUE section is updated to indicate that the sigpause( ) function suspends 42513 execution of the process until a signal is received, whereupon it returns -1 and sets errno to 42514 [EINTR]. 42515 Issue 6 42516 Extensions beyond the ISO C standard are now marked. 42517 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 42518 The DESCRIPTION is updated for alignment with the ISO/IEC 9899: 1999 standard. 42519 References to the wait3( ) function are removed. 42520 The sighold( ), sigignore( ), sigrelse( ), and sigset( ) functions are split out onto their own reference 42521 page. System Interfaces, Issue 6 1859 signbit( ) System Interfaces 42522 NAME 42523 signbit - test sign 42524 SYNOPSIS 42525 #include 42526 int signbit(real-floating x); 42527 DESCRIPTION 42528 CX The functionality described on this reference page is aligned with the ISO C standard. Any 42529 conflict between the requirements described here and the ISO C standard is unintentional. This 42530 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 42531 The signbit( ) macro shall determine whether the sign of its argument value is negative. NaNs, 42532 zeros, and infinities have a sign bit. 42533 RETURN VALUE 42534 The signbit( ) macro shall return a non-zero value if and only if the sign of its argument value is 42535 negative. 42536 ERRORS 42537 No errors are defined. 42538 EXAMPLES 42539 None. 42540 APPLICATION USAGE 42541 None. 42542 RATIONALE 42543 None. 42544 FUTURE DIRECTIONS 42545 None. 42546 SEE ALSO 42547 fpclassify( ), isfinite( ), isinf( ), isnan( ), isnormal( ), the Base Definitions volume of 42548 IEEE Std 1003.1-200x, 42549 CHANGE HISTORY 42550 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1860 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigpause( ) 42551 NAME 42552 sigpause - remove a signal from the signal mask and suspend the thread 42553 SYNOPSIS 42554 XSI #include 42555 int sigpause(int sig); 42556 42557 DESCRIPTION 42558 Refer to sighold( ). System Interfaces, Issue 6 1861 sigpending( ) System Interfaces 42559 NAME 42560 sigpending - examine pending signals 42561 SYNOPSIS 42562 CX #include | 42563 int sigpending(sigset_t *set); 42564 | 42565 DESCRIPTION 42566 The sigpending( ) function shall store, in the location referenced by the set argument, the set of 42567 signals that are blocked from delivery to the calling thread and that are pending on the process 42568 or the calling thread. 42569 RETURN VALUE 42570 Upon successful completion, sigpending( ) shall return 0; otherwise, -1 shall be returned and 42571 errno set to indicate the error. 42572 ERRORS 42573 No errors are defined. 42574 EXAMPLES 42575 None. 42576 APPLICATION USAGE 42577 None. 42578 RATIONALE 42579 None. 42580 FUTURE DIRECTIONS 42581 None. 42582 SEE ALSO 42583 sigaddset( ), sigdelset( ), sigemptyset( ), sigfillset( ), sigismember( ), sigprocmask( ), the Base Definitions 42584 volume of IEEE Std 1003.1-200x, 42585 CHANGE HISTORY 42586 First released in Issue 3. 42587 Issue 5 42588 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. | 42589 Issue 6 | 42590 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42591 extension over the ISO C standard. | 1862 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigprocmask( ) 42592 NAME 42593 sigprocmask - examine and change blocked signals 42594 SYNOPSIS 42595 CX #include | 42596 int sigprocmask(int how, const sigset_t *restrict set, 42597 sigset_t *restrict oset); 42598 | 42599 DESCRIPTION 42600 Refer to pthread_sigmask( ). System Interfaces, Issue 6 1863 sigqueue( ) System Interfaces 42601 NAME 42602 sigqueue - queue a signal to a process (REALTIME) 42603 SYNOPSIS 42604 RTS #include 42605 int sigqueue(pid_t pid, int signo, const union sigval value); 42606 42607 DESCRIPTION 42608 The sigqueue( ) function shall cause the signal specified by signo to be sent with the value 42609 specified by value to the process specified by pid. If signo is zero (the null signal), error checking 42610 is performed but no signal is actually sent. The null signal can be used to check the validity of 42611 pid. 42612 The conditions required for a process to have permission to queue a signal to another process 42613 are the same as for the kill( ) function. 42614 The sigqueue( ) function shall return immediately. If SA_SIGINFO is set for signo and if the 42615 resources were available to queue the signal, the signal shall be queued and sent to the receiving 42616 process. If SA_SIGINFO is not set for signo, then signo shall be sent at least once to the receiving 42617 process; it is unspecified whether value shall be sent to the receiving process as a result of this 42618 call. 42619 If the value of pid causes signo to be generated for the sending process, and if signo is not blocked 42620 for the calling thread and if no other thread has signo unblocked or is waiting in a sigwait( ) 42621 function for signo, either signo or at least the pending, unblocked signal shall be delivered to the 42622 calling thread before the sigqueue( ) function returns. Should any multiple pending signals in the 42623 range SIGRTMIN to SIGRTMAX be selected for delivery, it shall be the lowest numbered one. 42624 The selection order between realtime and non-realtime signals, or between multiple pending 42625 non-realtime signals, is unspecified. 42626 RETURN VALUE 42627 Upon successful completion, the specified signal shall have been queued, and the sigqueue( ) 42628 function shall return a value of zero. Otherwise, the function shall return a value of -1 and set 42629 errno to indicate the error. 42630 ERRORS 42631 The sigqueue( ) function shall fail if: 42632 [EAGAIN] No resources available to queue the signal. The process has already queued 42633 SIGQUEUE_MAX signals that are still pending at the receiver(s), or a system- 42634 wide resource limit has been exceeded. 42635 [EINVAL] The value of the signo argument is an invalid or unsupported signal number. 42636 [EPERM] The process does not have the appropriate privilege to send the signal to the 42637 receiving process. 42638 [ESRCH] The process pid does not exist. 1864 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigqueue( ) 42639 EXAMPLES 42640 None. 42641 APPLICATION USAGE 42642 None. 42643 RATIONALE 42644 The sigqueue( ) function allows an application to queue a realtime signal to itself or to another 42645 process, specifying the application-defined value. This is common practice in realtime 42646 applications on existing realtime systems. It was felt that specifying another function in the 42647 sig. . . name space already carved out for signals was preferable to extending the interface to 42648 kill( ). 42649 Such a function became necessary when the put/get event function of the message queues was 42650 removed. It should be noted that the sigqueue( ) function implies reduced performance in a 42651 security-conscious implementation as the access permissions between the sender and receiver 42652 have to be checked on each send when the pid is resolved into a target process. Such access 42653 checks were necessary only at message queue open in the previous interface. 42654 The standard developers required that sigqueue( ) have the same semantics with respect to the 42655 null signal as kill( ), and that the same permission checking be used. But because of the difficulty 42656 of implementing the ``broadcast'' semantic of kill( ) (for example, to process groups) and the 42657 interaction with resource allocation, this semantic was not adopted. The sigqueue( ) function 42658 queues a signal to a single process specified by the pid argument. 42659 The sigqueue( ) function can fail if the system has insufficient resources to queue the signal. An 42660 explicit limit on the number of queued signals that a process could send was introduced. While 42661 the limit is ``per-sender'', this volume of IEEE Std 1003.1-200x does not specify that the resources 42662 be part of the state of the sender. This would require either that the sender be maintained after 42663 exit until all signals that it had sent to other processes were handled or that all such signals that 42664 had not yet been acted upon be removed from the queue(s) of the receivers. This volume of 42665 IEEE Std 1003.1-200x does not preclude this behavior, but an implementation that allocated 42666 queuing resources from a system-wide pool (with per-sender limits) and that leaves queued 42667 signals pending after the sender exits is also permitted. 42668 FUTURE DIRECTIONS 42669 None. 42670 SEE ALSO 42671 Section 2.8.1 (on page 491), the Base Definitions volume of IEEE Std 1003.1-200x, 42672 CHANGE HISTORY 42673 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the 42674 POSIX Threads Extension. 42675 Issue 6 42676 The sigqueue( ) function is marked as part of the Realtime Signals Extension option. 42677 The [ENOSYS] error condition has been removed as stubs need not be provided if an 42678 implementation does not support the Realtime Signals Extension option. System Interfaces, Issue 6 1865 sigrelse( ) System Interfaces 42679 NAME 42680 sigrelse - remove a signal from signal mask or modify signal disposition 42681 SYNOPSIS 42682 XSI #include 42683 int sigrelse(int sig); 42684 42685 DESCRIPTION 42686 Refer to sighold( ). 1866 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigset( ) 42687 NAME 42688 sigset - signal management | 42689 SYNOPSIS 42690 #include 42691 XSI void (*sigset(int sig, void (*disp)(int)))(int); 42692 42693 DESCRIPTION 42694 Refer to sighold( ). System Interfaces, Issue 6 1867 sigsetjmp( ) System Interfaces 42695 NAME 42696 sigsetjmp - set jump point for a non-local goto 42697 SYNOPSIS 42698 CX #include | 42699 int sigsetjmp(sigjmp_buf env, int savemask); 42700 | 42701 DESCRIPTION 42702 The sigsetjmp( ) function shall be equivalent to the setjmp( ) function, except as follows: 42703 * References to setjmp( ) are equivalent to sigsetjmp( ). 42704 * References to longjmp( ) are equivalent to siglongjmp( ). 42705 * If the value of the savemask argument is not 0, sigsetjmp( ) shall also save the current signal 42706 mask of the calling thread as part of the calling environment. 42707 RETURN VALUE 42708 If the return is from a successful direct invocation, sigsetjmp( ) shall return 0. If the return is from 42709 a call to siglongjmp( ), sigsetjmp( ) shall return a non-zero value. 42710 ERRORS 42711 No errors are defined. 42712 EXAMPLES 42713 None. 42714 APPLICATION USAGE 42715 The distinction between setjmp( )/longjmp( ) and sigsetjmp( )/siglongjmp( ) is only significant for 42716 programs which use sigaction( ), sigprocmask( ), or sigsuspend( ). | 42717 Note that since this function is defined in terms of setjmp( ), if savemask is zero, it is unspecified | 42718 whether the signal mask is saved. | 42719 RATIONALE 42720 The ISO C standard specifies various restrictions on the usage of the setjmp( ) macro in order to 42721 permit implementors to recognize the name in the compiler and not implement an actual 42722 function. These same restrictions apply to the sigsetjmp( ) macro. 42723 There are processors that cannot easily support these calls, but this was not considered a 42724 sufficient reason to exclude them. 42725 4.2 BSD, 4.3 BSD, and XSI-conformant systems provide functions named _setjmp( ) and 42726 _longjmp( ) that, together with setjmp( ) and longjmp( ), provide the same functionality as 42727 sigsetjmp( ) and siglongjmp( ). On those systems, setjmp( ) and longjmp( ) save and restore signal 42728 masks, while _setjmp( ) and _longjmp( ) do not. On System V, Release 3 and in corresponding 42729 issues of the SVID, setjmp( ) and longjmp( ) are explicitly defined not to save and restore signal 42730 masks. In order to permit existing practice in both cases, the relation of setjmp( ) and longjmp( ) to 42731 signal masks is not specified, and a new set of functions is defined instead. 42732 The longjmp( ) and siglongjmp( ) functions operate as in the previous issue provided the matching 42733 setjmp( ) or sigsetjmp( ) has been performed in the same thread. Non-local jumps into contexts 42734 saved by other threads would be at best a questionable practice and were not considered worthy 42735 of standardization. 1868 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigsetjmp( ) 42736 FUTURE DIRECTIONS 42737 None. 42738 SEE ALSO 42739 siglongjmp( ), signal( ), sigprocmask( ), sigsuspend( ), the Base Definitions volume of 42740 IEEE Std 1003.1-200x, 42741 CHANGE HISTORY 42742 First released in Issue 3. 42743 Entry included for alignment with the POSIX.1-1988 standard. 42744 Issue 5 42745 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 42746 Issue 6 42747 The DESCRIPTION is reworded in terms of setjmp( ). | 42748 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42749 extension over the ISO C standard. | System Interfaces, Issue 6 1869 sigsuspend( ) System Interfaces 42750 NAME 42751 sigsuspend - wait for a signal 42752 SYNOPSIS 42753 CX #include | 42754 int sigsuspend(const sigset_t *sigmask); 42755 | 42756 DESCRIPTION 42757 The sigsuspend( ) function shall replace the current signal mask of the calling thread with the set 42758 of signals pointed to by sigmask and then suspend the thread until delivery of a signal whose 42759 action is either to execute a signal-catching function or to terminate the process. This shall not 42760 cause any other signals that may have been pending on the process to become pending on the 42761 thread. 42762 If the action is to terminate the process then sigsuspend( ) shall never return. If the action is to 42763 execute a signal-catching function, then sigsuspend( ) shall return after the signal-catching 42764 function returns, with the signal mask restored to the set that existed prior to the sigsuspend( ) 42765 call. 42766 It is not possible to block signals that cannot be ignored. This is enforced by the system without 42767 causing an error to be indicated. 42768 RETURN VALUE 42769 Since sigsuspend( ) suspends thread execution indefinitely, there is no successful completion 42770 return value. If a return occurs, -1 shall be returned and errno set to indicate the error. 42771 ERRORS 42772 The sigsuspend( ) function shall fail if: 42773 [EINTR] A signal is caught by the calling process and control is returned from the 42774 signal-catching function. 42775 EXAMPLES 42776 None. 42777 APPLICATION USAGE 42778 Normally, at the beginning of a critical code section, a specified set of signals is blocked using 42779 the sigprocmask( ) function. When the thread has completed the critical section and needs to wait 42780 for the previously blocked signal(s), it pauses by calling sigsuspend( ) with the mask that was 42781 returned by the sigprocmask( ) call. 42782 RATIONALE 42783 None. 42784 FUTURE DIRECTIONS 42785 None. 42786 SEE ALSO 42787 Section 2.4 (on page 478), pause( ), sigaction( ), sigaddset( ), sigdelset( ), sigemptyset( ), sigfillset( ), the 42788 Base Definitions volume of IEEE Std 1003.1-200x, 42789 CHANGE HISTORY 42790 First released in Issue 3. 42791 Entry included for alignment with the POSIX.1-1988 standard. 1870 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigsuspend( ) 42792 Issue 5 42793 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 42794 Issue 6 42795 The text in the RETURN VALUE section has been changed from ``suspends process execution'' 42796 to ``suspends thread execution''. This reflects IEEE PASC Interpretation 1003.1c #40. 42797 Text in the APPLICATION USAGE section has been replaced. | 42798 The SYNOPSIS is marked CX since the presence of this function in the header is an | 42799 extension over the ISO C standard. | System Interfaces, Issue 6 1871 sigtimedwait( ) System Interfaces 42800 NAME 42801 sigtimedwait, sigwaitinfo - wait for queued signals (REALTIME) 42802 SYNOPSIS 42803 RTS #include 42804 int sigtimedwait(const sigset_t *restrict set, 42805 siginfo_t *restrict info, 42806 const struct timespec *restrict timeout); 42807 int sigwaitinfo(const sigset_t *restrict set, 42808 siginfo_t *restrict info); 42809 42810 DESCRIPTION 42811 The sigtimedwait( ) function shall be equivalent to sigwaitinfo ( ) except that if none of the signals | 42812 specified by set are pending, sigtimedwait( ) shall wait for the time interval specified in the 42813 timespec structure referenced by timeout. If the timespec structure pointed to by timeout is 42814 zero-valued and if none of the signals specified by set are pending, then sigtimedwait( ) shall 42815 MON return immediately with an error. If timeout is the NULL pointer, the behavior is unspecified. If 42816 the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock shall be used to 42817 measure the time interval specified by the timeout argument. 42818 The sigwaitinfo ( ) function selects the pending signal from the set specified by set. Should any of 42819 multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected, it shall be the 42820 lowest numbered one. The selection order between realtime and non-realtime signals, or 42821 between multiple pending non-realtime signals, is unspecified. If no signal in set is pending at 42822 the time of the call, the calling thread shall be suspended until one or more signals in set become 42823 pending or until it is interrupted by an unblocked, caught signal. 42824 The sigwaitinfo ( ) function shall be equivalent to the sigwait( ) function if the info argument is | 42825 NULL. If the info argument is non-NULL, the sigwaitinfo ( ) function shall be equivalent to | 42826 sigwait( ), except that the selected signal number shall be stored in the si_signo member, and the 42827 cause of the signal shall be stored in the si_code member. If any value is queued to the selected 42828 signal, the first such queued value shall be dequeued and, if the info argument is non-NULL, the 42829 value shall be stored in the si_value member of info. The system resource used to queue the 42830 signal shall be released and returned to the system for other use. If no value is queued, the 42831 content of the si_value member is undefined. If no further signals are queued for the selected 42832 signal, the pending indication for that signal shall be reset. 42833 RETURN VALUE 42834 Upon successful completion (that is, one of the signals specified by set is pending or is 42835 generated) sigwaitinfo ( ) and sigtimedwait( ) shall return the selected signal number. Otherwise, 42836 the function shall return a value of -1 and set errno to indicate the error. 42837 ERRORS 42838 The sigtimedwait( ) function shall fail if: 42839 [EAGAIN] No signal specified by set was generated within the specified timeout period. 42840 The sigtimedwait( ) and sigwaitinfo ( ) functions may fail if: 42841 [EINTR] The wait was interrupted by an unblocked, caught signal. It shall be 42842 documented in system documentation whether this error causes these 42843 functions to fail. 42844 The sigtimedwait( ) function may also fail if: 1872 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigtimedwait( ) 42845 [EINVAL] The timeout argument specified a tv_nsec value less than zero or greater than 42846 or equal to 1 000 million. 42847 An implementation only checks for this error if no signal is pending in set and it is necessary to 42848 wait. 42849 EXAMPLES 42850 None. 42851 APPLICATION USAGE 42852 The sigtimedwait( ) function times out and returns an [EAGAIN] error. Application writers 42853 should note that this is inconsistent with other functions such as pthread_cond_timedwait( ) that 42854 return [ETIMEDOUT]. 42855 RATIONALE 42856 Existing programming practice on realtime systems uses the ability to pause waiting for a 42857 selected set of events and handle the first event that occurs in-line instead of in a signal-handling 42858 function. This allows applications to be written in an event-directed style similar to a state 42859 machine. This style of programming is useful for largescale transaction processing in which the 42860 overall throughput of an application and the ability to clearly track states are more important 42861 than the ability to minimize the response time of individual event handling. 42862 It is possible to construct a signal-waiting macro function out of the realtime signal function 42863 mechanism defined in this volume of IEEE Std 1003.1-200x. However, such a macro has to 42864 include the definition of a generalized handler for all signals to be waited on. A significant 42865 portion of the overhead of handler processing can be avoided if the signal-waiting function is 42866 provided by the kernel. This volume of IEEE Std 1003.1-200x therefore provides two signal- 42867 waiting functions-one that waits indefinitely and one with a timeout-as part of the overall 42868 realtime signal function specification. 42869 The specification of a function with a timeout allows an application to be written that can be 42870 broken out of a wait after a set period of time if no event has occurred. It was argued that setting 42871 a timer event before the wait and recognizing the timer event in the wait would also implement 42872 the same functionality, but at a lower performance level. Because of the performance 42873 degradation associated with the user-level specification of a timer event and the subsequent 42874 cancelation of that timer event after the wait completes for a valid event, and the complexity 42875 associated with handling potential race conditions associated with the user-level method, the 42876 separate function has been included. 42877 Note that the semantics of the sigwaitinfo ( ) function are nearly identical to that of the sigwait( ) 42878 function defined by this volume of IEEE Std 1003.1-200x. The only difference is that sigwaitinfo ( ) 42879 returns the queued signal value in the value argument. The return of the queued value is 42880 required so that applications can differentiate between multiple events queued to the same 42881 signal number. 42882 The two distinct functions are being maintained because some implementations may choose to 42883 implement the POSIX Threads Extension functions and not implement the queued signals 42884 extensions. Note, though, that sigwaitinfo ( ) does not return the queued value if the value 42885 argument is NULL, so the POSIX Threads Extension sigwait( ) function can be implemented as a 42886 macro on sigwaitinfo ( ). 42887 The sigtimedwait( ) function was separated from the sigwaitinfo ( ) function to address concerns 42888 regarding the overloading of the timeout pointer to indicate indefinite wait (no timeout), timed 42889 wait, and immediate return, and concerns regarding consistency with other functions where the 42890 conditional and timed waits were separate functions from the pure blocking function. The 42891 semantics of sigtimedwait( ) are specified such that sigwaitinfo ( ) could be implemented as a 42892 macro with a NULL pointer for timeout. System Interfaces, Issue 6 1873 sigtimedwait( ) System Interfaces 42893 The sigwait functions provide a synchronous mechanism for threads to wait for asynchronously 42894 generated signals. One important question was how many threads that are suspended in a call to 42895 a sigwait( ) function for a signal should return from the call when the signal is sent. Four choices 42896 were considered: 42897 1. Return an error for multiple simultaneous calls to sigwait functions for the same signal. 42898 2. One or more threads return. 42899 3. All waiting threads return. 42900 4. Exactly one thread returns. 42901 Prohibiting multiple calls to sigwait( ) for the same signal was felt to be overly restrictive. The 42902 ``one or more'' behavior made implementation of conforming packages easy at the expense of 42903 forcing POSIX threads clients to protect against multiple simultaneous calls to sigwait( ) in 42904 application code in order to achieve predictable behavior. There was concern that the ``all 42905 waiting threads'' behavior would result in ``signal broadcast storms'', consuming excessive CPU 42906 resources by replicating the signals in the general case. Furthermore, no convincing examples 42907 could be presented that delivery to all was either simpler or more powerful than delivery to one. 42908 Thus, the consensus was that exactly one thread that was suspended in a call to a sigwait 42909 function for a signal should return when that signal occurs. This is not an onerous restriction as: 42910 * A multi-way signal wait can be built from the single-way wait. 42911 * Signals should only be handled by application-level code, as library routines cannot guess 42912 what the application wants to do with signals generated for the entire process. 42913 * Applications can thus arrange for a single thread to wait for any given signal and call any 42914 needed routines upon its arrival. 42915 In an application that is using signals for interprocess communication, signal processing is 42916 typically done in one place. Alternatively, if the signal is being caught so that process cleanup 42917 can be done, the signal handler thread can call separate process cleanup routines for each 42918 portion of the application. Since the application main line started each portion of the application, 42919 it is at the right abstraction level to tell each portion of the application to clean up. 42920 Certainly, there exist programming styles where it is logical to consider waiting for a single 42921 signal in multiple threads. A simple sigwait_multiple( ) routine can be constructed to achieve this 42922 goal. A possible implementation would be to have each sigwait_multiple( ) caller registered as 42923 having expressed interest in a set of signals. The caller then waits on a thread-specific condition 42924 variable. A single server thread calls a sigwait( ) function on the union of all registered signals. 42925 When the sigwait( ) function returns, the appropriate state is set and condition variables are 42926 broadcast. New sigwait_multiple( ) callers may cause the pending sigwait( ) call to be canceled 42927 and reissued in order to update the set of signals being waited for. 42928 FUTURE DIRECTIONS 42929 None. 42930 SEE ALSO 42931 Section 2.8.1 (on page 491), pause( ), pthread_sigmask( ), sigaction( ), sigpending( ), sigsuspend( ), 42932 sigwait( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 42933 CHANGE HISTORY 42934 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the 42935 POSIX Threads Extension. 1874 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigtimedwait( ) 42936 Issue 6 42937 These functions are marked as part of the Realtime Signals Extension option. 42938 The Open Group Corrigendum U035/3 is applied. The SYNOPSIS of the sigwaitinfo ( ) function 42939 has been corrected so that the second argument is of type siginfo_t *. 42940 The [ENOSYS] error condition has been removed as stubs need not be provided if an 42941 implementation does not support the Realtime Signals Extension option. 42942 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that the 42943 CLOCK_MONOTONIC clock, if supported, is used to measure timeout intervals. 42944 The restrict keyword is added to the sigtimedwait( ) and sigwaitinfo ( ) prototypes for alignment 42945 with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1875 sigwait( ) System Interfaces 42946 NAME 42947 sigwait - wait for queued signals 42948 SYNOPSIS 42949 CX #include | 42950 int sigwait(const sigset_t *restrict set, int *restrict sig); 42951 | 42952 DESCRIPTION 42953 The sigwait( ) function shall select a pending signal from set, atomically clear it from the system's 42954 set of pending signals, and return that signal number in the location referenced by sig. If prior to 42955 the call to sigwait( ) there are multiple pending instances of a single signal number, it is 42956 implementation-defined whether upon successful return there are any remaining pending 42957 RTS signals for that signal number. If the implementation supports queued signals and there are 42958 multiple signals queued for the signal number selected, the first such queued signal shall cause a 42959 return from sigwait( ) and the remainder shall remain queued. If no signal in set is pending at the 42960 time of the call, the thread shall be suspended until one or more becomes pending. The signals 42961 defined by set shall have been blocked at the time of the call to sigwait( ); otherwise, the behavior 42962 is undefined. The effect of sigwait( ) on the signal actions for the signals in set is unspecified. 42963 If more than one thread is using sigwait( ) to wait for the same signal, no more than one of these 42964 threads shall return from sigwait( ) with the signal number. Which thread returns from sigwait( ) 42965 if more than a single thread is waiting is unspecified. 42966 RTS Should any of the multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected, it 42967 shall be the lowest numbered one. The selection order between realtime and non-realtime 42968 signals, or between multiple pending non-realtime signals, is unspecified. 42969 RETURN VALUE 42970 Upon successful completion, sigwait( ) shall store the signal number of the received signal at the 42971 location referenced by sig and return zero. Otherwise, an error number shall be returned to 42972 indicate the error. 42973 ERRORS 42974 The sigwait( ) function may fail if: 42975 [EINVAL] The set argument contains an invalid or unsupported signal number. 42976 EXAMPLES 42977 None. 42978 APPLICATION USAGE 42979 None. 42980 RATIONALE 42981 To provide a convenient way for a thread to wait for a signal, this volume of 42982 IEEE Std 1003.1-200x provides the sigwait( ) function. For most cases where a thread has to wait 42983 for a signal, the sigwait( ) function should be quite convenient, efficient, and adequate. 42984 However, requests were made for a lower-level primitive than sigwait( ) and for semaphores that 42985 could be used by threads. After some consideration, threads were allowed to use semaphores 42986 and sem_post( ) was defined to be async-signal and async-cancel-safe. 42987 In summary, when it is necessary for code run in response to an asynchronous signal to notify a 42988 thread, sigwait( ) should be used to handle the signal. Alternatively, if the implementation 42989 provides semaphores, they also can be used, either following sigwait( ) or from within a signal 42990 handling routine previously registered with sigaction( ). 1876 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sigwait( ) 42991 FUTURE DIRECTIONS 42992 None. 42993 SEE ALSO 42994 Section 2.4 (on page 478), Section 2.8.1 (on page 491), pause( ), pthread_sigmask( ), sigaction( ), 42995 sigpending( ), sigsuspend( ), sigwaitinfo ( ), the Base Definitions volume of IEEE Std 1003.1-200x, 42996 , 42997 CHANGE HISTORY 42998 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the 42999 POSIX Threads Extension. 43000 Issue 6 43001 The RATIONALE section is added. 43002 The restrict keyword is added to the sigwait( ) prototype for alignment with the 43003 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1877 sigwaitinfo( ) System Interfaces 43004 NAME 43005 sigwaitinfo - wait for queued signals (REALTIME) 43006 SYNOPSIS 43007 RTS #include 43008 int sigwaitinfo(const sigset_t *restrict set, siginfo_t *restrict info); 43009 43010 DESCRIPTION 43011 Refer to sigtimedwait( ). 1878 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sin( ) 43012 NAME 43013 sin, sinf, sinl - sine function 43014 SYNOPSIS 43015 #include 43016 double sin(double x); 43017 float sinf(float x); 43018 long double sinl(long double x); 43019 DESCRIPTION 43020 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43021 conflict between the requirements described here and the ISO C standard is unintentional. This 43022 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43023 These functions shall compute the sine of their argument x, measured in radians. 43024 An application wishing to check for error situations should set errno to zero and call 43025 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 43026 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 43027 zero, an error has occurred. 43028 RETURN VALUE 43029 Upon successful completion, these functions shall return the sine of x. 43030 MX If x is NaN, a NaN shall be returned. 43031 If x is ±0, x shall be returned. 43032 If x is subnormal, a range error may occur and x should be returned. 43033 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 43034 defined value shall be returned. 43035 ERRORS 43036 These functions shall fail if: 43037 MX Domain Error The x argument is ±Inf. 43038 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 43039 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 43040 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 43041 shall be raised. | 43042 These functions may fail if: 43043 MX Range Error The value of x is subnormal 43044 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 43045 then errno shall be set to [ERANGE]. If the integer expression | 43046 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 43047 floating-point exception shall be raised. | System Interfaces, Issue 6 1879 sin( ) System Interfaces 43048 EXAMPLES 43049 Taking the Sine of a 45-Degree Angle 43050 #include 43051 ... 43052 double radians = 45.0 * M_PI / 180; 43053 double result; 43054 ... 43055 result = sin(radians); 43056 APPLICATION USAGE 43057 These functions may lose accuracy when their argument is near a multiple of or is far from 0.0. 43058 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 43059 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 43060 RATIONALE 43061 None. 43062 FUTURE DIRECTIONS 43063 None. 43064 SEE ALSO 43065 asin( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 43066 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 43067 CHANGE HISTORY 43068 First released in Issue 1. Derived from Issue 1 of the SVID. 43069 Issue 5 43070 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 43071 in previous issues. 43072 Issue 6 43073 The sinf( ) and sinl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 43074 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 43075 revised to align with the ISO/IEC 9899: 1999 standard. 43076 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 43077 marked. 1880 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sinf( ) 43078 NAME 43079 sinf - sine function 43080 SYNOPSIS 43081 #include 43082 float sinf(float x); 43083 DESCRIPTION 43084 Refer to sin( ). System Interfaces, Issue 6 1881 sinh( ) System Interfaces 43085 NAME 43086 sinh, sinhf, sinhl - hyperbolic sine function 43087 SYNOPSIS 43088 #include 43089 double sinh(double x); 43090 float sinhf(float x); 43091 long double sinhl(long double x); 43092 DESCRIPTION 43093 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43094 conflict between the requirements described here and the ISO C standard is unintentional. This 43095 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43096 These functions shall compute the hyperbolic sine of their argument x. 43097 An application wishing to check for error situations should set errno to zero and call 43098 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 43099 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 43100 zero, an error has occurred. 43101 RETURN VALUE 43102 Upon successful completion, these functions shall return the hyperbolic sine of x. 43103 If the result would cause an overflow, a range error shall occur and ±HUGE_VAL, 43104 ±HUGE_VALF, and ±HUGE_VALL (with the same sign as x) shall be returned as appropriate for 43105 the type of the function. 43106 MX If x is NaN, a NaN shall be returned. 43107 If x is ±0, or ±Inf, x shall be returned. 43108 If x is subnormal, a range error may occur and x should be returned. 43109 ERRORS 43110 These functions shall fail if: 43111 Range Error The result would cause an overflow. 43112 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 43113 then errno shall be set to [ERANGE]. If the integer expression | 43114 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 43115 floating-point exception shall be raised. | 43116 These functions may fail if: 43117 MX Range Error The value x is subnormal. 43118 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 43119 then errno shall be set to [ERANGE]. If the integer expression | 43120 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 43121 floating-point exception shall be raised. | 1882 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sinh( ) 43122 EXAMPLES 43123 None. 43124 APPLICATION USAGE 43125 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 43126 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 43127 RATIONALE 43128 None. 43129 FUTURE DIRECTIONS 43130 None. 43131 SEE ALSO 43132 asinh( ), cosh( ), feclearexcept( ), fetestexcept( ), isnan( ), tanh( ), the Base Definitions volume of | 43133 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 43134 43135 CHANGE HISTORY 43136 First released in Issue 1. Derived from Issue 1 of the SVID. 43137 Issue 5 43138 The DESCRIPTION is updated to indicate how an application should check for an error. This 43139 text was previously published in the APPLICATION USAGE section. 43140 Issue 6 43141 The sinhf( ) and sinhl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 43142 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 43143 revised to align with the ISO/IEC 9899: 1999 standard. 43144 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 43145 marked. System Interfaces, Issue 6 1883 sinl( ) System Interfaces 43146 NAME 43147 sinl - sine function 43148 SYNOPSIS 43149 #include 43150 long double sinl(long double x); 43151 DESCRIPTION 43152 Refer to sin( ). 1884 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sleep( ) 43153 NAME 43154 sleep - suspend execution for an interval of time 43155 SYNOPSIS 43156 #include 43157 unsigned sleep(unsigned seconds); 43158 DESCRIPTION 43159 The sleep( ) function shall cause the calling thread to be suspended from execution until either 43160 the number of realtime seconds specified by the argument seconds has elapsed or a signal is 43161 delivered to the calling thread and its action is to invoke a signal-catching function or to 43162 terminate the process. The suspension time may be longer than requested due to the scheduling 43163 of other activity by the system. 43164 If a SIGALRM signal is generated for the calling process during execution of sleep( ) and if the 43165 SIGALRM signal is being ignored or blocked from delivery, it is unspecified whether sleep( ) 43166 returns when the SIGALRM signal is scheduled. If the signal is being blocked, it is also 43167 unspecified whether it remains pending after sleep( ) returns or it is discarded. 43168 If a SIGALRM signal is generated for the calling process during execution of sleep( ), except as a 43169 result of a prior call to alarm( ), and if the SIGALRM signal is not being ignored or blocked from 43170 delivery, it is unspecified whether that signal has any effect other than causing sleep( ) to return. 43171 If a signal-catching function interrupts sleep( ) and examines or changes either the time a 43172 SIGALRM is scheduled to be generated, the action associated with the SIGALRM signal, or 43173 whether the SIGALRM signal is blocked from delivery, the results are unspecified. 43174 If a signal-catching function interrupts sleep( ) and calls siglongjmp( ) or longjmp( ) to restore an 43175 environment saved prior to the sleep( ) call, the action associated with the SIGALRM signal and 43176 the time at which a SIGALRM signal is scheduled to be generated are unspecified. It is also 43177 unspecified whether the SIGALRM signal is blocked, unless the process' signal mask is restored 43178 as part of the environment. 43179 XSI Interactions between sleep( ) and any of setitimer( ), ualarm( ), or usleep( ) are unspecified. 43180 RETURN VALUE 43181 If sleep( ) returns because the requested time has elapsed, the value returned shall be 0. If sleep( ) 43182 returns due to delivery of a signal, the return value shall be the ``unslept'' amount (the requested 43183 time minus the time actually slept) in seconds. 43184 ERRORS 43185 No errors are defined. 43186 EXAMPLES 43187 None. 43188 APPLICATION USAGE 43189 None. 43190 RATIONALE 43191 There are two general approaches to the implementation of the sleep( ) function. One is to use the 43192 alarm( ) function to schedule a SIGALRM signal and then suspend the process waiting for that 43193 signal. The other is to implement an independent facility. This volume of IEEE Std 1003.1-200x 43194 permits either approach. 43195 In order to comply with the requirement that no primitive shall change a process attribute unless 43196 explicitly described by this volume of IEEE Std 1003.1-200x, an implementation using SIGALRM 43197 must carefully take into account any SIGALRM signal scheduled by previous alarm( ) calls, the System Interfaces, Issue 6 1885 sleep( ) System Interfaces 43198 action previously established for SIGALRM, and whether SIGALRM was blocked. If a SIGALRM 43199 has been scheduled before the sleep( ) would ordinarily complete, the sleep( ) must be shortened 43200 to that time and a SIGALRM generated (possibly simulated by direct invocation of the signal- 43201 catching function) before sleep( ) returns. If a SIGALRM has been scheduled after the sleep( ) 43202 would ordinarily complete, it must be rescheduled for the same time before sleep( ) returns. The 43203 action and blocking for SIGALRM must be saved and restored. 43204 Historical implementations often implement the SIGALRM-based version using alarm( ) and 43205 pause( ). One such implementation is prone to infinite hangups, as described in pause( ). Another 43206 such implementation uses the C-language setjmp( ) and longjmp( ) functions to avoid that 43207 window. That implementation introduces a different problem: when the SIGALRM signal 43208 interrupts a signal-catching function installed by the user to catch a different signal, the 43209 longjmp( ) aborts that signal-catching function. An implementation based on sigprocmask( ), 43210 alarm( ), and sigsuspend( ) can avoid these problems. 43211 Despite all reasonable care, there are several very subtle, but detectable and unavoidable, 43212 differences between the two types of implementations. These are the cases mentioned in this 43213 volume of IEEE Std 1003.1-200x where some other activity relating to SIGALRM takes place, and 43214 the results are stated to be unspecified. All of these cases are sufficiently unusual as not to be of 43215 concern to most applications. 43216 See also the discussion of the term realtime in alarm( ). 43217 Since sleep( ) can be implemented using alarm( ), the discussion about alarms occurring early | 43218 under alarm( ) applies to sleep( ) as well. 43219 Application writers should note that the type of the argument seconds and the return value of 43220 sleep( ) is unsigned. That means that a Strictly Conforming POSIX System Interfaces Application 43221 cannot pass a value greater than the minimum guaranteed value for {UINT_MAX}, which the 43222 ISO C standard sets as 65 535, and any application passing a larger value is restricting its 43223 portability. A different type was considered, but historical implementations, including those 43224 with a 16-bit int type, consistently use either unsigned or int. 43225 Scheduling delays may cause the process to return from the sleep( ) function significantly after 43226 the requested time. In such cases, the return value should be set to zero, since the formula 43227 (requested time minus the time actually spent) yields a negative number and sleep( ) returns an 43228 unsigned. 43229 FUTURE DIRECTIONS 43230 None. 43231 SEE ALSO 43232 alarm( ), getitimer( ), nanosleep( ), pause( ), sigaction( ), sigsetjmp( ), ualarm( ), usleep( ), the Base 43233 Definitions volume of IEEE Std 1003.1-200x, 43234 CHANGE HISTORY 43235 First released in Issue 1. Derived from Issue 1 of the SVID. 43236 Issue 5 43237 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 1886 Technical Standard (2001) (Draft April 16, 2001) System Interfaces snprintf( ) 43238 NAME 43239 snprintf - print formatted output 43240 SYNOPSIS 43241 #include 43242 int snprintf(char *restrict s, size_t n, 43243 const char *restrict format, ...); 43244 DESCRIPTION 43245 Refer to fprintf( ). System Interfaces, Issue 6 1887 socket( ) System Interfaces 43246 NAME 43247 socket - create an endpoint for communication 43248 SYNOPSIS 43249 #include 43250 int socket(int domain, int type, int protocol); 43251 DESCRIPTION 43252 The socket( ) function shall create an unbound socket in a communications domain, and return a 43253 file descriptor that can be used in later function calls that operate on sockets. 43254 The socket( ) function takes the following arguments: 43255 domain Specifies the communications domain in which a socket is to be created. 43256 type Specifies the type of socket to be created. 43257 protocol Specifies a particular protocol to be used with the socket. Specifying a protocol 43258 of 0 causes socket( ) to use an unspecified default protocol appropriate for the 43259 requested socket type. 43260 The domain argument specifies the address family used in the communications domain. The 43261 address families supported by the system are implementation-defined. 43262 Symbolic constants that can be used for the domain argument are defined in the 43263 header. 43264 The type argument specifies the socket type, which determines the semantics of communication 43265 over the socket. The following socket types are defined; implementations may specify additional 43266 socket types: 43267 SOCK_STREAM Provides sequenced, reliable, bidirectional, connection-mode byte 43268 streams, and may provide a transmission mechanism for out-of-band 43269 data. 43270 SOCK_DGRAM Provides datagrams, which are connectionless-mode, unreliable messages 43271 of fixed maximum length. 43272 SOCK_SEQPACKET Provides sequenced, reliable, bidirectional, connection-mode 43273 transmission path for records. A record can be sent using one or more 43274 output operations and received using one or more input operations, but a 43275 single operation never transfers part of more than one record. Record 43276 boundaries are visible to the receiver via the MSG_EOR flag. 43277 If the protocol argument is non-zero, it shall specify a protocol that is supported by the address 43278 family. If the protocol argument is zero, the default protocol for this address family and type shall 43279 be used. The protocols supported by the system are implementation-defined. 43280 The process may need to have appropriate privileges to use the socket( ) function or to create 43281 some sockets. 43282 RETURN VALUE 43283 Upon successful completion, socket( ) shall return a non-negative integer, the socket file 43284 descriptor. Otherwise, a value of -1 shall be returned and errno set to indicate the error. 43285 ERRORS 43286 The socket( ) function shall fail if: 43287 [EAFNOSUPPORT] 43288 The implementation does not support the specified address family. 1888 Technical Standard (2001) (Draft April 16, 2001) System Interfaces socket( ) 43289 [EMFILE] No more file descriptors are available for this process. 43290 [ENFILE] No more file descriptors are available for the system. 43291 [EPROTONOSUPPORT] 43292 The protocol is not supported by the address family, or the protocol is not 43293 supported by the implementation. 43294 [EPROTOTYPE] The socket type is not supported by the protocol. 43295 The socket( ) function may fail if: 43296 [EACCES] The process does not have appropriate privileges. 43297 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 43298 [ENOMEM] Insufficient memory was available to fulfill the request. 43299 EXAMPLES 43300 None. 43301 APPLICATION USAGE 43302 The documentation for specific address families specifies which protocols each address family 43303 supports. The documentation for specific protocols specifies which socket types each protocol 43304 supports. 43305 The application can determine whether an address family is supported by trying to create a 43306 socket with domain set to the protocol in question. 43307 RATIONALE 43308 None. 43309 FUTURE DIRECTIONS 43310 None. 43311 SEE ALSO 43312 accept( ), bind( ), connect( ), getsockname( ), getsockopt( ), listen( ), recv( ), recvfrom( ), recvmsg( ), 43313 send( ), sendmsg( ), setsockopt( ), shutdown( ), socketpair( ), the Base Definitions volume of 43314 IEEE Std 1003.1-200x, , 43315 CHANGE HISTORY 43316 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1889 socketpair( ) System Interfaces 43317 NAME 43318 socketpair - create a pair of connected sockets 43319 SYNOPSIS 43320 #include 43321 int socketpair(int domain, int type, int protocol, 43322 int socket_vector[2]); 43323 DESCRIPTION 43324 The socketpair( ) function shall create an unbound pair of connected sockets in a specified domain, 43325 of a specified type, under the protocol optionally specified by the protocol argument. The two 43326 sockets shall be identical. The file descriptors used in referencing the created sockets shall be 43327 returned in socket_vector[0] and socket_vector[1]. 43328 The socketpair( ) function takes the following arguments: 43329 domain Specifies the communications domain in which the sockets are to be created. 43330 type Specifies the type of sockets to be created. 43331 protocol Specifies a particular protocol to be used with the sockets. Specifying a 43332 protocol of 0 causes socketpair( ) to use an unspecified default protocol 43333 appropriate for the requested socket type. 43334 socket_vector Specifies a 2-integer array to hold the file descriptors of the created socket 43335 pair. 43336 The type argument specifies the socket type, which determines the semantics of communications 43337 over the socket. The following socket types are defined; implementations may specify additional 43338 socket types: 43339 SOCK_STREAM Provides sequenced, reliable, bidirectional, connection-mode byte 43340 streams, and may provide a transmission mechanism for out-of-band 43341 data. 43342 SOCK_DGRAM Provides datagrams, which are connectionless-mode, unreliable messages 43343 of fixed maximum length. 43344 SOCK_SEQPACKET Provides sequenced, reliable, bidirectional, connection-mode 43345 transmission paths for records. A record can be sent using one or more 43346 output operations and received using one or more input operations, but a 43347 single operation never transfers part of more than one record. Record 43348 boundaries are visible to the receiver via the MSG_EOR flag. 43349 If the protocol argument is non-zero, it shall specify a protocol that is supported by the address 43350 family. If the protocol argument is zero, the default protocol for this address family and type shall 43351 be used. The protocols supported by the system are implementation-defined. 43352 The process may need to have appropriate privileges to use the socketpair( ) function or to create 43353 some sockets. 43354 RETURN VALUE 43355 Upon successful completion, this function shall return 0; otherwise, -1 shall be returned and 43356 errno set to indicate the error. 43357 ERRORS 43358 The socketpair( ) function shall fail if: 43359 [EAFNOSUPPORT] 43360 The implementation does not support the specified address family. 1890 Technical Standard (2001) (Draft April 16, 2001) System Interfaces socketpair( ) 43361 [EMFILE] No more file descriptors are available for this process. 43362 [ENFILE] No more file descriptors are available for the system. 43363 [EOPNOTSUPP] The specified protocol does not permit creation of socket pairs. 43364 [EPROTONOSUPPORT] 43365 The protocol is not supported by the address family, or the protocol is not 43366 supported by the implementation. 43367 [EPROTOTYPE] The socket type is not supported by the protocol. 43368 The socketpair( ) function may fail if: 43369 [EACCES] The process does not have appropriate privileges. 43370 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 43371 [ENOMEM] Insufficient memory was available to fulfill the request. 43372 EXAMPLES 43373 None. 43374 APPLICATION USAGE 43375 The documentation for specific address families specifies which protocols each address family 43376 supports. The documentation for specific protocols specifies which socket types each protocol 43377 supports. 43378 The socketpair( ) function is used primarily with UNIX domain sockets and need not be 43379 supported for other domains. 43380 RATIONALE 43381 None. 43382 FUTURE DIRECTIONS 43383 None. 43384 SEE ALSO 43385 socket( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43386 CHANGE HISTORY 43387 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. System Interfaces, Issue 6 1891 sprintf( ) System Interfaces 43388 NAME 43389 sprintf - print formatted output 43390 SYNOPSIS 43391 #include 43392 int sprintf(char *restrict s, const char *restrict format, ...); 43393 DESCRIPTION 43394 Refer to fprintf( ). 1892 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sqrt( ) 43395 NAME 43396 sqrt, sqrtf, sqrtl - square root function 43397 SYNOPSIS 43398 #include 43399 double sqrt(double x); 43400 float sqrtf(float x); 43401 long double sqrtl(long double x); 43402 DESCRIPTION 43403 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43404 conflict between the requirements described here and the ISO C standard is unintentional. This 43405 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43406 These functions shall compute the square root of their argument x, x . 43407 An application wishing to check for error situations should set errno to zero and call 43408 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 43409 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 43410 zero, an error has occurred. 43411 RETURN VALUE 43412 Upon successful completion, these functions shall return the square root of x. 43413 MX For finite values of x < -0, a domain error shall occur, and either a NaN (if supported), or an 43414 implementation-defined value shall be returned. 43415 MX If x is NaN, a NaN shall be returned. 43416 If x is ±0, or +Inf, x shall be returned. 43417 If x is -Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 43418 defined value shall be returned. 43419 ERRORS 43420 These functions shall fail if: 43421 MX Domain Error The finite value of x is < -0, or x is -Inf. 43422 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 43423 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 43424 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 43425 shall be raised. | 43426 EXAMPLES 43427 Taking the Square Root of 9.0 43428 #include 43429 ... 43430 double x = 9.0; 43431 double result; 43432 ... 43433 result = sqrt(x); System Interfaces, Issue 6 1893 sqrt( ) System Interfaces 43434 APPLICATION USAGE 43435 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 43436 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 43437 RATIONALE 43438 None. 43439 FUTURE DIRECTIONS 43440 None. 43441 SEE ALSO 43442 feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 43443 Section 4.18, Treatment of Error Conditions for Mathematical Functions, , | 43444 CHANGE HISTORY 43445 First released in Issue 1. Derived from Issue 1 of the SVID. 43446 Issue 5 43447 The DESCRIPTION is updated to indicate how an application should check for an error. This 43448 text was previously published in the APPLICATION USAGE section. 43449 Issue 6 43450 The sqrtf( ) and sqrtl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 43451 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 43452 revised to align with the ISO/IEC 9899: 1999 standard. 43453 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 43454 marked. 1894 Technical Standard (2001) (Draft April 16, 2001) System Interfaces srand( ) 43455 NAME 43456 srand - pseudo-random number generator 43457 SYNOPSIS 43458 #include 43459 void srand(unsigned seed); 43460 DESCRIPTION 43461 Refer to rand( ). System Interfaces, Issue 6 1895 srand48( ) System Interfaces 43462 NAME 43463 srand48 - seed uniformly distributed double-precision pseudo-random number generator 43464 SYNOPSIS 43465 XSI #include 43466 void srand48(long seedval); 43467 43468 DESCRIPTION 43469 Refer to drand48( ). 1896 Technical Standard (2001) (Draft April 16, 2001) System Interfaces srandom( ) 43470 NAME 43471 srandom - seed pseudo-random number generator 43472 SYNOPSIS 43473 XSI #include 43474 void srandom(unsigned seed); 43475 43476 DESCRIPTION 43477 Refer to initstate( ). System Interfaces, Issue 6 1897 sscanf( ) System Interfaces 43478 NAME 43479 sscanf - convert formatted input 43480 SYNOPSIS 43481 #include 43482 int sscanf(const char *restrict s, const char *restrict format, ...); 43483 DESCRIPTION 43484 Refer to fscanf( ). 1898 Technical Standard (2001) (Draft April 16, 2001) System Interfaces stat( ) 43485 NAME 43486 stat - get file status 43487 SYNOPSIS 43488 #include 43489 int stat(const char *restrict path, struct stat *restrict buf); 43490 DESCRIPTION 43491 The stat( ) function shall obtain information about the named file and write it to the area pointed 43492 to by the buf argument. The path argument points to a pathname naming a file. Read, write, or | 43493 execute permission of the named file is not required. An implementation that provides | 43494 additional or alternate file access control mechanisms may, under implementation-defined 43495 conditions, cause stat( ) to fail. In particular, the system may deny the existence of the file 43496 specified by path. 43497 If the named file is a symbolic link, the stat( ) function shall continue pathname resolution using | 43498 the contents of the symbolic link, and shall return information pertaining to the resulting file if | 43499 the file exists. 43500 The buf argument is a pointer to a stat structure, as defined in the header, into 43501 which information is placed concerning the file. 43502 The stat( ) function shall update any time-related fields (as described in the Base Definitions 43503 volume of IEEE Std 1003.1-200x, Section 4.7, File Times Update), before writing into the stat 43504 structure. 43505 The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime 43506 shall have meaningful values for all file types defined in this volume of IEEE Std 1003.1-200x. 43507 The value of the member st_nlink shall be set to the number of links to the file. 43508 RETURN VALUE 43509 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 43510 indicate the error. 43511 ERRORS 43512 The stat( ) function shall fail if: 43513 [EACCES] Search permission is denied for a component of the path prefix. 43514 [EIO] An error occurred while reading from the file system. 43515 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 43516 argument. 43517 [ENAMETOOLONG] 43518 The length of the path argument exceeds {PATH_MAX} or a pathname | 43519 component is longer than {NAME_MAX}. | 43520 [ENOENT] A component of path does not name an existing file or path is an empty string. 43521 [ENOTDIR] A component of the path prefix is not a directory. 43522 [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 43523 serial number cannot be represented correctly in the structure pointed to by 43524 buf. 43525 The stat( ) function may fail if: 43526 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 43527 resolution of the path argument. System Interfaces, Issue 6 1899 stat( ) System Interfaces 43528 [ENAMETOOLONG] 43529 As a result of encountering a symbolic link in resolution of the path argument, | 43530 the length of the substituted pathname string exceeded {PATH_MAX}. | 43531 [EOVERFLOW] A value to be stored would overflow one of the members of the stat structure. 43532 EXAMPLES 43533 Obtaining File Status Information 43534 The following example shows how to obtain file status information for a file named 43535 /home/cnd/mod1. The structure variable buffer is defined for the stat structure. 43536 #include 43537 #include 43538 #include 43539 struct stat buffer; 43540 int status; 43541 ... 43542 status = stat("/home/cnd/mod1", &buffer); 43543 Getting Directory Information 43544 The following example fragment gets status information for each entry in a directory. The call to 43545 the stat( ) function stores file information in the stat structure pointed to by statbuf. The lines 43546 that follow the stat( ) call format the fields in the stat structure for presentation to the user of the 43547 program. 43548 #include 43549 #include 43550 #include 43551 #include 43552 #include 43553 #include 43554 #include 43555 #include 43556 #include 43557 #include 43558 struct dirent *dp; 43559 struct stat statbuf; 43560 struct passwd *pwd; 43561 struct group *grp; 43562 struct tm *tm; 43563 char datestring[256]; 43564 ... 43565 /* Loop through directory entries */ 43566 while ((dp = readdir(dir)) != NULL) { 43567 /* Get entry's information. */ 43568 if (stat(dp->d_name, &statbuf) == -1) 43569 continue; 43570 /* Print out type, permissions, and number of links. */ 43571 printf("%10.10s", sperm (statbuf.st_mode)); 43572 printf("%4d", statbuf.st_nlink); 1900 Technical Standard (2001) (Draft April 16, 2001) System Interfaces stat( ) 43573 /* Print out owners name if it is found using getpwuid(). */ 43574 if ((pwd = getpwuid(statbuf.st_uid)) != NULL) 43575 printf(" %-8.8s", pwd->pw_name); 43576 else 43577 printf(" %-8d", statbuf.st_uid); 43578 /* Print out group name if it's found using getgrgid(). */ 43579 if ((grp = getgrgid(statbuf.st_gid)) != NULL) 43580 printf(" %-8.8s", grp->gr_name); 43581 else 43582 printf(" %-8d", statbuf.st_gid); 43583 /* Print size of file. */ 43584 printf(" %9jd", (intmax_t)statbuf.st_size); 43585 tm = localtime(&statbuf.st_mtime); 43586 /* Get localized date string. */ 43587 strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); 43588 printf(" %s %s\n", datestring, dp->d_name); 43589 } 43590 APPLICATION USAGE 43591 None. 43592 RATIONALE 43593 The intent of the paragraph describing ``additional or alternate file access control mechanisms'' 43594 is to allow a secure implementation where a process with a label that does not dominate the 43595 file's label cannot perform a stat( ) function. This is not related to read permission; a process with 43596 a label that dominates the file's label does not need read permission. An implementation that 43597 supports write-up operations could fail fstat( ) function calls even though it has a valid file 43598 descriptor open for writing. 43599 FUTURE DIRECTIONS 43600 None. 43601 SEE ALSO 43602 fstat( ), lstat( ), readlink( ), symlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43603 , 43604 CHANGE HISTORY 43605 First released in Issue 1. Derived from Issue 1 of the SVID. 43606 Issue 5 43607 Large File Summit extensions are added. 43608 Issue 6 43609 In the SYNOPSIS, the optional include of the header is removed. 43610 The following new requirements on POSIX implementations derive from alignment with the | 43611 Single UNIX Specification: 43612 * The requirement to include has been removed. Although was 43613 required for conforming implementations of previous POSIX specifications, it was not 43614 required for UNIX applications. 43615 * The [EIO] mandatory error condition is added. System Interfaces, Issue 6 1901 stat( ) System Interfaces 43616 * The [ELOOP] mandatory error condition is added. 43617 * The [EOVERFLOW] mandatory error condition is added. This change is to support large 43618 files. 43619 * The [ENAMETOOLONG] and the second [EOVERFLOW] optional error conditions are 43620 added. 43621 The following changes were made to align with the IEEE P1003.1a draft standard: 43622 * Details are added regarding the treatment of symbolic links. 43623 * The [ELOOP] optional error condition is added. 43624 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 43625 The restrict keyword is added to the stat( ) prototype for alignment with the ISO/IEC 9899: 1999 43626 standard. 1902 Technical Standard (2001) (Draft April 16, 2001) System Interfaces statvfs( ) 43627 NAME 43628 statvfs - get file system information 43629 SYNOPSIS 43630 XSI #include 43631 int statvfs(const char *restrict path, struct statvfs *restrict buf); 43632 43633 DESCRIPTION 43634 Refer to fstatvfs( ). System Interfaces, Issue 6 1903 stdin System Interfaces 43635 NAME 43636 stderr, stdin, stdout - standard I/O streams 43637 SYNOPSIS 43638 #include 43639 extern FILE *stderr, *stdin, *stdout; 43640 DESCRIPTION 43641 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43642 conflict between the requirements described here and the ISO C standard is unintentional. This 43643 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43644 A file with associated buffering is called a stream and is declared to be a pointer to a defined type 43645 FILE. The fopen( ) function shall create certain descriptive data for a stream and return a pointer 43646 to designate the stream in all further transactions. Normally, there are three open streams with 43647 constant pointers declared in the header and associated with the standard open files. 43648 At program start-up, three streams shall be predefined and need not be opened explicitly: 43649 standard input (for reading conventional input), standard output (for writing conventional output), 43650 and standard error (for writing diagnostic output). When opened, the standard error stream is not 43651 fully buffered; the standard input and standard output streams are fully buffered if and only if 43652 the stream can be determined not to refer to an interactive device. 43653 CX The following symbolic values in define the file descriptors that shall be associated 43654 with the C-language stdin, stdout, and stderr when the application is started: 43655 STDIN_FILENO Standard input value, stdin. Its value is 0. 43656 STDOUT_FILENO Standard output value, stdout. Its value is 1. 43657 STDERR_FILENO Standard error value, stderr. Its value is 2. 43658 The stderr stream is expected to be open for reading and writing. | 43659 RETURN VALUE 43660 None. 43661 ERRORS 43662 No errors are defined. 43663 EXAMPLES 43664 None. 43665 APPLICATION USAGE 43666 None. 43667 RATIONALE 43668 None. 43669 FUTURE DIRECTIONS 43670 None. 43671 SEE ALSO 43672 fclose( ), feof( ), ferror( ), fileno( ), fopen( ), fread( ), fseek( ), getc( ), gets( ), popen( ), printf( ), putc( ), 43673 puts( ), read( ), scanf( ), setbuf( ), setvbuf( ), tmpfile( ), ungetc( ), vprintf( ), the Base Definitions 43674 volume of IEEE Std 1003.1-200x, , 1904 Technical Standard (2001) (Draft April 16, 2001) System Interfaces stdin 43675 CHANGE HISTORY 43676 First released in Issue 1. 43677 Issue 6 43678 Extensions beyond the ISO C standard are now marked. 43679 A note that stderr is expected to be open for reading and writing is added to the DESCRIPTION. System Interfaces, Issue 6 1905 strcasecmp( ) System Interfaces 43680 NAME 43681 strcasecmp, strncasecmp - case-insensitive string comparisons 43682 SYNOPSIS 43683 XSI #include 43684 int strcasecmp(const char *s1, const char *s2); 43685 int strncasecmp(const char *s1, const char *s2, size_t n); 43686 43687 DESCRIPTION 43688 The strcasecmp( ) function shall compare, while ignoring differences in case, the string pointed to 43689 by s1 to the string pointed to by s2. The strncasecmp( ) function shall compare, while ignoring 43690 differences in case, not more than n bytes from the string pointed to by s1 to the string pointed to 43691 by s2. 43692 In the POSIX locale, strcasecmp( ) and strncasecmp( ) shall behave as if the strings had been | 43693 converted to lowercase and then a byte comparison performed. The results are unspecified in | 43694 other locales. | 43695 RETURN VALUE 43696 Upon completion, strcasecmp( ) shall return an integer greater than, equal to, or less than 0, if the 43697 string pointed to by s1 is, ignoring case, greater than, equal to, or less than the string pointed to 43698 by s2, respectively. 43699 Upon successful completion, strncasecmp( ) shall return an integer greater than, equal to, or less 43700 than 0, if the possibly null-terminated array pointed to by s1 is, ignoring case, greater than, equal 43701 to, or less than the possibly null-terminated array pointed to by s2, respectively. 43702 ERRORS 43703 No errors are defined. 43704 EXAMPLES 43705 None. 43706 APPLICATION USAGE 43707 None. 43708 RATIONALE 43709 None. 43710 FUTURE DIRECTIONS 43711 None. 43712 SEE ALSO 43713 The Base Definitions volume of IEEE Std 1003.1-200x, 43714 CHANGE HISTORY 43715 First released in Issue 4, Version 2. 43716 Issue 5 43717 Moved from X/OPEN UNIX extension to BASE. 1906 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strcat( ) 43718 NAME 43719 strcat - concatenate two strings 43720 SYNOPSIS 43721 #include 43722 char *strcat(char *restrict s1, const char *restrict s2); 43723 DESCRIPTION 43724 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43725 conflict between the requirements described here and the ISO C standard is unintentional. This 43726 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43727 The strcat( ) function shall append a copy of the string pointed to by s2 (including the 43728 terminating null byte) to the end of the string pointed to by s1. The initial byte of s2 overwrites 43729 the null byte at the end of s1. If copying takes place between objects that overlap, the behavior is 43730 undefined. 43731 RETURN VALUE 43732 The strcat( ) function shall return s1; no return value is reserved to indicate an error. 43733 ERRORS 43734 No errors are defined. 43735 EXAMPLES 43736 None. 43737 APPLICATION USAGE 43738 This issue is aligned with the ISO C standard; this does not affect compatibility with XPG3 43739 applications. Reliable error detection by this function was never guaranteed. 43740 RATIONALE 43741 None. 43742 FUTURE DIRECTIONS 43743 None. 43744 SEE ALSO 43745 strncat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43746 CHANGE HISTORY 43747 First released in Issue 1. Derived from Issue 1 of the SVID. 43748 Issue 6 43749 The strcat( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1907 strchr( ) System Interfaces 43750 NAME 43751 strchr - string scanning operation 43752 SYNOPSIS 43753 #include 43754 char *strchr(const char *s, int c); 43755 DESCRIPTION 43756 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43757 conflict between the requirements described here and the ISO C standard is unintentional. This 43758 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43759 CX The strchr( ) function shall locate the first occurrence of c (converted to an unsignedchar) in the 43760 string pointed to by s. The terminating null byte is considered to be part of the string. 43761 RETURN VALUE 43762 Upon completion, strchr( ) shall return a pointer to the byte, or a null pointer if the byte was not 43763 found. 43764 ERRORS 43765 No errors are defined. 43766 EXAMPLES 43767 None. 43768 APPLICATION USAGE 43769 None. 43770 RATIONALE 43771 None. 43772 FUTURE DIRECTIONS 43773 None. 43774 SEE ALSO 43775 strrchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43776 CHANGE HISTORY 43777 First released in Issue 1. Derived from Issue 1 of the SVID. 43778 Issue 6 43779 Extensions beyond the ISO C standard are now marked. 1908 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strcmp( ) 43780 NAME 43781 strcmp - compare two strings 43782 SYNOPSIS 43783 #include 43784 int strcmp(const char *s1, const char *s2); 43785 DESCRIPTION 43786 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43787 conflict between the requirements described here and the ISO C standard is unintentional. This 43788 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43789 The strcmp( ) function shall compare the string pointed to by s1 to the string pointed to by s2. 43790 The sign of a non-zero return value shall be determined by the sign of the difference between the 43791 values of the first pair of bytes (both interpreted as type unsigned char) that differ in the strings 43792 being compared. 43793 RETURN VALUE 43794 Upon completion, strcmp( ) shall return an integer greater than, equal to, or less than 0, if the 43795 string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2, 43796 respectively. 43797 ERRORS 43798 No errors are defined. 43799 EXAMPLES 43800 Checking a Password Entry 43801 The following example compares the information read from standard input to the value of the 43802 name of the user entry. If the strcmp( ) function returns 0 (indicating a match), a further check 43803 will be made to see if the user entered the proper old password. The crypt( ) function shall | 43804 encrypt the old password entered by the user, using the value of the encrypted password in the | 43805 passwd structure as the salt. If this value matches the value of the encrypted passwd in the 43806 structure, the entered password oldpasswd is the correct user's password. Finally, the program 43807 encrypts the new password so that it can store the information in the passwd structure. 43808 #include 43809 #include 43810 #include 43811 ... 43812 int valid_change; 43813 struct passwd *p; 43814 char user[100]; 43815 char oldpasswd[100]; 43816 char newpasswd[100]; 43817 char savepasswd[100]; 43818 ... 43819 if (strcmp(p->pw_name, user) == 0) { 43820 if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { 43821 strcpy(savepasswd, crypt(newpasswd, user)); 43822 p->pw_passwd = savepasswd; 43823 valid_change = 1; 43824 } 43825 else { System Interfaces, Issue 6 1909 strcmp( ) System Interfaces 43826 fprintf(stderr, "Old password is not valid\n"); 43827 } 43828 } 43829 ... 43830 APPLICATION USAGE 43831 None. 43832 RATIONALE 43833 None. 43834 FUTURE DIRECTIONS 43835 None. 43836 SEE ALSO 43837 strncmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43838 CHANGE HISTORY 43839 First released in Issue 1. Derived from Issue 1 of the SVID. 43840 Issue 6 43841 Extensions beyond the ISO C standard are now marked. 1910 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strcoll( ) 43842 NAME 43843 strcoll - string comparison using collating information 43844 SYNOPSIS 43845 #include 43846 int strcoll(const char *s1, const char *s2); 43847 DESCRIPTION 43848 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43849 conflict between the requirements described here and the ISO C standard is unintentional. This 43850 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43851 The strcoll( ) function shall compare the string pointed to by s1 to the string pointed to by s2, 43852 both interpreted as appropriate to the LC_COLLATE category of the current locale. 43853 CX The strcoll( ) function shall not change the setting of errno if successful. 43854 Since no return value is reserved to indicate an error, an application wishing to check for error | 43855 situations should set errno to 0, then call strcoll( ), then check errno. 43856 RETURN VALUE 43857 Upon successful completion, strcoll( ) shall return an integer greater than, equal to, or less than 0, 43858 according to whether the string pointed to by s1 is greater than, equal to, or less than the string 43859 CX pointed to by s2 when both are interpreted as appropriate to the current locale. On error, 43860 strcoll( ) may set errno, but no return value is reserved to indicate an error. 43861 ERRORS 43862 The strcoll( ) function may fail if: 43863 CX [EINVAL] The s1 or s2 arguments contain characters outside the domain of the collating 43864 sequence. 43865 EXAMPLES 43866 Comparing Nodes 43867 The following example uses an application-defined function, node_compare( ), to compare two 43868 nodes based on an alphabetical ordering of the string field. 43869 #include 43870 ... 43871 struct node { /* These are stored in the table. */ 43872 char *string; 43873 int length; 43874 }; 43875 ... 43876 int node_compare(const void *node1, const void *node2) 43877 { 43878 return strcoll(((const struct node *)node1)->string, 43879 ((const struct node *)node2)->string); 43880 } 43881 ... 43882 APPLICATION USAGE 43883 The strxfrm( ) and strcmp( ) functions should be used for sorting large lists. System Interfaces, Issue 6 1911 strcoll( ) System Interfaces 43884 RATIONALE 43885 None. 43886 FUTURE DIRECTIONS 43887 None. 43888 SEE ALSO 43889 strcmp( ), strxfrm( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43890 CHANGE HISTORY 43891 First released in Issue 3. 43892 Issue 5 43893 The DESCRIPTION is updated to indicate that errno does not be changed if the function is 43894 successful. 43895 Issue 6 43896 Extensions beyond the ISO C standard are now marked. 43897 The following new requirements on POSIX implementations derive from alignment with the 43898 Single UNIX Specification: 43899 * The [EINVAL] optional error condition is added. 43900 An example is added. | 1912 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strcpy( ) 43901 NAME 43902 strcpy - copy a string 43903 SYNOPSIS 43904 #include 43905 char *strcpy(char *restrict s1, const char *restrict s2); 43906 DESCRIPTION 43907 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43908 conflict between the requirements described here and the ISO C standard is unintentional. This 43909 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43910 The strcpy( ) function shall copy the string pointed to by s2 (including the terminating null byte) 43911 into the array pointed to by s1. If copying takes place between objects that overlap, the behavior 43912 is undefined. 43913 RETURN VALUE 43914 The strcpy( ) function shall return s1; no return value is reserved to indicate an error. 43915 ERRORS 43916 No errors are defined. 43917 EXAMPLES 43918 Initializing a String 43919 The following example copies the string "----------" into the permstring variable. 43920 #include 43921 ... 43922 static char permstring[11]; 43923 ... 43924 strcpy(permstring, "----------"); 43925 ... 43926 Storing a Key and Data 43927 The following example allocates space for a key using malloc( ) then uses strcpy( ) to place the 43928 key there. Then it allocates space for data using malloc( ), and uses strcpy( ) to place data there. 43929 (The user-defined function dbfree( ) frees memory previously allocated to an array of type struct 43930 element *.) 43931 #include 43932 #include 43933 #include 43934 ... 43935 /* Structure used to read data and store it. */ 43936 struct element { 43937 char *key; 43938 char *data; 43939 }; 43940 struct element *tbl, *curtbl; 43941 char *key, *data; 43942 int count; 43943 ... 43944 void dbfree(struct element *, int); System Interfaces, Issue 6 1913 strcpy( ) System Interfaces 43945 ... 43946 if ((curtbl->key = malloc(strlen(key) + 1)) == NULL) { 43947 perror("malloc"); dbfree(tbl, count); return NULL; 43948 } 43949 strcpy(curtbl->key, key); 43950 if ((curtbl->data = malloc(strlen(data) + 1)) == NULL) { 43951 perror("malloc"); free(curtbl->key); dbfree(tbl, count); return NULL; 43952 } 43953 strcpy(curtbl->data, data); 43954 ... 43955 APPLICATION USAGE 43956 Character movement is performed differently in different implementations. Thus, overlapping 43957 moves may yield surprises. 43958 This issue is aligned with the ISO C standard; this does not affect compatibility with XPG3 43959 applications. Reliable error detection by this function was never guaranteed. 43960 RATIONALE 43961 None. 43962 FUTURE DIRECTIONS 43963 None. 43964 SEE ALSO 43965 strncpy( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43966 CHANGE HISTORY 43967 First released in Issue 1. Derived from Issue 1 of the SVID. 43968 Issue 6 43969 The strcpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 1914 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strcspn( ) 43970 NAME 43971 strcspn - get length of a complementary substring 43972 SYNOPSIS 43973 #include 43974 size_t strcspn(const char *s1, const char *s2); 43975 DESCRIPTION 43976 CX The functionality described on this reference page is aligned with the ISO C standard. Any 43977 conflict between the requirements described here and the ISO C standard is unintentional. This 43978 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 43979 The strcspn( ) function shall compute the length (in bytes) of the maximum initial segment of the | 43980 string pointed to by s1 which consists entirely of bytes not from the string pointed to by s2. | 43981 RETURN VALUE 43982 The strcspn( ) function shall return the length of the computed segment of the string pointed to 43983 by s1; no return value is reserved to indicate an error. 43984 ERRORS 43985 No errors are defined. 43986 EXAMPLES 43987 None. 43988 APPLICATION USAGE 43989 None. 43990 RATIONALE 43991 None. 43992 FUTURE DIRECTIONS 43993 None. 43994 SEE ALSO 43995 strspn( ), the Base Definitions volume of IEEE Std 1003.1-200x, 43996 CHANGE HISTORY 43997 First released in Issue 1. Derived from Issue 1 of the SVID. 43998 Issue 5 43999 The RETURN VALUE section is updated to indicated that strcspn( ) returns the length of s1, and 44000 not s1 itself as was previously stated. 44001 Issue 6 44002 The Open Group Corrigendum U030/1 is applied. The text of the RETURN VALUE section is 44003 updated to indicate that the computed segment length is returned, not the s1 length. System Interfaces, Issue 6 1915 strdup( ) System Interfaces 44004 NAME 44005 strdup - duplicate a string 44006 SYNOPSIS 44007 XSI #include 44008 char *strdup(const char *s1); 44009 44010 DESCRIPTION 44011 The strdup( ) function shall return a pointer to a new string, which is a duplicate of the string 44012 pointed to by s1. The returned pointer can be passed to free( ). A null pointer is returned if the 44013 new string cannot be created. 44014 RETURN VALUE 44015 The strdup( ) function shall return a pointer to a new string on success. Otherwise, it shall return 44016 a null pointer and set errno to indicate the error. 44017 ERRORS 44018 The strdup( ) function may fail if: 44019 [ENOMEM] Storage space available is insufficient. 44020 EXAMPLES 44021 None. 44022 APPLICATION USAGE 44023 None. 44024 RATIONALE 44025 None. 44026 FUTURE DIRECTIONS 44027 None. 44028 SEE ALSO 44029 free( ), malloc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44030 CHANGE HISTORY 44031 First released in Issue 4, Version 2. 44032 Issue 5 44033 Moved from X/OPEN UNIX extension to BASE. 1916 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strerror( ) 44034 NAME 44035 strerror, strerror_r - get error message string 44036 SYNOPSIS 44037 #include 44038 char *strerror(int errnum); 44039 TSF int strerror_r(int errnum, char *strerrbuf, size_t buflen); 44040 44041 DESCRIPTION 44042 CX For strerror( ): The functionality described on this reference page is aligned with the ISO C 44043 standard. Any conflict between the requirements described here and the ISO C standard is 44044 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44045 The strerror( ) function shall map the error number in errnum to a locale-dependent error 44046 message string and shall return a pointer to it. Typically, the values for errnum come from errno, 44047 but strerror( ) shall map any value of type int to a message. 44048 The string pointed to shall not be modified by the application, but may be overwritten by a 44049 CX subsequent call to strerror( ) or perror( ). 44050 CX The contents of the error message strings returned by strerror( ) should be determined by the 44051 setting of the LC_MESSAGES category in the current locale. 44052 The implementation shall behave as if no function defined in this volume of 44053 IEEE Std 1003.1-200x calls strerror( ). 44054 CX The strerror( ) function shall not change the setting of errno if successful. 44055 Since no return value is reserved to indicate an error, an application wishing to check for error | 44056 situations should set errno to 0, then call strerror( ), then check errno. 44057 The strerror( ) function need not be reentrant. A function that is not required to be reentrant is 44058 not required to be thread-safe. 44059 TSF The strerror_r( ) function shall map the error number in errnum to a locale-dependent error 44060 message string and shall return the string in the buffer pointed to by strerrbuf, with length buflen. 44061 44062 RETURN VALUE 44063 Upon successful completion, strerror( ) shall return a pointer to the generated message string. On 44064 error errno may be set, but no return value is reserved to indicate an error. 44065 TSF Upon successful completion, strerror_r( ) shall return 0. Otherwise, an error number shall be 44066 returned to indicate the error. 44067 ERRORS 44068 These functions may fail if: 44069 [EINVAL] The value of errnum is not a valid error number. 44070 The strerror_r( ) function may fail if: 44071 TSF [ERANGE] Insufficient storage was supplied via strerrbuf and buflen to contain the 44072 generated message string. System Interfaces, Issue 6 1917 strerror( ) System Interfaces 44073 EXAMPLES 44074 None. 44075 APPLICATION USAGE 44076 None. 44077 RATIONALE 44078 None. 44079 FUTURE DIRECTIONS 44080 None. 44081 SEE ALSO 44082 perror( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44083 CHANGE HISTORY 44084 First released in Issue 3. 44085 Issue 5 44086 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 44087 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 44088 Issue 6 44089 Extensions beyond the ISO C standard are now marked. 44090 The following new requirements on POSIX implementations derive from alignment with the 44091 Single UNIX Specification: 44092 * In the RETURN VALUE section, the fact that errno may be set is added. 44093 * The [EINVAL] optional error condition is added. 44094 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 44095 The strerror_r( ) function is added in response to IEEE PASC Interpretation 1003.1c #39. 44096 The strerror_r( ) function is marked as part of the Thread-Safe Functions option. 1918 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strfmon( ) 44097 NAME 44098 strfmon - convert monetary value to a string 44099 SYNOPSIS 44100 XSI #include 44101 ssize_t strfmon(char *restrict s, size_t maxsize, 44102 const char *restrict format, ...); 44103 44104 DESCRIPTION 44105 The strfmon( ) function shall place characters into the array pointed to by s as controlled by the 44106 string pointed to by format. No more than maxsize bytes are placed into the array. 44107 The format is a character string, beginning and ending in its initial state, if any, that contains two | 44108 types of objects: plain characters, which are simply copied to the output stream, and conversion | 44109 specifications, each of which shall result in the fetching of zero or more arguments which are 44110 converted and formatted. The results are undefined if there are insufficient arguments for the 44111 format. If the format is exhausted while arguments remain, the excess arguments are simply 44112 ignored. 44113 The application shall ensure that a conversion specification consists of the following sequence: 44114 * A '%' character 44115 * Optional flags 44116 * Optional field width 44117 * Optional left precision 44118 * Optional right precision 44119 * A required conversion specifier character that determines the conversion to be performed 44120 Flags 44121 One or more of the following optional flags can be specified to control the conversion: 44122 =f An '=' followed by a single character f which is used as the numeric fill character. In | 44123 order to work with precision or width counts, the fill character shall be a single byte | 44124 character; if not, the behavior is undefined. The default numeric fill character is the | 44125 . This flag does not affect field width filling which always uses the . 44126 This flag is ignored unless a left precision (see below) is specified. 44127 ^ Do not format the currency amount with grouping characters. The default is to insert 44128 the grouping characters if defined for the current locale. 44129 + or ( Specify the style of representing positive and negative currency amounts. Only one of 44130 '+' or '(' may be specified. If '+' is specified, the locale's equivalent of '+' and '-' 44131 are used (for example, in the U.S., the empty string if positive and '-' if negative). If 44132 '(' is specified, negative amounts are enclosed within parentheses. If neither flag is 44133 specified, the '+' style is used. 44134 ! Suppress the currency symbol from the output conversion. 44135 - Specify the alignment. If this flag is present the result of the conversion is left-justified | 44136 (padded to the right) rather than right-justified. This flag shall be ignored unless a field | 44137 width (see below) is specified. | System Interfaces, Issue 6 1919 strfmon( ) System Interfaces 44138 Field Width 44139 w A decimal digit string w specifying a minimum field width in bytes in which the result 44140 of the conversion is right-justified (or left-justified if the flag '-' is specified). The 44141 default is 0. 44142 Left Precision 44143 #n A '#' followed by a decimal digit string n specifying a maximum number of digits 44144 expected to be formatted to the left of the radix character. This option can be used to 44145 keep the formatted output from multiple calls to the strfmon( ) function aligned in the 44146 same columns. It can also be used to fill unused positions with a special character as in 44147 "$***123.45". This option causes an amount to be formatted as if it has the number 44148 of digits specified by n. If more than n digit positions are required, this conversion 44149 specification is ignored. Digit positions in excess of those actually required are filled 44150 with the numeric fill character (see the =f flag above). 44151 If grouping has not been suppressed with the ' ' flag, and it is defined for the current 44152 locale, grouping separators are inserted before the fill characters (if any) are added. 44153 Grouping separators are not applied to fill characters even if the fill character is a digit. 44154 To ensure alignment, any characters appearing before or after the number in the 44155 formatted output such as currency or sign symbols are padded as necessary with 44156 s to make their positive and negative formats an equal length. 44157 Right Precision 44158 .p A period followed by a decimal digit string p specifying the number of digits after the 44159 radix character. If the value of the right precision p is 0, no radix character appears. If a 44160 right precision is not included, a default specified by the current locale is used. The 44161 amount being formatted is rounded to the specified number of digits prior to 44162 formatting. 44163 Conversion Specifier Characters 44164 The conversion specifier characters and their meanings are: 44165 i The double argument is formatted according to the locale's international currency | 44166 format (for example, in the U.S.: USD 1,234.56). If the argument is ±Inf or NaN, the | 44167 result of the conversion is unspecified. | 44168 n The double argument is formatted according to the locale's national currency format | 44169 (for example, in the U.S.: $1,234.56). If the argument is ±Inf or NaN, the result of the | 44170 conversion is unspecified. | 44171 % Convert to a '%'; no argument is converted. The entire conversion specification shall 44172 be %%. 44173 Locale Information 44174 The LC_MONETARY category of the program's locale affects the behavior of this function 44175 including the monetary radix character (which may be different from the numeric radix 44176 character affected by the LC_NUMERIC category), the grouping separator, the currency 44177 symbols, and formats. The international currency symbol should be conformant with the 44178 ISO 4217: 1995 standard. 44179 If the value of maxsize is greater than {SSIZE_MAX}, the result is implementation-defined. 1920 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strfmon( ) 44180 RETURN VALUE 44181 If the total number of resulting bytes including the terminating null byte is not more than 44182 maxsize, strfmon( ) shall return the number of bytes placed into the array pointed to by s, not 44183 including the terminating null byte. Otherwise, -1 shall be returned, the contents of the array are | 44184 unspecified, and errno shall be set to indicate the error. | 44185 ERRORS 44186 The strfmon( ) function shall fail if: 44187 [E2BIG] Conversion stopped due to lack of space in the buffer. System Interfaces, Issue 6 1921 strfmon( ) System Interfaces 44188 EXAMPLES | 44189 Given a locale for the U.S. and the values 123.45, -123.45, and 3456.781: ______________________________________________________________________ | 44190 Conversion | 44191 _Specification Output Comments _____________________________________________________________________ || 44192 %n $123.45 Default formatting. | 44193 -$123.45 | 44194 _ $3,456.78 _____________________________________________________________________ 44195 %11n $123.45 Right align within an 11 character field. | 44196 -$123.45 | 44197 _ $3,456.78 _____________________________________________________________________ 44198 %#5n $ 123.45 Aligned columns for values up to 99,999. | 44199 -$ 123.45 | 44200 _ $ 3,456.78 _____________________________________________________________________ 44201 %=*#5n $***123.45 Specify a fill character. | 44202 -$***123.45 | 44203 _ $*3,456.78 _____________________________________________________________________ 44204 %=0#5n $000123.45 Fill characters do not use grouping | 44205 -$000123.45 even if the fill character is a digit. | 44206 _ $03,456.78 _____________________________________________________________________ 44207 % #5n $ 123.45 Disable the grouping separator. | 44208 -$ 123.45 | 44209 _ $ 3456.78 _____________________________________________________________________ 44210 % #5.0n $ 123 Round off to whole units. | 44211 -$ 123 | 44212 _ $ 3457 _____________________________________________________________________ 44213 % #5.4n $ 123.4500 Increase the precision. | 44214 -$ 123.4500 | 44215 _ $ 3456.7810 _____________________________________________________________________ 44216 %(#5n $ 123.45 Use an alternative pos/neg style. | 44217 ($ 123.45) | 44218 _ $ 3,456.78 _____________________________________________________________________ || 44219 %(!#5n 123.45 Disable the currency symbol. | 44220 ( 123.45) | 44221 _ 3,456.78 _____________________________________________________________________ | 44222 %-14#5.4n $ 123.4500 Left-justify the output. | 44223 -$ 123.4500 | 44224 _ $3,456.7810 _____________________________________________________________________ || 44225 %14#5.4n $ 123.4500 Corresponding right-justified output. | 44226 -$ 123.4500 | 44227 _ $3,456.7810 _____________________________________________________________________ || 44228 APPLICATION USAGE 44229 None. 44230 RATIONALE 44231 None. 1922 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strfmon( ) 44232 FUTURE DIRECTIONS 44233 Lowercase conversion characters are reserved for future standards use and uppercase for 44234 implementation-defined use. 44235 SEE ALSO 44236 localeconv( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44237 CHANGE HISTORY 44238 First released in Issue 4. 44239 Issue 5 44240 Moved from ENHANCED I18N to BASE. 44241 The [ENOSYS] error is removed. 44242 A sentence is added to the DESCRIPTION warning about values of maxsize that are greater than 44243 {SSIZE_MAX}. 44244 Issue 6 44245 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 44246 The restrict keyword is added to the strfmon( ) prototype for alignment with the 44247 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1923 strftime( ) System Interfaces 44248 NAME 44249 strftime - convert date and time to a string 44250 SYNOPSIS 44251 #include 44252 size_t strftime(char *restrict s, size_t maxsize, 44253 const char *restrict format, const struct tm *restrict timeptr); | 44254 DESCRIPTION | 44255 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44256 conflict between the requirements described here and the ISO C standard is unintentional. This 44257 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44258 The strftime( ) function shall place bytes into the array pointed to by s as controlled by the string 44259 pointed to by format. The format is a character string, beginning and ending in its initial shift | 44260 state, if any. The format string consists of zero or more conversion specifications and ordinary | 44261 characters. A conversion specification consists of a '%' character, possibly followed by an E or O 44262 modifier, and a terminating conversion specifier character that determines the conversion 44263 specification's behavior. All ordinary characters (including the terminating null byte) are copied 44264 unchanged into the array. If copying takes place between objects that overlap, the behavior is 44265 undefined. No more than maxsize bytes are placed into the array. Each conversion specifier is | 44266 replaced by appropriate characters as described in the following list. The appropriate characters | 44267 are determined using the LC_TIME category of the current locale and by the values of zero or | 44268 more members of the broken-down time structure pointed to by timeptr, as specified in brackets | 44269 in the description. If any of the specified values are outside the normal range, the characters | 44270 stored are unspecified. | 44271 CX Local timezone information is used as though strftime( ) called tzset( ). 44272 The following conversion specifications are supported: 44273 %a Replaced by the locale's abbreviated weekday name. [tm_wday] | 44274 %A Replaced by the locale's full weekday name. [tm_wday] | 44275 %b Replaced by the locale's abbreviated month name. [tm_mon] | 44276 %B Replaced by the locale's full month name. [tm_mon] | 44277 %c Replaced by the locale's appropriate date and time representation. (See the Base | 44278 Definitions volume of IEEE Std 1003.1-200x, .) | 44279 %C Replaced by the year divided by 100 and truncated to an integer, as a decimal number | 44280 [00,99]. [tm_year] | 44281 %d Replaced by the day of the month as a decimal number [01,31]. [tm_mday] | 44282 %D Equivalent to %m/%d/%y. [tm_mon, tm_mday, tm_year] | 44283 %e Replaced by the day of the month as a decimal number [1,31]; a single digit is preceded | 44284 by a space. [tm_mday] | 44285 %F Equivalent to %Y-%m-%d (the ISO 8601: 2000 standard date format). [tm_year, tm_mon, | 44286 tm_mday] | 44287 %g Replaced by the last 2 digits of the week-based year (see below) as a decimal number | 44288 [00,99]. [tm_year, tm_wday, tm_yday] | 44289 %G Replaced by the week-based year (see below) as a decimal number (for example, 1977). | 44290 [tm_year, tm_wday, tm_yday] | 1924 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strftime( ) 44291 %h Equivalent to %b. [tm_mon] | 44292 %H Replaced by the hour (24-hour clock) as a decimal number [00,23]. [tm_hour] | 44293 %I Replaced by the hour (12-hour clock) as a decimal number [01,12]. [tm_hour] | 44294 %j Replaced by the day of the year as a decimal number [001,366]. [tm_yday] | 44295 %m Replaced by the month as a decimal number [01,12]. [tm_mon] | 44296 %M Replaced by the minute as a decimal number [00,59]. [tm_min] | 44297 %n Replaced by a . 44298 %p Replaced by the locale's equivalent of either a.m. or p.m. [tm_hour] | 44299 CX %r Replaced by the time in a.m. and p.m. notation; in the POSIX locale this shall be | 44300 equivalent to %I:%M:%S %p. [tm_hour, tm_min, tm_sec] | 44301 %R Replaced by the time in 24 hour notation (%H:%M). [tm_hour, tm_min] | 44302 %S Replaced by the second as a decimal number [00,60]. [tm_sec] | 44303 %t Replaced by a . 44304 %T Replaced by the time (%H:%M:%S). [tm_hour, tm_min, tm_sec] | 44305 %u Replaced by the weekday as a decimal number [1,7], with 1 representing Monday. | 44306 [tm_wday] | 44307 %U Replaced by the week number of the year as a decimal number [00,53]. The frist | 44308 Sunday of January is the first day of week 1; days in the new year before this are in | 44309 week 0. [tm_year, tm_wday, tm_yday] | 44310 %V Replaced by the week number of the year (Monday as the first day of the week) as a 44311 decimal number [01,53]. If the week containing 1 January has four or more days in the 44312 new year, then it is considered week 1. Otherwise, it is the last week of the previous 44313 year, and the next week is week 1. Both January 4th and the first Thursday of January | 44314 are always in week 1. [tm_year, tm_wday, tm_yday] | 44315 %w Replaced by the weekday as a decimal number [0,6], with 0 representing Sunday. | 44316 [tm_wday] | 44317 %W Replaced by the week number of the year as a decimal number [00,53]. The first | 44318 Monday of January is the first day of week 1; days in the new year before this are in | 44319 week 0. [tm_year, tm_wday, tm_yday] | 44320 %x Replaced by the locale's appropriate date representation. (See the Base Definitions | 44321 volume of IEEE Std 1003.1-200x, .) | 44322 %X Replaced by the locale's appropriate time representation. (See the Base Definitions | 44323 volume of IEEE Std 1003.1-200x, .) | 44324 %y Replaced by the last two digits of the year as a decimal number [00,99]. [tm_year] | 44325 %Y Replaced by the year as a decimal number (for example, 1997). [tm_year] | 44326 %z Replaced by the offset from UTC in the ISO 8601: 2000 standard format (+hhmm or | 44327 -hhmm), or by no characters if no timezone is determinable. For example, "-0430" | 44328 CX means 4 hours 30 minutes behind UTC (west of Greenwich). If tm_isdst is zero, the | 44329 standard time offset is used. If tm_isdst is greater than zero, the daylight savings time | 44330 offset is used. If tm_isdst is negative, no characters are returned. [tm_isdst] | System Interfaces, Issue 6 1925 strftime( ) System Interfaces 44331 %Z Replaced by the timezone name or abbreviation, or by no bytes if no timezone | 44332 information exists. [tm_isdst] | 44333 %% Replaced by %. 44334 If a conversion specification does not correspond to any of the above, the behavior is undefined. 44335 Modified Conversion Specifiers 44336 Some conversion specifiers can be modified by the E or O modifier characters to indicate that an | 44337 alternative format or specification should be used rather than the one normally used by the 44338 unmodified conversion specifier. If the alternative format or specification does not exist for the 44339 current locale, (see ERA in the Base Definitions volume of IEEE Std 1003.1-200x, Section 7.3.5, 44340 LC_TIME) the behavior shall be as if the unmodified conversion specification were used. 44341 %Ec Replaced by the locale's alternative appropriate date and time representation. 44342 %EC Replaced by the name of the base year (period) in the locale's alternative 44343 representation. 44344 %Ex Replaced by the locale's alternative date representation. 44345 %EX Replaced by the locale's alternative time representation. 44346 %Ey Replaced by the offset from %EC (year only) in the locale's alternative representation. 44347 %EY Replaced by the full alternative year representation. 44348 %Od Replaced by the day of the month, using the locale's alternative numeric symbols, filled 44349 as needed with leading zeros if there is any alternative symbol for zero; otherwise, with 44350 leading spaces. 44351 %Oe Replaced by the day of the month, using the locale's alternative numeric symbols, filled 44352 as needed with leading spaces. 44353 %OH Replaced by the hour (24-hour clock) using the locale's alternative numeric symbols. 44354 %OI Replaced by the hour (12-hour clock) using the locale's alternative numeric symbols. 44355 %Om Replaced by the month using the locale's alternative numeric symbols. 44356 %OM Replaced by the minutes using the locale's alternative numeric symbols. 44357 %OS Replaced by the seconds using the locale's alternative numeric symbols. 44358 %Ou Replaced by the weekday as a number in the locale's alternative representation 44359 (Monday=1). 44360 %OU Replaced by the week number of the year (Sunday as the first day of the week, rules 44361 corresponding to %U) using the locale's alternative numeric symbols. 44362 %OV Replaced by the week number of the year (Monday as the first day of the week, rules 44363 corresponding to %V) using the locale's alternative numeric symbols. 44364 %Ow Replaced by the number of the weekday (Sunday=0) using the locale's alternative 44365 numeric symbols. 44366 %OW Replaced by the week number of the year (Monday as the first day of the week) using 44367 the locale's alternative numeric symbols. 44368 %Oy Replaced by the year (offset from %C) using the locale's alternative numeric symbols. 44369 %g, %G, and %V give values according to the ISO 8601: 2000 standard week-based year. In this | 44370 system, weeks begin on a Monday and week 1 of the year is the week that includes January 4th, | 1926 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strftime( ) 44371 which is also the week that includes the first Thursday of the year, and is also the first week that 44372 contains at least four days in the year. If the first Monday of January is the 2nd, 3rd, or 4th, the 44373 preceding days are part of the last week of the preceding year; thus, for Saturday 2nd January 44374 1999, %G is replaced by 1998 and %V is replaced by 53. If December 29th, 30th, or 31st is a 44375 Monday, it and any following days are part of week 1 of the following year. Thus, for Tuesday 44376 30th December 1997, %G is replaced by 1998 and %V is replaced by 01. 44377 If a conversion specifier is not one of the above, the behavior is undefined. | 44378 RETURN VALUE 44379 If the total number of resulting bytes including the terminating null byte is not more than 44380 maxsize, strftime( ) shall return the number of bytes placed into the array pointed to by s, not 44381 including the terminating null byte. Otherwise, 0 shall be returned and the contents of the array | 44382 are unspecified. | 44383 ERRORS 44384 No errors are defined. 44385 EXAMPLES 44386 Getting a Localized Date String 44387 The following example first sets the locale to the user's default. The locale information will be 44388 used in the nl_langinfo ( ) and strftime( ) functions. The nl_langinfo ( ) function returns the localized 44389 date string which specifies how the date is laid out. The strftime( ) function takes this information 44390 and, using the tm structure for values, places the date and time information into datestring. 44391 #include 44392 #include 44393 #include 44394 ... 44395 struct tm *tm; 44396 char datestring[256]; 44397 ... 44398 setlocale (LC_ALL, ""); 44399 ... 44400 strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); 44401 ... 44402 APPLICATION USAGE 44403 The range of values for %S is [00,60] rather than [00,59] to allow for the occasional leap second. 44404 Some of the conversion specifications are duplicates of others. They are included for | 44405 compatibility with nl_cxtime( ) and nl_ascxtime( ), which were published in Issue 2. | 44406 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 44407 In the C locale, the E and O modifiers are ignored and the replacement strings for the following 44408 specifiers are: 44409 %a The first three characters of %A. 44410 %A One of Sunday, Monday, . . ., Saturday. 44411 %b The first three characters of %B. 44412 %B One of January, February, . . ., December. 44413 %c Equivalent to %a %b %e %T %Y. System Interfaces, Issue 6 1927 strftime( ) System Interfaces 44414 %p One of AM or PM. 44415 %r Equivalent to %I:%M:%S %p. 44416 %x Equivalent to %m/%d/%y. 44417 %X Equivalent to %T. 44418 %Z Implementation-defined. 44419 RATIONALE 44420 None. 44421 FUTURE DIRECTIONS 44422 None. 44423 SEE ALSO 44424 asctime( ), clock( ), ctime( ), difftime( ), getdate( ), gmtime( ), localtime( ), mktime( ), strptime( ), time( ), | 44425 tzset( ), utime( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 44426 CHANGE HISTORY 44427 First released in Issue 3. 44428 Issue 5 44429 The description of %OV is changed to be consistent with %V and defines Monday as the first day 44430 of the week. 44431 The description of %Oy is clarified. 44432 Issue 6 44433 Extensions beyond the ISO C standard are now marked. 44434 The Open Group Corrigendum U033/8 is applied. The %V conversion specifier is changed from 44435 ``Otherwise, it is week 53 of the previous year, and the next week is week 1'' to ``Otherwise, it is 44436 the last week of the previous year, and the next week is week 1''. 44437 The following new requirements on POSIX implementations derive from alignment with the 44438 Single UNIX Specification: 44439 * The %C, %D, %e, %h, %n, %r, %R, %t, and %T conversion specifiers are added. 44440 * The modified conversion specifiers are added for consistency with the ISO POSIX-2 standard 44441 date utility. 44442 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 44443 * The strftime( ) prototype is updated. 44444 * The DESCRIPTION is extensively revised. | 44445 * The %z conversion specifier is added. | 44446 A new example is added. | 1928 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strlen( ) 44447 NAME 44448 strlen - get string length 44449 SYNOPSIS 44450 #include 44451 size_t strlen(const char *s); 44452 DESCRIPTION 44453 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44454 conflict between the requirements described here and the ISO C standard is unintentional. This 44455 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44456 The strlen( ) function shall compute the number of bytes in the string to which s points, not 44457 including the terminating null byte. 44458 RETURN VALUE 44459 The strlen( ) function shall return the length of s; no return value shall be reserved to indicate an 44460 error. 44461 ERRORS 44462 No errors are defined. 44463 EXAMPLES 44464 Getting String Lengths 44465 The following example sets the maximum length of key and data by using strlen( ) to get the 44466 lengths of those strings. 44467 #include 44468 ... 44469 struct element { 44470 char *key; 44471 char *data; 44472 }; 44473 ... 44474 char *key, *data; 44475 int len; 44476 *keylength = *datalength = 0; 44477 ... 44478 if ((len = strlen(key)) > *keylength) 44479 *keylength = len; 44480 if ((len = strlen(data)) > *datalength) 44481 *datalength = len; 44482 ... 44483 APPLICATION USAGE 44484 None. 44485 RATIONALE 44486 None. 44487 FUTURE DIRECTIONS 44488 None. System Interfaces, Issue 6 1929 strlen( ) System Interfaces 44489 SEE ALSO 44490 The Base Definitions volume of IEEE Std 1003.1-200x, 44491 CHANGE HISTORY 44492 First released in Issue 1. Derived from Issue 1 of the SVID. 44493 Issue 5 44494 The RETURN VALUE section is updated to indicate that strlen( ) returns the length of s, and not 44495 s itself as was previously stated. 1930 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strncasecmp( ) 44496 NAME 44497 strncasecmp - case-insensitive string comparison 44498 SYNOPSIS 44499 XSI #include 44500 int strncasecmp(const char *s1, const char *s2, size_t n); 44501 44502 DESCRIPTION 44503 Refer to strcasecmp( ). System Interfaces, Issue 6 1931 strncat( ) System Interfaces 44504 NAME 44505 strncat - concatenate a string with part of another 44506 SYNOPSIS 44507 #include 44508 char *strncat(char *restrict s1, const char *restrict s2, size_t n); 44509 DESCRIPTION 44510 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44511 conflict between the requirements described here and the ISO C standard is unintentional. This 44512 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44513 The strncat( ) function shall append not more than n bytes (a null byte and bytes that follow it 44514 are not appended) from the array pointed to by s2 to the end of the string pointed to by s1. The 44515 initial byte of s2 overwrites the null byte at the end of s1. A terminating null byte is always 44516 appended to the result. If copying takes place between objects that overlap, the behavior is 44517 undefined. 44518 RETURN VALUE 44519 The strncat( ) function shall return s1; no return value shall be reserved to indicate an error. 44520 ERRORS 44521 No errors are defined. 44522 EXAMPLES 44523 None. 44524 APPLICATION USAGE 44525 None. 44526 RATIONALE 44527 None. 44528 FUTURE DIRECTIONS 44529 None. 44530 SEE ALSO 44531 strcat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44532 CHANGE HISTORY 44533 First released in Issue 1. Derived from Issue 1 of the SVID. 44534 Issue 6 44535 The strncat( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 1932 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strncmp( ) 44536 NAME 44537 strncmp - compare part of two strings 44538 SYNOPSIS 44539 #include 44540 int strncmp(const char *s1, const char *s2, size_t n); 44541 DESCRIPTION 44542 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44543 conflict between the requirements described here and the ISO C standard is unintentional. This 44544 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44545 The strncmp( ) function shall compare not more than n bytes (bytes that follow a null byte are not 44546 compared) from the array pointed to by s1 to the array pointed to by s2. 44547 The sign of a non-zero return value is determined by the sign of the difference between the 44548 values of the first pair of bytes (both interpreted as type unsigned char) that differ in the strings 44549 being compared. 44550 RETURN VALUE 44551 Upon successful completion, strncmp( ) shall return an integer greater than, equal to, or less than 44552 0, if the possibly null-terminated array pointed to by s1 is greater than, equal to, or less than the 44553 possibly null-terminated array pointed to by s2 respectively. 44554 ERRORS 44555 No errors are defined. 44556 EXAMPLES 44557 None. 44558 APPLICATION USAGE 44559 None. 44560 RATIONALE 44561 None. 44562 FUTURE DIRECTIONS 44563 None. 44564 SEE ALSO 44565 strcmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44566 CHANGE HISTORY 44567 First released in Issue 1. Derived from Issue 1 of the SVID. 44568 Issue 6 44569 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 1933 strncpy( ) System Interfaces 44570 NAME 44571 strncpy - copy part of a string 44572 SYNOPSIS 44573 #include 44574 char *strncpy(char *restrict s1, const char *restrict s2, size_t n); 44575 DESCRIPTION 44576 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44577 conflict between the requirements described here and the ISO C standard is unintentional. This 44578 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44579 The strncpy( ) function shall copy not more than n bytes (bytes that follow a null byte are not 44580 copied) from the array pointed to by s2 to the array pointed to by s1. If copying takes place 44581 between objects that overlap, the behavior is undefined. 44582 If the array pointed to by s2 is a string that is shorter than n bytes, null bytes shall be appended 44583 to the copy in the array pointed to by s1, until n bytes in all are written. 44584 RETURN VALUE 44585 The strncpy( ) function shall return s1; no return value is reserved to indicate an error. 44586 ERRORS 44587 No errors are defined. 44588 EXAMPLES 44589 None. 44590 APPLICATION USAGE 44591 Character movement is performed differently in different implementations. Thus, overlapping 44592 moves may yield surprises. 44593 If there is no null byte in the first n bytes of the array pointed to by s2, the result is not null- 44594 terminated. 44595 RATIONALE 44596 None. 44597 FUTURE DIRECTIONS 44598 None. 44599 SEE ALSO 44600 strcpy( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44601 CHANGE HISTORY 44602 First released in Issue 1. Derived from Issue 1 of the SVID. 44603 Issue 6 44604 The strncpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 1934 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strpbrk( ) 44605 NAME 44606 strpbrk - scan string for byte 44607 SYNOPSIS 44608 #include 44609 char *strpbrk(const char *s1, const char *s2); 44610 DESCRIPTION 44611 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44612 conflict between the requirements described here and the ISO C standard is unintentional. This 44613 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44614 The strpbrk( ) function shall locate the first occurrence in the string pointed to by s1 of any byte 44615 from the string pointed to by s2. 44616 RETURN VALUE 44617 Upon successful completion, strpbrk( ) shall return a pointer to the byte or a null pointer if no 44618 byte from s2 occurs in s1. 44619 ERRORS 44620 No errors are defined. 44621 EXAMPLES 44622 None. 44623 APPLICATION USAGE 44624 None. 44625 RATIONALE 44626 None. 44627 FUTURE DIRECTIONS 44628 None. 44629 SEE ALSO 44630 strchr( ), strrchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44631 CHANGE HISTORY 44632 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 1935 strptime( ) System Interfaces 44633 NAME 44634 strptime - date and time conversion 44635 SYNOPSIS 44636 XSI #include 44637 char *strptime(const char *restrict buf, const char *restrict format, 44638 struct tm *restrict tm); 44639 44640 DESCRIPTION 44641 The strptime( ) function shall convert the character string pointed to by buf to values which are 44642 stored in the tm structure pointed to by tm, using the format specified by format. 44643 The format is composed of zero or more directives. Each directive is composed of one of the 44644 following: one or more white-space characters (as specified by isspace( )); an ordinary character 44645 (neither '%' nor a white-space character); or a conversion specification. Each conversion 44646 specification is composed of a '%' character followed by a conversion character which specifies 44647 the replacement required. The application shall ensure that there is white-space or other non- 44648 alphanumeric characters between any two conversion specifications. The following conversion 44649 specifications are supported: 44650 %a The day of the week, using the locale's weekday names; either the abbreviated or full 44651 name may be specified. 44652 %A Equivalent to %a. | 44653 %b The month, using the locale's month names; either the abbreviated or full name may be 44654 specified. 44655 %B Equivalent to %b. | 44656 %c Replaced by the locale's appropriate date and time representation. 44657 %C The century number [0,99]; leading zeros are permitted but not required. 44658 %d The day of the month [1,31]; leading zeros are permitted but not required. 44659 %D The date as %m/%d/%y. 44660 %e Equivalent to %d. | 44661 %h Equivalent to %b. | 44662 %H The hour (24-hour clock) [0,23]; leading zeros are permitted but not required. 44663 %I The hour (12-hour clock) [1,12]; leading zeros are permitted but not required. 44664 %j The day number of the year [1,366]; leading zeros are permitted but not required. 44665 %m The month number [1,12]; leading zeros are permitted but not required. 44666 %M The minute [0,59]; leading zeros are permitted but not required. | 44667 %n Any white space. 44668 %p The locale's equivalent of a.m or p.m. 44669 %r 12-hour clock time using the AM/PM notation if t_fmt_ampm is not an empty string in 44670 the LC_TIME portion of the current locale; in the POSIX locale, this shall be equivalent | 44671 to %I:%M:%S %p. | 44672 %R The time as %H:%M. 1936 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strptime( ) 44673 %S The seconds [0,60]; leading zeros are permitted but not required. 44674 %t Any white space. 44675 %T The time as %H:%M:%S. 44676 %U The week number of the year (Sunday as the first day of the week) as a decimal number 44677 [00,53]; leading zeros are permitted but not required. 44678 %w The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros are 44679 permitted but not required. 44680 %W The week number of the year (Monday as the first day of the week) as a decimal 44681 number [00,53]; leading zeros are permitted but not required. 44682 %x The date, using the locale's date format. 44683 %X The time, using the locale's time format. 44684 %y The year within century. When a century is not otherwise specified, values in the range | 44685 [69,99] shall refer to years 1969 to 1999 inclusive, and values in the range [00,68] shall | 44686 refer to years 2000 to 2068 inclusive; leading zeros shall be permitted but shall not be | 44687 required. | 44688 Note: It is expected that in a future version of IEEE Std 1003.1-200x the default century | 44689 inferred from a 2-digit year will change. (This would apply to all commands | 44690 accepting a 2-digit year as input.) | 44691 %Y The year, including the century (for example, 1988). | 44692 %% Replaced by %. 44693 Modified Conversion Specifiers 44694 Some conversion specifiers can be modified by the E and O modifier characters to indicate that 44695 an alternative format or specification should be used rather than the one normally used by the 44696 unmodified conversion specifier. If the alternative format or specification does not exist in the 44697 current locale, the behavior shall be as if the unmodified conversion specification were used. 44698 %Ec The locale's alternative appropriate date and time representation. 44699 %EC The name of the base year (period) in the locale's alternative representation. 44700 %Ex The locale's alternative date representation. 44701 %EX The locale's alternative time representation. 44702 %Ey The offset from %EC (year only) in the locale's alternative representation. 44703 %EY The full alternative year representation. 44704 %Od The day of the month using the locale's alternative numeric symbols; leading zeros are 44705 permitted but not required. 44706 %Oe Equivalent to %Od. | 44707 %OH The hour (24-hour clock) using the locale's alternative numeric symbols. 44708 %OI The hour (12-hour clock) using the locale's alternative numeric symbols. 44709 %Om The month using the locale's alternative numeric symbols. 44710 %OM The minutes using the locale's alternative numeric symbols. System Interfaces, Issue 6 1937 strptime( ) System Interfaces 44711 %OS The seconds using the locale's alternative numeric symbols. 44712 %OU The week number of the year (Sunday as the first day of the week) using the locale's 44713 alternative numeric symbols. 44714 %Ow The number of the weekday (Sunday=0) using the locale's alternative numeric symbols. 44715 %OW The week number of the year (Monday as the first day of the week) using the locale's 44716 alternative numeric symbols. 44717 %Oy The year (offset from %C) using the locale's alternative numeric symbols. 44718 A conversion specification composed of white-space characters is executed by scanning input 44719 up to the first character that is not white-space (which remains unscanned), or until no more 44720 characters can be scanned. 44721 A conversion specification that is an ordinary character is executed by scanning the next 44722 character from the buffer. If the character scanned from the buffer differs from the one 44723 comprising the directive, the directive fails, and the differing and subsequent characters remain 44724 unscanned. 44725 A series of conversion specifications composed of %n, %t, white-space characters, or any 44726 combination is executed by scanning up to the first character that is not white space (which 44727 remains unscanned), or until no more characters can be scanned. 44728 Any other conversion specification is executed by scanning characters until a character matching 44729 the next directive is scanned, or until no more characters can be scanned. These characters, 44730 except the one matching the next directive, are then compared to the locale values associated 44731 with the conversion specifier. If a match is found, values for the appropriate tm structure 44732 members are set to values corresponding to the locale information. Case is ignored when 44733 matching items in buf such as month or weekday names. If no match is found, strptime( ) fails 44734 and no more characters are scanned. 44735 RETURN VALUE 44736 Upon successful completion, strptime( ) shall return a pointer to the character following the last 44737 character parsed. Otherwise, a null pointer shall be returned. 44738 ERRORS 44739 No errors are defined. 44740 EXAMPLES 44741 None. 44742 APPLICATION USAGE 44743 Several ``equivalent to'' formats and the special processing of white-space characters are | 44744 provided in order to ease the use of identical format strings for strftime( ) and strptime( ). | 44745 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 44746 It is unspecified whether multiple calls to strptime( ) using the same tm structure will update the 44747 current contents of the structure or overwrite all contents of the structure. Conforming | 44748 applications should make a single call to strptime( ) with a format and all data needed to | 44749 completely specify the date and time being converted. 44750 RATIONALE 44751 None. 1938 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strptime( ) 44752 FUTURE DIRECTIONS 44753 The strptime( ) function is expected to be mandatory in the next version of this volume of 44754 IEEE Std 1003.1-200x. 44755 SEE ALSO 44756 scanf( ), strftime( ), time( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44757 CHANGE HISTORY 44758 First released in Issue 4. 44759 Issue 5 44760 Moved from ENHANCED I18N to BASE. 44761 The [ENOSYS] error is removed. 44762 The exact meaning of the %y and %Oy specifiers are clarified in the DESCRIPTION. 44763 Issue 6 44764 The Open Group Corrigendum U033/5 is applied. The %r specifier description is reworded. 44765 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 44766 The restrict keyword is added to the strptime( ) prototype for alignment with the 44767 ISO/IEC 9899: 1999 standard. 44768 The Open Group Corrigendum U047/2 is applied. 44769 The DESCRIPTION is updated to use the terms ``conversion specifier'' and ``conversion 44770 specification'' for consistency with strftime( ). System Interfaces, Issue 6 1939 strrchr( ) System Interfaces 44771 NAME 44772 strrchr - string scanning operation 44773 SYNOPSIS 44774 #include 44775 char *strrchr(const char *s, int c); 44776 DESCRIPTION 44777 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44778 conflict between the requirements described here and the ISO C standard is unintentional. This 44779 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44780 CX The strrchr( ) function shall locate the last occurrence of c (converted to an unsignedchar) in the 44781 string pointed to by s. The terminating null byte is considered to be part of the string. 44782 RETURN VALUE 44783 Upon successful completion, strrchr( ) shall return a pointer to the byte or a null pointer if c does 44784 not occur in the string. 44785 ERRORS 44786 No errors are defined. 44787 EXAMPLES 44788 Finding the Base Name of a File 44789 The following example uses strrchr( ) to get a pointer to the base name of a file. The strrchr( ) 44790 function searches backwards through the name of the file to find the last '/' character in name. 44791 This pointer (plus one) will point to the base name of the file. 44792 #include 44793 ... 44794 const char *name; 44795 char *basename; 44796 ... 44797 basename = strrchr(name, '/') + 1; 44798 ... 44799 APPLICATION USAGE 44800 None. 44801 RATIONALE 44802 None. 44803 FUTURE DIRECTIONS 44804 None. 44805 SEE ALSO 44806 strchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44807 CHANGE HISTORY 44808 First released in Issue 1. Derived from Issue 1 of the SVID. 1940 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strspn( ) 44809 NAME 44810 strspn - get length of a substring 44811 SYNOPSIS 44812 #include 44813 size_t strspn(const char *s1, const char *s2); 44814 DESCRIPTION 44815 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44816 conflict between the requirements described here and the ISO C standard is unintentional. This 44817 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44818 The strspn( ) function shall compute the length (in bytes) of the maximum initial segment of the | 44819 string pointed to by s1 which consists entirely of bytes from the string pointed to by s2. | 44820 RETURN VALUE 44821 The strspn( ) function shall return the length of s1; no return value is reserved to indicate an 44822 error. 44823 ERRORS 44824 No errors are defined. 44825 EXAMPLES 44826 None. 44827 APPLICATION USAGE 44828 None. 44829 RATIONALE 44830 None. 44831 FUTURE DIRECTIONS 44832 None. 44833 SEE ALSO 44834 strcspn( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44835 CHANGE HISTORY 44836 First released in Issue 1. Derived from Issue 1 of the SVID. 44837 Issue 5 44838 The RETURN VALUE section is updated to indicate that strspn( ) returns the length of s, and not 44839 s itself as was previously stated. System Interfaces, Issue 6 1941 strstr( ) System Interfaces 44840 NAME 44841 strstr - find a substring 44842 SYNOPSIS 44843 #include 44844 char *strstr(const char *s1, const char *s2); 44845 DESCRIPTION 44846 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44847 conflict between the requirements described here and the ISO C standard is unintentional. This 44848 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44849 The strstr( ) function shall locate the first occurrence in the string pointed to by s1 of the 44850 sequence of bytes (excluding the terminating null byte) in the string pointed to by s2. 44851 RETURN VALUE 44852 Upon successful completion, strstr( ) shall return a pointer to the located string or a null pointer 44853 if the string is not found. 44854 If s2 points to a string with zero length, the function shall return s1. 44855 ERRORS 44856 No errors are defined. 44857 EXAMPLES 44858 None. 44859 APPLICATION USAGE 44860 None. 44861 RATIONALE 44862 None. 44863 FUTURE DIRECTIONS 44864 None. 44865 SEE ALSO 44866 strchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 44867 CHANGE HISTORY 44868 First released in Issue 3. 44869 Entry included for alignment with the ANSI C standard. 1942 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtod( ) 44870 NAME 44871 strtod, strtof, strtold - convert string to a double-precision number 44872 SYNOPSIS 44873 #include 44874 double strtod(const char *restrict nptr, char **restrict endptr); 44875 float strtof(const char *restrict nptr, char **restrict endptr); 44876 long double strtold(const char *restrict nptr, char **restrict endptr); 44877 DESCRIPTION 44878 CX The functionality described on this reference page is aligned with the ISO C standard. Any 44879 conflict between the requirements described here and the ISO C standard is unintentional. This 44880 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 44881 These functions shall convert the initial portion of the string pointed to by nptr to double, float, 44882 and long double representation, respectively. First, they decompose the input string into three 44883 parts: 44884 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace( )) 44885 2. A subject sequence interpreted as a floating-point constant or representing infinity or NaN 44886 3. A final string of one or more unrecognized characters, including the terminating null byte 44887 of the input string 44888 Then they shall attempt to convert the subject sequence to a floating-point number, and return | 44889 the result. | 44890 The expected form of the subject sequence is an optional plus or minus sign, then one of the 44891 following: 44892 * A non-empty sequence of decimal digits optionally containing a radix character, then an 44893 optional exponent part 44894 * A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally containing a radix 44895 character, then an optional binary exponent part 44896 * One of INF or INFINITY, ignoring case 44897 * One of NAN or NAN(n-char-sequenceopt), ignoring case in the NAN part, where: 44898 n-char-sequence: 44899 digit 44900 nondigit 44901 n-char-sequence digit 44902 n-char-sequence nondigit 44903 The subject sequence is defined as the longest initial subsequence of the input string, starting 44904 with the first non-white-space character, that is of the expected form. The subject sequence 44905 contains no characters if the input string is not of the expected form. 44906 If the subject sequence has the expected form for a floating-point number, the sequence of 44907 characters starting with the first digit or the decimal-point character (whichever occurs first) | 44908 shall be interpreted as a floating constant of the C language, except that the radix character shall | 44909 be used in place of a period, and that if neither an exponent part nor a radix character appears in | 44910 a decimal floating-point number, or if a binary exponent part does not appear in a hexadecimal | 44911 floating-point number, an exponent part of the appropriate type with value zero is assumed to | 44912 follow the last digit in the string. If the subject sequence begins with a minus sign, the sequence | 44913 shall be interpreted as negated. A character sequence INF or INFINITY shall be interpreted as an | System Interfaces, Issue 6 1943 strtod( ) System Interfaces 44914 infinity, if representable in the return type, else as if it were a floating constant that is too large | 44915 for the range of the return type. A character sequence NAN or NAN(n-char-sequenceopt) shall be | 44916 interpreted as a quiet NaN, if supported in the return type, else as if it were a subject sequence | 44917 part that does not have the expected form; the meaning of the n-char sequences is | 44918 implementation-defined. A pointer to the final string is stored in the object pointed to by endptr, | 44919 provided that endptr is not a null pointer. 44920 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the value 44921 resulting from the conversion is correctly rounded. 44922 CX The radix character is defined in the program's locale (category LC_NUMERIC). In the POSIX 44923 locale, or in a locale where the radix character is not defined, the radix character shall default to a 44924 period ('.'). 44925 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 44926 accepted. 44927 If the subject sequence is empty or does not have the expected form, no conversion shall be | 44928 performed; the value of str is stored in the object pointed to by endptr, provided that endptr is not | 44929 a null pointer. 44930 CX The strtod( ) function shall not change the setting of errno if successful. 44931 Since 0 is returned on error and is also a valid return on success, an application wishing to check | 44932 for error situations should set errno to 0, then call strtod( ), strtof( ), or strtold( ), then check errno. 44933 RETURN VALUE 44934 Upon successful completion, these functions shall return the converted value. If no conversion 44935 could be performed, 0 shall be returned, and errno may be set to [EINVAL]. 44936 If the correct value is outside the range of representable values, HUGE_VAL, HUGE_VALF, or 44937 HUGE_VALL shall be returned (according to the sign of the value), and errno shall be set to 44938 [ERANGE]. 44939 If the correct value would cause an underflow, a value whose magnitude is no greater than the 44940 smallest normalized positive number in the return type shall be returned and errno set to 44941 [ERANGE]. 44942 ERRORS 44943 These functions shall fail if: 44944 CX [ERANGE] The value to be returned would cause overflow or underflow. 44945 These functions may fail if: 44946 CX [EINVAL] No conversion could be performed. 44947 EXAMPLES | 44948 None. 44949 APPLICATION USAGE 44950 If the subject sequence has the hexadecimal form and FLT_RADIX is not a power of 2, adn the | 44951 result is not exactly representable, the result should be one of the two numbers in the | 44952 appropriate internal format that are adjacent to the hexadecimal floating source value, with the | 44953 extra stipulation that the error should have a correct sign for the current rounding direction. | 44954 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in ) 44955 significant digits, the result should be correctly rounded. If the subject sequence D has the 44956 decimal form and more than DECIMAL_DIG significant digits, consider the two bounding, 44957 adjacent decimal strings L and U, both having DECIMAL_DIG significant digits, such that the 1944 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtod( ) 44958 values of L, D, and U satisfy L <= D <= U. The result should be one of the (equal or adjacent) 44959 values that would be obtained by correctly rounding L and U according to the current rounding 44960 direction, with the extra stipulation that the error with respect to D should have a correct sign 44961 for the current rounding direction. 44962 The changes to strtod( ) introduced by the ISO/IEC 9899: 1999 standard can alter the behavior of 44963 well-formed applications complying with the ISO/IEC 9899: 1990 standard and thus earlier 44964 versions of IEEE Std 1003.1-200x. One such example would be: 44965 int 44966 what_kind_of_number (char *s) 44967 { 44968 char *endp; 44969 double d; 44970 long l; 44971 d = strtod(s, &endp); 44972 if (s != endp && *endp == `\0') 44973 printf("It's a float with value %g\n", d); 44974 else 44975 { 44976 l = strtol(s, &endp, 0); 44977 if (s != endp && *endp == `\0') 44978 printf("It's an integer with value %ld\n", 1); 44979 else 44980 return 1; 44981 } 44982 return 0; 44983 } 44984 If the function is called with: 44985 what_kind_of_number ("0x10") 44986 an ISO/IEC 9899: 1990 standard-compliant library will result in the function printing: 44987 It's an integer with value 16 44988 With the ISO/IEC 9899: 1999 standard, the result is: 44989 It's a float with value 16 44990 The change in behavior is due to the inclusion of floating-point numbers in hexadecimal 44991 notation without requiring that either a decimal point or the binary exponent be present. 44992 RATIONALE 44993 None. 44994 FUTURE DIRECTIONS 44995 None. 44996 SEE ALSO 44997 isspace( ), localeconv( ), scanf( ), setlocale( ), strtol( ), the Base Definitions volume of 44998 IEEE Std 1003.1-200x, , , the Base Definitions volume of 44999 IEEE Std 1003.1-200x, Chapter 7, Locale System Interfaces, Issue 6 1945 strtod( ) System Interfaces 45000 CHANGE HISTORY 45001 First released in Issue 1. Derived from Issue 1 of the SVID. 45002 Issue 5 45003 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 45004 Issue 6 45005 Extensions beyond the ISO C standard are now marked. 45006 The following new requirements on POSIX implementations derive from alignment with the 45007 Single UNIX Specification: 45008 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 45009 added if no conversion could be performed. 45010 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 45011 * The strtod( ) function is updated. 45012 * The strtof( ) and strtold( ) functions are added. 45013 * The DESCRIPTION is extensively revised. 45014 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | 1946 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtof( ) 45015 NAME 45016 strtof - convert string to a double-precision number 45017 SYNOPSIS 45018 #include 45019 float strtof(const char *restrict nptr, char **restrict endptr); 45020 DESCRIPTION 45021 Refer to strtod( ). System Interfaces, Issue 6 1947 strtoimax( ) System Interfaces 45022 NAME 45023 strtoimax, strtoumax - convert string to integer type 45024 SYNOPSIS 45025 #include 45026 intmax_t strtoimax(const char *restrict nptr, char **restrict endptr, 45027 int base); 45028 uintmax_t strtoumax(const char *restrict nptr, char **restrict endptr, 45029 int base); 45030 DESCRIPTION 45031 CX The functionality described on this reference page is aligned with the ISO C standard. Any 45032 conflict between the requirements described here and the ISO C standard is unintentional. This 45033 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45034 These functions shall be equivalent to the strtol( ), strtoll( ), strtoul( ), and strtoull( ) functions, 45035 except that the initial portion of the string shall be converted to intmax_t and uintmax_t 45036 representation, respectively. 45037 RETURN VALUE 45038 These functions shall return the converted value, if any. 45039 If no conversion could be performed, zero shall be returned. 45040 If the correct value is outside the range of representable values, {INTMAX_MAX}, 45041 {INTMAX_MIN}, or {UINTMAX_MAX} shall be returned (according to the return type and sign 45042 of the value, if any), and errno shall be set to [ERANGE]. 45043 ERRORS 45044 These functions shall fail if: 45045 [ERANGE] The value to be returned is not representable. 45046 These functions may fail if: 45047 [EINVAL] The value of base is not supported. 45048 EXAMPLES 45049 None. 45050 APPLICATION USAGE 45051 None. 45052 RATIONALE 45053 None. 45054 FUTURE DIRECTIONS 45055 None. 45056 SEE ALSO 45057 strtol( ), strtoul( ), the Base Definitions volume of IEEE Std 1003.1-200x, 45058 CHANGE HISTORY 45059 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. 1948 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtok( ) 45060 NAME 45061 strtok, strtok_r - split string into tokens 45062 SYNOPSIS 45063 #include 45064 char *strtok(char *restrict s1, const char *restrict s2); 45065 TSF char *strtok_r(char *restrict s, const char *restrict sep, 45066 char **restrict lasts); 45067 45068 DESCRIPTION 45069 CX For strtok( ): The functionality described on this reference page is aligned with the ISO C 45070 standard. Any conflict between the requirements described here and the ISO C standard is 45071 unintentional. This volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45072 A sequence of calls to strtok( ) breaks the string pointed to by s1 into a sequence of tokens, each 45073 of which is delimited by a byte from the string pointed to by s2. The first call in the sequence has 45074 s1 as its first argument, and is followed by calls with a null pointer as their first argument. The 45075 separator string pointed to by s2 may be different from call to call. 45076 The first call in the sequence searches the string pointed to by s1 for the first byte that is not 45077 contained in the current separator string pointed to by s2. If no such byte is found, then there 45078 are no tokens in the string pointed to by s1 and strtok( ) shall return a null pointer. If such a byte 45079 is found, it is the start of the first token. 45080 The strtok( ) function then searches from there for a byte that is contained in the current 45081 separator string. If no such byte is found, the current token extends to the end of the string 45082 pointed to by s1, and subsequent searches for a token shall return a null pointer. If such a byte is 45083 found, it is overwritten by a null byte, which terminates the current token. The strtok( ) function 45084 saves a pointer to the following byte, from which the next search for a token shall start. 45085 Each subsequent call, with a null pointer as the value of the first argument, starts searching from 45086 the saved pointer and behaves as described above. 45087 The implementation shall behave as if no function defined in this volume of 45088 IEEE Std 1003.1-200x calls strtok( ). 45089 CX The strtok( ) function need not be reentrant. A function that is not required to be reentrant is not 45090 required to be thread-safe. 45091 TSF The strtok_r( ) function considers the null-terminated string s as a sequence of zero or more text 45092 tokens separated by spans of one or more characters from the separator string sep. The 45093 argument lasts points to a user-provided pointer which points to stored information necessary 45094 for strtok_r( ) to continue scanning the same string. 45095 In the first call to strtok_r( ), s points to a null-terminated string, sep to a null-terminated string of 45096 separator characters, and the value pointed to by lasts is ignored. The strtok_r( ) function shall 45097 return a pointer to the first character of the first token, write a null character into s immediately 45098 following the returned token, and update the pointer to which lasts points. 45099 In subsequent calls, s is a NULL pointer and lasts shall be unchanged from the previous call so 45100 that subsequent calls shall move through the string s, returning successive tokens until no 45101 tokens remain. The separator string sep may be different from call to call. When no token 45102 remains in s, a NULL pointer shall be returned. System Interfaces, Issue 6 1949 strtok( ) System Interfaces 45103 RETURN VALUE 45104 Upon successful completion, strtok( ) shall return a pointer to the first byte of a token. Otherwise, 45105 if there is no token, strtok( ) shall return a null pointer. 45106 TSF The strtok_r( ) function shall return a pointer to the token found, or a NULL pointer when no 45107 token is found. 45108 ERRORS 45109 No errors are defined. 45110 EXAMPLES 45111 Searching for Word Separators 45112 The following example searches for tokens separated by space characters. 45113 #include 45114 ... 45115 char *token; 45116 char *line = "LINE TO BE SEPARATED"; 45117 char *search = " "; 45118 /* Token will point to "LINE". */ 45119 token = strtok(line, search); 45120 /* Token will point to "TO". */ 45121 token = strtok(NULL, search); 45122 Breaking a Line 45123 The following example uses strtok( ) to break a line into two character strings separated by any 45124 combination of s, s, or s. 45125 #include 45126 ... 45127 struct element { 45128 char *key; 45129 char *data; 45130 }; 45131 ... 45132 char line[LINE_MAX]; 45133 char *key, *data; 45134 ... 45135 key = strtok(line, " \n"); 45136 data = strtok(NULL, " \n"); 45137 ... 45138 APPLICATION USAGE 45139 The strtok_r( ) function is thread-safe and stores its state in a user-supplied buffer instead of 45140 possibly using a static data area that may be overwritten by an unrelated call from another 45141 thread. 45142 RATIONALE 45143 The strtok( ) function searches for a separator string within a larger string. It returns a pointer to 45144 the last substring between separator strings. This function uses static storage to keep track of 45145 the current string position between calls. The new function, strtok_r( ), takes an additional 45146 argument, lasts, to keep track of the current position in the string. 1950 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtok( ) 45147 FUTURE DIRECTIONS 45148 None. 45149 SEE ALSO 45150 The Base Definitions volume of IEEE Std 1003.1-200x, 45151 CHANGE HISTORY 45152 First released in Issue 1. Derived from Issue 1 of the SVID. 45153 Issue 5 45154 The strtok_r( ) function is included for alignment with the POSIX Threads Extension. 45155 A note indicating that the strtok( ) function need not be reentrant is added to the DESCRIPTION. 45156 Issue 6 45157 Extensions beyond the ISO C standard are now marked. 45158 The strtok_r( ) function is marked as part of the Thread-Safe Functions option. 45159 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 45160 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 45161 its avoidance of possibly using a static data area. 45162 The restrict keyword is added to the strtok( ) and strtok_r( ) prototypes for alignment with the 45163 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1951 strtol( ) System Interfaces 45164 NAME 45165 strtol, strtoll - convert string to a long integer 45166 SYNOPSIS 45167 #include 45168 long strtol(const char *restrict str, char **restrict endptr, int base); 45169 long long strtoll(const char *restrict str, char **restrict endptr, 45170 int base) 45171 DESCRIPTION 45172 CX The functionality described on this reference page is aligned with the ISO C standard. Any 45173 conflict between the requirements described here and the ISO C standard is unintentional. This 45174 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45175 These functions shall convert the initial portion of the string pointed to by str to a type long and 45176 long long representation, respectively. First, they decompose the input string into three parts: 45177 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace( )) 45178 2. A subject sequence interpreted as an integer represented in some radix determined by the 45179 value of base 45180 3. A final string of one or more unrecognized characters, including the terminating null byte 45181 of the input string. 45182 Then they shall attempt to convert the subject sequence to an integer, and return the result. | 45183 If the value of base is 0, the expected form of the subject sequence is that of a decimal constant, 45184 octal constant, or hexadecimal constant, any of which may be preceded by a '+' or '-' sign. A 45185 decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An 45186 octal constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to 45187 '7' only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the 45188 decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively. 45189 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 45190 of letters and digits representing an integer with the radix specified by base, optionally preceded 45191 by a '+' or '-' sign. The letters from 'a' (or 'A') to 'z' (or 'Z') inclusive are ascribed the 45192 values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the 45193 value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and 45194 digits, following the sign if present. 45195 The subject sequence is defined as the longest initial subsequence of the input string, starting 45196 with the first non-white-space character that is of the expected form. The subject sequence shall | 45197 contain no characters if the input string is empty or consists entirely of white-space characters, | 45198 or if the first non-white-space character is other than a sign or a permissible letter or digit. 45199 If the subject sequence has the expected form and the value of base is 0, the sequence of | 45200 characters starting with the first digit shall be interpreted as an integer constant. If the subject | 45201 sequence has the expected form and the value of base is between 2 and 36, it shall be used as the | 45202 base for conversion, ascribing to each letter its value as given above. If the subject sequence | 45203 begins with a minus sign, the value resulting from the conversion shall be negated. A pointer to | 45204 the final string shall be stored in the object pointed to by endptr, provided that endptr is not a null | 45205 pointer. 45206 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 45207 accepted. 1952 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtol( ) 45208 If the subject sequence is empty or does not have the expected form, no conversion is performed; 45209 the value of str is stored in the object pointed to by endptr, provided that endptr is not a null 45210 pointer. 45211 CX The strtol( ) function shall not change the setting of errno if successful. 45212 Since 0, {LONG_MIN} or {LLONG_MIN}, and {LONG_MAX} or {LLONG_MAX} are returned on | 45213 error and are also valid returns on success, an application wishing to check for error situations 45214 should set errno to 0, then call strtol( ) or strtoll( ), then check errno. 45215 RETURN VALUE 45216 Upon successful completion, these functions shall return the converted value, if any. If no 45217 CX conversion could be performed, 0 shall be returned and errno may be set to [EINVAL]. 45218 If the correct value is outside the range of representable values, {LONG_MIN}, {LONG_MAX}, 45219 {LLONG_MIN} or {LLONG_MAX} shall be returned (according to the sign of the value), and 45220 errno set to [ERANGE]. 45221 ERRORS 45222 These functions shall fail if: 45223 [ERANGE] The value to be returned is not representable. 45224 These functions may fail if: 45225 CX [EINVAL] The value of base is not supported. 45226 EXAMPLES 45227 None. 45228 APPLICATION USAGE 45229 None. 45230 RATIONALE 45231 None. 45232 FUTURE DIRECTIONS 45233 None. 45234 SEE ALSO 45235 isalpha( ), scanf( ), strtod( ), the Base Definitions volume of IEEE Std 1003.1-200x, 45236 CHANGE HISTORY 45237 First released in Issue 1. Derived from Issue 1 of the SVID. 45238 Issue 5 45239 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 45240 Issue 6 45241 Extensions beyond the ISO C standard are now marked. 45242 The following new requirements on POSIX implementations derive from alignment with the 45243 Single UNIX Specification: 45244 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 45245 added if no conversion could be performed. 45246 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 45247 * The strtol( ) prototype is updated. 45248 * The strtoll( ) function is added. System Interfaces, Issue 6 1953 strtold( ) System Interfaces 45249 NAME 45250 strtold - convert string to a double-precision number 45251 SYNOPSIS 45252 #include 45253 long double strtold(const char *restrict nptr, char **restrict endptr); 45254 DESCRIPTION 45255 Refer to strtod( ). 1954 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtoll( ) 45256 NAME 45257 strtoll - convert string to a long integer 45258 SYNOPSIS 45259 #include 45260 long long strtoll(const char *restrict str, char **restrict endptr, 45261 int base); | 45262 DESCRIPTION | 45263 Refer to strtol( ). System Interfaces, Issue 6 1955 strtoul( ) System Interfaces 45264 NAME 45265 strtoul, strtoull - convert string to an unsigned long 45266 SYNOPSIS 45267 #include 45268 unsigned long strtoul(const char *restrict str, | 45269 char **restrict endptr, int base); | 45270 unsigned long long strtoull(const char *restrict str, | 45271 char **restrict endptr, int base); | 45272 DESCRIPTION | 45273 CX The functionality described on this reference page is aligned with the ISO C standard. Any 45274 conflict between the requirements described here and the ISO C standard is unintentional. This 45275 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45276 These functions shall convert the initial portion of the string pointed to by str to a type unsigned | 45277 long and unsigned long long representation, respectively. First, they decompose the input | 45278 string into three parts: 45279 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace( )) 45280 2. A subject sequence interpreted as an integer represented in some radix determined by the 45281 value of base 45282 3. A final string of one or more unrecognized characters, including the terminating null byte 45283 of the input string 45284 Then they shall attempt to convert the subject sequence to an unsigned integer, and return the | 45285 result. | 45286 If the value of base is 0, the expected form of the subject sequence is that of a decimal constant, 45287 octal constant, or hexadecimal constant, any of which may be preceded by a '+' or '-' sign. A 45288 decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An 45289 octal constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to 45290 '7' only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the 45291 decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively. 45292 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 45293 of letters and digits representing an integer with the radix specified by base, optionally preceded 45294 by a '+' or '-' sign. The letters from 'a' (or 'A') to 'z' (or 'Z') inclusive are ascribed the 45295 values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the 45296 value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and 45297 digits, following the sign if present. 45298 The subject sequence is defined as the longest initial subsequence of the input string, starting 45299 with the first non-white-space character that is of the expected form. The subject sequence shall | 45300 contain no characters if the input string is empty or consists entirely of white-space characters, | 45301 or if the first non-white-space character is other than a sign or a permissible letter or digit. 45302 If the subject sequence has the expected form and the value of base is 0, the sequence of | 45303 characters starting with the first digit shall be interpreted as an integer constant. If the subject | 45304 sequence has the expected form and the value of base is between 2 and 36, it shall be used as the | 45305 base for conversion, ascribing to each letter its value as given above. If the subject sequence | 45306 begins with a minus sign, the value resulting from the conversion shall be negated. A pointer to | 45307 the final string shall be stored in the object pointed to by endptr, provided that endptr is not a null | 45308 pointer. 1956 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtoul( ) 45309 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 45310 accepted. 45311 If the subject sequence is empty or does not have the expected form, no conversion shall be | 45312 performed; the value of str shall be stored in the object pointed to by endptr, provided that endptr | 45313 is not a null pointer. 45314 CX The strtoul( ) function shall not change the setting of errno if successful. 45315 Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and are also valid returns | 45316 on success, an application wishing to check for error situations should set errno to 0, then call 45317 strtoul( ) or strtoull( ), then check errno. 45318 RETURN VALUE 45319 Upon successful completion, these functions shall return the converted value, if any. If no 45320 CX conversion could be performed, 0 shall be returned and errno may be set to [EINVAL]. If the 45321 correct value is outside the range of representable values, {ULONG_MAX} or {ULLONG_MAX} 45322 shall be returned and errno set to [ERANGE]. 45323 ERRORS 45324 These functions shall fail if: 45325 CX [EINVAL] The value of base is not supported. 45326 [ERANGE] The value to be returned is not representable. 45327 These functions may fail if: 45328 CX [EINVAL] No conversion could be performed. 45329 EXAMPLES 45330 None. 45331 APPLICATION USAGE 45332 None. 45333 RATIONALE 45334 None. 45335 FUTURE DIRECTIONS 45336 None. 45337 SEE ALSO 45338 isalpha( ), scanf( ), strtod( ), strtol( ), the Base Definitions volume of IEEE Std 1003.1-200x, 45339 45340 CHANGE HISTORY 45341 First released in Issue 4. Derived from the ANSI C standard. 45342 Issue 5 45343 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 45344 Issue 6 45345 Extensions beyond the ISO C standard are now marked. 45346 The following new requirements on POSIX implementations derive from alignment with the 45347 Single UNIX Specification: 45348 * The [EINVAL] error condition is added for when the value of base is not supported. 45349 In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 45350 added if no conversion could be performed. System Interfaces, Issue 6 1957 strtoul( ) System Interfaces 45351 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 45352 * The strtoul( ) prototype is updated. 45353 * The strtoull( ) function is added. 1958 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strtoumax( ) 45354 NAME 45355 strtoumax - convert string to integer type 45356 SYNOPSIS 45357 #include 45358 uintmax_t strtoumax(const char *restrict nptr, char **restrict endptr, 45359 int base); 45360 DESCRIPTION 45361 Refer to strtoimax( ). System Interfaces, Issue 6 1959 strxfrm( ) System Interfaces 45362 NAME 45363 strxfrm - string transformation 45364 SYNOPSIS 45365 #include 45366 size_t strxfrm(char *restrict s1, const char *restrict s2, size_t n); 45367 DESCRIPTION 45368 CX The functionality described on this reference page is aligned with the ISO C standard. Any 45369 conflict between the requirements described here and the ISO C standard is unintentional. This 45370 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45371 The strxfrm( ) function shall transform the string pointed to by s2 and place the resulting string 45372 into the array pointed to by s1. The transformation is such that if strcmp( ) is applied to two 45373 transformed strings, it shall return a value greater than, equal to, or less than 0, corresponding to 45374 the result of strcoll( ) applied to the same two original strings. No more than n bytes are placed 45375 into the resulting array pointed to by s1, including the terminating null byte. If n is 0, s1 is 45376 permitted to be a null pointer. If copying takes place between objects that overlap, the behavior 45377 is undefined. 45378 CX The strxfrm( ) function shall not change the setting of errno if successful. 45379 Since no return value is reserved to indicate an error, an application wishing to check for error | 45380 situations should set errno to 0, then call strxfrm( ), then check errno. | 45381 RETURN VALUE 45382 Upon successful completion, strxfrm( ) shall return the length of the transformed string (not 45383 including the terminating null byte). If the value returned is n or more, the contents of the array 45384 pointed to by s1 are unspecified. | 45385 CX On error, strxfrm( ) may set errno but no return value is reserved to indicate an error. 45386 ERRORS 45387 The strxfrm( ) function may fail if: 45388 CX [EINVAL] The string pointed to by the s2 argument contains characters outside the 45389 domain of the collating sequence. 45390 EXAMPLES 45391 None. 45392 APPLICATION USAGE 45393 The transformation function is such that two transformed strings can be ordered by strcmp( ) as 45394 appropriate to collating sequence information in the program's locale (category LC_COLLATE). 45395 The fact that when n is 0 s1 is permitted to be a null pointer is useful to determine the size of the 45396 s1 array prior to making the transformation. 45397 RATIONALE 45398 None. 45399 FUTURE DIRECTIONS 45400 None. 45401 SEE ALSO 45402 strcmp( ), strcoll( ), the Base Definitions volume of IEEE Std 1003.1-200x, 1960 Technical Standard (2001) (Draft April 16, 2001) System Interfaces strxfrm( ) 45403 CHANGE HISTORY 45404 First released in Issue 3. 45405 Entry included for alignment with the ISO C standard. 45406 Issue 5 45407 The DESCRIPTION is updated to indicate that errno does not changed if the function is 45408 successful. 45409 Issue 6 45410 Extensions beyond the ISO C standard are now marked. 45411 The following new requirements on POSIX implementations derive from alignment with the 45412 Single UNIX Specification: 45413 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 45414 added if no conversion could be performed. 45415 The strxfrm( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 1961 swab( ) System Interfaces 45416 NAME 45417 swab - swap bytes 45418 SYNOPSIS 45419 XSI #include 45420 void swab(const void *restrict src, void *restrict dest, 45421 ssize_t nbytes); 45422 45423 DESCRIPTION 45424 The swab( ) function shall copy nbytes bytes, which are pointed to by src, to the object pointed to 45425 by dest, exchanging adjacent bytes. The nbytes argument should be even. If nbytes is odd, swab( ) 45426 copies and exchanges nbytes-1 bytes and the disposition of the last byte is unspecified. If 45427 copying takes place between objects that overlap, the behavior is undefined. If nbytes is 45428 negative, swab( ) does nothing. 45429 RETURN VALUE 45430 None. 45431 ERRORS 45432 No errors are defined. 45433 EXAMPLES 45434 None. 45435 APPLICATION USAGE 45436 None. 45437 RATIONALE 45438 None. 45439 FUTURE DIRECTIONS 45440 None. 45441 SEE ALSO 45442 The Base Definitions volume of IEEE Std 1003.1-200x, 45443 CHANGE HISTORY 45444 First released in Issue 1. Derived from Issue 1 of the SVID. 45445 Issue 6 45446 The restrict keyword is added to the swab( ) prototype for alignment with the 45447 ISO/IEC 9899: 1999 standard. 1962 Technical Standard (2001) (Draft April 16, 2001) System Interfaces swapcontext( ) 45448 NAME 45449 swapcontext - swap user context 45450 SYNOPSIS 45451 XSI #include 45452 int swapcontext(ucontext_t *restrict oucp, 45453 const ucontext_t *restrict ucp); 45454 45455 DESCRIPTION 45456 Refer to makecontext( ). System Interfaces, Issue 6 1963 swprintf( ) System Interfaces 45457 NAME 45458 swprintf - print formatted wide-character output 45459 SYNOPSIS 45460 #include 45461 #include 45462 int swprintf(wchar_t *ws, size_t n, const wchar_t *format, ...); 45463 DESCRIPTION 45464 Refer to fwprintf( ). 1964 Technical Standard (2001) (Draft April 16, 2001) System Interfaces swscanf( ) 45465 NAME 45466 swscanf - convert formatted wide-character input 45467 SYNOPSIS 45468 #include 45469 #include 45470 int swscanf(const wchar_t *restrict ws, | 45471 const wchar_t *restrict format, ... ); | 45472 DESCRIPTION | 45473 Refer to fwscanf( ). System Interfaces, Issue 6 1965 symlink( ) System Interfaces 45474 NAME 45475 symlink - make symbolic link to a file 45476 SYNOPSIS 45477 #include 45478 int symlink(const char *path1, const char *path2); 45479 DESCRIPTION 45480 The symlink( ) function shall create a symbolic link called path2 that contains the string pointed 45481 to by path1 (path2 is the name of the symbolic link created, path1 is the string contained in the 45482 symbolic link). 45483 The string pointed to by path1 shall be treated only as a character string and shall not be 45484 validated as a pathname. | 45485 If the symlink( ) function fails for any reason other than [EIO], any file named by path2 shall be 45486 unaffected. 45487 RETURN VALUE 45488 Upon successful completion, symlink( ) shall return 0; otherwise, it shall return -1 and set errno to 45489 indicate the error. 45490 ERRORS 45491 The symlink( ) function shall fail if: 45492 [EACCES] Write permission is denied in the directory where the symbolic link is being 45493 created, or search permission is denied for a component of the path prefix of 45494 path2. 45495 [EEXIST] The path2 argument names an existing file or symbolic link. 45496 [EIO] An I/O error occurs while reading from or writing to the file system. 45497 [ELOOP] A loop exists in symbolic links encountered during resolution of the path2 45498 argument. 45499 [ENAMETOOLONG] 45500 The length of the path2 argument exceeds {PATH_MAX} or a pathname | 45501 component is longer than {NAME_MAX} or the length of the path1 argument | 45502 is longer than {SYMLINK_MAX}. 45503 [ENOENT] A component of path2 does not name an existing file or path2 is an empty 45504 string. 45505 [ENOSPC] The directory in which the entry for the new symbolic link is being placed 45506 cannot be extended because no space is left on the file system containing the 45507 directory, or the new symbolic link cannot be created because no space is left 45508 on the file system which shall contain the link, or the file system is out of file- 45509 allocation resources. 45510 [ENOTDIR] A component of the path prefix of path2 is not a directory. 45511 [EROFS] The new symbolic link would reside on a read-only file system. 45512 The symlink( ) function may fail if: 45513 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 45514 resolution of the path2 argument. 45515 [ENAMETOOLONG] 45516 As a result of encountering a symbolic link in resolution of the path2 | 1966 Technical Standard (2001) (Draft April 16, 2001) System Interfaces symlink( ) 45517 argument, the length of the substituted pathname string exceeded | 45518 {PATH_MAX} bytes (including the terminating null byte), or the length of the 45519 string pointed to by path1 exceeded {SYMLINK_MAX}. 45520 EXAMPLES 45521 None. 45522 APPLICATION USAGE 45523 Like a hard link, a symbolic link allows a file to have multiple logical names. The presence of a 45524 hard link guarantees the existence of a file, even after the original name has been removed. A 45525 symbolic link provides no such assurance; in fact, the file named by the path1 argument need not 45526 exist when the link is created. A symbolic link can cross file system boundaries. 45527 Normal permission checks are made on each component of the symbolic link pathname during | 45528 its resolution. | 45529 RATIONALE 45530 Since IEEE Std 1003.1-200x does not require any association of file times with symbolic links, 45531 there is no requirement that file times be updated by symlink( ). 45532 FUTURE DIRECTIONS 45533 None. 45534 SEE ALSO 45535 lchown( ), link( ), lstat( ), open( ), readlink( ), unlink( ), the Base Definitions volume of 45536 IEEE Std 1003.1-200x, 45537 CHANGE HISTORY 45538 First released in Issue 4, Version 2. 45539 Issue 5 45540 Moved from X/OPEN UNIX extension to BASE. 45541 Issue 6 45542 The following changes were made to align with the IEEE P1003.1a draft standard: | 45543 * The DESCRIPTION text is updated. 45544 * The [ELOOP] optional error condition is added. System Interfaces, Issue 6 1967 sync( ) System Interfaces 45545 NAME 45546 sync - schedule file system updates 45547 SYNOPSIS 45548 XSI #include 45549 void sync(void); 45550 45551 DESCRIPTION 45552 The sync( ) function shall cause all information in memory that updates file systems to be 45553 scheduled for writing out to all file systems. 45554 The writing, although scheduled, is not necessarily complete upon return from sync( ). 45555 RETURN VALUE 45556 The sync( ) function shall not return a value. 45557 ERRORS 45558 No errors are defined. 45559 EXAMPLES 45560 None. 45561 APPLICATION USAGE 45562 None. 45563 RATIONALE 45564 None. 45565 FUTURE DIRECTIONS 45566 None. 45567 SEE ALSO 45568 fsync( ), the Base Definitions volume of IEEE Std 1003.1-200x, 45569 CHANGE HISTORY 45570 First released in Issue 4, Version 2. 45571 Issue 5 45572 Moved from X/OPEN UNIX extension to BASE. 1968 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sysconf( ) 45573 NAME 45574 sysconf - get configurable system variables 45575 SYNOPSIS 45576 #include 45577 long sysconf(int name); 45578 DESCRIPTION 45579 The sysconf( ) function provides a method for the application to determine the current value of a 45580 configurable system limit or option (variable). Support for some system variables is dependent 45581 on implementation options (as indicated by the margin codes in the following table). Where an 45582 implementation option is not supported, the variable need not be supported. 45583 The name argument represents the system variable to be queried. The following table lists the 45584 minimal set of system variables from or that can be returned by sysconf( ), 45585 and the symbolic constants, defined in that are the corresponding values used for 45586 name. Support for some configuration variables is dependent on implementation options (see 45587 shading and margin codes in the table below). Where an implementation option is not 45588 supported, the variable need not be supported. 45589 _____________________________________________________________________________________ 45590 Variable Value of Name _____________________________________________________________________________________ 45591 AIO {AIO_LISTIO_MAX} _SC_AIO_LISTIO_MAX 45592 {AIO_MAX} _SC_AIO_MAX 45593 {AIO_PRIO_DELTA_MAX} _SC_AIO_PRIO_DELTA_MAX 45594 {ARG_MAX} _SC_ARG_MAX 45595 XSI {ATEXIT_MAX} _SC_ATEXIT_MAX 45596 {BC_BASE_MAX} _SC_BC_BASE_MAX 45597 {BC_DIM_MAX} _SC_BC_DIM_MAX 45598 {BC_SCALE_MAX} _SC_BC_SCALE_MAX 45599 {BC_STRING_MAX} _SC_BC_STRING_MAX 45600 {CHILD_MAX} _SC_CHILD_MAX 45601 Clock ticks/second _SC_CLK_TCK 45602 {COLL_WEIGHTS_MAX} _SC_COLL_WEIGHTS_MAX 45603 XSI {DELAYTIMER_MAX} _SC_DELAYTIMER_MAX 45604 {EXPR_NEST_MAX} _SC_EXPR_NEST_MAX 45605 {HOST_NAME_MAX} _SC_HOST_NAME_MAX | 45606 XSI {IOV_MAX} _SC_IOV_MAX | 45607 {LINE_MAX} _SC_LINE_MAX 45608 {LOGIN_NAME_MAX} _SC_LOGIN_NAME_MAX 45609 {NGROUPS_MAX} _SC_NGROUPS_MAX 45610 TSF Maximum size of getgrgid_r( ) and _SC_GETGR_R_SIZE_MAX 45611 getgrnam_r( ) data buffers 45612 Maximum size of getpwuid_r( ) and _SC_GETPW_R_SIZE_MAX 45613 getpwnam_r( ) data buffers 45614 MSG {MQ_OPEN_MAX} _SC_MQ_OPEN_MAX 45615 {MQ_PRIO_MAX} _SC_MQ_PRIO_MAX 45616 {OPEN_MAX} _SC_OPEN_MAX _____________________________________________________________________________________ |||| System Interfaces, Issue 6 1969 sysconf( ) System Interfaces 45617 _____________________________________________________________________________________ | 45618 Variable Value of Name _____________________________________________________________________________________ || 45619 ADV _POSIX_ADVISORY_INFO _SC_ADVISORY_INFO | 45620 BAR _POSIX_BARRIERS _SC_BARRIERS 45621 AIO _POSIX_ASYNCHRONOUS_IO _SC_ASYNCHRONOUS_IO 45622 _POSIX_BASE _SC_BASE | 45623 _POSIX_C_LANG_SUPPORT _SC_C_LANG_SUPPORT 45624 _POSIX_C_LANG_SUPPORT_R _SC_C_LANG_SUPPORT_R 45625 CS _POSIX_CLOCK_SELECTION _SC_CLOCK_SELECTION 45626 CPT _POSIX_CPUTIME _SC_CPUTIME 45627 _POSIX_DEVICE_IO _SC_DEVICE_IO 45628 _POSIX_DEVICE_SPECIFIC _SC_DEVICE_SPECIFIC 45629 _POSIX_DEVICE_SPECIFIC_R _SC_DEVICE_SPECIFIC_R 45630 _POSIX_FD_MGMT _SC_FD_MGMT 45631 _POSIX_FIFO _SC_FIFO 45632 _POSIX_FILE_ATTRIBUTES _SC_FILE_ATTRIBUTES 45633 _POSIX_FILE_LOCKING _SC_FILE_LOCKING 45634 _POSIX_FILE_SYSTEM _SC_FILE_SYSTEM 45635 FSC _POSIX_FSYNC _SC_FSYNC 45636 _POSIX_JOB_CONTROL _SC_JOB_CONTROL 45637 MF _POSIX_MAPPED_FILES _SC_MAPPED_FILES 45638 ML _POSIX_MEMLOCK _SC_MEMLOCK 45639 MLR _POSIX_MEMLOCK_RANGE _SC_MEMLOCK_RANGE 45640 MPR _POSIX_MEMORY_PROTECTION _SC_MEMORY_PROTECTION 45641 MSG _POSIX_MESSAGE_PASSING _SC_MESSAGE_PASSING 45642 MON _POSIX_MONOTONIC_CLOCK _SC_MONOTONIC_CLOCK 45643 _POSIX_MULTI_PROCESS _SC_MULTI_PROCESS | 45644 _POSIX_NETWORKING _SC_NETWORKING | 45645 _POSIX_PIPE _SC_PIPE 45646 PIO _POSIX_PRIORITIZED_IO _SC_PRIORITIZED_IO 45647 PS _POSIX_PRIORITY_SCHEDULING _SC_PRIORITY_SCHEDULING 45648 THR _POSIX_READER_WRITER_LOCKS _SC_READER_WRITER_LOCKS 45649 RTS _POSIX_REALTIME_SIGNALS _SC_REALTIME_SIGNALS 45650 _POSIX_REGEXP _SC_REGEXP 45651 _POSIX_SAVED_IDS _SC_SAVED_IDS 45652 SEM _POSIX_SEMAPHORES _SC_SEMAPHORES 45653 SHM _POSIX_SHARED_MEMORY_OBJECTS _SC_SHARED_MEMORY_OBJECTS 45654 _POSIX_SHELL _SC_SHELL 45655 _POSIX_SIGNALS _SC_SIGNALS 45656 _POSIX_SINGLE_PROCESS _SC_SINGLE_PROCESS 45657 SPN _POSIX_SPAWN _SC_SPAWN 45658 SPI _POSIX_SPIN_LOCKS _SC_SPIN_LOCKS 45659 SS _POSIX_SPORADIC_SERVER _SC_SPORADIC_SERVER 45660 SIO _POSIX_SYNCHRONIZED_IO _SC_SYNCHRONIZED_IO 45661 _POSIX_SYSTEM_DATABASE _SC_SYSTEM_DATABASE 45662 _POSIX_SYSTEM_DATABASE_R _SC_SYSTEM_DATABASE_R _____________________________________________________________________________________ 1970 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sysconf( ) 45663 ______________________________________________________________________________________ 45664 _ Variable Value of Name _____________________________________________________________________________________ | 45665 TSA _POSIX_THREAD_ATTR_STACKADDR _SC_THREAD_ATTR_STACKADDR 45666 TSS _POSIX_THREAD_ATTR_STACKSIZE _SC_THREAD_ATTR_STACKSIZE 45667 TCT _POSIX_THREAD_CPUTIME _SC_THREAD_CPUTIME 45668 TPI _POSIX_THREAD_PRIO_INHERIT _SC_THREAD_PRIO_INHERIT 45669 TPP _POSIX_THREAD_PRIO_PROTECT _SC_THREAD_PRIO_PROTECT 45670 TPS _POSIX_THREAD_PRIORITY_SCHEDULING _SC_THREAD_PRIORITY_SCHEDULING 45671 TSH _POSIX_THREAD_PROCESS_SHARED _SC_THREAD_PROCESS_SHARED 45672 TSF _POSIX_THREAD_SAFE_FUNCTIONS _SC_THREAD_SAFE_FUNCTIONS 45673 TSP _POSIX_THREAD_SPORADIC_SERVER _SC_THREAD_SPORADIC_SERVER 45674 THR _POSIX_THREADS _SC_THREADS 45675 TMO _POSIX_TIMEOUTS _SC_TIMEOUTS 45676 TMR _POSIX_TIMERS _SC_TIMERS 45677 TRC _POSIX_TRACE _SC_TRACE 45678 TEF _POSIX_TRACE_EVENT_FILTER _SC_TRACE_EVENT_FILTER 45679 TRI _POSIX_TRACE_INHERIT _SC_TRACE_INHERIT 45680 TRL _POSIX_TRACE_LOG _SC_TRACE_LOG 45681 TYM _POSIX_TYPED_MEMORY_OBJECTS _SC_TYPED_MEMORY_OBJECTS 45682 _POSIX_USER_GROUPS _SC_USER_GROUPS 45683 _POSIX_USER_GROUPS_R _SC_USER_GROUPS_R 45684 _POSIX_VERSION _SC_VERSION 45685 _POSIX_V6_ILP32_OFF32 _SC_V6_ILP32_OFF32 45686 _POSIX_V6_ILP32_OFFBIG _SC_V6_ILP32_OFFBIG 45687 _POSIX_V6_LP64_OFF64 _SC_V6_LP64_OFF64 45688 _POSIX_V6_LPBIG_OFFBIG _SC_V6_LPBIG_OFFBIG 45689 _POSIX2_C_BIND _SC_2_C_BIND 45690 _POSIX2_C_DEV _SC_2_C_DEV 45691 _POSIX2_C_VERSION _SC_2_C_VERSION 45692 _POSIX2_CHAR_TERM _SC_2_CHAR_TERM 45693 _POSIX2_FORT_DEV _SC_2_FORT_DEV 45694 _POSIX2_FORT_RUN _SC_2_FORT_RUN 45695 _POSIX2_LOCALEDEF _SC_2_LOCALEDEF 45696 BE _POSIX2_PBS _SC_2_PBS 45697 _POSIX2_PBS_ACCOUNTING _SC_2_PBS_ACCOUNTING 45698 _POSIX2_PBS_LOCATE _SC_2_PBS_LOCATE 45699 _POSIX2_PBS_MESSAGE _SC_2_PBS_MESSAGE 45700 _POSIX2_PBS_TRACK _SC_2_PBS_TRACK 45701 _POSIX2_SW_DEV _SC_2_SW_DEV 45702 _POSIX2_UPE _SC_2_UPE 45703 _POSIX2_VERSION _SC_2_VERSION 45704 _REGEX_VERSION _SC_REGEX_VERSION 45705 XSI {PAGE_SIZE} _SC_PAGE_SIZE 45706 _ {PAGESIZE} _SC_PAGESIZE _____________________________________________________________________________________ System Interfaces, Issue 6 1971 sysconf( ) System Interfaces 45707 _____________________________________________________________________________________ 45708 _ Variable Value of Name ____________________________________________________________________________________ | 45709 THR {PTHREAD_DESTRUCTOR_ITERATIONS} _SC_THREAD_DESTRUCTOR_ITERATIONS 45710 {PTHREAD_KEYS_MAX} _SC_THREAD_KEYS_MAX 45711 {PTHREAD_STACK_MIN} _SC_THREAD_STACK_MIN 45712 {PTHREAD_THREADS_MAX} _SC_THREAD_THREADS_MAX 45713 {RE_DUP_MAX} _SC_RE_DUP_MAX 45714 RTS {RTSIG_MAX} _SC_RTSIG_MAX 45715 SEM {SEM_NSEMS_MAX} _SC_SEM_NSEMS_MAX 45716 {SEM_VALUE_MAX} _SC_SEM_VALUE_MAX 45717 RTS {SIGQUEUE_MAX} _SC_SIGQUEUE_MAX 45718 {STREAM_MAX} _SC_STREAM_MAX 45719 {SYMLOOP_MAX} _SC_SYMLOOP_MAX 45720 TMR {TIMER_MAX} _SC_TIMER_MAX 45721 {TTY_NAME_MAX} _SC_TTY_NAME_MAX 45722 {TZNAME_MAX} _SC_TZNAME_MAX 45723 XSI _XBS5_ILP32_OFF32 (LEGACY) _SC_XBS5_ILP32_OFF32 (LEGACY) 45724 _XBS5_ILP32_OFFBIG (LEGACY) _SC_XBS5_ILP32_OFFBIG (LEGACY) 45725 _XBS5_LP64_OFF64 (LEGACY) _SC_XBS5_LP64_OFF64 (LEGACY) 45726 _XBS5_LPBIG_OFFBIG (LEGACY) _SC_XBS5_LPBIG_OFFBIG (LEGACY) 45727 _XOPEN_CRYPT _SC_XOPEN_CRYPT 45728 _XOPEN_ENH_I18N _SC_XOPEN_ENH_I18N 45729 _XOPEN_LEGACY _SC_XOPEN_LEGACY 45730 _XOPEN_REALTIME _SC_XOPEN_REALTIME 45731 _XOPEN_REALTIME_THREADS _SC_XOPEN_REALTIME_THREADS 45732 _XOPEN_SHM _SC_XOPEN_SHM 45733 _XOPEN_UNIX _SC_XOPEN_UNIX 45734 _XOPEN_VERSION _SC_XOPEN_VERSION 45735 _ _XOPEN_XCU_VERSION _SC_XOPEN_XCU_VERSION ____________________________________________________________________________________ 45736 RETURN VALUE 45737 If name is an invalid value, sysconf( ) shall return -1 and set errno to indicate the error. If the 45738 variable corresponding to name has no limit, sysconf( ) shall return -1 without changing the value 45739 of errno. Note that indefinite limits do not imply infinite limits; see . 45740 Otherwise, sysconf( ) shall return the current variable value on the system. The value returned 45741 shall not be more restrictive than the corresponding value described to the application when it 45742 was compiled with the implementation's or . The value shall not change | 45743 during the lifetime of the calling process. | 45744 ERRORS 45745 The sysconf( ) function shall fail if: 45746 [EINVAL] The value of the name argument is invalid. 45747 EXAMPLES 45748 None. 45749 APPLICATION USAGE 45750 As -1 is a permissible return value in a successful situation, an application wishing to check for 45751 error situations should set errno to 0, then call sysconf( ), and, if it returns -1, check to see if errno 45752 is non-zero. 45753 If the value of sysconf(_SC_2_VERSION) is not equal to the value of the _POSIX2_VERSION 45754 symbolic constant, the utilities available via system( ) or popen( ) might not behave as described in 45755 the Shell and Utilities volume of IEEE Std 1003.1-200x. This would mean that the application is 1972 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sysconf( ) 45756 not running in an environment that conforms to the Shell and Utilities volume of 45757 IEEE Std 1003.1-200x. Some applications might be able to deal with this, others might not. 45758 However, the functions defined in this volume of IEEE Std 1003.1-200x continue to operate as 45759 specified, even if: sysconf(_SC_2_VERSION) reports that the utilities no longer perform as 45760 specified. 45761 RATIONALE 45762 This functionality was added in response to requirements of application developers and of 45763 system vendors who deal with many international system configurations. It is closely related to 45764 pathconf( ) and fpathconf( ). 45765 Although a conforming application can run on all systems by never demanding more resources | 45766 than the minimum values published in this volume of IEEE Std 1003.1-200x, it is useful for that 45767 application to be able to use the actual value for the quantity of a resource available on any 45768 given system. To do this, the application makes use of the value of a symbolic constant in 45769 or . 45770 However, once compiled, the application must still be able to cope if the amount of resource 45771 available is increased. To that end, an application may need a means of determining the quantity 45772 of a resource, or the presence of an option, at execution time. 45773 Two examples are offered: 45774 1. Applications may wish to act differently on systems with or without job control. 45775 Applications vendors who wish to distribute only a single binary package to all instances 45776 of a computer architecture would be forced to assume job control is never available if it 45777 were to rely solely on the value published in this volume of 45778 IEEE Std 1003.1-200x. 45779 2. International applications vendors occasionally require knowledge of the number of clock 45780 ticks per second. Without these facilities, they would be required to either distribute their 45781 applications partially in source form or to have 50Hz and 60Hz versions for the various 45782 countries in which they operate. 45783 It is the knowledge that many applications are actually distributed widely in executable form 45784 that leads to this facility. If limited to the most restrictive values in the headers, such 45785 applications would have to be prepared to accept the most limited environments offered by the 45786 smallest microcomputers. Although this is entirely portable, there was a consensus that they 45787 should be able to take advantage of the facilities offered by large systems, without the 45788 restrictions associated with source and object distributions. 45789 During the discussions of this feature, it was pointed out that it is almost always possible for an 45790 application to discern what a value might be at runtime by suitably testing the various functions 45791 themselves. And, in any event, it could always be written to adequately deal with error returns 45792 from the various functions. In the end, it was felt that this imposed an unreasonable level of 45793 complication and sophistication on the application writer. 45794 This runtime facility is not meant to provide ever-changing values that applications have to 45795 check multiple times. The values are seen as changing no more frequently than once per system 45796 initialization, such as by a system administrator or operator with an automatic configuration 45797 program. This volume of IEEE Std 1003.1-200x specifies that they shall not change within the 45798 lifetime of the process. 45799 Some values apply to the system overall and others vary at the file system or directory level. The 45800 latter are described in pathconf( ). 45801 Note that all values returned must be expressible as integers. String values were considered, but 45802 the additional flexibility of this approach was rejected due to its added complexity of System Interfaces, Issue 6 1973 sysconf( ) System Interfaces 45803 implementation and use. 45804 Some values, such as {PATH_MAX}, are sometimes so large that they must not be used to, say, 45805 allocate arrays. The sysconf( ) function returns a negative value to show that this symbolic 45806 constant is not even defined in this case. 45807 Similar to pathconf( ), this permits the implementation not to have a limit. When one resource is 45808 infinite, returning an error indicating that some other resource limit has been reached is 45809 conforming behavior. 45810 FUTURE DIRECTIONS 45811 None. 45812 SEE ALSO 45813 confstr( ), pathconf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 45814 , the Shell and Utilities volume of IEEE Std 1003.1-200x, getconf 45815 CHANGE HISTORY 45816 First released in Issue 3. 45817 Entry included for alignment with the POSIX.1-1988 standard. 45818 Issue 5 45819 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 45820 Threads Extension. 45821 The _XBS_ variables and name values are added to the table of system variables in the 45822 DESCRIPTION. These are all marked EX. 45823 Issue 6 45824 The symbol CLK_TCK is obsolescent and removed. It is replaced with the phrase ``clock ticks 45825 per second''. 45826 The symbol {PASS_MAX} is removed. 45827 The following changes were made to align with the IEEE P1003.1a draft standard: 45828 * Table entries added for the following variables: _SC_REGEXP, _SC_SHELL, 45829 _SC_REGEX_VERSION, _SC_SYMLOOP_MAX. 45830 The following sysconf( ) variables and their associated names are added for alignment with 45831 IEEE Std 1003.1d-1999: 45832 _POSIX_ADVISORY_INFO 45833 _POSIX_CPUTIME 45834 _POSIX_SPAWN 45835 _POSIX_SPORADIC_SERVER 45836 _POSIX_THREAD_CPUTIME 45837 _POSIX_THREAD_SPORADIC_SERVER 45838 _POSIX_TIMEOUTS 45839 The following changes are made to the DESCRIPTION for alignment with IEEE Std 1003.1j-2000: 45840 * A statement expressing the dependency of support for some system variables on 45841 implementation options is added. 45842 * The following system variables are added: 1974 Technical Standard (2001) (Draft April 16, 2001) System Interfaces sysconf( ) 45843 _POSIX_BARRIERS 45844 _POSIX_CLOCK_SELECTION 45845 _POSIX_MONOTONIC_CLOCK 45846 _POSIX_READER_WRITER_LOCKS 45847 _POSIX_SPIN_LOCKS 45848 _POSIX_TYPED_MEMORY_OBJECTS 45849 The following system variables are added for alignment with IEEE Std 1003.2d-1994: 45850 _POSIX2_PBS 45851 _POSIX2_PBS_ACCOUNTING 45852 _POSIX2_PBS_LOCATE 45853 _POSIX2_PBS_MESSAGE 45854 _POSIX2_PBS_TRACK 45855 The following sysconf( ) variables and their associated names are added for alignment with 45856 IEEE Std 1003.1q-2000: 45857 _POSIX_TRACE 45858 _POSIX_TRACE_EVENT_FILTER 45859 _POSIX_TRACE_INHERIT 45860 _POSIX_TRACE_LOG 45861 The macros associated with the c89 programming models are marked LEGACY, and new 45862 equivalent macros associated with c99 are introduced. System Interfaces, Issue 6 1975 syslog( ) System Interfaces 45863 NAME 45864 syslog - log a message 45865 SYNOPSIS 45866 XSI #include 45867 void syslog(int priority, const char *message, ... /* argument */); 45868 45869 DESCRIPTION 45870 Refer to closelog( ). 1976 Technical Standard (2001) (Draft April 16, 2001) System Interfaces system( ) 45871 NAME 45872 system - issue a command 45873 SYNOPSIS 45874 #include 45875 int system(const char *command); 45876 DESCRIPTION 45877 CX The functionality described on this reference page is aligned with the ISO C standard. Any 45878 conflict between the requirements described here and the ISO C standard is unintentional. This 45879 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 45880 If command is a null pointer, the system( ) function shall determine whether the host environment | 45881 has a command processor. If command is not a null pointer, the system( ) function shall pass the | 45882 string pointed to by command to that command processor to be executed in an implementation- | 45883 defined manner; this might then cause the program calling system( ) to behave in a non- 45884 conforming manner or to terminate. 45885 CX The environment of the executed command shall be as if a child process were created using | 45886 fork( ), and the child process invoked the sh utility using execl( ) as follows: 45887 execl(, "sh", "-c", command, (char *)0); 45888 where is an unspecified pathname for the sh utility. | 45889 The system( ) function shall ignore the SIGINT and SIGQUIT signals, and shall block the | 45890 SIGCHLD signal, while waiting for the command to terminate. If this might cause the | 45891 application to miss a signal that would have killed it, then the application should examine the 45892 return value from system( ) and take whatever action is appropriate to the application if the 45893 command terminated due to receipt of a signal. 45894 The system( ) function shall not affect the termination status of any child of the calling processes 45895 other than the process or processes it itself creates. 45896 The system( ) function shall not return until the child process has terminated. 45897 RETURN VALUE 45898 If command is a null pointer, system( ) shall return non-zero to indicate that a command processor 45899 CX is available, or zero if none is available. The system( ) function shall always return non-zero when | 45900 command is NULL. 45901 CX If command is not a null pointer, system( ) shall return the termination status of the command 45902 language interpreter in the format specified by waitpid( ). The termination status shall be as | 45903 defined for the sh utility; otherwise, the termination status is unspecified. If some error prevents | 45904 the command language interpreter from executing after the child process is created, the return 45905 value from system( ) shall be as if the command language interpreter had terminated using 45906 exit(127) or _exit(127). If a child process cannot be created, or if the termination status for the 45907 command language interpreter cannot be obtained, system( ) shall return -1 and set errno to 45908 indicate the error. 45909 ERRORS 45910 CX The system( ) function may set errno values as described by fork( ). 45911 In addition, system( ) may fail if: 45912 CX [ECHILD] The status of the child process created by system( ) is no longer available. System Interfaces, Issue 6 1977 system( ) System Interfaces 45913 EXAMPLES 45914 None. 45915 APPLICATION USAGE 45916 If the return value of system( ) is not -1, its value can be decoded through the use of the macros 45917 described in . For convenience, these macros are also provided in . 45918 Note that, while system( ) must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting | 45919 for the child to terminate, the handling of signals in the executed command is as specified by 45920 fork( ) and exec. For example, if SIGINT is being caught or is set to SIG_DFL when system( ) is 45921 called, then the child is started with SIGINT handling set to SIG_DFL. 45922 Ignoring SIGINT and SIGQUIT in the parent process prevents coordination problems (two 45923 processes reading from the same terminal, for example) when the executed command ignores or 45924 catches one of the signals. It is also usually the correct action when the user has given a 45925 command to the application to be executed synchronously (as in the '!' command in many 45926 interactive applications). In either case, the signal should be delivered only to the child process, 45927 not to the application itself. There is one situation where ignoring the signals might have less 45928 than the desired effect. This is when the application uses system( ) to perform some task invisible 45929 to the user. If the user typed the interrupt character (" C", for example) while system( ) is being 45930 used in this way, one would expect the application to be killed, but only the executed command 45931 is killed. Applications that use system( ) in this way should carefully check the return status from 45932 system( ) to see if the executed command was successful, and should take appropriate action 45933 when the command fails. 45934 Blocking SIGCHLD while waiting for the child to terminate prevents the application from 45935 catching the signal and obtaining status from system( )'s child process before system( ) can get the 45936 status itself. 45937 The context in which the utility is ultimately executed may differ from that in which system( ) 45938 was called. For example, file descriptors that have the FD_CLOEXEC flag set are closed, and the 45939 process ID and parent process ID are different. Also, if the executed utility changes its 45940 environment variables or its current working directory, that change is not reflected in the caller's 45941 context. 45942 There is no defined way for an application to find the specific path for the shell. However, 45943 confstr( ) can provide a value for PATH that is guaranteed to find the sh utility. 45944 RATIONALE 45945 The system( ) function should not be used by programs that have set user (or group) ID 45946 privileges. The fork( ) and exec family of functions (except execlp( ) and execvp( )), should be used 45947 instead. This prevents any unforeseen manipulation of the environment of the user that could 45948 cause execution of commands not anticipated by the calling program. 45949 There are three levels of specification for the system( ) function. The ISO C standard gives the 45950 most basic. It requires that the function exists, and defines a way for an application to query 45951 whether a command language interpreter exists. It says nothing about the command language or 45952 the environment in which the command is interpreted. 45953 IEEE Std 1003.1-200x places additional restrictions on system( ). It requires that if there is a 45954 command language interpreter, the environment must be as specified by fork( ) and exec. This 45955 ensures, for example, that close-on-exec works, that file locks are not inherited, and that the 45956 process ID is different. It also specifies the return value from system( ) when the command line 45957 can be run, thus giving the application some information about the command's completion 45958 statu. 1978 Technical Standard (2001) (Draft April 16, 2001) System Interfaces system( ) 45959 Finally, IEEE Std 1003.1-200x requires the command to be interpreted as in the shell command 45960 language defined in the Shell and Utilities volume of IEEE Std 1003.1-200x. 45961 Note that, system(NULL) is required to return non-zero, indicating that there is a command 45962 language interpreter. At first glance, this would seem to conflict with the ISO C standard which 45963 allows system(NULL) to return zero. There is no conflict, however. A system must have a 45964 command language interpreter, and is non-conforming if none is present. It is therefore 45965 permissible for the system( ) function on such a system to implement the behavior specified by 45966 the ISO C standard as long as it is understood that the implementation does not conform to 45967 IEEE Std 1003.1-200x if system(NULL) returns zero. 45968 It was explicitly decided that when command is NULL, system( ) should not be required to check 45969 to make sure that the command language interpreter actually exists with the correct mode, that 45970 there are enough processes to execute it, and so on. The call system(NULL) could, theoretically, 45971 check for such problems as too many existing child processes, and return zero. However, it 45972 would be inappropriate to return zero due to such a (presumably) transient condition. If some 45973 condition exists that is not under the control of this application and that would cause any 45974 system( ) call to fail, that system has been rendered non-conforming. 45975 Early drafts required, or allowed, system( ) to return with errno set to [EINTR] if it was 45976 interrupted with a signal. This error return was removed, and a requirement that system( ) not 45977 return until the child has terminated was added. This means that if a waitpid( ) call in system( ) 45978 exits with errno set to [EINTR], system( ) must re-issue the waitpid( ). This change was made for 45979 two reasons: 45980 1. There is no way for an application to clean up if system( ) returns [EINTR], short of calling 45981 wait( ), and that could have the undesirable effect of returning the status of children other 45982 than the one started by system( ). 45983 2. While it might require a change in some historical implementations, those 45984 implementations already have to be changed because they use wait( ) instead of waitpid( ). 45985 Note that if the application is catching SIGCHLD signals, it will receive such a signal before a 45986 successful system( ) call returns. 45987 To conform to IEEE Std 1003.1-200x, system( ) must use waitpid( ), or some similar function, 45988 instead of wait( ). 45989 The following code sample illustrates how system( ) might be implemented on an 45990 implementation conforming to IEEE Std 1003.1-200x. 45991 #include 45992 int system(const char *cmd) 45993 { 45994 int stat; 45995 pid_t pid; 45996 struct sigaction sa, savintr, savequit; 45997 sigset_t saveblock; 45998 if (cmd == NULL) 45999 return(1); 46000 sa.sa_handler = SIG_IGN; 46001 sigemptyset(&sa.sa_mask); 46002 sa.sa_flags = 0; 46003 sigemptyset(&savintr.sa_mask); 46004 sigemptyset(&savequit.sa_mask); 46005 sigaction(SIGINT, &sa, &savintr); 46006 sigaction(SIGQUIT, &sa, &savequit); System Interfaces, Issue 6 1979 system( ) System Interfaces 46007 sigaddset(&sa.sa_mask, SIGCHLD); 46008 sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock); 46009 if ((pid = fork()) == 0) { 46010 sigaction(SIGINT, &savintr, (struct sigaction *)0); 46011 sigaction(SIGQUIT, &savequit, (struct sigaction *)0); 46012 sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); 46013 execl("/bin/sh", "sh", "-c", cmd, (char *)0); 46014 _exit(127); 46015 } 46016 if (pid == -1) { 46017 stat = -1; /* errno comes from fork() */ 46018 } else { 46019 while (waitpid(pid, &stat, 0) == -1) { 46020 if (errno != EINTR){ 46021 stat = -1; 46022 break; 46023 } 46024 } 46025 } 46026 sigaction(SIGINT, &savintr, (struct sigaction *)0); 46027 sigaction(SIGQUIT, &savequit, (struct sigaction *)0); 46028 sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); 46029 return(stat); 46030 } 46031 Note that, while a particular implementation of system( ) (such as the one above) can assume a 46032 particular path for the shell, such a path is not necessarily valid on another system. The above 46033 example is not portable, and is not intended to be. 46034 One reviewer suggested that an implementation of system( ) might want to use an environment 46035 variable such as SHELL to determine which command interpreter to use. The supposed 46036 implementation would use the default command interpreter if the one specified by the 46037 environment variable was not available. This would allow a user, when using an application 46038 that prompts for command lines to be processed using system( ), to specify a different command 46039 interpreter. Such an implementation is discouraged. If the alternate command interpreter did not 46040 follow the command line syntax specified in the Shell and Utilities volume of 46041 IEEE Std 1003.1-200x, then changing SHELL would render system( ) non-conforming. This would 46042 affect applications that expected the specified behavior from system( ), and since the Shell and 46043 Utilities volume of IEEE Std 1003.1-200x does not mention that SHELL affects system( ), the 46044 application would not know that it needed to unset SHELL. 46045 FUTURE DIRECTIONS 46046 None. 46047 SEE ALSO 46048 exec, pipe( ), waitpid( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 46049 , , , the Shell and Utilities volume of IEEE Std 1003.1-200x, sh | 46050 CHANGE HISTORY 46051 First released in Issue 1. Derived from Issue 1 of the SVID. | 1980 Technical Standard (2001) (Draft April 16, 2001) System Interfaces system( ) 46052 Issue 6 | 46053 The following changes were made to align with the IEEE P1003.1a draft standard: 46054 * The DESCRIPTION is adjusted to reflect the behavior on systems that do not support the 46055 Shell option. System Interfaces, Issue 6 1981 tan( ) System Interfaces 46056 NAME 46057 tan, tanf, tanl - tangent function 46058 SYNOPSIS 46059 #include 46060 double tan(double x); 46061 float tanf(float x); 46062 long double tanl(long double x); 46063 DESCRIPTION 46064 CX The functionality described on this reference page is aligned with the ISO C standard. Any 46065 conflict between the requirements described here and the ISO C standard is unintentional. This 46066 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 46067 These functions shall compute the tangent of their argument x, measured in radians. 46068 An application wishing to check for error situations should set errno to zero and call 46069 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 46070 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 46071 zero, an error has occurred. 46072 RETURN VALUE 46073 Upon successful completion, these functions shall return the tangent of x. 46074 If the correct value would cause underflow, and is not representable, a range error may occur, 46075 MX and either 0.0 (if supported), or an implementation-defined value shall be returned. 46076 MX If x is NaN, a NaN shall be returned. 46077 If x is ±0, x shall be returned. 46078 If x is subnormal, a range error may occur and x should be returned. 46079 If x is ±Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 46080 defined value shall be returned. 46081 If the correct value would cause underflow, and is representable, a range error may occur and 46082 the correct value shall be returned. 46083 XSI If the correct value would cause overflow, a range error shall occur and tan( ), tanf( ), and tanl( ) 46084 shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively. 46085 ERRORS 46086 These functions shall fail if: 46087 MX Domain Error The value x is ±Inf. 46088 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46089 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 46090 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 46091 shall be raised. | 46092 XSI Range Error The result overflows 46093 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46094 then errno shall be set to [ERANGE]. If the integer expression | 46095 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 46096 floating-point exception shall be raised. | 46097 These functions may fail if: 1982 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tan( ) 46098 MX Range Error The result underflows, or the value x is subnormal. 46099 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46100 then errno shall be set to [ERANGE]. If the integer expression | 46101 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 46102 floating-point exception shall be raised. | 46103 EXAMPLES 46104 Taking the Tangent of a 45-Degree Angle 46105 #include 46106 ... 46107 double radians = 45.0 * M_PI / 180; 46108 double result; 46109 ... 46110 result = tan (radians); 46111 APPLICATION USAGE 46112 There are no known floating-point representations such that for a normal argument, tan(x) is 46113 either overflow or underflow. 46114 These functions may lose accuracy when their argument is near a multiple of /2 or is far from 46115 0.0. 46116 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 46117 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 46118 RATIONALE 46119 None. 46120 FUTURE DIRECTIONS 46121 None. 46122 SEE ALSO 46123 atan( ), feclearexcept( ), fetestexcept( ), isnan( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 46124 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 46125 CHANGE HISTORY 46126 First released in Issue 1. Derived from Issue 1 of the SVID. 46127 Issue 5 46128 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 46129 in previous issues. 46130 Issue 6 46131 The tanf( ) and tanl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 46132 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 46133 revised to align with the ISO/IEC 9899: 1999 standard. 46134 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 46135 marked. System Interfaces, Issue 6 1983 tanf( ) System Interfaces 46136 NAME 46137 tanf - tangent function 46138 SYNOPSIS 46139 #include 46140 float tanf(float x); 46141 DESCRIPTION 46142 Refer to tan( ). 1984 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tanh( ) 46143 NAME 46144 tanh, tanhf, tanhl - hyperbolic tangent functions 46145 SYNOPSIS 46146 #include 46147 double tanh(double x); 46148 float tanhf(float x); 46149 long double tanhl(long double x); 46150 DESCRIPTION 46151 CX The functionality described on this reference page is aligned with the ISO C standard. Any 46152 conflict between the requirements described here and the ISO C standard is unintentional. This 46153 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 46154 These functions shall compute the hyperbolic tangent of their argument x. 46155 An application wishing to check for error situations should set errno to zero and call 46156 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 46157 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 46158 zero, an error has occurred. 46159 RETURN VALUE 46160 Upon successful completion, these functions shall return the hyperbolic tangent of x. 46161 MX If x is NaN, a NaN shall be returned. 46162 If x is ±0, x shall be returned. 46163 If x is ±Inf, ±1 shall be returned. 46164 If x is subnormal, a range error may occur and x should be returned. 46165 ERRORS 46166 These functions may fail if: 46167 MX Range Error The value of x is subnormal. 46168 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46169 then errno shall be set to [ERANGE]. If the integer expression | 46170 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 46171 floating-point exception shall be raised. | 46172 EXAMPLES 46173 None. 46174 APPLICATION USAGE 46175 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 46176 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 46177 RATIONALE 46178 None. 46179 FUTURE DIRECTIONS 46180 None. 46181 SEE ALSO 46182 atanh( ), feclearexcept( ), fetestexcept( ), isnan( ), tan( ), the Base Definitions volume of | 46183 IEEE Std 1003.1-200x, Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 46184 System Interfaces, Issue 6 1985 tanh( ) System Interfaces 46185 CHANGE HISTORY 46186 First released in Issue 1. Derived from Issue 1 of the SVID. 46187 Issue 5 46188 The DESCRIPTION is updated to indicate how an application should check for an error. This 46189 text was previously published in the APPLICATION USAGE section. 46190 Issue 6 46191 The tanhf( ) and tanhl( ) functions are added for alignment with the ISO/IEC 9899: 1999 standard. 46192 The DESCRIPTION, RETURN VALUE, ERRORS, and APPLICATION USAGE sections are 46193 revised to align with the ISO/IEC 9899: 1999 standard. 46194 IEC 60559: 1989 standard floating-point extensions over the ISO/IEC 9899: 1999 standard are 46195 marked. 1986 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tanl( ) 46196 NAME 46197 tanl - tangent function 46198 SYNOPSIS 46199 #include 46200 long double tanl(long double x); 46201 DESCRIPTION 46202 Refer to tan( ). System Interfaces, Issue 6 1987 tcdrain( ) System Interfaces 46203 NAME 46204 tcdrain - wait for transmission of output 46205 SYNOPSIS 46206 #include 46207 int tcdrain(int fildes); 46208 DESCRIPTION 46209 The tcdrain( ) function shall block until all output written to the object referred to by fildes is | 46210 transmitted. The fildes argument is an open file descriptor associated with a terminal. 46211 Any attempts to use tcdrain( ) from a process which is a member of a background process group 46212 on a fildes associated with its controlling terminal, shall cause the process group to be sent a 46213 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process | 46214 shall be allowed to perform the operation, and no signal is sent. | 46215 RETURN VALUE 46216 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46217 indicate the error. 46218 ERRORS 46219 The tcdrain( ) function shall fail if: 46220 [EBADF] The fildes argument is not a valid file descriptor. 46221 [EINTR] A signal interrupted tcdrain( ). 46222 [ENOTTY] The file associated with fildes is not a terminal. 46223 The tcdrain( ) function may fail if: 46224 [EIO] The process group of the writing process is orphaned, and the writing process 46225 is not ignoring or blocking SIGTTOU. 46226 EXAMPLES 46227 None. 46228 APPLICATION USAGE 46229 None. 46230 RATIONALE 46231 None. 46232 FUTURE DIRECTIONS 46233 None. 46234 SEE ALSO 46235 tcflush( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the Base 46236 Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface 46237 CHANGE HISTORY 46238 First released in Issue 3. 46239 Entry included for alignment with the POSIX.1-1988 standard. 46240 Issue 6 46241 The following new requirements on POSIX implementations derive from alignment with the 46242 Single UNIX Specification: 46243 * In the DESCRIPTION, the final paragraph is no longer conditional on 46244 _POSIX_JOB_CONTROL. This is a FIPS requirement. 1988 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcdrain( ) 46245 * The [EIO] error is added. System Interfaces, Issue 6 1989 tcflow( ) System Interfaces 46246 NAME 46247 tcflow - suspend or restart the transmission or reception of data 46248 SYNOPSIS 46249 #include 46250 int tcflow(int fildes, int action); 46251 DESCRIPTION 46252 The tcflow( ) function shall suspend or restart transmission or reception of data on the object 46253 referred to by fildes, depending on the value of action. The fildes argument is an open file 46254 descriptor associated with a terminal. 46255 * If action is TCOOFF, output shall be suspended. 46256 * If action is TCOON, suspended output shall be restarted. 46257 * If action is TCIOFF, the system shall transmit a STOP character, which is intended to cause 46258 the terminal device to stop transmitting data to the system. 46259 * If action is TCION, the system shall transmit a START character, which is intended to cause 46260 the terminal device to start transmitting data to the system. 46261 The default on the opening of a terminal file is that neither its input nor its output are 46262 suspended. 46263 Attempts to use tcflow( ) from a process which is a member of a background process group on a 46264 fildes associated with its controlling terminal, shall cause the process group to be sent a 46265 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process | 46266 shall be allowed to perform the operation, and no signal is sent. | 46267 RETURN VALUE 46268 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46269 indicate the error. 46270 ERRORS 46271 The tcflow( ) function shall fail if: 46272 [EBADF] The fildes argument is not a valid file descriptor. 46273 [EINVAL] The action argument is not a supported value. 46274 [ENOTTY] The file associated with fildes is not a terminal. 46275 The tcflow( ) function may fail if: 46276 [EIO] The process group of the writing process is orphaned, and the writing process 46277 is not ignoring or blocking SIGTTOU. 46278 EXAMPLES 46279 None. 46280 APPLICATION USAGE 46281 None. 46282 RATIONALE 46283 None. 46284 FUTURE DIRECTIONS 46285 None. 1990 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcflow( ) 46286 SEE ALSO 46287 tcsendbreak( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the 46288 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface 46289 CHANGE HISTORY 46290 First released in Issue 3. 46291 Entry included for alignment with the POSIX.1-1988 standard. 46292 Issue 6 46293 The following new requirements on POSIX implementations derive from alignment with the 46294 Single UNIX Specification: 46295 * The [EIO] error is added. System Interfaces, Issue 6 1991 tcflush( ) System Interfaces 46296 NAME 46297 tcflush - flush non-transmitted output data, non-read input data, or both 46298 SYNOPSIS 46299 #include 46300 int tcflush(int fildes, int queue_selector); 46301 DESCRIPTION 46302 Upon successful completion, tcflush( ) shall discard data written to the object referred to by fildes 46303 (an open file descriptor associated with a terminal) but not transmitted, or data received but not 46304 read, depending on the value of queue_selector: 46305 * If queue_selector is TCIFLUSH, it shall flush data received but not read. 46306 * If queue_selector is TCOFLUSH, it shall flush data written but not transmitted. 46307 * If queue_selector is TCIOFLUSH, it shall flush both data received but not read and data 46308 written but not transmitted. 46309 Attempts to use tcflush( ) from a process which is a member of a background process group on a 46310 fildes associated with its controlling terminal shall cause the process group to be sent a SIGTTOU | 46311 signal. If the calling process is blocking or ignoring SIGTTOU signals, the process shall be | 46312 allowed to perform the operation, and no signal is sent. | 46313 RETURN VALUE 46314 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46315 indicate the error. 46316 ERRORS 46317 The tcflush( ) function shall fail if: 46318 [EBADF] The fildes argument is not a valid file descriptor. 46319 [EINVAL] The queue_selector argument is not a supported value. 46320 [ENOTTY] The file associated with fildes is not a terminal. 46321 The tcflush( ) function may fail if: 46322 [EIO] The process group of the writing process is orphaned, and the writing process 46323 is not ignoring or blocking SIGTTOU. 46324 EXAMPLES 46325 None. 46326 APPLICATION USAGE 46327 None. 46328 RATIONALE 46329 None. 46330 FUTURE DIRECTIONS 46331 None. 46332 SEE ALSO 46333 tcdrain( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the 46334 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface 1992 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcflush( ) 46335 CHANGE HISTORY 46336 First released in Issue 3. 46337 Entry included for alignment with the POSIX.1-1988 standard. 46338 Issue 6 46339 The Open Group Corrigendum U035/1 is applied. In the ERRORS and APPLICATION USAGE 46340 sections, references to tcflow( ) are replaced with tcflush( ). 46341 The following new requirements on POSIX implementations derive from alignment with the 46342 Single UNIX Specification: 46343 * In the DESCRIPTION, the final paragraph is no longer conditional on 46344 _POSIX_JOB_CONTROL. This is a FIPS requirement. 46345 * The [EIO] error is added. System Interfaces, Issue 6 1993 tcgetattr( ) System Interfaces 46346 NAME 46347 tcgetattr - get the parameters associated with the terminal 46348 SYNOPSIS 46349 #include 46350 int tcgetattr(int fildes, struct termios *termios_p); 46351 DESCRIPTION 46352 The tcgetattr( ) function shall get the parameters associated with the terminal referred to by fildes 46353 and store them in the termios structure referenced by termios_p. The fildes argument is an open 46354 file descriptor associated with a terminal. 46355 The termios_p argument is a pointer to a termios structure. 46356 The tcgetattr( ) operation is allowed from any process. 46357 If the terminal device supports different input and output baud rates, the baud rates stored in 46358 the termios structure returned by tcgetattr( ) shall reflect the actual baud rates, even if they are 46359 equal. If differing baud rates are not supported, the rate returned as the output baud rate shall be 46360 the actual baud rate. If the terminal device does not support split baud rates, the input baud rate 46361 stored in the termios structure shall be the output rate (as one of the symbolic values). 46362 RETURN VALUE 46363 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46364 indicate the error. 46365 ERRORS 46366 The tcgetattr( ) function shall fail if: 46367 [EBADF] The fildes argument is not a valid file descriptor. 46368 [ENOTTY] The file associated with fildes is not a terminal. 46369 EXAMPLES 46370 None. 46371 APPLICATION USAGE 46372 None. 46373 RATIONALE 46374 Care must be taken when changing the terminal attributes. Applications should always do a 46375 tcgetattr( ), save the termios structure values returned, and then do a tcsetattr( ) changing only 46376 the necessary fields. The application should use the values saved from the tcgetattr( ) to reset the 46377 terminal state whenever it is done with the terminal. This is necessary because terminal 46378 attributes apply to the underlying port and not to each individual open instance; that is, all 46379 processes that have used the terminal see the latest attribute changes. 46380 A program that uses these functions should be written to catch all signals and take other 46381 appropriate actions to ensure that when the program terminates, whether planned or not, the 46382 terminal device's state is restored to its original state. 46383 Existing practice dealing with error returns when only part of a request can be honored is based 46384 on calls to the ioctl( ) function. In historical BSD and System V implementations, the 46385 corresponding ioctl( ) returns zero if the requested actions were semantically correct, even if 46386 some of the requested changes could not be made. Many existing applications assume this 46387 behavior and would no longer work correctly if the return value were changed from zero to -1 46388 in this case. 1994 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcgetattr( ) 46389 Note that either specification has a problem. When zero is returned, it implies everything 46390 succeeded even if some of the changes were not made. When -1 is returned, it implies 46391 everything failed even though some of the changes were made. 46392 Applications that need all of the requested changes made to work properly should follow 46393 tcsetattr( ) with a call to tcgetattr( ) and compare the appropriate field values. 46394 FUTURE DIRECTIONS 46395 None. 46396 SEE ALSO 46397 tcsetattr( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base 46398 Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface 46399 CHANGE HISTORY 46400 First released in Issue 3. 46401 Entry included for alignment with the POSIX.1-1988 standard. 46402 Issue 6 46403 In the DESCRIPTION, the rate returned as the input baud rate shall be the output rate. 46404 Previously, the number zero was also allowed but was obsolescent. System Interfaces, Issue 6 1995 tcgetpgrp( ) System Interfaces 46405 NAME 46406 tcgetpgrp - get the foreground process group ID 46407 SYNOPSIS 46408 #include 46409 pid_t tcgetpgrp(int fildes); 46410 DESCRIPTION 46411 The tcgetpgrp( ) function shall return the value of the process group ID of the foreground process 46412 group associated with the terminal. 46413 If there is no foreground process group, tcgetpgrp( ) shall return a value greater than 1 that does 46414 not match the process group ID of any existing process group. 46415 The tcgetpgrp( ) function is allowed from a process that is a member of a background process 46416 group; however, the information may be subsequently changed by a process that is a member of 46417 a foreground process group. 46418 RETURN VALUE 46419 Upon successful completion, tcgetpgrp( ) shall return the value of the process group ID of the 46420 foreground process associated with the terminal. Otherwise, -1 shall be returned and errno set to 46421 indicate the error. 46422 ERRORS 46423 The tcgetpgrp( ) function shall fail if: 46424 [EBADF] The fildes argument is not a valid file descriptor. 46425 [ENOTTY] The calling process does not have a controlling terminal, or the file is not the 46426 controlling terminal. 46427 EXAMPLES 46428 None. 46429 APPLICATION USAGE 46430 None. 46431 RATIONALE 46432 None. 46433 FUTURE DIRECTIONS 46434 None. 46435 SEE ALSO 46436 setsid( ), setpgid( ), tcsetpgrp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 46437 , 46438 CHANGE HISTORY 46439 First released in Issue 3. 46440 Entry included for alignment with the POSIX.1-1988 standard. 46441 Issue 6 46442 In the SYNOPSIS, the optional include of the header is removed. 46443 The following new requirements on POSIX implementations derive from alignment with the 46444 Single UNIX Specification: 46445 * The requirement to include has been removed. Although was 46446 required for conforming implementations of previous POSIX specifications, it was not 46447 required for UNIX applications. 1996 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcgetpgrp( ) 46448 * In the DESCRIPTION, text previously conditional on support for _POSIX_JOB_CONTROL is 46449 now mandatory. This is a FIPS requirement. System Interfaces, Issue 6 1997 tcgetsid( ) System Interfaces 46450 NAME 46451 tcgetsid - get process group ID for session leader for controlling terminal 46452 SYNOPSIS 46453 XSI #include 46454 pid_t tcgetsid(int fildes); 46455 46456 DESCRIPTION 46457 The tcgetsid( ) function shall obtain the process group ID of the session for which the terminal 46458 specified by fildes is the controlling terminal. 46459 RETURN VALUE 46460 Upon successful completion, tcgetsid( ) shall return the process group ID associated with the 46461 terminal. Otherwise, a value of (pid_t)-1 shall be returned and errno set to indicate the error. 46462 ERRORS 46463 The tcgetsid( ) function shall fail if: 46464 [EBADF] The fildes argument is not a valid file descriptor. 46465 [ENOTTY] The calling process does not have a controlling terminal, or the file is not the 46466 controlling terminal. 46467 EXAMPLES 46468 None. 46469 APPLICATION USAGE 46470 None. 46471 RATIONALE 46472 None. 46473 FUTURE DIRECTIONS 46474 None. 46475 SEE ALSO 46476 The Base Definitions volume of IEEE Std 1003.1-200x, 46477 CHANGE HISTORY 46478 First released in Issue 4, Version 2. 46479 Issue 5 46480 Moved from X/OPEN UNIX extension to BASE. 46481 The [EACCES] error has been removed from the list of mandatory errors, and the description of 46482 [ENOTTY] has been reworded. 1998 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcsendbreak( ) 46483 NAME 46484 tcsendbreak - send a ``break'' for a specific duration 46485 SYNOPSIS 46486 #include 46487 int tcsendbreak(int fildes, int duration); 46488 DESCRIPTION 46489 If the terminal is using asynchronous serial data transmission, tcsendbreak( ) shall cause | 46490 transmission of a continuous stream of zero-valued bits for a specific duration. If duration is 0, it 46491 shall cause transmission of zero-valued bits for at least 0,25 seconds, and not more than 0,5 46492 seconds. If duration is not 0, it shall send zero-valued bits for an implementation-defined period 46493 of time. 46494 The fildes argument is an open file descriptor associated with a terminal. | 46495 If the terminal is not using asynchronous serial data transmission, it is implementation-defined | 46496 whether tcsendbreak( ) sends data to generate a break condition or returns without taking any 46497 action. 46498 Attempts to use tcsendbreak( ) from a process which is a member of a background process group 46499 on a fildes associated with its controlling terminal shall cause the process group to be sent a | 46500 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process | 46501 shall be allowed to perform the operation, and no signal is sent. | 46502 RETURN VALUE 46503 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46504 indicate the error. 46505 ERRORS 46506 The tcsendbreak( ) function shall fail if: 46507 [EBADF] The fildes argument is not a valid file descriptor. 46508 [ENOTTY] The file associated with fildes is not a terminal. 46509 The tcsendbreak( ) function may fail if: 46510 [EIO] The process group of the writing process is orphaned, and the writing process 46511 is not ignoring or blocking SIGTTOU. 46512 EXAMPLES 46513 None. 46514 APPLICATION USAGE 46515 None. 46516 RATIONALE 46517 None. 46518 FUTURE DIRECTIONS 46519 None. 46520 SEE ALSO 46521 The Base Definitions volume of IEEE Std 1003.1-200x, , , the Base 46522 Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal Interface System Interfaces, Issue 6 1999 tcsendbreak( ) System Interfaces 46523 CHANGE HISTORY 46524 First released in Issue 3. 46525 Entry included for alignment with the POSIX.1-1988 standard. 46526 Issue 6 46527 The following new requirements on POSIX implementations derive from alignment with the 46528 Single UNIX Specification: 46529 * In the DESCRIPTION, text previously conditional on _POSIX_JOB_CONTROL is now 46530 mandated. This is a FIPS requirement. 46531 * The [EIO] error is added. 2000 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcsetattr( ) 46532 NAME 46533 tcsetattr - set the parameters associated with the terminal 46534 SYNOPSIS 46535 #include 46536 int tcsetattr(int fildes, int optional_actions, 46537 const struct termios *termios_p); 46538 DESCRIPTION 46539 The tcsetattr( ) function shall set the parameters associated with the terminal referred to by the 46540 open file descriptor fildes (an open file descriptor associated with a terminal) from the termios 46541 structure referenced by termios_p as follows: 46542 * If optional_actions is TCSANOW, the change shall occur immediately. 46543 * If optional_actions is TCSADRAIN, the change shall occur after all output written to fildes is 46544 transmitted. This function should be used when changing parameters that affect output. 46545 * If optional_actions is TCSAFLUSH, the change shall occur after all output written to fildes is 46546 transmitted, and all input so far received but not read shall be discarded before the change is 46547 made. 46548 If the output baud rate stored in the termios structure pointed to by termios_p is the zero baud 46549 rate, B0, the modem control lines shall no longer be asserted. Normally, this shall disconnect the 46550 line. 46551 If the input baud rate stored in the termios structure pointed to by termios_p is 0, the input baud 46552 rate given to the hardware is the same as the output baud rate stored in the termios structure. 46553 The tcsetattr( ) function shall return successfully if it was able to perform any of the requested 46554 actions, even if some of the requested actions could not be performed. It shall set all the 46555 attributes that the implementation supports as requested and leaves all the attributes not 46556 supported by the implementation unchanged. If no part of the request can be honored, it shall 46557 return -1 and set errno to [EINVAL]. If the input and output baud rates differ and are a 46558 combination that is not supported, neither baud rate shall be changed. A subsequent call to | 46559 tcgetattr( ) shall return the actual state of the terminal device (reflecting both the changes made 46560 and not made in the previous tcsetattr( ) call). The tcsetattr( ) function shall not change the values 46561 found in the termios structure under any circumstances. 46562 The effect of tcsetattr( ) is undefined if the value of the termios structure pointed to by termios_p 46563 was not derived from the result of a call to tcgetattr( ) on fildes; an application should modify 46564 only fields and flags defined by this volume of IEEE Std 1003.1-200x between the call to 46565 tcgetattr( ) and tcsetattr( ), leaving all other fields and flags unmodified. 46566 No actions defined by this volume of IEEE Std 1003.1-200x, other than a call to tcsetattr( ) or a 46567 close of the last file descriptor in the system associated with this terminal device, shall cause any 46568 of the terminal attributes defined by this volume of IEEE Std 1003.1-200x to change. 46569 If tcsetattr( ) is called from a process which is a member of a background process group on a 46570 fildes associated with its controlling terminal: 46571 * If the calling process is blocking or ignoring SIGTTOU signals, the operation completes 46572 normally and no signal is sent. 46573 * Otherwise, a SIGTTOU signal shall be sent to the process group. System Interfaces, Issue 6 2001 tcsetattr( ) System Interfaces 46574 RETURN VALUE 46575 Upon successful completion, 0 shall be shall be returned. Otherwise, -1 shall be returned and | 46576 errno set to indicate the error. 46577 ERRORS 46578 The tcsetattr( ) function shall fail if: 46579 [EBADF] The fildes argument is not a valid file descriptor. 46580 [EINTR] A signal interrupted tcsetattr( ). 46581 [EINVAL] The optional_actions argument is not a supported value, or an attempt was 46582 made to change an attribute represented in the termios structure to an 46583 unsupported value. 46584 [ENOTTY] The file associated with fildes is not a terminal. 46585 The tcsetattr( ) function may fail if: 46586 [EIO] The process group of the writing process is orphaned, and the writing process 46587 is not ignoring or blocking SIGTTOU. 46588 EXAMPLES 46589 None. 46590 APPLICATION USAGE 46591 If trying to change baud rates, applications should call tcsetattr( ) then call tcgetattr( ) in order to 46592 determine what baud rates were actually selected. 46593 RATIONALE 46594 The tcsetattr( ) function can be interrupted in the following situations: 46595 * It is interrupted while waiting for output to drain. 46596 * It is called from a process in a background process group and SIGTTOU is caught. 46597 See also the RATIONALE section in tcgetattr( ). 46598 FUTURE DIRECTIONS 46599 Using an input baud rate of 0 to set the input rate equal to the output rate may not necessarily be 46600 supported in a future version of this volume of IEEE Std 1003.1-200x. 46601 SEE ALSO 46602 cfgetispeed( ), tcgetattr( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 46603 , the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 11, General Terminal 46604 Interface 46605 CHANGE HISTORY 46606 First released in Issue 3. 46607 Entry included for alignment with the POSIX.1-1988 standard. 46608 Issue 6 46609 The following new requirements on POSIX implementations derive from alignment with the 46610 Single UNIX Specification: 46611 * In the DESCRIPTION, text previously conditional on _POSIX_JOB_CONTROL is now 46612 mandated. This is a FIPS requirement. 46613 * The [EIO] error is added. 2002 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcsetattr( ) 46614 In the DESCRIPTION, the text describing use of tcsetattr( ) from a process which is a member of | 46615 a background process group is clarified. System Interfaces, Issue 6 2003 tcsetpgrp( ) System Interfaces 46616 NAME 46617 tcsetpgrp - set the foreground process group ID 46618 SYNOPSIS 46619 #include 46620 int tcsetpgrp(int fildes, pid_t pgid_id); 46621 DESCRIPTION 46622 If the process has a controlling terminal, tcsetpgrp( ) shall set the foreground process group ID 46623 associated with the terminal to pgid_id. The application shall ensure that the file associated with 46624 fildes is the controlling terminal of the calling process and the controlling terminal is currently 46625 associated with the session of the calling process. The application shall ensure that the value of 46626 pgid_id matches a process group ID of a process in the same session as the calling process. 46627 Attempts to use tcsetpgrp( ) from a process which is a member of a background process group on 46628 a fildes associated with its controlling terminal shall cause the process group to be sent a 46629 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process | 46630 shall be allowed to perform the operation, and no signal is sent. | 46631 RETURN VALUE 46632 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 46633 indicate the error. 46634 ERRORS 46635 The tcsetpgrp( ) function shall fail if: 46636 [EBADF] The fildes argument is not a valid file descriptor. 46637 [EINVAL] This implementation does not support the value in the pgid_id argument. 46638 [ENOTTY] The calling process does not have a controlling terminal, or the file is not the 46639 controlling terminal, or the controlling terminal is no longer associated with 46640 the session of the calling process. 46641 [EPERM] The value of pgid_id is a value supported by the implementation, but does not 46642 match the process group ID of a process in the same session as the calling 46643 process. 46644 EXAMPLES 46645 None. 46646 APPLICATION USAGE 46647 None. 46648 RATIONALE 46649 None. 46650 FUTURE DIRECTIONS 46651 None. 46652 SEE ALSO 46653 tcgetpgrp( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 46654 CHANGE HISTORY 46655 First released in Issue 3. 46656 Entry included for alignment with the POSIX.1-1988 standard. 2004 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tcsetpgrp( ) 46657 Issue 6 46658 In the SYNOPSIS, the inclusion of is no longer required. 46659 The following new requirements on POSIX implementations derive from alignment with the 46660 Single UNIX Specification: 46661 * The requirement to include has been removed. Although was 46662 required for conforming implementations of previous POSIX specifications, it was not 46663 required for UNIX applications. 46664 * In the DESCRIPTION and ERRORS sections, text previously conditional on 46665 _POSIX_JOB_CONTROL is now mandated. This is a FIPS requirement. 46666 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 46667 The Open Group Corrigendum U047/4 is applied. System Interfaces, Issue 6 2005 tdelete( ) System Interfaces 46668 NAME 46669 tdelete, tfind, tsearch, twalk - manage a binary search tree 46670 SYNOPSIS 46671 XSI #include 46672 void *tdelete(const void *restrict key, void **restrict rootp, 46673 int(*compar)(const void *, const void *)); 46674 void *tfind(const void *key, void *const *rootp, 46675 int(*compar)(const void *, const void *)); 46676 void *tsearch(const void *key, void **rootp, 46677 int (*compar)(const void *, const void *)); 46678 void twalk(const void *root, 46679 void (*action)(const void *, VISIT, int)); 46680 46681 DESCRIPTION 46682 The tdelete( ), tfind( ), tsearch( ), and twalk( ) functions manipulate binary search trees. 46683 Comparisons are made with a user-supplied routine, the address of which is passed as the 46684 compar argument. This routine is called with two arguments, the pointers to the elements being 46685 compared. The application shall ensure that the user-supplied routine returns an integer less 46686 than, equal to, or greater than 0, according to whether the first argument is to be considered less 46687 than, equal to, or greater than the second argument. The comparison function need not compare 46688 every byte, so arbitrary data may be contained in the elements in addition to the values being 46689 compared. 46690 The tsearch( ) function shall build and access the tree. The key argument is a pointer to an element | 46691 to be accessed or stored. If there is a node in the tree whose element is equal to the value pointed 46692 to by key, a pointer to this found node shall be returned. Otherwise, the value pointed to by key | 46693 shall be inserted (that is, a new node is created and the value of key is copied to this node), and a | 46694 pointer to this node returned. Only pointers are copied, so the application shall ensure that the 46695 calling routine stores the data. The rootp argument points to a variable that points to the root | 46696 node of the tree. A null pointer value for the variable pointed to by rootp denotes an empty tree; | 46697 in this case, the variable shall be set to point to the node which shall be at the root of the new 46698 tree. 46699 Like tsearch( ), tfind( ) shall search for a node in the tree, returning a pointer to it if found. 46700 However, if it is not found, tfind( ) shall return a null pointer. The arguments for tfind( ) are the 46701 same as for tsearch( ). 46702 The tdelete( ) function shall delete a node from a binary search tree. The arguments are the same | 46703 as for tsearch( ). The variable pointed to by rootp shall be changed if the deleted node was the | 46704 root of the tree. The tdelete( ) function shall return a pointer to the parent of the deleted node, or a 46705 null pointer if the node is not found. 46706 The twalk( ) function shall traverse a binary search tree. The root argument is a pointer to the root | 46707 node of the tree to be traversed. (Any node in a tree may be used as the root for a walk below 46708 that node.) The argument action is the name of a routine to be invoked at each node. This routine 46709 is, in turn, called with three arguments. The first argument shall be the address of the node being | 46710 visited. The structure pointed to by this argument is unspecified and shall not be modified by | 46711 the application, but it shall be possible to cast a pointer-to-node into a pointer-to-pointer-to- | 46712 element to access the element stored in the node. The second argument shall be a value from an | 46713 enumeration data type: | 46714 typedef enum { preorder, postorder, endorder, leaf } VISIT; 2006 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tdelete( ) 46715 (defined in ), depending on whether this is the first, second, or third time that the 46716 node is visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a | 46717 leaf. The third argument shall be the level of the node in the tree, with the root being level 0. | 46718 If the calling function alters the pointer to the root, the result is undefined. 46719 RETURN VALUE 46720 If the node is found, both tsearch( ) and tfind( ) shall return a pointer to it. If not, tfind( ) shall 46721 return a null pointer, and tsearch( ) shall return a pointer to the inserted item. 46722 A null pointer shall be returned by tsearch( ) if there is not enough space available to create a new 46723 node. 46724 A null pointer shall be returned by tdelete( ), tfind( ), and tsearch( ) if rootp is a null pointer on 46725 entry. 46726 The tdelete( ) function shall return a pointer to the parent of the deleted node, or a null pointer if 46727 the node is not found. 46728 The twalk( ) function shall not return a value. 46729 ERRORS 46730 No errors are defined. 46731 EXAMPLES 46732 The following code reads in strings and stores structures containing a pointer to each string and 46733 a count of its length. It then walks the tree, printing out the stored strings and their lengths in 46734 alphabetical order. 46735 #include 46736 #include 46737 #include 46738 #define STRSZ 10000 46739 #define NODSZ 500 46740 struct node { /* Pointers to these are stored in the tree. */ 46741 char *string; 46742 int length; 46743 }; 46744 char string_space[STRSZ]; /* Space to store strings. */ 46745 struct node nodes[NODSZ]; /* Nodes to store. */ 46746 void *root = NULL; /* This points to the root. */ 46747 int main(int argc, char *argv[]) 46748 { 46749 char *strptr = string_space; 46750 struct node *nodeptr = nodes; 46751 void print_node(const void *, VISIT, int); 46752 int i = 0, node_compare(const void *, const void *); 46753 while (gets(strptr) != NULL && i++ < NODSZ) { 46754 /* Set node. */ 46755 nodeptr->string = strptr; 46756 nodeptr->length = strlen(strptr); 46757 /* Put node into the tree. */ 46758 (void) tsearch((void *)nodeptr, (void **)&root, 46759 node_compare); System Interfaces, Issue 6 2007 tdelete( ) System Interfaces 46760 /* Adjust pointers, so we do not overwrite tree. */ 46761 strptr += nodeptr->length + 1; 46762 nodeptr++; 46763 } 46764 twalk(root, print_node); 46765 return 0; 46766 } 46767 /* 46768 * This routine compares two nodes, based on an 46769 * alphabetical ordering of the string field. 46770 */ 46771 int 46772 node_compare(const void *node1, const void *node2) 46773 { 46774 return strcmp(((const struct node *) node1)->string, 46775 ((const struct node *) node2)->string); 46776 } 46777 /* 46778 * This routine prints out a node, the second time 46779 * twalk encounters it or if it is a leaf. 46780 */ 46781 void 46782 print_node(const void *ptr, VISIT order, int level) 46783 { 46784 const struct node *p = *(const struct node **) ptr; 46785 if (order == postorder order == leaf) { 46786 (void) printf("string = %s, length = %d\n", 46787 p->string, p->length); 46788 } 46789 } 46790 APPLICATION USAGE 46791 The root argument to twalk( ) is one level of indirection less than the rootp arguments to tdelete( ) 46792 and tsearch( ). 46793 There are two nomenclatures used to refer to the order in which tree nodes are visited. The 46794 tsearch( ) function uses preorder, postorder, and endorder to refer respectively to visiting a node 46795 before any of its children, after its left child and before its right, and after both its children. The 46796 alternative nomenclature uses preorder, inorder, and postorder to refer to the same visits, which 46797 could result in some confusion over the meaning of postorder. 46798 RATIONALE 46799 None. 46800 FUTURE DIRECTIONS 46801 None. 46802 SEE ALSO 46803 hcreate( ), lsearch( ), the Base Definitions volume of IEEE Std 1003.1-200x, 2008 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tdelete( ) 46804 CHANGE HISTORY 46805 First released in Issue 1. Derived from Issue 1 of the SVID. 46806 Issue 5 46807 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 46808 previous issues. 46809 Issue 6 46810 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 46811 The restrict keyword is added to the tdelete( ) prototype for alignment with the 46812 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2009 telldir( ) System Interfaces 46813 NAME 46814 telldir - current location of a named directory stream 46815 SYNOPSIS 46816 XSI #include 46817 long telldir(DIR *dirp); 46818 46819 DESCRIPTION 46820 The telldir( ) function shall obtain the current location associated with the directory stream | 46821 specified by dirp. | 46822 If the most recent operation on the directory stream was a seekdir( ), the directory position 46823 returned from the telldir( ) shall be the same as that supplied as a loc argument for seekdir( ). 46824 RETURN VALUE 46825 Upon successful completion, telldir( ) shall return the current location of the specified directory 46826 stream. 46827 ERRORS 46828 No errors are defined. 46829 EXAMPLES 46830 None. 46831 APPLICATION USAGE 46832 None. 46833 RATIONALE 46834 None. 46835 FUTURE DIRECTIONS 46836 None. 46837 SEE ALSO 46838 opendir( ), readdir( ), seekdir( ), the Base Definitions volume of IEEE Std 1003.1-200x, 46839 CHANGE HISTORY 46840 First released in Issue 2. 2010 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tempnam( ) 46841 NAME 46842 tempnam - create a name for a temporary file 46843 SYNOPSIS 46844 XSI #include 46845 char *tempnam(const char *dir, const char *pfx); 46846 46847 DESCRIPTION 46848 The tempnam( ) function shall generate a pathname that may be used for a temporary file. | 46849 The tempnam( ) function allows the user to control the choice of a directory. The dir argument 46850 points to the name of the directory in which the file is to be created. If dir is a null pointer or 46851 points to a string which is not a name for an appropriate directory, the path prefix defined as 46852 P_tmpdir in the header shall be used. If that directory is not accessible, an | 46853 implementation-defined directory may be used. 46854 Many applications prefer their temporary files to have certain initial letter sequences in their 46855 names. The pfx argument should be used for this. This argument may be a null pointer or point 46856 to a string of up to five bytes to be used as the beginning of the filename. 46857 Some implementations of tempnam( ) may use tmpnam( ) internally. On such implementations, if 46858 called more than {TMP_MAX} times in a single process, the behavior is implementation-defined. 46859 RETURN VALUE 46860 Upon successful completion, tempnam( ) shall allocate space for a string, put the generated | 46861 pathname in that space, and return a pointer to it. The pointer shall be suitable for use in a | 46862 subsequent call to free( ). Otherwise, it shall return a null pointer and set errno to indicate the 46863 error. 46864 ERRORS 46865 The tempnam( ) function shall fail if: 46866 [ENOMEM] Insufficient storage space is available. 46867 EXAMPLES 46868 Generating a Pathname | 46869 The following example generates a pathname for a temporary file in directory /tmp, with the | 46870 prefix file. After the filename has been created, the call to free( ) deallocates the space used to 46871 store the filename. 46872 #include 46873 #include 46874 ... 46875 char *directory = "/tmp"; 46876 char *fileprefix = "file"; 46877 char *file; 46878 file = tempnam(directory, fileprefix); 46879 free(file); 46880 APPLICATION USAGE 46881 This function only creates pathnames. It is the application's responsibility to create and remove | 46882 the files. Between the time a pathname is created and the file is opened, it is possible for some | 46883 other process to create a file with the same name. Applications may find tmpfile( ) more useful. System Interfaces, Issue 6 2011 tempnam( ) System Interfaces 46884 RATIONALE 46885 None. 46886 FUTURE DIRECTIONS 46887 None. 46888 SEE ALSO 46889 fopen( ), free( ), open( ), tmpfile( ), tmpnam( ), unlink( ), the Base Definitions volume of 46890 IEEE Std 1003.1-200x, 46891 CHANGE HISTORY 46892 First released in Issue 1. Derived from Issue 1 of the SVID. 46893 Issue 5 46894 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 46895 previous issues. 2012 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tfind( ) 46896 NAME 46897 tfind - search binary search tree 46898 SYNOPSIS 46899 XSI #include 46900 void *tfind(const void *key, void *const *rootp, 46901 int (*compar)(const void *, const void *)); 46902 46903 DESCRIPTION 46904 Refer to tdelete( ). System Interfaces, Issue 6 2013 tgamma( ) System Interfaces 46905 NAME 46906 tgamma, tgammaf, tgammal - compute gamma( ) function 46907 SYNOPSIS 46908 #include 46909 double tgamma(double x); 46910 float tgammaf(float x); 46911 long double tgammal(long double x); 46912 DESCRIPTION 46913 CX The functionality described on this reference page is aligned with the ISO C standard. Any 46914 conflict between the requirements described here and the ISO C standard is unintentional. This 46915 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 46916 These functions shall compute the gamma( ) function of x. 46917 An application wishing to check for error situations should set errno to zero and call 46918 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 46919 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 46920 zero, an error has occurred. 46921 RETURN VALUE 46922 Upon successful completion, these functions shall return Gamma(x). 46923 If x is a negative integer, a domain error shall occur, and either a NaN (if supported), or an 46924 implementation-defined value shall be returned. 46925 If the correct value would cause overflow, a range error shall occur and tgamma( ), tgammaf( ), 46926 and tgammal( ) shall return the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL, 46927 respectively. 46928 MX If x is NaN, a NaN shall be returned. 46929 If x is +Inf, x shall be returned. 46930 If x is ±0, a pole error shall occur, and tgamma( ), tgammaf( ), and tgammal( ) shall return 46931 ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL, respectively. 46932 If x is -Inf, a domain error shall occur, and either a NaN (if supported), or an implementation- 46933 defined value shall be returned. 46934 ERRORS 46935 These functions shall fail if: 46936 MX Domain Error The value of x is a negative integer, or x is -Inf. 46937 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46938 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 46939 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 46940 shall be raised. | 46941 MX Pole Error The value of x is zero. 46942 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46943 then errno shall be set to [ERANGE]. If the integer expression | 46944 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the divide-by- | 46945 zero floating-point exception shall be raised. | 46946 Range Error The value overflows. 2014 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tgamma( ) 46947 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 46948 then errno shall be set to [ERANGE]. If the integer expression | 46949 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 46950 floating-point exception shall be raised. | 46951 EXAMPLES 46952 None. 46953 APPLICATION USAGE 46954 For IEEE Std 754-1985 double, overflow happens when 0 < x < 1/DBL_MAX, and 171.7 < x. 46955 Overflow also happens near negative integers. 46956 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 46957 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 46958 RATIONALE 46959 This function is named tgamma( ) in order to avoid conflicts with the historical gamma( ) and 46960 lgamma( ) functions. 46961 FUTURE DIRECTIONS 46962 It is possible that the error response for a negative integer argument may be changed to a pole 46963 error and a return value of ±Inf. 46964 SEE ALSO 46965 feclearexcept( ), fetestexcept( ), lgamma( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 46966 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 46967 CHANGE HISTORY 46968 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2015 time( ) System Interfaces 46969 NAME 46970 time - get time 46971 SYNOPSIS 46972 #include 46973 time_t time(time_t *tloc); 46974 DESCRIPTION 46975 CX The functionality described on this reference page is aligned with the ISO C standard. Any 46976 conflict between the requirements described here and the ISO C standard is unintentional. This 46977 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 46978 CX The time( ) function shall return the value of time in seconds since the Epoch. 46979 The tloc argument points to an area where the return value is also stored. If tloc is a null pointer, 46980 no value is stored. 46981 RETURN VALUE 46982 Upon successful completion, time( ) shall return the value of time. Otherwise, (time_t)-1 shall be 46983 returned. 46984 ERRORS 46985 No errors are defined. 46986 EXAMPLES 46987 Getting the Current Time 46988 The following example uses the time( ) function to calculate the time elapsed, in seconds, since 46989 January 1, 1970 0:00 UTC, localtime( ) to convert that value to a broken-down time, and asctime( ) 46990 to convert the broken-down time values into a printable string. 46991 #include 46992 #include 46993 main() 46994 { 46995 time_t result; 46996 result = time(NULL); 46997 printf("%s%ld secs since the Epoch\n", 46998 asctime(localtime(&result)), 46999 (long)result); 47000 return(0); 47001 } 47002 This example writes the current time to stdout in a form like this: 47003 Wed Jun 26 10:32:15 1996 47004 835810335 secs since the Epoch 2016 Technical Standard (2001) (Draft April 16, 2001) System Interfaces time( ) 47005 Timing an Event 47006 The following example gets the current time, prints it out in the user's format, and prints the 47007 number of minutes to an event being timed. 47008 #include 47009 #include 47010 ... 47011 time_t now; 47012 int minutes_to_event; 47013 ... 47014 time(&now); 47015 minutes_to_event = ...; | 47016 printf("The time is "); | 47017 puts(asctime(localtime(&now))); 47018 printf("There are %d minutes to the event.\n", 47019 minutes_to_event); 47020 ... 47021 APPLICATION USAGE 47022 None. 47023 RATIONALE 47024 The time( ) function returns a value in seconds (type time_t) while times( ) returns a set of values 47025 in clock ticks (type clock_t). Some historical implementations, such as 4.3 BSD, have 47026 mechanisms capable of returning more precise times (see below). A generalized timing scheme 47027 to unify these various timing mechanisms has been proposed but not adopted. 47028 Implementations in which time_t is a 32-bit signed integer (many historical implementations) 47029 fail in the year 2038. IEEE Std 1003.1-200x does not address this problem. However, the use of 47030 the time_t type is mandated in order to ease the eventual fix. 47031 The use of the , header instead of , allows compatibility with the ISO C 47032 standard. 47033 Many historical implementations (including Version 7) and the 1984 /usr/group standard use 47034 long instead of time_t. This volume of IEEE Std 1003.1-200x uses the latter type in order to agree 47035 with the ISO C standard. 47036 4.3 BSD includes time( ) only as an alternate function to the more flexible gettimeofday( ) function. 47037 FUTURE DIRECTIONS 47038 In a future version of this volume of IEEE Std 1003.1-200x, time_t is likely to be required to be 47039 capable of representing times far in the future. Whether this will be mandated as a 64-bit type or 47040 a requirement that a specific date in the future be representable (for example, 10000 AD) is not 47041 yet determined. Systems purchased after the approval of this volume of IEEE Std 1003.1-200x 47042 should be evaluated to determine whether their lifetime will extend past 2038. 47043 SEE ALSO 47044 asctime( ), clock( ), ctime( ), difftime( ), gmtime( ), localtime( ), mktime( ), strftime( ), strptime( ), utime( ), 47045 the Base Definitions volume of IEEE Std 1003.1-200x, 47046 CHANGE HISTORY 47047 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 2017 time( ) System Interfaces 47048 Issue 6 47049 Extensions beyond the ISO C standard are now marked. | 47050 The EXAMPLES, RATIONALE, and FUTURE DIRECTIONS sections are added. | 2018 Technical Standard (2001) (Draft April 16, 2001) System Interfaces timer_create( ) 47051 NAME 47052 timer_create - create a per-process timer (REALTIME) 47053 SYNOPSIS 47054 TMR #include 47055 #include 47056 int timer_create(clockid_t clockid, struct sigevent *restrict evp, 47057 timer_t *restrict timerid); 47058 47059 DESCRIPTION 47060 The timer_create( ) function shall create a per-process timer using the specified clock, clock_id, as 47061 the timing base. The timer_create( ) function shall return, in the location referenced by timerid, a 47062 timer ID of type timer_t used to identify the timer in timer requests. This timer ID shall be 47063 unique within the calling process until the timer is deleted. The particular clock, clock_id, is 47064 defined in . The timer whose ID is returned shall be in a disarmed state upon return 47065 from timer_create( ). 47066 The evp argument, if non-NULL, points to a sigevent structure. This structure, allocated by the 47067 application, defines the asynchronous notification to occur as specified in Section 2.4.1 (on page 47068 478) when the timer expires. If the evp argument is NULL, the effect is as if the evp argument 47069 pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, 47070 the sigev_signo having a default signal number, and the sigev_value member having the value of 47071 the timer ID. 47072 Each implementation shall define a set of clocks that can be used as timing bases for per-process 47073 MON timers. All implementations shall support a clock_id of CLOCK_REALTIME. If the Monotonic 47074 Clock option is supported, implementations shall support a clock_id of CLOCK_MONOTONIC. 47075 Per-process timers shall not be inherited by a child process across a fork( ) and shall be disarmed 47076 and deleted by an exec. 47077 CPT If _POSIX_CPUTIME is defined, implementations shall support clock_id values representing the 47078 CPU-time clock of the calling process. 47079 TCT If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock_id values 47080 representing the CPU-time clock of the calling thread. 47081 CPT|TCT It is implementation-defined whether a timer_create( ) function will succeed if the value defined 47082 by clock_id corresponds to the CPU-time clock of a process or thread different from the process 47083 or thread invoking the function. 47084 RETURN VALUE 47085 If the call succeeds, timer_create( ) shall return zero and update the location referenced by timerid 47086 to a timer_t, which can be passed to the per-process timer calls. If an error occurs, the function 47087 shall return a value of -1 and set errno to indicate the error. The value of timerid is undefined if 47088 an error occurs. 47089 ERRORS 47090 The timer_create( ) function shall fail if: 47091 [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. 47092 [EAGAIN] The calling process has already created all of the timers it is allowed by this 47093 implementation. 47094 [EINVAL] The specified clock ID is not defined. System Interfaces, Issue 6 2019 timer_create( ) System Interfaces 47095 CPT|TCT [ENOTSUP] The implementation does not support the creation of a timer attached to the 47096 CPU-time clock that is specified by clock_id and associated with a process or 47097 thread different from the process or thread invoking timer_create( ). 47098 EXAMPLES 47099 None. 47100 APPLICATION USAGE 47101 None. 47102 RATIONALE 47103 Periodic Timer Overrun and Resource Allocation 47104 The specified timer facilities may deliver realtime signals (that is, queued signals) on | 47105 implementations that support this option. Since realtime applications cannot afford to lose | 47106 notifications of asynchronous events, like timer expirations or asynchronous I/O completions, it 47107 must be possible to ensure that sufficient resources exist to deliver the signal when the event 47108 occurs. In general, this is not a difficulty because there is a one-to-one correspondence between a 47109 request and a subsequent signal generation. If the request cannot allocate the signal delivery 47110 resources, it can fail the call with an [EAGAIN] error. 47111 Periodic timers are a special case. A single request can generate an unspecified number of | 47112 signals. This is not a problem if the requesting process can service the signals as fast as they are | 47113 generated, thus making the signal delivery resources available for delivery of subsequent 47114 periodic timer expiration signals. But, in general, this cannot be assured-processing of periodic 47115 timer signals may ``overrun''; that is, subsequent periodic timer expirations may occur before the 47116 currently pending signal has been delivered. 47117 Also, for signals, according to the POSIX.1-1990 standard, if subsequent occurrences of a 47118 pending signal are generated, it is implementation-defined whether a signal is delivered for each 47119 occurrence. This is not adequate for some realtime applications. So a mechanism is required to 47120 allow applications to detect how many timer expirations were delayed without requiring an 47121 indefinite amount of system resources to store the delayed expirations. 47122 The specified facilities provide for an overrun count. The overrun count is defined as the number 47123 of extra timer expirations that occurred between the time a timer expiration signal is generated 47124 and the time the signal is delivered. The signal-catching function, if it is concerned with 47125 overruns, can retrieve this count on entry. With this method, a periodic timer only needs one 47126 ``signal queuing resource'' that can be allocated at the time of the timer_create( ) function call. 47127 A function is defined to retrieve the overrun count so that an application need not allocate static 47128 storage to contain the count, and an implementation need not update this storage 47129 asynchronously on timer expirations. But, for some high-frequency periodic applications, the 47130 overhead of an additional system call on each timer expiration may be prohibitive. The 47131 functions, as defined, permit an implementation to maintain the overrun count in user space, 47132 associated with the timerid. The timer_getoverrun( ) function can then be implemented as a macro 47133 that uses the timerid argument (which may just be a pointer to a user space structure containing 47134 the counter) to locate the overrun count with no system call overhead. Other implementations, 47135 less concerned with this class of applications, can avoid the asynchronous update of user space 47136 by maintaining the count in a system structure at the cost of the extra system call to obtain it. 2020 Technical Standard (2001) (Draft April 16, 2001) System Interfaces timer_create( ) 47137 Timer Expiration Signal Parameters 47138 The Realtime Signals Extension option supports an application-specific datum that is delivered 47139 to the extended signal handler. This value is explicitly specified by the application, along with 47140 the signal number to be delivered, in a sigevent structure. The type of the application-defined 47141 value can be either an integer constant or a pointer. This explicit specification of the value, as 47142 opposed to always sending the timer ID, was selected based on existing practice. 47143 It is common practice for realtime applications (on non-POSIX systems or realtime extended 47144 POSIX systems) to use the parameters of event handlers as the case label of a switch statement 47145 or as a pointer to an application-defined data structure. Since timer_ids are dynamically allocated | 47146 by the timer_create( ) function, they can be used for neither of these functions without additional 47147 application overhead in the signal handler; for example, to search an array of saved timer IDs to 47148 associate the ID with a constant or application data structure. 47149 FUTURE DIRECTIONS 47150 None. 47151 SEE ALSO 47152 clock_getres( ), timer_delete( ), timer_getoverrun( ), the Base Definitions volume of 47153 IEEE Std 1003.1-200x, 47154 CHANGE HISTORY 47155 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 47156 Issue 6 47157 The timer_create( ) function is marked as part of the Timers option. 47158 The [ENOSYS] error condition has been removed as stubs need not be provided if an 47159 implementation does not support the Timers option. 47160 CPU-time clocks are added for alignment with IEEE Std 1003.1d-1999. 47161 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding the 47162 requirement for the CLOCK_MONOTONIC clock under the Monotonic Clock option. 47163 The restrict keyword is added to the timer_create( ) prototype for alignment with the 47164 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2021 timer_delete( ) System Interfaces 47165 NAME 47166 timer_delete - delete a per-process timer (REALTIME) 47167 SYNOPSIS 47168 TMR #include 47169 int timer_delete(timer_t timerid); 47170 47171 DESCRIPTION 47172 The timer_delete( ) function deletes the specified timer, timerid, previously created by the 47173 timer_create( ) function. If the timer is armed when timer_delete( ) is called, the behavior shall be 47174 as if the timer is automatically disarmed before removal. The disposition of pending signals for 47175 the deleted timer is unspecified. 47176 RETURN VALUE 47177 If successful, the timer_delete( ) function shall return a value of zero. Otherwise, the function shall 47178 return a value of -1 and set errno to indicate the error. 47179 ERRORS 47180 The timer_delete( ) function shall fail if: 47181 [EINVAL] The timer ID specified by timerid is not a valid timer ID. 47182 EXAMPLES 47183 None. 47184 APPLICATION USAGE 47185 None. 47186 RATIONALE 47187 None. 47188 FUTURE DIRECTIONS 47189 None. 47190 SEE ALSO 47191 timer_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47192 CHANGE HISTORY 47193 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 47194 Issue 6 47195 The timer_delete( ) function is marked as part of the Timers option. 47196 The [ENOSYS] error condition has been removed as stubs need not be provided if an 47197 implementation does not support the Timers option. 2022 Technical Standard (2001) (Draft April 16, 2001) System Interfaces timer_getoverrun( ) 47198 NAME 47199 timer_getoverrun, timer_gettime, timer_settime - per-process timers (REALTIME) 47200 SYNOPSIS 47201 TMR #include 47202 int timer_getoverrun(timer_t timerid); 47203 int timer_gettime(timer_t timerid, struct itimerspec *value); 47204 int timer_settime(timer_t timerid, int flags, 47205 const struct itimerspec *restrict value, 47206 struct itimerspec *restrict ovalue); 47207 47208 DESCRIPTION 47209 The timer_gettime( ) function shall store the amount of time until the specified timer, timerid, | 47210 expires and the reload value of the timer into the space pointed to by the value argument. The 47211 it_value member of this structure shall contain the amount of time before the timer expires, or 47212 zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if 47213 the timer was armed with absolute time. The it_interval member of value shall contain the reload 47214 value last set by timer_settime( ). 47215 The timer_settime( ) function shall set the time until the next expiration of the timer specified by 47216 timerid from the it_value member of the value argument and arms the timer if the it_value 47217 member of value is non-zero. If the specified timer was already armed when timer_settime( ) is 47218 called, this call shall reset the time until next expiration to the value specified. If the it_value 47219 member of value is zero, the timer shall be disarmed. The effect of disarming or resetting a timer 47220 with pending expiration notifications is unspecified. 47221 If the flag TIMER_ABSTIME is not set in the argument flags, timer_settime( ) shall behave as if the | 47222 time until next expiration is set to be equal to the interval specified by the it_value member of | 47223 value. That is, the timer shall expire in it_value nanoseconds from when the call is made. If the 47224 flag TIMER_ABSTIME is set in the argument flags, timer_settime( ) shall behave as if the time | 47225 until next expiration is set to be equal to the difference between the absolute time specified by | 47226 the it_value member of value and the current value of the clock associated with timerid. That is, | 47227 the timer shall expire when the clock reaches the value specified by the it_value member of value. 47228 If the specified time has already passed, the function shall succeed and the expiration 47229 notification shall be made. 47230 The reload value of the timer shall be set to the value specified by the it_interval member of | 47231 value. When a timer is armed with a non-zero it_interval, a periodic (or repetitive) timer is 47232 specified. 47233 Time values that are between two consecutive non-negative integer multiples of the resolution 47234 of the specified timer shall be rounded up to the larger multiple of the resolution. Quantization 47235 error shall not cause the timer to expire earlier than the rounded time value. 47236 If the argument ovalue is not NULL, the function timer_settime( ) shall store, in the location 47237 referenced by ovalue, a value representing the previous amount of time before the timer would 47238 have expired, or zero if the timer was disarmed, together with the previous timer reload value. | 47239 Timers shall not expire before their scheduled time. | 47240 Only a single signal shall be queued to the process for a given timer at any point in time. When a | 47241 timer for which a signal is still pending expires, no signal shall be queued, and a timer overrun | 47242 RTS shall occur. When a timer expiration signal is delivered to or accepted by a process, if the | 47243 implementation supports the Realtime Signals Extension, the timer_getoverrun( ) function shall | 47244 return the timer expiration overrun count for the specified timer. The overrun count returned | 47245 contains the number of extra timer expirations that occurred between the time the signal was | System Interfaces, Issue 6 2023 timer_getoverrun( ) System Interfaces 47246 generated (queued) and when it was delivered or accepted, up to but not including an | 47247 implementation-defined maximum of {DELAYTIMER_MAX}. If the number of such extra | 47248 expirations is greater than or equal to {DELAYTIMER_MAX}, then the overrun count shall be set | 47249 to {DELAYTIMER_MAX}. The value returned by timer_getoverrun( ) shall apply to the most | 47250 recent expiration signal delivery or acceptance for the timer. If no expiration signal has been | 47251 delivered for the timer, or if the Realtime Signals Extension is not supported, the return value of | 47252 timer_getoverrun( ) is unspecified. | 47253 RETURN VALUE 47254 If the timer_getoverrun( ) function succeeds, it shall return the timer expiration overrun count as 47255 explained above. 47256 If the timer_gettime( ) or timer_settime( ) functions succeed, a value of 0 shall be returned. 47257 If an error occurs for any of these functions, the value -1 shall be returned, and errno set to 47258 indicate the error. 47259 ERRORS 47260 The timer_getoverrun( ), timer_gettime( ), and timer_settime( ) functions shall if: | 47261 [EINVAL] The timerid argument does not correspond to an ID returned by timer_create( ) 47262 but not yet deleted by timer_delete( ). 47263 The timer_settime( ) function shall fail if: 47264 [EINVAL] A value structure specified a nanosecond value less than zero or greater than 47265 or equal to 1,000 million, and the it_value member of that structure did not 47266 specify zero seconds and nanoseconds. 47267 EXAMPLES 47268 None. 47269 APPLICATION USAGE 47270 None. 47271 RATIONALE 47272 Practical clocks tick at a finite rate, with rates of 100 Hertz and 1,000 Hertz being common. The 47273 inverse of this tick rate is the clock resolution, also called the clock granularity, which in either 47274 case is expressed as a time duration, being 10 milliseconds and 1 millisecond respectively for 47275 these common rates. The granularity of practical clocks implies that if one reads a given clock 47276 twice in rapid succession, one may get the same time value twice; and that timers must wait for 47277 the next clock tick after the theoretical expiration time, to ensure that a timer never returns too 47278 soon. Note also that the granularity of the clock may be significantly coarser than the resolution 47279 of the data format used to set and get time and interval values. Also note that some 47280 implementations may choose to adjust time and/or interval values to exactly match the ticks of 47281 the underlying clock. 47282 This volume of IEEE Std 1003.1-200x defines functions that allow an application to determine the 47283 implementation-supported resolution for the clocks and requires an implementation to 47284 document the resolution supported for timers and nanosleep( ) if they differ from the supported 47285 clock resolution. This is more of a procurement issue than a runtime application issue. 47286 FUTURE DIRECTIONS 47287 None. 2024 Technical Standard (2001) (Draft April 16, 2001) System Interfaces timer_getoverrun( ) 47288 SEE ALSO 47289 clock_getres( ), timer_create( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47290 CHANGE HISTORY 47291 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 47292 Issue 6 47293 The timer_getoverrun( ), timer_gettime( ), and timer_settime( ) functions are marked as part of the 47294 Timers option. 47295 The [ENOSYS] error condition has been removed as stubs need not be provided if an 47296 implementation does not support the Timers option. 47297 The [EINVAL] error condition is updated to include the following: ``and the it_value member of 47298 that structure did not specify zero seconds and nanoseconds.'' This change is for IEEE PASC 47299 Interpretation 1003.1 #89. 47300 The DESCRIPTION for timer_getoverrun( ) is updated to clarify that ``If no expiration signal has 47301 been delivered for the timer, or if the Realtime Signals Extension is not supported, the return 47302 value of timer_getoverrun( ) is unspecified''. 47303 The restrict keyword is added to the timer_settime( ) prototype for alignment with the 47304 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2025 times( ) System Interfaces 47305 NAME 47306 times - get process and waited-for child process times 47307 SYNOPSIS 47308 #include 47309 clock_t times(struct tms *buffer); 47310 DESCRIPTION 47311 The times( ) function shall fill the tms structure pointed to by buffer with time-accounting 47312 information. The tms structure is defined in . | 47313 All times are measured in terms of the number of clock ticks used. 47314 The times of a terminated child process shall be included in the tms_cutime and tms_cstime 47315 elements of the parent when wait( ) or waitpid( ) returns the process ID of this terminated child. If 47316 a child process has not waited for its children, their times shall not be included in its times. 47317 * The tms_utime structure member is the CPU time charged for the execution of user 47318 instructions of the calling process. 47319 * The tms_stime structure member is the CPU time charged for execution by the system on 47320 behalf of the calling process. 47321 * The tms_cutime structure member is the sum of the tms_utime and tms_cutime times of the 47322 child processes. 47323 * The tms_cstime structure member is the sum of the tms_stime and tms_cstime times of the child 47324 processes. 47325 RETURN VALUE 47326 Upon successful completion, times( ) shall return the elapsed real time, in clock ticks, since an 47327 arbitrary point in the past (for example, system start-up time). This point does not change from 47328 one invocation of times( ) within the process to another. The return value may overflow the 47329 possible range of type clock_t. If times( ) fails, (clock_t)-1 shall be returned and errno set to 47330 indicate the error. 47331 ERRORS 47332 No errors are defined. 47333 EXAMPLES 47334 Timing a Database Lookup 47335 The following example defines two functions, start_clock( ) and end_clock( ), that are used to time 47336 a lookup. It also defines variables of type clock_t and tms to measure the duration of 47337 transactions. The start_clock( ) function saves the beginning times given by the times( ) function. 47338 The end_clock( ) function gets the ending times and prints the difference between the two times. 47339 #include 47340 #include 47341 ... 47342 void start_clock(void); 47343 void end_clock(char *msg); 47344 ... 47345 static clock_t st_time; 47346 static clock_t en_time; 47347 static struct tms st_cpu; 47348 static struct tms en_cpu; 2026 Technical Standard (2001) (Draft April 16, 2001) System Interfaces times( ) 47349 ... 47350 void 47351 start_clock() 47352 { 47353 st_time = times(&st_cpu); 47354 } 47355 void 47356 end_clock(char *msg) 47357 { 47358 en_time = times(&en_cpu); 47359 printf(msg); 47360 printf("Real Time: %ld, User Time %ld, System Time %ld\n", 47361 en_time - st_time, 47362 en_cpu.tms_utime - st_cpu.tms_utime, 47363 en_cpu.tms_stime - st_cpu.tms_stime); 47364 } 47365 APPLICATION USAGE 47366 Applications should use sysconf(_SC_CLK_TCK) to determine the number of clock ticks per 47367 second as it may vary from system to system. 47368 RATIONALE 47369 The accuracy of the times reported is intentionally left unspecified to allow implementations 47370 flexibility in design, from uniprocessor to multi-processor networks. 47371 The inclusion of times of child processes is recursive, so that a parent process may collect the 47372 total times of all of its descendants. But the times of a child are only added to those of its parent 47373 when its parent successfully waits on the child. Thus, it is not guaranteed that a parent process 47374 can always see the total times of all its descendants; see also the discussion of the term realtime in 47375 alarm( ). 47376 If the type clock_t is defined to be a signed 32-bit integer, it overflows in somewhat more than a 47377 year if there are 60 clock ticks per second, or less than a year if there are 100. There are individual 47378 systems that run continuously for longer than that. This volume of IEEE Std 1003.1-200x permits 47379 an implementation to make the reference point for the returned value be the start-up time of the 47380 process, rather than system start-up time. 47381 The term charge in this context has nothing to do with billing for services. The operating system 47382 accounts for time used in this way. That information must be correct, regardless of how that 47383 information is used. 47384 FUTURE DIRECTIONS 47385 None. 47386 SEE ALSO 47387 exec, fork( ), sysconf( ), time( ), wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47388 47389 CHANGE HISTORY 47390 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 2027 timezone( ) System Interfaces 47391 NAME 47392 timezone - difference from UTC and local standard time 47393 SYNOPSIS 47394 XSI #include | 47395 extern long timezone; | 47396 47397 DESCRIPTION 47398 Refer to tzset( ). 2028 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tmpfile( ) 47399 NAME 47400 tmpfile - create a temporary file 47401 SYNOPSIS 47402 #include 47403 FILE *tmpfile(void); 47404 DESCRIPTION 47405 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47406 conflict between the requirements described here and the ISO C standard is unintentional. This 47407 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47408 The tmpfile( ) function shall create a temporary file and open a corresponding stream. The file | 47409 shall be automatically deleted when all references to the file are closed. The file is opened as in | 47410 fopen( ) for update (w+). 47411 CX In some implementations, a permanent file may be left behind if the process calling tmpfile( ) is 47412 killed while it is processing a call to tmpfile( ). 47413 An error message may be written to standard error if the stream cannot be opened. 47414 RETURN VALUE 47415 Upon successful completion, tmpfile( ) shall return a pointer to the stream of the file that is 47416 CX created. Otherwise, it shall return a null pointer and set errno to indicate the error. 47417 ERRORS 47418 The tmpfile( ) function shall fail if: 47419 CX [EINTR] A signal was caught during tmpfile( ). 47420 CX [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 47421 CX [ENFILE] The maximum allowable number of files is currently open in the system. 47422 CX [ENOSPC] The directory or file system which would contain the new file cannot be 47423 expanded. 47424 CX [EOVERFLOW] The file is a regular file and the size of the file cannot be represented correctly 47425 in an object of type off_t. 47426 The tmpfile( ) function may fail if: 47427 CX [EMFILE] {FOPEN_MAX} streams are currently open in the calling process. 47428 CX [ENOMEM] Insufficient storage space is available. 47429 EXAMPLES 47430 Creating a Temporary File 47431 The following example creates a temporary file for update, and returns a pointer to a stream for 47432 the created file in the fp variable. 47433 #include 47434 ... 47435 FILE *fp; 47436 fp = tmpfile (); System Interfaces, Issue 6 2029 tmpfile( ) System Interfaces 47437 APPLICATION USAGE 47438 It should be possible to open at least {TMP_MAX} temporary files during the lifetime of the 47439 program (this limit may be shared with tmpnam( )) and there should be no limit on the number 47440 simultaneously open other than this limit and any limit on the number of open files 47441 ({FOPEN_MAX}). 47442 RATIONALE 47443 None. 47444 FUTURE DIRECTIONS 47445 None. 47446 SEE ALSO 47447 fopen( ), tmpnam( ), unlink( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47448 CHANGE HISTORY 47449 First released in Issue 1. Derived from Issue 1 of the SVID. 47450 Issue 5 47451 Large File Summit extensions are added. 47452 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 47453 in previous issues. 47454 Issue 6 47455 Extensions beyond the ISO C standard are now marked. 47456 The following new requirements on POSIX implementations derive from alignment with the 47457 Single UNIX Specification: 47458 * In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 47459 large files. 47460 * The [EMFILE] optional error condition is added. 47461 The APPLICATION USAGE section is added for alignment with the ISO/IEC 9899: 1999 47462 standard. 2030 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tmpnam( ) 47463 NAME 47464 tmpnam - create a name for a temporary file 47465 SYNOPSIS 47466 #include 47467 char *tmpnam(char *s); 47468 DESCRIPTION 47469 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47470 conflict between the requirements described here and the ISO C standard is unintentional. This 47471 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47472 The tmpnam( ) function shall generate a string that is a valid filename and that is not the same as 47473 the name of an existing file. The function is potentially capable of generating {TMP_MAX} 47474 different strings, but any or all of them may already be in use by existing files and thus not be 47475 suitable return values. 47476 The tmpnam( ) function generates a different string each time it is called from the same process, 47477 up to {TMP_MAX} times. If it is called more than {TMP_MAX} times, the behavior is 47478 implementation-defined. 47479 The implementation shall behave as if no function defined in this volume of 47480 IEEE Std 1003.1-200x calls tmpnam( ). 47481 CX If the application uses any of the functions guaranteed to be available if either 47482 _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined, the application shall 47483 ensure that the tmpnam( ) function is called with a non-NULL parameter. 47484 RETURN VALUE 47485 Upon successful completion, tmpnam( ) shall return a pointer to a string. If no suitable string can 47486 be generated, the tmpnam( ) function shall return a null pointer. 47487 If the argument s is a null pointer, tmpnam( ) shall leave its result in an internal static object and 47488 return a pointer to that object. Subsequent calls to tmpnam( ) may modify the same object. If the 47489 argument s is not a null pointer, it is presumed to point to an array of at least L_tmpnam chars; 47490 tmpnam( ) shall write its result in that array and shall return the argument as its value. 47491 ERRORS 47492 No errors are defined. 47493 EXAMPLES 47494 Generating a Filename 47495 The following example generates a unique filename and stores it in the array pointed to by ptr. 47496 #include 47497 ... 47498 char filename[L_tmpnam+1]; 47499 char *ptr; 47500 ptr = tmpnam(filename); 47501 APPLICATION USAGE 47502 This function only creates filenames. It is the application's responsibility to create and remove 47503 the files. 47504 Between the time a pathname is created and the file is opened, it is possible for some other | 47505 process to create a file with the same name. Applications may find tmpfile( ) more useful. System Interfaces, Issue 6 2031 tmpnam( ) System Interfaces 47506 RATIONALE 47507 None. 47508 FUTURE DIRECTIONS 47509 None. 47510 SEE ALSO 47511 fopen( ), open( ), tempnam( ), tmpfile( ), unlink( ), the Base Definitions volume of 47512 IEEE Std 1003.1-200x, 47513 CHANGE HISTORY 47514 First released in Issue 1. Derived from Issue 1 of the SVID. 47515 Issue 5 47516 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 47517 Issue 6 47518 Extensions beyond the ISO C standard are now marked. 47519 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 47520 The DESCRIPTION is expanded for alignment with the ISO/IEC 9899: 1999 standard. 2032 Technical Standard (2001) (Draft April 16, 2001) System Interfaces toascii( ) 47521 NAME 47522 toascii - translate integer to a 7-bit ASCII character 47523 SYNOPSIS 47524 XSI #include 47525 int toascii(int c); 47526 47527 DESCRIPTION 47528 The toascii( ) function shall convert its argument into a 7-bit ASCII character. 47529 RETURN VALUE 47530 The toascii( ) function shall return the value (c &0x7f). 47531 ERRORS 47532 No errors are returned. 47533 EXAMPLES 47534 None. 47535 APPLICATION USAGE 47536 None. 47537 RATIONALE 47538 None. 47539 FUTURE DIRECTIONS 47540 None. 47541 SEE ALSO 47542 isascii( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47543 CHANGE HISTORY 47544 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 2033 tolower( ) System Interfaces 47545 NAME 47546 tolower - transliterate uppercase characters to lowercase 47547 SYNOPSIS 47548 #include 47549 int tolower(int c); 47550 DESCRIPTION 47551 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47552 conflict between the requirements described here and the ISO C standard is unintentional. This 47553 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47554 The tolower( ) function has as a domain a type int, the value of which is representable as an 47555 unsigned char or the value of EOF. If the argument has any other value, the behavior is 47556 undefined. If the argument of tolower( ) represents an uppercase letter, and there exists a 47557 CX corresponding lowercase letter (as defined by character type information in the program locale 47558 category LC_CTYPE),the result shall be the corresponding lowercase letter. All other arguments | 47559 in the domain are returned unchanged. | 47560 RETURN VALUE 47561 Upon successful completion, tolower( ) shall return the lowercase letter corresponding to the 47562 argument passed; otherwise, it shall return the argument unchanged. 47563 ERRORS 47564 No errors are defined. 47565 EXAMPLES 47566 None. 47567 APPLICATION USAGE 47568 None. 47569 RATIONALE 47570 None. 47571 FUTURE DIRECTIONS 47572 None. 47573 SEE ALSO 47574 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 47575 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 47576 CHANGE HISTORY 47577 First released in Issue 1. Derived from Issue 1 of the SVID. 47578 Issue 6 47579 Extensions beyond the ISO C standard are now marked. 2034 Technical Standard (2001) (Draft April 16, 2001) System Interfaces toupper( ) 47580 NAME 47581 toupper - transliterate lowercase characters to uppercase 47582 SYNOPSIS 47583 #include 47584 int toupper(int c); 47585 DESCRIPTION 47586 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47587 conflict between the requirements described here and the ISO C standard is unintentional. This 47588 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47589 The toupper( ) function has as a domain a type int, the value of which is representable as an 47590 unsigned char or the value of EOF. If the argument has any other value, the behavior is 47591 undefined. If the argument of toupper( ) represents a lowercase letter, and there exists a 47592 CX corresponding uppercase letter (as defined by character type information in the program locale 47593 category LC_CTYPE),the result shall be the corresponding uppercase letter. All other arguments | 47594 in the domain are returned unchanged. | 47595 RETURN VALUE 47596 Upon successful completion, toupper( ) shall return the uppercase letter corresponding to the 47597 argument passed. 47598 ERRORS 47599 No errors are defined. 47600 EXAMPLES 47601 None. 47602 APPLICATION USAGE 47603 None. 47604 RATIONALE 47605 None. 47606 FUTURE DIRECTIONS 47607 None. 47608 SEE ALSO 47609 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 47610 volume of IEEE Std 1003.1-200x, Chapter 7, Locale 47611 CHANGE HISTORY 47612 First released in Issue 1. Derived from Issue 1 of the SVID. 47613 Issue 6 47614 Extensions beyond the ISO C standard are now marked. System Interfaces, Issue 6 2035 towctrans( ) System Interfaces 47615 NAME 47616 towctrans - wide-character transliteration | 47617 SYNOPSIS 47618 #include 47619 wint_t towctrans(wint_t wc, wctrans_t desc); 47620 DESCRIPTION 47621 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47622 conflict between the requirements described here and the ISO C standard is unintentional. This 47623 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47624 The towctrans( ) function shall transliterate the wide-character code wc using the mapping | 47625 described by desc. The current setting of the LC_CTYPE category should be the same as during 47626 CX the call to wctrans( ) that returned the value desc. If the value of desc is invalid (that is, not 47627 obtained by a call to wctrans( ) or desc is invalidated by a subsequent call to setlocale( ) that has 47628 affected category LC_CTYPE), the result is unspecified. 47629 An application wishing to check for error situations should set errno to 0 before calling 47630 towctrans( ). If errno is non-zero on return, an error has occurred. 47631 RETURN VALUE 47632 If successful, the towctrans( ) function shall return the mapped value of wc using the mapping 47633 described by desc. Otherwise, it shall return wc unchanged. 47634 ERRORS 47635 The towctrans( ) function may fail if: 47636 CX [EINVAL] desc contains an invalid transliteration descriptor. 47637 EXAMPLES 47638 None. 47639 APPLICATION USAGE 47640 The strings "tolower" and "toupper" are reserved for the standard mapping names. In the 47641 table below, the functions in the left column are equivalent to the functions in the right column. 47642 towlower(wc) towctrans(wc, wctrans("tolower")) 47643 towupper(wc) towctrans(wc, wctrans("toupper")) 47644 RATIONALE 47645 None. 47646 FUTURE DIRECTIONS 47647 None. 47648 SEE ALSO 47649 towlower( ), towupper( ), wctrans( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47650 47651 CHANGE HISTORY 47652 First released in Issue 5. Derived from ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 47653 Issue 6 47654 Extensions beyond the ISO C standard are now marked. 2036 Technical Standard (2001) (Draft April 16, 2001) System Interfaces towlower( ) 47655 NAME 47656 towlower - transliterate uppercase wide-character code to lowercase 47657 SYNOPSIS 47658 #include 47659 wint_t towlower(wint_t wc); 47660 DESCRIPTION 47661 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47662 conflict between the requirements described here and the ISO C standard is unintentional. This 47663 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47664 The towlower( ) function has as a domain a type wint_t, the value of which the application shall 47665 ensure is a character representable as a wchar_t, and a wide-character code corresponding to a 47666 valid character in the current locale or the value of WEOF. If the argument has any other value, 47667 the behavior is undefined. If the argument of towlower( ) represents an uppercase wide-character 47668 code, and there exists a corresponding lowercase wide-character code (as defined by character 47669 type information in the program locale category LC_CTYPE), the result shall be the | 47670 corresponding lowercase wide-character code. All other arguments in the domain are returned | 47671 unchanged. | 47672 RETURN VALUE 47673 Upon successful completion, towlower( ) shall return the lowercase letter corresponding to the 47674 argument passed; otherwise, it shall return the argument unchanged. 47675 ERRORS 47676 No errors are defined. 47677 EXAMPLES 47678 None. 47679 APPLICATION USAGE 47680 None. 47681 RATIONALE 47682 None. 47683 FUTURE DIRECTIONS 47684 None. 47685 SEE ALSO 47686 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the 47687 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 47688 CHANGE HISTORY 47689 First released in Issue 4. 47690 Issue 5 47691 The following change has been made in this issue for alignment with 47692 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 47693 * The SYNOPSIS has been changed to indicate that this function and associated data types are 47694 now made visible by inclusion of the header rather than . 47695 Issue 6 47696 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 2037 towupper( ) System Interfaces 47697 NAME 47698 towupper - transliterate lowercase wide-character code to uppercase 47699 SYNOPSIS 47700 #include 47701 wint_t towupper(wint_t wc); 47702 DESCRIPTION 47703 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47704 conflict between the requirements described here and the ISO C standard is unintentional. This 47705 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47706 The towupper( ) function has as a domain a type wint_t, the value of which the application shall 47707 ensure is a character representable as a wchar_t, and a wide-character code corresponding to a 47708 valid character in the current locale or the value of WEOF. If the argument has any other value, 47709 the behavior is undefined. If the argument of towupper( ) represents a lowercase wide-character 47710 code, and there exists a corresponding uppercase wide-character code (as defined by character 47711 type information in the program locale category LC_CTYPE), the result shall be the | 47712 corresponding uppercase wide-character code. All other arguments in the domain are returned | 47713 unchanged. | 47714 RETURN VALUE 47715 Upon successful completion, towupper( ) shall return the uppercase letter corresponding to the 47716 argument passed. Otherwise, it shall return the argument unchanged. 47717 ERRORS 47718 No errors are defined. 47719 EXAMPLES 47720 None. 47721 APPLICATION USAGE 47722 None. 47723 RATIONALE 47724 None. 47725 FUTURE DIRECTIONS 47726 None. 47727 SEE ALSO 47728 setlocale( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , the 47729 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 7, Locale 47730 CHANGE HISTORY 47731 First released in Issue 4. 47732 Issue 5 47733 The following change has been made in this issue for alignment with 47734 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 47735 * The SYNOPSIS has been changed to indicate that this function and associated data types are 47736 now made visible by inclusion of the header rather than . 47737 Issue 6 47738 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2038 Technical Standard (2001) (Draft April 16, 2001) System Interfaces trunc( ) 47739 NAME 47740 trunc, truncf, truncl - round to truncated integer value 47741 SYNOPSIS 47742 #include 47743 double trunc(double x); 47744 float truncf(float x); 47745 long double truncl(long double x); 47746 DESCRIPTION 47747 CX The functionality described on this reference page is aligned with the ISO C standard. Any 47748 conflict between the requirements described here and the ISO C standard is unintentional. This 47749 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 47750 These functions shall round their argument to the integer value, in floating format, nearest to but 47751 no larger in magnitude than the argument. 47752 RETURN VALUE 47753 Upon successful completion, these functions shall return the truncated integer value. 47754 MX If x is NaN, a NaN shall be returned. 47755 If x is ±0, or ±Inf, x shall be returned. 47756 ERRORS 47757 No errors are defined. 47758 EXAMPLES 47759 None. 47760 APPLICATION USAGE 47761 None. 47762 RATIONALE 47763 None. 47764 FUTURE DIRECTIONS 47765 None. 47766 SEE ALSO 47767 The Base Definitions volume of IEEE Std 1003.1-200x, 47768 CHANGE HISTORY 47769 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2039 truncate( ) System Interfaces 47770 NAME 47771 truncate - truncate a file to a specified length 47772 SYNOPSIS 47773 XSI #include 47774 int truncate(const char *path, off_t length); 47775 47776 DESCRIPTION 47777 The truncate( ) function shall cause the regular file named by path to have a size which shall be 47778 equal to length bytes. 47779 If the file previously was larger than length, the extra data is discarded. If the file was previously 47780 shorter than length, its size is increased, and the extended area appears as if it were zero-filled. 47781 The application shall ensure that the process has write permission for the file. 47782 If the request would cause the file size to exceed the soft file size limit for the process, the 47783 request shall fail and the implementation shall generate the SIGXFSZ signal for the process. 47784 This function shall not modify the file offset for any open file descriptions associated with the 47785 file. Upon successful completion, if the file size is changed, this function shall mark for update 47786 the st_ctime and st_mtime fields of the file, and the S_ISUID and S_ISGID bits of the file mode 47787 may be cleared. 47788 RETURN VALUE 47789 Upon successful completion, truncate( ) shall return 0. Otherwise, -1 shall be returned, and errno 47790 set to indicate the error. 47791 ERRORS 47792 The truncate( ) function shall fail if: 47793 [EINTR] A signal was caught during execution. 47794 [EINVAL] The length argument was less than 0. 47795 [EFBIG] or [EINVAL] 47796 The length argument was greater than the maximum file size. 47797 [EIO] An I/O error occurred while reading from or writing to a file system. 47798 [EACCES] A component of the path prefix denies search permission, or write permission 47799 is denied on the file. 47800 [EISDIR] The named file is a directory. 47801 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 47802 argument. 47803 [ENAMETOOLONG] 47804 The length of the path argument exceeds {PATH_MAX} or a pathname | 47805 component is longer than {NAME_MAX}. | 47806 [ENOENT] A component of path does not name an existing file or path is an empty string. 47807 [ENOTDIR] A component of the path prefix of path is not a directory. 47808 [EROFS] The named file resides on a read-only file system. 47809 The truncate( ) function may fail if: 2040 Technical Standard (2001) (Draft April 16, 2001) System Interfaces truncate( ) 47810 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 47811 resolution of the path argument. 47812 [ENAMETOOLONG] 47813 Pathname resolution of a symbolic link produced an intermediate result | 47814 whose length exceeds {PATH_MAX}. 47815 EXAMPLES 47816 None. 47817 APPLICATION USAGE 47818 None. 47819 RATIONALE 47820 None. 47821 FUTURE DIRECTIONS 47822 None. 47823 SEE ALSO 47824 open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47825 CHANGE HISTORY 47826 First released in Issue 4, Version 2. 47827 Issue 5 47828 Moved from X/OPEN UNIX extension to BASE. 47829 Large File Summit extensions are added. 47830 Issue 6 47831 This reference page is split out from the ftruncate( ) reference page. 47832 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 47833 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 47834 [ELOOP] error condition is added. System Interfaces, Issue 6 2041 truncf( ) System Interfaces 47835 NAME 47836 truncf, truncl - round to truncated integer value 47837 SYNOPSIS 47838 #include 47839 float truncf(float x); 47840 long double truncl(long double x); 47841 DESCRIPTION 47842 Refer to trunc( ). 2042 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tsearch( ) 47843 NAME 47844 tsearch - search a binary search tree 47845 SYNOPSIS 47846 XSI #include 47847 void *tsearch(const void *key, void **rootp, 47848 int (*compar)(const void *, const void *)); 47849 47850 DESCRIPTION 47851 Refer to tdelete( ). System Interfaces, Issue 6 2043 ttyname( ) System Interfaces 47852 NAME 47853 ttyname, ttyname_r - find pathname of a terminal | 47854 SYNOPSIS 47855 #include 47856 char *ttyname(int fildes); 47857 TSF int ttyname_r(int fildes, char *name, size_t namesize); 47858 47859 DESCRIPTION 47860 The ttyname( ) function shall return a pointer to a string containing a null-terminated pathname | 47861 of the terminal associated with file descriptor fildes. The return value may point to static data | 47862 whose content is overwritten by each call. 47863 The ttyname( ) function need not be reentrant. A function that is not required to be reentrant is 47864 not required to be thread-safe. 47865 TSF The ttyname_r( ) function shall store the null-terminated pathname of the terminal associated | 47866 with the file descriptor fildes in the character array referenced by name. The array is namesize | 47867 characters long and should have space for the name and the terminating null character. The | 47868 maximum length of the terminal name shall be {TTY_NAME_MAX}. | 47869 RETURN VALUE 47870 Upon successful completion, ttyname( ) shall return a pointer to a string. Otherwise, a null 47871 pointer shall be returned and errno set to indicate the error. 47872 TSF If successful, the ttyname_r( ) function shall return zero. Otherwise, an error number shall be 47873 returned to indicate the error. 47874 ERRORS 47875 The ttyname( ) function may fail if: 47876 [EBADF] The fildes argument is not a valid file descriptor. 47877 [ENOTTY] The fildes argument does not refer to a terminal. 47878 The ttyname_r( ) function may fail if: 47879 TSF [EBADF] The fildes argument is not a valid file descriptor. 47880 TSF [ENOTTY] The fildes argument does not refer to a terminal. | 47881 TSF [ERANGE] The value of namesize is smaller than the length of the string to be returned 47882 including the terminating null character. 47883 EXAMPLES 47884 None. 47885 APPLICATION USAGE 47886 None. 47887 RATIONALE 47888 The term terminal is used instead of the historical term terminal device in order to avoid a 47889 reference to an undefined term. 47890 The thread-safe version places the terminal name in a user-supplied buffer and returns a non- 47891 zero value if it fails. The non-thread-safe version may return the name in a static data area that 47892 may be overwritten by each call. 2044 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ttyname( ) 47893 FUTURE DIRECTIONS 47894 None. 47895 SEE ALSO 47896 The Base Definitions volume of IEEE Std 1003.1-200x, 47897 CHANGE HISTORY 47898 First released in Issue 1. Derived from Issue 1 of the SVID. 47899 Issue 5 47900 The ttyname_r( ) function is included for alignment with the POSIX Threads Extension. 47901 A note indicating that the ttyname( ) function need not be reentrant is added to the 47902 DESCRIPTION. 47903 Issue 6 47904 The ttyname_r( ) function is marked as part of the Thread-Safe Functions option. 47905 The following new requirements on POSIX implementations derive from alignment with the 47906 Single UNIX Specification: 47907 * The statement that errno is set on error is added. 47908 * The [EBADF] and [ENOTTY] optional error conditions are added. System Interfaces, Issue 6 2045 twalk( ) System Interfaces 47909 NAME 47910 twalk - traverse a binary search tree 47911 SYNOPSIS 47912 XSI #include 47913 void twalk(const void *root, 47914 void (*action)(const void *, VISIT, int )); 47915 47916 DESCRIPTION 47917 Refer to tdelete( ). 2046 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tzname 47918 NAME 47919 tzname - timezone strings 47920 SYNOPSIS 47921 CX #include | 47922 extern char *tzname[2]; 47923 | 47924 DESCRIPTION 47925 Refer to tzset( ). System Interfaces, Issue 6 2047 tzset( ) System Interfaces 47926 NAME 47927 daylight, timezone, tzname, tzset - set timezone conversion information 47928 SYNOPSIS 47929 #include 47930 XSI extern int daylight; 47931 extern long timezone; 47932 CX extern char *tzname[2]; | 47933 void tzset(void); 47934 | 47935 DESCRIPTION 47936 The tzset( ) function shall use the value of the environment variable TZ to set time conversion | 47937 information used by ctime( ), localtime( ), mktime( ), and strftime( ). If TZ is absent from the 47938 environment, implementation-defined default timezone information shall be used. | 47939 The tzset( ) function shall set the external variable tzname as follows: 47940 tzname[0] = "std"; 47941 tzname[1] = "dst"; 47942 where std and dst are as described in the Base Definitions volume of IEEE Std 1003.1-200x, 47943 Chapter 8, Environment Variables. 47944 XSI The tzset( ) function also shall set the external variable daylight to 0 if Daylight Savings Time 47945 conversions should never be applied for the timezone in use; otherwise, non-zero. The external 47946 variable timezone shall be set to the difference, in seconds, between Coordinated Universal Time 47947 (UTC) and local standard time. 47948 RETURN VALUE 47949 The tzset( ) function shall not return a value. 47950 ERRORS 47951 No errors are defined. 47952 EXAMPLES 47953 Example TZ variables and their timezone differences are given in the table below: 47954 ________________________ 47955 _ TZ timezone _______________________ 47956 EST5EDT 5*60*60 | 47957 GMT0 0*60*60 | 47958 JST-9 -9*60*60 | 47959 MET-1MEST -1*60*60 | 47960 MST7MDT 7*60*60 | 47961 _ PST8PDT 8*60*60 _______________________ || 47962 APPLICATION USAGE | 47963 None. 47964 RATIONALE 47965 None. 47966 FUTURE DIRECTIONS 47967 None. 2048 Technical Standard (2001) (Draft April 16, 2001) System Interfaces tzset( ) 47968 SEE ALSO 47969 ctime( ), localtime( ), mktime( ), strftime( ), the Base Definitions volume of IEEE Std 1003.1-200x, 47970 47971 CHANGE HISTORY 47972 First released in Issue 1. Derived from Issue 1 of the SVID. | 47973 Issue 6 | 47974 The example is corrected. | System Interfaces, Issue 6 2049 ualarm( ) System Interfaces 47975 NAME 47976 ualarm - set the interval timer 47977 SYNOPSIS 47978 OB XSI #include 47979 useconds_t ualarm(useconds_t useconds, useconds_t interval); 47980 47981 DESCRIPTION 47982 The ualarm( ) function shall cause the SIGALRM signal to be generated for the calling process 47983 after the number of realtime microseconds specified by the useconds argument has elapsed. 47984 When the interval argument is non-zero, repeated timeout notification occurs with a period in 47985 microseconds specified by the interval argument. If the notification signal, SIGALRM, is not 47986 caught or ignored, the calling process is terminated. 47987 Implementations may place limitations on the granularity of timer values. For each interval 47988 timer, if the requested timer value requires a finer granularity than the implementation supports, 47989 the actual timer value shall be rounded up to the next supported value. 47990 Interactions between ualarm( ) and any of the following are unspecified: 47991 alarm( ) 47992 nanosleep( ) 47993 setitimer( ) 47994 timer_create( ) 47995 timer_delete( ) 47996 timer_getoverrun( ) 47997 timer_gettime( ) 47998 timer_settime( ) 47999 sleep( ) 48000 RETURN VALUE 48001 The ualarm( ) function shall return the number of microseconds remaining from the previous 48002 ualarm( ) call. If no timeouts are pending or if ualarm( ) has not previously been called, ualarm( ) 48003 shall return 0. 48004 ERRORS 48005 No errors are defined. 48006 EXAMPLES 48007 None. 48008 APPLICATION USAGE 48009 Applications are recommended to use nanosleep( ) if the Timers option is supported, or 48010 setitimer( ), timer_create( ), timer_delete( ), timer_getoverrun( ), timer_gettime( ), or timer_settime( ) 48011 instead of this function. 48012 RATIONALE 48013 None. 48014 FUTURE DIRECTIONS 48015 None. 48016 SEE ALSO 48017 alarm( ), nanosleep( ), setitimer( ), sleep( ), timer_create( ), timer_delete( ), timer_getoverrun( ), the Base 48018 Definitions volume of IEEE Std 1003.1-200x, 2050 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ualarm( ) 48019 CHANGE HISTORY 48020 First released in Issue 4, Version 2. 48021 Issue 5 48022 Moved from X/OPEN UNIX extension to BASE. 48023 Issue 6 48024 This function is marked obsolescent. System Interfaces, Issue 6 2051 ulimit( ) System Interfaces 48025 NAME 48026 ulimit - get and set process limits 48027 SYNOPSIS 48028 XSI #include 48029 long ulimit(int cmd, ...); 48030 48031 DESCRIPTION 48032 The ulimit( ) function shall control process limits. The process limits that can be controlled by | 48033 this function include the maximum size of a single file that can be written (this is equivalent to | 48034 using setrlimit( ) with RLIMIT_FSIZE). The cmd values, defined in include: | 48035 UL_GETFSIZE Return the file size limit (RLIMIT_FSIZE) of the process. The limit shall be in | 48036 units of 512-byte blocks and shall be inherited by child processes. Files of any | 48037 size can be read. The return value shall be the integer part of the soft file size | 48038 limit divided by 512. If the result cannot be represented as a long, the result is | 48039 unspecified. 48040 UL_SETFSIZE Set the file size limit for output operations of the process to the value of the 48041 second argument, taken as a long, multiplied by 512. If the result would 48042 overflow an rlim_t, the actual value set is unspecified. Any process may 48043 decrease its own limit, but only a process with appropriate privileges may 48044 increase the limit. The return value shall be the integer part of the new file size 48045 limit divided by 512. 48046 The ulimit( ) function shall not change the setting of errno if successful. 48047 As all return values are permissible in a successful situation, an application wishing to check for 48048 error situations should set errno to 0, then call ulimit( ), and, if it returns -1, check to see if errno is 48049 non-zero. 48050 RETURN VALUE 48051 Upon successful completion, ulimit( ) shall return the value of the requested limit. Otherwise, -1 48052 shall be returned and errno set to indicate the error. 48053 ERRORS 48054 The ulimit( ) function shall fail and the limit shall be unchanged if: 48055 [EINVAL] The cmd argument is not valid. 48056 [EPERM] A process not having appropriate privileges attempts to increase its file size 48057 limit. 48058 EXAMPLES 48059 None. 48060 APPLICATION USAGE 48061 None. 48062 RATIONALE 48063 None. 48064 FUTURE DIRECTIONS 48065 None. 2052 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ulimit( ) 48066 SEE ALSO 48067 getrlimit( ), setrlimit( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48068 CHANGE HISTORY 48069 First released in Issue 1. Derived from Issue 1 of the SVID. 48070 Issue 5 48071 In the description of UL_SETFSIZE, the text is corrected to refer to rlim_t rather than the 48072 spurious rlimit_t. 48073 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. System Interfaces, Issue 6 2053 umask( ) System Interfaces 48074 NAME 48075 umask - set and get file mode creation mask 48076 SYNOPSIS 48077 #include 48078 mode_t umask(mode_t cmask); 48079 DESCRIPTION 48080 The umask( ) function shall set the process' file mode creation mask to cmask and return the 48081 previous value of the mask. Only the file permission bits of cmask (see ) are used; the 48082 meaning of the other bits is implementation-defined. 48083 The process' file mode creation mask is used during open( ), creat( ), mkdir( ), and mkfifo( ) to turn 48084 off permission bits in the mode argument supplied. Bit positions that are set in cmask are cleared 48085 in the mode of the created file. 48086 RETURN VALUE 48087 The file permission bits in the value returned by umask( ) shall be the previous value of the file 48088 mode creation mask. The state of any other bits in that value is unspecified, except that a 48089 subsequent call to umask( ) with the returned value as cmask shall leave the state of the mask the 48090 same as its state before the first call, including any unspecified use of those bits. 48091 ERRORS 48092 No errors are defined. 48093 EXAMPLES 48094 None. 48095 APPLICATION USAGE 48096 None. 48097 RATIONALE 48098 Unsigned argument and return types for umask( ) were proposed. The return type and the 48099 argument were both changed to mode_t. 48100 Historical implementations have made use of additional bits in cmask for their implementation- 48101 defined purposes. The addition of the text that the meaning of other bits of the field is 48102 implementation-defined permits these implementations to conform to this volume of 48103 IEEE Std 1003.1-200x. 48104 FUTURE DIRECTIONS 48105 None. 48106 SEE ALSO 48107 creat( ), mkdir( ), mkfifo( ), open( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48108 , 48109 CHANGE HISTORY 48110 First released in Issue 1. Derived from Issue 1 of the SVID. 48111 Issue 6 48112 In the SYNOPSIS, the optional include of the header is removed. | 2054 Technical Standard (2001) (Draft April 16, 2001) System Interfaces umask( ) 48113 The following new requirements on POSIX implementations derive from alignment with the | 48114 Single UNIX Specification: 48115 * The requirement to include has been removed. Although was 48116 required for conforming implementations of previous POSIX specifications, it was not 48117 required for UNIX applications. System Interfaces, Issue 6 2055 uname( ) System Interfaces 48118 NAME 48119 uname - get name of current system 48120 SYNOPSIS 48121 #include 48122 int uname(struct utsname *name); 48123 DESCRIPTION 48124 The uname( ) function shall store information identifying the current system in the structure 48125 pointed to by name. 48126 The uname( ) function uses the utsname structure defined in . 48127 The uname( ) function shall return a string naming the current system in the character array 48128 sysname. Similarly, nodename shall contain the name of this node within an implementation- | 48129 defined communications network. The arrays release and version shall further identify the | 48130 operating system. The array machine shall contain a name that identifies the hardware that the | 48131 system is running on. 48132 The format of each member is implementation-defined. 48133 RETURN VALUE 48134 Upon successful completion, a non-negative value shall be returned. Otherwise, -1 shall be 48135 returned and errno set to indicate the error. 48136 ERRORS 48137 No errors are defined. 48138 EXAMPLES 48139 None. 48140 APPLICATION USAGE 48141 The inclusion of the nodename member in this structure does not imply that it is sufficient 48142 information for interfacing to communications networks. 48143 RATIONALE 48144 The values of the structure members are not constrained to have any relation to the version of 48145 this volume of IEEE Std 1003.1-200x implemented in the operating system. An application 48146 should instead depend on _POSIX_VERSION and related constants defined in . 48147 This volume of IEEE Std 1003.1-200x does not define the sizes of the members of the structure 48148 and permits them to be of different sizes, although most implementations define them all to be 48149 the same size: eight bytes plus one byte for the string terminator. That size for nodename is not 48150 enough for use with many networks. 48151 The uname( ) function originated in System III, System V, and related implementations, and it | 48152 does not exist in Version 7 or 4.3 BSD. The values it returns are set at system compile time in 48153 those historical implementations. 48154 4.3 BSD has gethostname( ) and gethostid( ), which return a symbolic name and a numeric value, 48155 respectively. There are related sethostname( ) and sethostid( ) functions that are used to set the 48156 values the other two functions return. The former functions are included in this specification, the | 48157 latter are not. | 48158 FUTURE DIRECTIONS 48159 None. 2056 Technical Standard (2001) (Draft April 16, 2001) System Interfaces uname( ) 48160 SEE ALSO 48161 The Base Definitions volume of IEEE Std 1003.1-200x, 48162 CHANGE HISTORY 48163 First released in Issue 1. Derived from Issue 1 of the SVID. System Interfaces, Issue 6 2057 ungetc( ) System Interfaces 48164 NAME 48165 ungetc - push byte back into input stream 48166 SYNOPSIS 48167 #include 48168 int ungetc(int c, FILE *stream); 48169 DESCRIPTION 48170 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48171 conflict between the requirements described here and the ISO C standard is unintentional. This 48172 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48173 The ungetc( ) function shall push the byte specified by c (converted to an unsigned char) back 48174 onto the input stream pointed to by stream. The pushed-back bytes shall be returned by 48175 subsequent reads on that stream in the reverse order of their pushing. A successful intervening 48176 call (with the stream pointed to by stream) to a file-positioning function (fseek( ), fsetpos( ), or 48177 rewind( )) shall discard any pushed-back bytes for the stream. The external storage | 48178 corresponding to the stream shall be unchanged. | 48179 One byte of push-back shall be provided. If ungetc( ) is called too many times on the same stream | 48180 without an intervening read or file-positioning operation on that stream, the operation may fail. 48181 If the value of c equals that of the macro EOF, the operation shall fail and the input stream shall | 48182 be left unchanged. | 48183 A successful call to ungetc( ) shall clear the end-of-file indicator for the stream. The value of the 48184 file-position indicator for the stream after reading or discarding all pushed-back bytes shall be 48185 the same as it was before the bytes were pushed back. The file-position indicator is decremented 48186 by each successful call to ungetc( ); if its value was 0 before a call, its value is unspecified after | 48187 the call. | 48188 RETURN VALUE 48189 Upon successful completion, ungetc( ) shall return the byte pushed back after conversion. 48190 Otherwise, it shall return EOF. 48191 ERRORS 48192 No errors are defined. 48193 EXAMPLES 48194 None. 48195 APPLICATION USAGE 48196 None. 48197 RATIONALE 48198 None. 48199 FUTURE DIRECTIONS 48200 None. 48201 SEE ALSO 48202 fseek( ), getc( ), fsetpos( ), read( ), rewind( ), setbuf( ), the Base Definitions volume of 48203 IEEE Std 1003.1-200x, 48204 CHANGE HISTORY 48205 First released in Issue 1. Derived from Issue 1 of the SVID. 2058 Technical Standard (2001) (Draft April 16, 2001) System Interfaces ungetwc( ) 48206 NAME 48207 ungetwc - push wide-character code back into input stream 48208 SYNOPSIS 48209 #include 48210 #include 48211 wint_t ungetwc(wint_t wc, FILE *stream); 48212 DESCRIPTION 48213 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48214 conflict between the requirements described here and the ISO C standard is unintentional. This 48215 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48216 The ungetwc( ) function shall push the character corresponding to the wide-character code 48217 specified by wc back onto the input stream pointed to by stream. The pushed-back characters 48218 shall be returned by subsequent reads on that stream in the reverse order of their pushing. A 48219 successful intervening call (with the stream pointed to by stream) to a file-positioning function 48220 (fseek( ), fsetpos( ), or rewind( )) discards any pushed-back characters for the stream. The external 48221 storage corresponding to the stream is unchanged. 48222 At least one character of push-back shall be provided. If ungetwc( ) is called too many times on | 48223 the same stream without an intervening read or file-positioning operation on that stream, the 48224 operation may fail. 48225 If the value of wc equals that of the macro WEOF, the operation shall fail and the input stream | 48226 shall be left unchanged. | 48227 A successful call to ungetwc( ) shall clear the end-of-file indicator for the stream. The value of the 48228 file-position indicator for the stream after reading or discarding all pushed-back characters shall 48229 be the same as it was before the characters were pushed back. The file-position indicator is 48230 decremented (by one or more) by each successful call to ungetwc( ); if its value was 0 before a | 48231 call, its value is unspecified after the call. | 48232 RETURN VALUE 48233 Upon successful completion, ungetwc( ) shall return the wide-character code corresponding to 48234 the pushed-back character. Otherwise, it shall return WEOF. 48235 ERRORS 48236 The ungetwc( ) function may fail if: 48237 CX [EILSEQ] An invalid character sequence is detected, or a wide-character code does not | 48238 correspond to a valid character. | 48239 EXAMPLES 48240 None. 48241 APPLICATION USAGE 48242 None. 48243 RATIONALE 48244 None. 48245 FUTURE DIRECTIONS 48246 None. System Interfaces, Issue 6 2059 ungetwc( ) System Interfaces 48247 SEE ALSO 48248 fseek( ), fsetpos( ), read( ), rewind( ), setbuf( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48249 , 48250 CHANGE HISTORY 48251 First released in Issue 4. Derived from the MSE working draft. 48252 Issue 5 48253 The Optional Header (OH) marking is removed from . | 48254 Issue 6 | 48255 The [EILSEQ] optional error condition is marked CX. | 2060 Technical Standard (2001) (Draft April 16, 2001) System Interfaces unlink( ) 48256 NAME 48257 unlink - remove a directory entry 48258 SYNOPSIS 48259 #include 48260 int unlink(const char *path); 48261 DESCRIPTION 48262 The unlink( ) function shall remove a link to a file. If path names a symbolic link, unlink( ) shall | 48263 remove the symbolic link named by path and shall not affect any file or directory named by the | 48264 contents of the symbolic link. Otherwise, unlink( ) shall remove the link named by the pathname | 48265 pointed to by path and shall decrement the link count of the file referenced by the link. | 48266 When the file's link count becomes 0 and no process has the file open, the space occupied by the 48267 file shall be freed and the file shall no longer be accessible. If one or more processes have the file 48268 open when the last link is removed, the link shall be removed before unlink( ) returns, but the 48269 removal of the file contents shall be postponed until all references to the file are closed. 48270 The path argument shall not name a directory unless the process has appropriate privileges and | 48271 the implementation supports using unlink( ) on directories. 48272 Upon successful completion, unlink( ) shall mark for update the st_ctime and st_mtime fields of 48273 the parent directory. Also, if the file's link count is not 0, the st_ctime field of the file shall be 48274 marked for update. 48275 RETURN VALUE 48276 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 48277 indicate the error. If -1 is returned, the named file shall not be changed. 48278 ERRORS 48279 The unlink( ) function shall fail and shall not unlink the file if: 48280 [EACCES] Search permission is denied for a component of the path prefix, or write 48281 permission is denied on the directory containing the directory entry to be 48282 removed. 48283 [EBUSY] The file named by the path argument cannot be unlinked because it is being 48284 used by the system or another process and the implementation considers this 48285 an error. 48286 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 48287 argument. 48288 [ENAMETOOLONG] 48289 The length of the path argument exceeds {PATH_MAX} or a pathname | 48290 component is longer than {NAME_MAX}. | 48291 [ENOENT] A component of path does not name an existing file or path is an empty string. 48292 [ENOTDIR] A component of the path prefix is not a directory. 48293 [EPERM] The file named by path is a directory, and either the calling process does not 48294 have appropriate privileges, or the implementation prohibits using unlink( ) 48295 on directories. 48296 XSI [EPERM] or [EACCES] 48297 The S_ISVTX flag is set on the directory containing the file referred to by the 48298 path argument and the caller is not the file owner, nor is the caller the 48299 directory owner, nor does the caller have appropriate privileges. System Interfaces, Issue 6 2061 unlink( ) System Interfaces 48300 [EROFS] The directory entry to be unlinked is part of a read-only file system. 48301 The unlink( ) function may fail and not unlink the file if: 48302 XSI [EBUSY] The file named by path is a named STREAM. 48303 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 48304 resolution of the path argument. 48305 [ENAMETOOLONG] 48306 As a result of encountering a symbolic link in resolution of the path argument, | 48307 the length of the substituted pathname string exceeded {PATH_MAX}. | 48308 [ETXTBSY] The entry to be unlinked is the last directory entry to a pure procedure (shared 48309 text) file that is being executed. 48310 EXAMPLES 48311 Removing a Link to a File 48312 The following example shows how to remove a link to a file named /home/cnd/mod1 by 48313 removing the entry named /modules/pass1. 48314 #include 48315 char *path = "/modules/pass1"; 48316 int status; 48317 ... 48318 status = unlink(path); 48319 Checking for an Error 48320 The following example fragment creates a temporary password lock file named LOCKFILE, 48321 which is defined as /etc/ptmp, and gets a file descriptor for it. If the file cannot be opened for 48322 writing, unlink( ) is used to remove the link between the file descriptor and LOCKFILE. 48323 #include 48324 #include 48325 #include 48326 #include 48327 #include 48328 #include 48329 #define LOCKFILE "/etc/ptmp" 48330 int pfd; /* Integer for file descriptor returned by open call. */ 48331 FILE *fpfd; /* File pointer for use in putpwent(). */ 48332 ... 48333 /* Open password Lock file. If it exists, this is an error. */ 48334 if ((pfd = open(LOCKFILE, O_WRONLY| O_CREAT | O_EXCL, S_IRUSR 48335 | S_IWUSR | S_IRGRP | S_IROTH)) == -1) { 48336 fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n"); 48337 exit(1); 48338 } 48339 /* Lock file created, proceed with fdopen of lock file so that 48340 putpwent() can be used. 48341 */ 48342 if ((fpfd = fdopen(pfd, "w")) == NULL) { 2062 Technical Standard (2001) (Draft April 16, 2001) System Interfaces unlink( ) 48343 close(pfd); 48344 unlink(LOCKFILE); 48345 exit(1); 48346 } 48347 Replacing Files 48348 The following example fragment uses unlink( ) to discard links to files, so that they can be 48349 replaced with new versions of the files. The first call remove the link to LOCKFILE if an error 48350 occurs. Successive calls remove the links to SAVEFILE and PASSWDFILE so that new links can 48351 be created, then removes the link to LOCKFILE when it is no longer needed. 48352 #include 48353 #include 48354 #include 48355 #include 48356 #include 48357 #include 48358 #define LOCKFILE "/etc/ptmp" 48359 #define PASSWDFILE "/etc/passwd" 48360 #define SAVEFILE "/etc/opasswd" 48361 ... 48362 /* If no change was made, assume error and leave passwd unchanged. */ 48363 if (!valid_change) { 48364 fprintf(stderr, "Could not change password for user %s\n", user); 48365 unlink(LOCKFILE); 48366 exit(1); 48367 } 48368 /* Change permissions on new password file. */ 48369 chmod(LOCKFILE, S_IRUSR | S_IRGRP | S_IROTH); 48370 /* Remove saved password file. */ 48371 unlink(SAVEFILE); 48372 /* Save current password file. */ 48373 link(PASSWDFILE, SAVEFILE); 48374 /* Remove current password file. */ 48375 unlink(PASSWDFILE); 48376 /* Save new password file as current password file. */ 48377 link(LOCKFILE,PASSWDFILE); 48378 /* Remove lock file. */ 48379 unlink(LOCKFILE); 48380 exit(0); 48381 APPLICATION USAGE 48382 Applications should use rmdir( ) to remove a directory. 48383 RATIONALE 48384 Unlinking a directory is restricted to the superuser in many historical implementations for 48385 reasons given in link( ) (see also rename( )). System Interfaces, Issue 6 2063 unlink( ) System Interfaces 48386 The meaning of [EBUSY] in historical implementations is ``mount point busy''. Since this volume 48387 of IEEE Std 1003.1-200x does not cover the system administration concepts of mounting and 48388 unmounting, the description of the error was changed to ``resource busy''. (This meaning is used 48389 by some device drivers when a second process tries to open an exclusive use device.) The 48390 wording is also intended to allow implementations to refuse to remove a directory if it is the 48391 root or current working directory of any process. 48392 FUTURE DIRECTIONS 48393 None. 48394 SEE ALSO 48395 close( ), link( ), remove( ), rmdir( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48396 48397 CHANGE HISTORY 48398 First released in Issue 1. Derived from Issue 1 of the SVID. 48399 Issue 5 48400 The [EBUSY] error is added to the ``may fail'' part of the ERRORS section. 48401 Issue 6 48402 The following new requirements on POSIX implementations derive from alignment with the | 48403 Single UNIX Specification: 48404 * In the DESCRIPTION, the effect is specified if path specifies a symbolic link. 48405 * The [ELOOP] mandatory error condition is added. 48406 * A second [ENAMETOOLONG] is added as an optional error condition. 48407 * The [ETXTBSY] optional error condition is added. 48408 The following changes were made to align with the IEEE P1003.1a draft standard: 48409 * The [ELOOP] optional error condition is added. 48410 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2064 Technical Standard (2001) (Draft April 16, 2001) System Interfaces unlockpt( ) 48411 NAME 48412 unlockpt - unlock a pseudo-terminal master/slave pair 48413 SYNOPSIS 48414 XSI #include 48415 int unlockpt(int fildes); 48416 48417 DESCRIPTION 48418 The unlockpt( ) function shall unlock the slave pseudo-terminal device associated with the 48419 master to which fildes refers. 48420 Conforming applications shall ensure that they call unlockpt( ) before opening the slave side of a | 48421 pseudo-terminal device. 48422 RETURN VALUE 48423 Upon successful completion, unlockpt( ) shall return 0. Otherwise, it shall return -1 and set errno 48424 to indicate the error. 48425 ERRORS 48426 The unlockpt( ) function may fail if: 48427 [EBADF] The fildes argument is not a file descriptor open for writing. 48428 [EINVAL] The fildes argument is not associated with a master pseudo-terminal device. 48429 EXAMPLES 48430 None. 48431 APPLICATION USAGE 48432 None. 48433 RATIONALE 48434 None. 48435 FUTURE DIRECTIONS 48436 None. 48437 SEE ALSO 48438 grantpt( ), open( ), ptsname( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48439 CHANGE HISTORY 48440 First released in Issue 4, Version 2. 48441 Issue 5 48442 Moved from X/OPEN UNIX extension to BASE. 48443 Issue 6 48444 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 2065 unsetenv( ) System Interfaces 48445 NAME 48446 unsetenv - remove environment variable 48447 SYNOPSIS 48448 CX #include | 48449 int unsetenv(const char *name); 48450 | 48451 DESCRIPTION 48452 The unsetenv( ) function shall remove an environment variable from the environment of the | 48453 calling process. The name argument points to a string, which is the name of the variable to be | 48454 removed. The named argument shall not contain an '=' character. If the named variable does 48455 not exist in the current environment, the environment shall be unchanged and the function is | 48456 considered to have completed successfully. 48457 If the application modifies environ or the pointers to which it points, the behavior of unsetenv( ) is 48458 undefined. The unsetenv( ) function shall update the list of pointers to which environ points. 48459 The unsetenv( ) function need not be reentrant. A function that is not required to be reentrant is 48460 not required to be thread-safe. 48461 RETURN VALUE 48462 Upon successful completion, zero shall be returned. Otherwise, -1 shall be returned, errno set to 48463 indicate the error, and the environment shall be unchanged. 48464 ERRORS 48465 The unsetenv( ) function shall fail if: 48466 [EINVAL] The name argument is a null pointer, points to an empty string, or points to a 48467 string containing an '=' character. 48468 EXAMPLES 48469 None. 48470 APPLICATION USAGE 48471 None. 48472 RATIONALE 48473 Refer to the RATIONALE section in setenv( ). 48474 FUTURE DIRECTIONS 48475 None. 48476 SEE ALSO 48477 getenv( ), setenv( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 48478 , 48479 CHANGE HISTORY 48480 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 2066 Technical Standard (2001) (Draft April 16, 2001) System Interfaces usleep( ) 48481 NAME 48482 usleep - suspend execution for an interval 48483 SYNOPSIS 48484 OB XSI #include 48485 int usleep(useconds_t useconds); 48486 48487 DESCRIPTION 48488 The usleep( ) function shall cause the calling thread to be suspended from execution until either 48489 the number of realtime microseconds specified by the argument useconds has elapsed or a signal 48490 is delivered to the calling thread and its action is to invoke a signal-catching function or to 48491 terminate the process. The suspension time may be longer than requested due to the scheduling 48492 of other activity by the system. 48493 The useconds argument shall be less than one million. If the value of useconds is 0, then the call | 48494 has no effect. 48495 If a SIGALRM signal is generated for the calling process during execution of usleep( ) and if the 48496 SIGALRM signal is being ignored or blocked from delivery, it is unspecified whether usleep( ) 48497 returns when the SIGALRM signal is scheduled. If the signal is being blocked, it is also 48498 unspecified whether it remains pending after usleep( ) returns or it is discarded. 48499 If a SIGALRM signal is generated for the calling process during execution of usleep( ), except as a 48500 result of a prior call to alarm( ), and if the SIGALRM signal is not being ignored or blocked from 48501 delivery, it is unspecified whether that signal has any effect other than causing usleep( ) to return. 48502 If a signal-catching function interrupts usleep( ) and examines or changes either the time a 48503 SIGALRM is scheduled to be generated, the action associated with the SIGALRM signal, or 48504 whether the SIGALRM signal is blocked from delivery, the results are unspecified. 48505 If a signal-catching function interrupts usleep( ) and calls siglongjmp( ) or longjmp( ) to restore an 48506 environment saved prior to the usleep( ) call, the action associated with the SIGALRM signal and 48507 the time at which a SIGALRM signal is scheduled to be generated are unspecified. It is also 48508 unspecified whether the SIGALRM signal is blocked, unless the process' signal mask is restored 48509 as part of the environment. 48510 Implementations may place limitations on the granularity of timer values. For each interval 48511 timer, if the requested timer value requires a finer granularity than the implementation supports, 48512 the actual timer value shall be rounded up to the next supported value. 48513 Interactions between usleep( ) and any of the following are unspecified: 48514 nanosleep( ) 48515 setitimer( ) 48516 timer_create( ) 48517 timer_delete( ) 48518 timer_getoverrun( ) 48519 timer_gettime( ) 48520 timer_settime( ) 48521 ualarm( ) 48522 sleep( ) System Interfaces, Issue 6 2067 usleep( ) System Interfaces 48523 RETURN VALUE 48524 Upon successful completion, usleep( ) shall return 0; otherwise, it shall return -1 and set errno to 48525 indicate the error. 48526 ERRORS 48527 The usleep( ) function may fail if: 48528 [EINVAL] The time interval specified one million or more microseconds. 48529 EXAMPLES 48530 None. 48531 APPLICATION USAGE 48532 Applications are recommended to use nanosleep( ) if the Timers option is supported, or 48533 setitimer( ), timer_create( ), timer_delete( ), timer_getoverrun( ), timer_gettime( ), or timer_settime( ) 48534 instead of this function. 48535 RATIONALE 48536 None. 48537 FUTURE DIRECTIONS 48538 None. 48539 SEE ALSO 48540 alarm( ), getitimer( ), nanosleep( ), sigaction( ), sleep( ), timer_create( ), timer_delete( ), 48541 timer_getoverrun( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48542 CHANGE HISTORY 48543 First released in Issue 4, Version 2. 48544 Issue 5 48545 Moved from X/OPEN UNIX extension to BASE. 48546 The DESCRIPTION is changed to indicate that timers are now thread-based rather than 48547 process-based. 48548 Issue 6 48549 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 48550 This function is marked obsolescent. 2068 Technical Standard (2001) (Draft April 16, 2001) System Interfaces utime( ) 48551 NAME 48552 utime - set file access and modification times 48553 SYNOPSIS 48554 #include 48555 int utime(const char *path, const struct utimbuf *times); 48556 DESCRIPTION 48557 The utime( ) function shall set the access and modification times of the file named by the path 48558 argument. 48559 If times is a null pointer, the access and modification times of the file shall be set to the current | 48560 time. The effective user ID of the process shall match the owner of the file, or the process has | 48561 write permission to the file or has appropriate privileges, to use utime( ) in this manner. | 48562 If times is not a null pointer, times shall be interpreted as a pointer to a utimbuf structure and the | 48563 access and modification times shall be set to the values contained in the designated structure. | 48564 Only a process with effective user ID equal to the user ID of the file or a process with | 48565 appropriate privileges may use utime( ) this way. | 48566 The utimbuf structure is defined in the header. The times in the structure utimbuf | 48567 are measured in seconds since the Epoch. 48568 Upon successful completion, utime( ) shall mark the time of the last file status change, st_ctime, 48569 to be updated; see . 48570 RETURN VALUE 48571 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno shall 48572 be set to indicate the error, and the file times shall not be affected. 48573 ERRORS 48574 The utime( ) function shall fail if: 48575 [EACCES] Search permission is denied by a component of the path prefix; or the times 48576 argument is a null pointer and the effective user ID of the process does not 48577 match the owner of the file, the process does not have write permission for the 48578 file, and the process does not have appropriate privileges. 48579 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 48580 argument. 48581 [ENAMETOOLONG] 48582 The length of the path argument exceeds {PATH_MAX} or a pathname | 48583 component is longer than {NAME_MAX}. | 48584 [ENOENT] A component of path does not name an existing file or path is an empty string. 48585 [ENOTDIR] A component of the path prefix is not a directory. 48586 [EPERM] The times argument is not a null pointer and the calling process' effective user 48587 ID does not match the owner of the file and the calling process does not have 48588 the appropriate privileges. 48589 [EROFS] The file system containing the file is read-only. 48590 The utime( ) function may fail if: 48591 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 48592 resolution of the path argument. System Interfaces, Issue 6 2069 utime( ) System Interfaces 48593 [ENAMETOOLONG] 48594 As a result of encountering a symbolic link in resolution of the path argument, | 48595 the length of the substituted pathname string exceeded {PATH_MAX}. | 48596 EXAMPLES 48597 None. 48598 APPLICATION USAGE 48599 None. 48600 RATIONALE 48601 The actime structure member must be present so that an application may set it, even though an 48602 implementation may ignore it and not change the access time on the file. If an application 48603 intends to leave one of the times of a file unchanged while changing the other, it should use 48604 stat( ) to retrieve the file's st_atime and st_mtime parameters, set actime and modtime in the buffer, 48605 and change one of them before making the utime( ) call. 48606 FUTURE DIRECTIONS 48607 None. 48608 SEE ALSO 48609 The Base Definitions volume of IEEE Std 1003.1-200x, , 48610 CHANGE HISTORY 48611 First released in Issue 1. Derived from Issue 1 of the SVID. 48612 Issue 6 48613 In the SYNOPSIS, the optional include of the header is removed. 48614 The following new requirements on POSIX implementations derive from alignment with the | 48615 Single UNIX Specification: 48616 * The requirement to include has been removed. Although was 48617 required for conforming implementations of previous POSIX specifications, it was not 48618 required for UNIX applications. 48619 * The [ELOOP] mandatory error condition is added. 48620 * A second [ENAMETOOLONG] is added as an optional error condition. 48621 The following changes were made to align with the IEEE P1003.1a draft standard: 48622 * The [ELOOP] optional error condition is added. 48623 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2070 Technical Standard (2001) (Draft April 16, 2001) System Interfaces utimes( ) 48624 NAME 48625 utimes - set file access and modification times (LEGACY) 48626 SYNOPSIS 48627 XSI #include 48628 int utimes(const char *path, const struct timeval times[2]); 48629 48630 DESCRIPTION 48631 The utimes( ) function shall set the access and modification times of the file pointed to by the path 48632 argument to the value of the times argument. The utimes( ) function allows time specifications 48633 accurate to the microsecond. 48634 For utimes( ), the times argument is an array of timeval structures. The first array member 48635 represents the date and time of last access, and the second member represents the date and time 48636 of last modification. The times in the timeval structure are measured in seconds and 48637 microseconds since the Epoch, although rounding toward the nearest second may occur. 48638 If the times argument is a null pointer, the access and modification times of the file shall be set to | 48639 the current time. The effective user ID of the process shall match the owner of the file, or has | 48640 write access to the file or appropriate privileges to use this call in this manner. Upon completion, | 48641 utimes( ) shall mark the time of the last file status change, st_ctime, for update. 48642 RETURN VALUE 48643 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno shall 48644 be set to indicate the error, and the file times shall not be affected. 48645 ERRORS 48646 The utimes( ) function shall fail if: 48647 [EACCES] Search permission is denied by a component of the path prefix; or the times 48648 argument is a null pointer and the effective user ID of the process does not 48649 match the owner of the file and write access is denied. 48650 [ELOOP] A loop exists in symbolic links encountered during resolution of the path 48651 argument. 48652 [ENAMETOOLONG] 48653 The length of the path argument exceeds {PATH_MAX} or a pathname | 48654 component is longer than {NAME_MAX}. | 48655 [ENOENT] A component of path does not name an existing file or path is an empty string. 48656 [ENOTDIR] A component of the path prefix is not a directory. 48657 [EPERM] The times argument is not a null pointer and the calling process' effective user 48658 ID has write access to the file but does not match the owner of the file and the 48659 calling process does not have the appropriate privileges. 48660 [EROFS] The file system containing the file is read-only. 48661 The utimes( ) function may fail if: 48662 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 48663 resolution of the path argument. 48664 [ENAMETOOLONG] 48665 Pathname resolution of a symbolic link produced an intermediate result | 48666 whose length exceeds {PATH_MAX}. System Interfaces, Issue 6 2071 utimes( ) System Interfaces 48667 EXAMPLES 48668 None. 48669 APPLICATION USAGE 48670 For applications portability, the utime( ) function should be used to set file access and 48671 modification times instead of utimes( ). 48672 RATIONALE 48673 None. 48674 FUTURE DIRECTIONS 48675 This function may be withdrawn in a future version. 48676 SEE ALSO 48677 The Base Definitions volume of IEEE Std 1003.1-200x, 48678 CHANGE HISTORY 48679 First released in Issue 4, Version 2. 48680 Issue 5 48681 Moved from X/OPEN UNIX extension to BASE. 48682 Issue 6 48683 This function is marked LEGACY. 48684 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. | 48685 The wording of the mandatory [ELOOP] error condition is updated, and a second optional 48686 [ELOOP] error condition is added. 2072 Technical Standard (2001) (Draft April 16, 2001) System Interfaces va_arg( ) 48687 NAME 48688 va_arg, va_copy, va_end, va_start - handle variable argument list 48689 SYNOPSIS 48690 #include 48691 type va_arg(va_list ap, type); 48692 void va_copy(va_list dest, va_list src); 48693 void va_end(va_list ap); 48694 void va_start(va_list ap, argN); 48695 DESCRIPTION 48696 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, . System Interfaces, Issue 6 2073 vfork( ) System Interfaces 48697 NAME 48698 vfork - create new process; share virtual memory 48699 SYNOPSIS 48700 OB XSI #include 48701 pid_t vfork(void); 48702 48703 DESCRIPTION 48704 The vfork( ) function shall be equivalent to fork( ), except that the behavior is undefined if the | 48705 process created by vfork( ) either modifies any data other than a variable of type pid_t used to 48706 store the return value from vfork( ), or returns from the function in which vfork( ) was called, or 48707 calls any other function before successfully calling _exit( ) or one of the exec family of functions. 48708 RETURN VALUE 48709 Upon successful completion, vfork( ) shall return 0 to the child process and return the process ID 48710 of the child process to the parent process. Otherwise, -1 shall be returned to the parent, no child 48711 process shall be created, and errno shall be set to indicate the error. 48712 ERRORS 48713 The vfork( ) function shall fail if: 48714 [EAGAIN] The system-wide limit on the total number of processes under execution 48715 would be exceeded, or the system-imposed limit on the total number of 48716 processes under execution by a single user would be exceeded. 48717 [ENOMEM] There is insufficient swap space for the new process. 48718 EXAMPLES 48719 None. 48720 APPLICATION USAGE 48721 Conforming applications are recommended not to depend on vfork( ), but to use fork( ) instead. | 48722 The vfork( ) function may be withdrawn in a future version. 48723 On some implementations, vfork( ) is equivalent to fork( ). | 48724 The vfork( ) function differs from fork( ) only in that the child process can share code and data 48725 with the calling process (parent process). This speeds cloning activity significantly at a risk to 48726 the integrity of the parent process if vfork( ) is misused. 48727 The use of vfork( ) for any purpose except as a prelude to an immediate call to a function from 48728 the exec family, or to _exit( ), is not advised. 48729 The vfork( ) function can be used to create new processes without fully copying the address 48730 space of the old process. If a forked process is simply going to call exec, the data space copied 48731 from the parent to the child by fork( ) is not used. This is particularly inefficient in a paged 48732 environment, making vfork( ) particularly useful. Depending upon the size of the parent's data 48733 space, vfork( ) can give a significant performance improvement over fork( ). 48734 The vfork( ) function can normally be used just like fork( ). It does not work, however, to return 48735 while running in the child's context from the caller of vfork( ) since the eventual return from 48736 vfork( ) would then return to a no longer existent stack frame. Care should be taken, also, to call 48737 _exit( ) rather than exit( ) if exec cannot be used, since exit( ) flushes and closes standard I/O 48738 channels, thereby damaging the parent process' standard I/O data structures. (Even with fork( ), 48739 it is wrong to call exit( ), since buffered data would then be flushed twice.) 48740 If signal handlers are invoked in the child process after vfork( ), they must follow the same rules 48741 as other code in the child process. 2074 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vfork( ) 48742 RATIONALE 48743 None. 48744 FUTURE DIRECTIONS 48745 This function may be withdrawn in a future version. 48746 SEE ALSO 48747 exec, exit( ), fork( ), wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 48748 CHANGE HISTORY 48749 First released in Issue 4, Version 2. 48750 Issue 5 48751 Moved from X/OPEN UNIX extension to BASE. 48752 Issue 6 48753 Marked obsolescent. System Interfaces, Issue 6 2075 vfprintf( ) System Interfaces 48754 NAME 48755 vfprintf, vprintf, vsnprintf, vsprintf - format output of a stdarg argument list 48756 SYNOPSIS 48757 #include 48758 #include 48759 int vfprintf(FILE *restrict stream, const char *restrict format, 48760 va_list ap); 48761 int vprintf(const char *restrict format, va_list ap); 48762 int vsnprintf(char *restrict s, size_t n, const char *restrict format, 48763 va_list ap); 48764 int vsprintf(char *restrict s, const char *restrict format, va_list ap); 48765 DESCRIPTION 48766 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48767 conflict between the requirements described here and the ISO C standard is unintentional. This 48768 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48769 The vprintf( ), vfprintf( ), vsnprintf( ), and vsprintf( ) functions shall be equivalent to printf( ), 48770 fprintf( ), snprintf( ), and sprintf( ) respectively, except that instead of being called with a variable 48771 number of arguments, they are called with an argument list as defined by . 48772 These functions shall not invoke the va_end macro. As these functions invoke the va_arg macro, | 48773 the value of ap after the return is unspecified. | 48774 RETURN VALUE 48775 Refer to fprintf( ). 48776 ERRORS 48777 Refer to fprintf( ). 48778 EXAMPLES 48779 None. 48780 APPLICATION USAGE 48781 Applications using these functions should call va_end(ap) afterwards to clean up. 48782 RATIONALE 48783 None. 48784 FUTURE DIRECTIONS 48785 None. 48786 SEE ALSO 48787 fprintf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 48788 CHANGE HISTORY 48789 First released in Issue 1. Derived from Issue 1 of the SVID. 48790 Issue 5 48791 The vsnprintf( ) function is added. 48792 Issue 6 48793 The vfprintf( ), vprintf( ), vsnprintf( ), and vsprintf( ) functions are updated for alignment with the 48794 ISO/IEC 9899: 1999 standard. 2076 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vfscanf( ) 48795 NAME 48796 vfscanf, vscanf, vsscanf - format input of a stdarg list 48797 SYNOPSIS 48798 #include 48799 #include 48800 int vfscanf(FILE *restrict stream, const char *restrict format, 48801 va_list arg); 48802 int vscanf(const char *restrict format, va_list arg); 48803 int vsscanf(const char *restrict s, const char *restrict format, 48804 va_list arg); 48805 DESCRIPTION 48806 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48807 conflict between the requirements described here and the ISO C standard is unintentional. This 48808 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48809 The vscanf( ), vfscanf( ), and vsscanf( ) functions shall be equivalent to the scanf( ), fscanf( ), and | 48810 sscanf( ) functions, respectively, except that instead of being called with a variable number of 48811 arguments, they are called with an argument list as defined in the header. These | 48812 functions shall not invoke the va_end macro. As these functions invoke the va_arg macro, the | 48813 value of ap after the return is unspecified. | 48814 RETURN VALUE 48815 Refer to fscanf( ). 48816 ERRORS 48817 Refer to fscanf( ). 48818 EXAMPLES 48819 None. 48820 APPLICATION USAGE 48821 Applications using these functions should call va_end(ap) afterwards to clean up. 48822 RATIONALE 48823 None. 48824 FUTURE DIRECTIONS 48825 None. 48826 SEE ALSO 48827 fscanf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 48828 CHANGE HISTORY 48829 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2077 vfwprintf( ) System Interfaces 48830 NAME 48831 vfwprintf, vswprintf, vwprintf - wide-character formatted output of a stdarg argument list 48832 SYNOPSIS 48833 #include 48834 #include 48835 #include 48836 int vfwprintf(FILE *restrict stream, const wchar_t *restrict format, 48837 va_list arg); 48838 int vswprintf(wchar_t *restrict ws, size_t n, 48839 const wchar_t *restrict format, va_list arg); 48840 int vwprintf(const wchar_t *restrict format, va_list arg); 48841 DESCRIPTION 48842 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48843 conflict between the requirements described here and the ISO C standard is unintentional. This 48844 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48845 The vfwprintf( ), vswprintf( ), and vwprintf( ) functions shall be equivalent to fwprintf( ), swprintf( ), 48846 and wprintf( ) respectively, except that instead of being called with a variable number of 48847 arguments, they are called with an argument list as defined by . 48848 These functions shall not invoke the va_end macro. However, as these functions do invoke the | 48849 va_arg macro, the value of ap after the return is unspecified. | 48850 RETURN VALUE 48851 Refer to fwprintf( ). 48852 ERRORS 48853 Refer to fwprintf( ). 48854 EXAMPLES 48855 None. 48856 APPLICATION USAGE 48857 Applications using these functions should call va_end(ap) afterwards to clean up. 48858 RATIONALE 48859 None. 48860 FUTURE DIRECTIONS 48861 None. 48862 SEE ALSO 48863 fwprintf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 48864 48865 CHANGE HISTORY 48866 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 48867 (E). 48868 Issue 6 48869 The vfwprintf( ), vswprintf( ), and vwprintf( ) prototypes are updated for alignment with the 48870 ISO/IEC 9899: 1999 standard. ( ) 2078 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vfwscanf( ) 48871 NAME 48872 vfwscanf, vswscanf, vwscanf - wide-character formattted input of a stdarg list 48873 SYNOPSIS 48874 #include 48875 #include 48876 #include 48877 int vfwscanf(FILE *restrict stream, const wchar_t *restrict format, 48878 va_list arg); 48879 int vswscanf(const wchar_t *restrict ws, const wchar_t *restrict format, 48880 va_list arg); 48881 int vwscanf(const wchar_t *restrict format, va_list arg); 48882 DESCRIPTION 48883 CX The functionality described on this reference page is aligned with the ISO C standard. Any 48884 conflict between the requirements described here and the ISO C standard is unintentional. This 48885 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 48886 The vfwscanf( ), vswscanf( ), and vwscanf( ) functions shall be equivalent to the fwscanf( ), | 48887 swscanf( ), and wscanf( ) functions, respectively, except that instead of being called with a 48888 variable number of arguments, they are called with an argument list as defined in the | 48889 header. These functions shall not invoke the va_end macro. As these functions invoke the va_arg | 48890 macro, the value of ap after the return is unspecified. | 48891 RETURN VALUE 48892 Refer to fwscanf( ). 48893 ERRORS 48894 Refer to fwscanf( ). 48895 EXAMPLES 48896 None. 48897 APPLICATION USAGE 48898 Applications using these functions should call va_end(ap) afterwards to clean up. 48899 RATIONALE 48900 None. 48901 FUTURE DIRECTIONS 48902 None. 48903 SEE ALSO 48904 fwscanf( ), the Base Definitions volume of IEEE Std 1003.1-200x, , , 48905 48906 CHANGE HISTORY 48907 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2079 vprintf( ) System Interfaces 48908 NAME 48909 vprintf - format output of a stdarg argument list 48910 SYNOPSIS 48911 #include 48912 #include 48913 int vprintf(const char *restrict format, va_list ap); | 48914 DESCRIPTION | 48915 Refer to vfprintf( ). 2080 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vscanf( ) 48916 NAME 48917 vscanf - format input of a stdarg list 48918 SYNOPSIS 48919 #include 48920 #include 48921 int vscanf(const char *restrict format, va_list arg); 48922 DESCRIPTION 48923 Refer to vfscanf( ). System Interfaces, Issue 6 2081 vsnprintf( ) System Interfaces 48924 NAME 48925 vsnprintf, vsprintf - format output of a stdarg argument list 48926 SYNOPSIS 48927 #include 48928 #include 48929 int vsnprintf(char *restrict s, size_t n, | 48930 const char *restrict format, va_list ap); | 48931 int vsprintf(char *restrict s, const char *restrict format, | 48932 va_list ap); | 48933 DESCRIPTION | 48934 Refer to vfprintf( ). 2082 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vsscanf( ) 48935 NAME 48936 vsscanf - format input of a stdarg list 48937 SYNOPSIS 48938 #include 48939 #include 48940 int vsscanf(const char *restrict s, const char *restrict format, 48941 va_list arg); 48942 DESCRIPTION 48943 Refer to vfscanf( ). System Interfaces, Issue 6 2083 vswprintf( ) System Interfaces 48944 NAME 48945 vswprintf - wide-character formatted output of a stdarg argument list 48946 SYNOPSIS 48947 #include 48948 #include 48949 #include 48950 int vswprintf(wchar_t *restrict ws, size_t n, | 48951 const wchar_t *restrict format, va_list arg); | 48952 DESCRIPTION | 48953 Refer to vfwprintf( ). 2084 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vswscanf( ) 48954 NAME 48955 vswscanf - wide-character formattted input of a stdarg list 48956 SYNOPSIS 48957 #include 48958 #include 48959 #include 48960 int vswscanf(const wchar_t *restrict ws, const wchar_t *restrict format, 48961 va_list arg); 48962 DESCRIPTION 48963 Refer to vfwscanf( ). System Interfaces, Issue 6 2085 vwprintf( ) System Interfaces 48964 NAME 48965 vwprintf - wide-character formatted output of a stdarg argument list 48966 SYNOPSIS 48967 #include 48968 #include 48969 #include 48970 int vwprintf(const wchar_t *restrict format, va_list arg); | 48971 DESCRIPTION | 48972 Refer to vfwprintf( ). 2086 Technical Standard (2001) (Draft April 16, 2001) System Interfaces vwscanf( ) 48973 NAME 48974 vwscanf - wide-character formattted input of a stdarg list 48975 SYNOPSIS 48976 #include 48977 #include 48978 #include 48979 int vwscanf(const wchar_t *restrict format, va_list arg); 48980 DESCRIPTION 48981 Refer to vfwscanf( ). System Interfaces, Issue 6 2087 wait( ) System Interfaces 48982 NAME 48983 wait, waitpid - wait for a child process to stop or terminate 48984 SYNOPSIS 48985 #include 48986 pid_t wait(int *stat_loc); 48987 pid_t waitpid(pid_t pid, int *stat_loc, int options); 48988 DESCRIPTION 48989 The wait( ) and waitpid( ) functions shall obtain status information pertaining to one of the | 48990 caller's child processes. Various options permit status information to be obtained for child | 48991 processes that have terminated or stopped. If status information is available for two or more | 48992 child processes, the order in which their status is reported is unspecified. | 48993 The wait( ) function shall suspend execution of the calling thread until status information for one 48994 of the terminated child processes of the calling process is available, or until delivery of a signal 48995 whose action is either to execute a signal-catching function or to terminate the process. If more 48996 than one thread is suspended in wait( ) or waitpid( ) awaiting termination of the same process, 48997 exactly one thread shall return the process status at the time of the target process termination. If 48998 status information is available prior to the call to wait( ), return shall be immediate. 48999 The waitpid( ) function shall be equivalent to wait( ) if the pid argument is (pid_t)-1 and the | 49000 options argument is 0. Otherwise, its behavior shall be modified by the values of the pid and 49001 options arguments. 49002 The pid argument specifies a set of child processes for which status is requested. The waitpid( ) 49003 function shall only return the status of a child process from this set: 49004 * If pid is equal to (pid_t)-1, status is requested for any child process. In this respect, waitpid ( ) 49005 is then equivalent to wait( ). 49006 * If pid is greater than 0, it specifies the process ID of a single child process for which status is 49007 requested. 49008 * If pid is 0, status is requested for any child process whose process group ID is equal to that of 49009 the calling process. 49010 * If pid is less than (pid_t)-1, status is requested for any child process whose process group ID 49011 is equal to the absolute value of pid. 49012 The options argument is constructed from the bitwise-inclusive OR of zero or more of the 49013 following flags, defined in the header: 49014 XSI WCONTINUED The waitpid( ) function shall report the status of any continued child process 49015 specified by pid whose status has not been reported since it continued from a 49016 job control stop. 49017 WNOHANG The waitpid( ) function shall not suspend execution of the calling thread if 49018 status is not immediately available for one of the child processes specified by 49019 pid. 49020 WUNTRACED The status of any child processes specified by pid that are stopped, and whose 49021 status has not yet been reported since they stopped, shall also be reported to 49022 the requesting process. 49023 XSI If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN, and the 49024 process has no unwaited-for children that were transformed into zombie processes, the calling 49025 thread shall block until all of the children of the process containing the calling thread terminate, 49026 and wait( ) and waitpid( ) shall fail and set errno to [ECHILD]. 2088 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wait( ) 49027 If wait( ) or waitpid( ) return because the status of a child process is available, these functions 49028 shall return a value equal to the process ID of the child process. In this case, if the value of the 49029 argument stat_loc is not a null pointer, information shall be stored in the location pointed to by 49030 stat_loc. The value stored at the location pointed to by stat_loc shall be 0 if and only if the status 49031 returned is from a terminated child process that terminated by one of the following means: 49032 1. The process returned 0 from main( ). 49033 2. The process called _exit( ) or exit( ) with a status argument of 0. 49034 3. The process was terminated because the last thread in the process terminated. 49035 Regardless of its value, this information may be interpreted using the following macros, which 49036 are defined in and evaluate to integral expressions; the stat_val argument is the 49037 integer value pointed to by stat_loc. 49038 WIFEXITED(stat_val) 49039 Evaluates to a non-zero value if status was returned for a child process that terminated 49040 normally. 49041 WEXITSTATUS(stat_val) 49042 If the value of WIFEXITED(stat_val) is non-zero, this macro evaluates to the low-order 8 bits 49043 of the status argument that the child process passed to _exit( ) or exit( ), or the value the child 49044 process returned from main( ). 49045 WIFSIGNALED(stat_val) 49046 Evaluates to non-zero value if status was returned for a child process that terminated due to 49047 the receipt of a signal that was not caught (see ). 49048 WTERMSIG(stat_val) 49049 If the value of WIFSIGNALED(stat_val) is non-zero, this macro evaluates to the number of 49050 the signal that caused the termination of the child process. 49051 WIFSTOPPED(stat_val) 49052 Evaluates to a non-zero value if status was returned for a child process that is currently 49053 stopped. 49054 WSTOPSIG(stat_val) 49055 If the value of WIFSTOPPED(stat_val) is non-zero, this macro evaluates to the number of the 49056 signal that caused the child process to stop. 49057 XSI WIFCONTINUED(stat_val) 49058 Evaluates to a non-zero value if status was returned for a child process that has continued 49059 from a job control stop. 49060 SPN It is unspecified whether the status value returned by calls to wait( ) or waitpid( ) for processes 49061 created by posix_spawn( ) or posix_spawnp( ) can indicate a WIFSTOPPED(stat_val) before | 49062 subsequent calls to wait( ) or waitpid( ) indicate WIFEXITED(stat_val) as the result of an error | 49063 detected before the new process image starts executing. 49064 It is unspecified whether the status value returned by calls to wait( ) or waitpid( ) for processes 49065 created by posix_spawn( ) or posix_spawnp( ) can indicate a WIFSIGNALED(stat_val) if a signal is | 49066 sent to the parent's process group after posix_spawn( ) or posix_spawnp( ) is called. | 49067 If the information pointed to by stat_loc was stored by a call to waitpid( ) that specified the 49068 XSI WUNTRACED flag and did not specify the WCONTINUED flag, exactly one of the macros 49069 WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and WIFSTOPPED(*stat_loc) shall evaluate to 49070 a non-zero value. System Interfaces, Issue 6 2089 wait( ) System Interfaces 49071 If the information pointed to by stat_loc was stored by a call to waitpid( ) that specified the 49072 XSI WUNTRACED and WCONTINUED flags, exactly one of the macros WIFEXITED(*stat_loc), 49073 XSI WIFSIGNALED(*stat_loc), WIFSTOPPED(*stat_loc), and WIFCONTINUED(*stat_loc) shall 49074 evaluate to a non-zero value. 49075 If the information pointed to by stat_loc was stored by a call to waitpid( ) that did not specify the 49076 XSI WUNTRACED or WCONTINUED flags, or by a call to the wait( ) function, exactly one of the 49077 macros WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to a non-zero value. 49078 If the information pointed to by stat_loc was stored by a call to waitpid( ) that did not specify the 49079 XSI WUNTRACED flag and specified the WCONTINUED flag, or by a call to the wait( ) function, 49080 XSI exactly one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and 49081 WIFCONTINUED(*stat_loc)shall evaluate to a non-zero value. 49082 If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues the SIGCHLD 49083 signal, then if wait( ) or waitpid( ) returns because the status of a child process is available, any 49084 pending SIGCHLD signal associated with the process ID of the child process shall be discarded. 49085 Any other pending SIGCHLD signals shall remain pending. 49086 Otherwise, if SIGCHLD is blocked, if wait( ) or waitpid( ) return because the status of a child 49087 process is available, any pending SIGCHLD signal shall be cleared unless the status of another 49088 child process is available. 49089 For all other conditions, it is unspecified whether child status will be available when a SIGCHLD 49090 signal is delivered. 49091 There may be additional implementation-defined circumstances under which wait( ) or waitpid( ) 49092 report status. This shall not occur unless the calling process or one of its child processes explicitly 49093 makes use of a non-standard extension. In these cases the interpretation of the reported status is 49094 implementation-defined. 49095 XSI If a parent process terminates without waiting for all of its child processes to terminate, the 49096 remaining child processes shall be assigned a new parent process ID corresponding to an 49097 implementation-defined system process. 49098 RETURN VALUE 49099 If wait( ) or waitpid( ) returns because the status of a child process is available, these functions 49100 shall return a value equal to the process ID of the child process for which status is reported. If 49101 wait( ) or waitpid( ) returns due to the delivery of a signal to the calling process, -1 shall be 49102 returned and errno set to [EINTR]. If waitpid( ) was invoked with WNOHANG set in options, it 49103 has at least one child process specified by pid for which status is not available, and status is not 49104 available for any process specified by pid, 0 is returned. Otherwise, (pid_t)-1 shall be returned, 49105 and errno set to indicate the error. 49106 ERRORS 49107 The wait( ) function shall fail if: 49108 [ECHILD] The calling process has no existing unwaited-for child processes. 49109 [EINTR] The function was interrupted by a signal. The value of the location pointed to 49110 by stat_loc is undefined. 49111 The waitpid( ) function shall fail if: 49112 [ECHILD] The process specified by pid does not exist or is not a child of the calling 49113 process, or the process group specified by pid does not exist or does not have 49114 any member process that is a child of the calling process. 2090 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wait( ) 49115 [EINTR] The function was interrupted by a signal. The value of the location pointed to 49116 by stat_loc is undefined. 49117 [EINVAL] The options argument is not valid. 49118 EXAMPLES 49119 None. 49120 APPLICATION USAGE 49121 None. 49122 RATIONALE 49123 A call to the wait( ) or waitpid( ) function only returns status on an immediate child process of the 49124 calling process; that is, a child that was produced by a single fork( ) call (perhaps followed by an 49125 exec or other function calls) from the parent. If a child produces grandchildren by further use of 49126 fork( ), none of those grandchildren nor any of their descendants affect the behavior of a wait( ) 49127 from the original parent process. Nothing in this volume of IEEE Std 1003.1-200x prevents an 49128 implementation from providing extensions that permit a process to get status from a grandchild 49129 or any other process, but a process that does not use such extensions must be guaranteed to see 49130 status from only its direct children. 49131 The waitpid( ) function is provided for three reasons: 49132 1. To support job control 49133 2. To permit a non-blocking version of the wait( ) function 49134 3. To permit a library routine, such as system( ) or pclose( ), to wait for its children without 49135 interfering with other terminated children for which the process has not waited 49136 The first two of these facilities are based on the wait3( ) function provided by 4.3 BSD. The 49137 function uses the options argument, which is equivalent to an argument to wait3( ). The | 49138 WUNTRACED flag is used only in conjunction with job control on systems supporting job 49139 control. Its name comes from 4.3 BSD and refers to the fact that there are two types of stopped 49140 processes in that implementation: processes being traced via the ptrace( ) debugging facility and 49141 (untraced) processes stopped by job control signals. Since ptrace( ) is not part of this volume of 49142 IEEE Std 1003.1-200x, only the second type is relevant. The name WUNTRACED was retained 49143 because its usage is the same, even though the name is not intuitively meaningful in this context. 49144 The third reason for the waitpid( ) function is to permit independent sections of a process to 49145 spawn and wait for children without interfering with each other. For example, the following 49146 problem occurs in developing a portable shell, or command interpreter: 49147 stream = popen("/bin/true"); 49148 (void) system("sleep 100"); 49149 (void) pclose(stream); 49150 On all historical implementations, the final pclose( ) fails to reap the wait( ) status of the popen( ). 49151 The status values are retrieved by macros, rather than given as specific bit encodings as they are 49152 in most historical implementations (and thus expected by existing programs). This was 49153 necessary to eliminate a limitation on the number of signals an implementation can support that 49154 was inherent in the traditional encodings. This volume of IEEE Std 1003.1-200x does require that 49155 a status value of zero corresponds to a process calling _exit(0), as this is the most common 49156 encoding expected by existing programs. Some of the macro names were adopted from 4.3 BSD. 49157 These macros syntactically operate on an arbitrary integer value. The behavior is undefined 49158 unless that value is one stored by a successful call to wait( ) or waitpid( ) in the location pointed 49159 to by the stat_loc argument. An early proposal attempted to make this clearer by specifying each System Interfaces, Issue 6 2091 wait( ) System Interfaces 49160 argument as *stat_loc rather than stat_val. However, that did not follow the conventions of other 49161 specifications in this volume of IEEE Std 1003.1-200x or traditional usage. It also could have 49162 implied that the argument to the macro must literally be *stat_loc; in fact, that value can be 49163 stored or passed as an argument to other functions before being interpreted by these macros. 49164 The extension that affects wait( ) and waitpid( ) and is common in historical implementations is 49165 the ptrace( ) function. It is called by a child process and causes that child to stop and return a 49166 status that appears identical to the status indicated by WIFSTOPPED. The status of ptrace( ) 49167 children is traditionally returned regardless of the WUNTRACED flag (or by the wait( ) 49168 function). Most applications do not need to concern themselves with such extensions because 49169 they have control over what extensions they or their children use. However, applications, such 49170 as command interpreters, that invoke arbitrary processes may see this behavior when those 49171 arbitrary processes misuse such extensions. 49172 Implementations that support core file creation or other implementation-defined actions on 49173 termination of some processes traditionally provide a bit in the status returned by wait( ) to 49174 indicate that such actions have occurred. 49175 Allowing the wait( ) family of functions to discard a pending SIGCHLD signal that is associated 49176 with a successfully waited-for child process puts them into the sigwait( ) and sigwaitinfo ( ) 49177 category with respect to SIGCHLD. 49178 This definition allows implementations to treat a pending SIGCHLD signal as accepted by the 49179 process in wait( ), with the same meaning of ``accepted'' as when that word is applied to the 49180 sigwait( ) family of functions. 49181 Allowing the wait( ) family of functions to behave this way permits an implementation to be able 49182 to deal precisely with SIGCHLD signals. 49183 In particular, an implementation that does accept (discard) the SIGCHLD signal can make the 49184 following guarantees regardless of the queuing depth of signals in general (the list of waitable 49185 children can hold the SIGCHLD queue): 49186 1. If a SIGCHLD signal handler is established via sigaction( ) without the SA_RESETHAND 49187 flag, SIGCHLD signals can be accurately counted; that is, exactly one SIGCHLD signal will 49188 be delivered to or accepted by the process for every child process that terminates. 49189 2. A single wait( ) issued from a SIGCHLD signal handler can be guaranteed to return 49190 immediately with status information for a child process. 49191 3. When SA_SIGINFO is requested, the SIGCHLD signal handler can be guaranteed to 49192 receive a non-NULL pointer to a siginfo_t structure that describes a child process for 49193 which a wait via waitpid( ) or waitid( ) will not block or fail. 49194 4. The system( ) function will not cause a processs SIGCHLD handler to be called as a result of 49195 the fork( )/exec executed within system( ) because system( ) will accept the SIGCHLD signal 49196 when it performs a waitpid( ) for its child process. This is a desirable behavior of system( ) 49197 so that it can be used in a library without causing side effects to the application linked with 49198 the library. 49199 An implementation that does not permit the wait( ) family of functions to accept (discard) a 49200 pending SIGCHLD signal associated with a successfully waited-for child, cannot make the 49201 guarantees described above for the following reasons: 49202 Guarantee #1 49203 Although it might be assumed that reliable queuing of all SIGCHLD signals generated by 49204 the system can make this guarantee, the counter example is the case of a process that blocks 49205 SIGCHLD and performs an indefinite loop of fork( )/wait( ) operations. If the 2092 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wait( ) 49206 implementation supports queued signals, then eventually the system will run out of 49207 memory for the queue. The guarantee cannot be made because there must be some limit to 49208 the depth of queuing. 49209 Guarantees #2 and #3 49210 These cannot be guaranteed unless the wait( ) family of functions accepts the SIGCHLD 49211 signal. Otherwise, a fork( )/wait( ) executed while SIGCHLD is blocked (as in the system( ) 49212 function) will result in an invocation of the handler when SIGCHLD is unblocked, after the 49213 process has disappeared. 49214 Guarantee #4 49215 Although possible to make this guarantee, system( ) would have to set the SIGCHLD 49216 handler to SIG_DFL so that the SIGCHLD signal generated by its fork( ) would be discarded 49217 (the SIGCHLD default action is to be ignored), then restore it to its previous setting. This 49218 would have the undesirable side effect of discarding all SIGCHLD signals pending to the 49219 process. 49220 FUTURE DIRECTIONS 49221 None. 49222 SEE ALSO 49223 exec, exit( ), fork( ), waitid( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 49224 49225 CHANGE HISTORY 49226 First released in Issue 1. Derived from Issue 1 of the SVID. 49227 Issue 5 49228 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 49229 Issue 6 49230 In the SYNOPSIS, the optional include of the header is removed. 49231 The following new requirements on POSIX implementations derive from alignment with the 49232 Single UNIX Specification: 49233 * The requirement to include has been removed. Although was 49234 required for conforming implementations of previous POSIX specifications, it was not 49235 required for UNIX applications. 49236 The following changes were made to align with the IEEE P1003.1a draft standard: 49237 * The processing of the SIGCHLD signal and the [ECHILD] error is clarified. 49238 The semantics of WIFSTOPPED(stat_val), WIFEXITED(stat_val), and WIFSIGNALED(stat_val) 49239 are defined with respect to posix_spawn( ) or posix_spawnp( ) for alignment with 49240 IEEE Std 1003.1d-1999. 49241 The DESCRIPTION is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2093 waitid( ) System Interfaces 49242 NAME 49243 waitid - wait for a child process to change state 49244 SYNOPSIS 49245 XSI #include 49246 int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options); 49247 49248 DESCRIPTION 49249 The waitid( ) function shall suspend the calling thread until one child of the process containing 49250 the calling thread changes state. It records the current state of a child in the structure pointed to 49251 by infop. If a child process changed state prior to the call to waitid( ), waitid( ) shall return 49252 immediately. If more than one thread is suspended in wait( ) or waitpid( ) waiting termination of 49253 the same process, exactly one thread shall return the process status at the time of the target 49254 process termination. 49255 The idtype and id arguments are used to specify which children waitid( ) waits for. 49256 If idtype is P_PID, waitid( ) shall wait for the child with a process ID equal to (pid_t)id. 49257 If idtype is P_PGID, waitid( ) shall wait for any child with a process group ID equal to (pid_t)id. 49258 If idtype is P_ALL, waitid( ) shall wait for any children and id is ignored. 49259 The options argument is used to specify which state changes waitid( ) shall wait for. It is formed 49260 by OR'ing together one or more of the following flags: 49261 WEXITED Wait for processes that have exited. 49262 WSTOPPED Status shall be returned for any child that has stopped upon receipt of a signal. 49263 WCONTINUED Status shall be returned for any child that was stopped and has been 49264 continued. 49265 WNOHANG Return immediately if there are no children to wait for. 49266 WNOWAIT Keep the process whose status is returned in infop in a waitable state. This 49267 shall not affect the state of the process; the process may be waited for again 49268 after this call completes. 49269 The application shall ensure that the infop argument points to a siginfo_t structure. If waitid( ) 49270 returns because a child process was found that satisfied the conditions indicated by the 49271 arguments idtype and options, then the structure pointed to by infop shall be filled in by the 49272 system with the status of the process. The si_signo member shall always be equal to SIGCHLD. 49273 RETURN VALUE 49274 If WNOHANG was specified and there are no children to wait for, 0 shall be returned. If waitid( ) | 49275 returns due to the change of state of one of its children, 0 shall be returned. Otherwise, -1 shall 49276 be returned and errno set to indicate the error. 49277 ERRORS 49278 The waitid( ) function shall fail if: 49279 [ECHILD] The calling process has no existing unwaited-for child processes. 49280 [EINTR] The waitid( ) function was interrupted by a signal. 49281 [EINVAL] An invalid value was specified for options, or idtype and id specify an invalid 49282 set of processes. 2094 Technical Standard (2001) (Draft April 16, 2001) System Interfaces waitid( ) 49283 EXAMPLES 49284 None. 49285 APPLICATION USAGE 49286 None. 49287 RATIONALE 49288 None. 49289 FUTURE DIRECTIONS 49290 None. 49291 SEE ALSO 49292 exec, exit( ), wait( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49293 CHANGE HISTORY 49294 First released in Issue 4, Version 2. 49295 Issue 5 49296 Moved from X/OPEN UNIX extension to BASE. 49297 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 49298 Issue 6 49299 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 2095 waitpid( ) System Interfaces 49300 NAME 49301 waitpid - wait for a child process to stop or terminate 49302 SYNOPSIS 49303 #include 49304 pid_t waitpid(pid_t pid, int *stat_loc, int options); 49305 DESCRIPTION 49306 Refer to wait( ). 2096 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcrtomb( ) 49307 NAME 49308 wcrtomb - convert a wide-character code to a character (restartable) 49309 SYNOPSIS 49310 #include 49311 size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps); 49312 DESCRIPTION 49313 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49314 conflict between the requirements described here and the ISO C standard is unintentional. This 49315 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49316 If s is a null pointer, the wcrtomb( ) function shall be equivalent to the call: 49317 wcrtomb(buf, L'\0', ps) 49318 where buf is an internal buffer. 49319 If s is not a null pointer, the wcrtomb( ) function shall determine the number of bytes needed to 49320 represent the character that corresponds to the wide character given by wc (including any shift | 49321 sequences), and store the resulting bytes in the array whose first element is pointed to by s. At | 49322 most {MB_CUR_MAX} bytes are stored. If wc is a null wide character, a null byte shall be stored, | 49323 preceded by any shift sequence needed to restore the initial shift state. The resulting state | 49324 described shall be the initial conversion state. | 49325 If ps is a null pointer, the wcrtomb( ) function shall use its own internal mbstate_t object, which is | 49326 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 49327 pointed to by ps shall be used to completely describe the current conversion state of the | 49328 associated character sequence. The implementation shall behave as if no function defined in this | 49329 volume of IEEE Std 1003.1-200x calls wcrtomb( ). | 49330 CX If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS 49331 functions, the application shall ensure that the wcrtomb( ) function is called with a non-NULL ps 49332 argument. 49333 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. | 49334 RETURN VALUE 49335 The wcrtomb( ) function shall return the number of bytes stored in the array object (including any 49336 shift sequences). When wc is not a valid wide character, an encoding error shall occur. In this 49337 case, the function shall store the value of the macros [EILSEQ] in errno and shall return 49338 (size_t)-1; the conversion state shall be undefined. 49339 ERRORS 49340 The wcrtomb( ) function may fail if: 49341 CX [EINVAL] ps points to an object that contains an invalid conversion state. 49342 [EILSEQ] Invalid wide-character code is detected. System Interfaces, Issue 6 2097 wcrtomb( ) System Interfaces 49343 EXAMPLES 49344 None. 49345 APPLICATION USAGE 49346 None. 49347 RATIONALE 49348 None. 49349 FUTURE DIRECTIONS 49350 None. 49351 SEE ALSO 49352 mbsinit( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49353 CHANGE HISTORY 49354 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 49355 (E). 49356 Issue 6 49357 In the DESCRIPTION, a note on using this function in a threaded application is added. 49358 Extensions beyond the ISO C standard are now marked. 49359 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 49360 The wcrtomb( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2098 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcscat( ) 49361 NAME 49362 wcscat - concatenate two wide-character strings 49363 SYNOPSIS 49364 #include 49365 wchar_t *wcscat(wchar_t *restrict ws1, const wchar_t *restrict ws2); 49366 DESCRIPTION 49367 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49368 conflict between the requirements described here and the ISO C standard is unintentional. This 49369 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49370 The wcscat( ) function shall append a copy of the wide-character string pointed to by ws2 49371 (including the terminating null wide-character code) to the end of the wide-character string 49372 pointed to by ws1. The initial wide-character code of ws2 shall overwrite the null wide-character | 49373 code at the end of ws1. If copying takes place between objects that overlap, the behavior is | 49374 undefined. 49375 RETURN VALUE 49376 The wcscat( ) function shall return ws1; no return value is reserved to indicate an error. 49377 ERRORS 49378 No errors are defined. 49379 EXAMPLES 49380 None. 49381 APPLICATION USAGE 49382 None. 49383 RATIONALE 49384 None. 49385 FUTURE DIRECTIONS 49386 None. 49387 SEE ALSO 49388 wcsncat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49389 CHANGE HISTORY 49390 First released in Issue 4. Derived from the MSE working draft. 49391 Issue 6 49392 The Open Group Corrigendum U040/2 is applied. In the RETURN VALUE section, s1 is changed 49393 to ws1. 49394 The wcscat( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2099 wcschr( ) System Interfaces 49395 NAME 49396 wcschr - wide-character string scanning operation 49397 SYNOPSIS 49398 #include 49399 wchar_t *wcschr(const wchar_t *ws, wchar_t wc); 49400 DESCRIPTION 49401 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49402 conflict between the requirements described here and the ISO C standard is unintentional. This 49403 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49404 The wcschr( ) function shall locate the first occurrence of wc in the wide-character string pointed 49405 to by ws. The application shall ensure that the value of wc is a character representable as a type 49406 wchar_t and a wide-character code corresponding to a valid character in the current locale. The 49407 terminating null wide-character code is considered to be part of the wide-character string. 49408 RETURN VALUE 49409 Upon completion, wcschr( ) shall return a pointer to the wide-character code, or a null pointer if 49410 the wide-character code is not found. 49411 ERRORS 49412 No errors are defined. 49413 EXAMPLES 49414 None. 49415 APPLICATION USAGE 49416 None. 49417 RATIONALE 49418 None. 49419 FUTURE DIRECTIONS 49420 None. 49421 SEE ALSO 49422 wcsrchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49423 CHANGE HISTORY 49424 First released in Issue 4. Derived from the MSE working draft. 49425 Issue 6 49426 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2100 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcscmp( ) 49427 NAME 49428 wcscmp - compare two wide-character strings 49429 SYNOPSIS 49430 #include 49431 int wcscmp(const wchar_t *ws1, const wchar_t *ws2); 49432 DESCRIPTION 49433 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49434 conflict between the requirements described here and the ISO C standard is unintentional. This 49435 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49436 The wcscmp( ) function shall compare the wide-character string pointed to by ws1 to the wide- 49437 character string pointed to by ws2. 49438 The sign of a non-zero return value shall be determined by the sign of the difference between the | 49439 values of the first pair of wide-character codes that differ in the objects being compared. | 49440 RETURN VALUE 49441 Upon completion, wcscmp( ) shall return an integer greater than, equal to, or less than 0, if the 49442 wide-character string pointed to by ws1 is greater than, equal to, or less than the wide-character 49443 string pointed to by ws2, respectively. 49444 ERRORS 49445 No errors are defined. 49446 EXAMPLES 49447 None. 49448 APPLICATION USAGE 49449 None. 49450 RATIONALE 49451 None. 49452 FUTURE DIRECTIONS 49453 None. 49454 SEE ALSO 49455 wcsncmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49456 CHANGE HISTORY 49457 First released in Issue 4. Derived from the MSE working draft. System Interfaces, Issue 6 2101 wcscoll( ) System Interfaces 49458 NAME 49459 wcscoll - wide-character string comparison using collating information 49460 SYNOPSIS 49461 #include 49462 int wcscoll(const wchar_t *ws1, const wchar_t *ws2); 49463 DESCRIPTION 49464 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49465 conflict between the requirements described here and the ISO C standard is unintentional. This 49466 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49467 The wcscoll( ) function shall compare the wide-character string pointed to by ws1 to the wide- 49468 character string pointed to by ws2, both interpreted as appropriate to the LC_COLLATE category 49469 of the current locale. 49470 CX The wcscoll( ) function shall not change the setting of errno if successful. 49471 An application wishing to check for error situations should set errno to 0 before calling wcscoll( ). 49472 If errno is non-zero on return, an error has occurred. 49473 RETURN VALUE 49474 Upon successful completion, wcscoll( ) shall return an integer greater than, equal to, or less than 49475 0, according to whether the wide-character string pointed to by ws1 is greater than, equal to, or 49476 less than the wide-character string pointed to by ws2, when both are interpreted as appropriate 49477 CX to the current locale. On error, wcscoll( ) shall set errno, but no return value is reserved to 49478 indicate an error. 49479 ERRORS 49480 The wcscoll( ) function may fail if: 49481 CX [EINVAL] The ws1 or ws2 arguments contain wide-character codes outside the domain of 49482 the collating sequence. 49483 EXAMPLES 49484 None. 49485 APPLICATION USAGE 49486 The wcsxfrm( ) and wcscmp( ) functions should be used for sorting large lists. 49487 RATIONALE 49488 None. 49489 FUTURE DIRECTIONS 49490 None. 49491 SEE ALSO 49492 wcscmp( ), wcsxfrm( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49493 CHANGE HISTORY 49494 First released in Issue 4. Derived from the MSE working draft. 49495 Issue 5 49496 Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 49497 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 2102 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcscpy( ) 49498 NAME 49499 wcscpy - copy a wide-character string 49500 SYNOPSIS 49501 #include 49502 wchar_t *wcscpy(wchar_t *restrict ws1, const wchar_t *restrict ws2); 49503 DESCRIPTION 49504 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49505 conflict between the requirements described here and the ISO C standard is unintentional. This 49506 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49507 The wcscpy( ) function shall copy the wide-character string pointed to by ws2 (including the 49508 terminating null wide-character code) into the array pointed to by ws1. If copying takes place 49509 between objects that overlap, the behavior is undefined. 49510 RETURN VALUE 49511 The wcscpy( ) function shall return ws1; no return value is reserved to indicate an error. 49512 ERRORS 49513 No errors are defined. 49514 EXAMPLES 49515 None. 49516 APPLICATION USAGE 49517 None. 49518 RATIONALE 49519 None. 49520 FUTURE DIRECTIONS 49521 None. 49522 SEE ALSO 49523 wcsncpy( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49524 CHANGE HISTORY 49525 First released in Issue 4. Derived from the MSE working draft. 49526 Issue 6 49527 The wcscpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2103 wcscspn( ) System Interfaces 49528 NAME 49529 wcscspn - get length of a complementary wide substring 49530 SYNOPSIS 49531 #include 49532 size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2); 49533 DESCRIPTION 49534 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49535 conflict between the requirements described here and the ISO C standard is unintentional. This 49536 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49537 The wcscspn( ) function shall compute the length (in wide characters) of the maximum initial | 49538 segment of the wide-character string pointed to by ws1 which consists entirely of wide-character | 49539 codes not from the wide-character string pointed to by ws2. 49540 RETURN VALUE 49541 The wcscspn( ) function shall return the length of the initial substring of ws1; no return value is 49542 reserved to indicate an error. 49543 ERRORS 49544 No errors are defined. 49545 EXAMPLES 49546 None. 49547 APPLICATION USAGE 49548 None. 49549 RATIONALE 49550 None. 49551 FUTURE DIRECTIONS 49552 None. 49553 SEE ALSO 49554 wcsspn( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49555 CHANGE HISTORY 49556 First released in Issue 4. Derived from the MSE working draft. 49557 Issue 5 49558 The RETURN VALUE section is updated to indicate that wcscspn( ) returns the length of ws1, 49559 rather than ws1 itself. 2104 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcsftime( ) 49560 NAME 49561 wcsftime - convert date and time to a wide-character string 49562 SYNOPSIS 49563 #include 49564 size_t wcsftime(wchar_t *restrict wcs, size_t maxsize, 49565 const wchar_t *restrict format, const struct tm *restrict timeptr); | 49566 DESCRIPTION | 49567 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49568 conflict between the requirements described here and the ISO C standard is unintentional. This 49569 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49570 The wcsftime( ) function shall be equivalent to the strftime( ) function, except that: 49571 * The argument wcs points to the initial element of an array of wide characters into which the 49572 generated output is to be placed. 49573 * The argument maxsize indicates the maximum number of wide characters to be placed in the 49574 output array. 49575 * The argument format is a wide-character string and the conversion specifications are replaced 49576 by corresponding sequences of wide characters. 49577 * The return value indicates the number of wide characters placed in the output array. 49578 If copying takes place between objects that overlap, the behavior is undefined. 49579 RETURN VALUE 49580 If the total number of resulting wide-character codes including the terminating null wide- 49581 character code is no more than maxsize, wcsftime( ) shall return the number of wide-character 49582 codes placed into the array pointed to by wcs, not including the terminating null wide-character | 49583 code. Otherwise, zero is returned and the contents of the array are unspecified. | 49584 ERRORS 49585 No errors are defined. 49586 EXAMPLES 49587 None. 49588 APPLICATION USAGE 49589 None. 49590 RATIONALE 49591 None. 49592 FUTURE DIRECTIONS 49593 None. 49594 SEE ALSO 49595 strftime( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49596 CHANGE HISTORY 49597 First released in Issue 4. 49598 Issue 5 49599 Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 49600 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, the type of the format 49601 argument is changed from const char * to const wchar_t *. System Interfaces, Issue 6 2105 wcsftime( ) System Interfaces 49602 Issue 6 49603 The wcsftime( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2106 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcslen( ) 49604 NAME 49605 wcslen - get wide-character string length 49606 SYNOPSIS 49607 #include 49608 size_t wcslen(const wchar_t *ws); 49609 DESCRIPTION 49610 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49611 conflict between the requirements described here and the ISO C standard is unintentional. This 49612 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49613 The wcslen( ) function shall compute the number of wide-character codes in the wide-character 49614 string to which ws points, not including the terminating null wide-character code. 49615 RETURN VALUE 49616 The wcslen( ) function shall return the length of ws; no return value is reserved to indicate an 49617 error. 49618 ERRORS 49619 No errors are defined. 49620 EXAMPLES 49621 None. 49622 APPLICATION USAGE 49623 None. 49624 RATIONALE 49625 None. 49626 FUTURE DIRECTIONS 49627 None. 49628 SEE ALSO 49629 The Base Definitions volume of IEEE Std 1003.1-200x, 49630 CHANGE HISTORY 49631 First released in Issue 4. Derived from the MSE working draft. System Interfaces, Issue 6 2107 wcsncat( ) System Interfaces 49632 NAME 49633 wcsncat - concatenate a wide-character string with part of another 49634 SYNOPSIS 49635 #include 49636 wchar_t *wcsncat(wchar_t *restrict ws1, const wchar_t *restrict ws2, 49637 size_t n); 49638 DESCRIPTION 49639 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49640 conflict between the requirements described here and the ISO C standard is unintentional. This 49641 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49642 The wcsncat( ) function shall append not more than n wide-character codes (a null wide- 49643 character code and wide-character codes that follow it are not appended) from the array pointed 49644 to by ws2 to the end of the wide-character string pointed to by ws1. The initial wide-character 49645 code of ws2 shall overwrite the null wide-character code at the end of ws1. A terminating null | 49646 wide-character code shall always be appended to the result. If copying takes place between | 49647 objects that overlap, the behavior is undefined. 49648 RETURN VALUE 49649 The wcsncat( ) function shall return ws1; no return value is reserved to indicate an error. 49650 ERRORS 49651 No errors are defined. 49652 EXAMPLES 49653 None. 49654 APPLICATION USAGE 49655 None. 49656 RATIONALE 49657 None. 49658 FUTURE DIRECTIONS 49659 None. 49660 SEE ALSO 49661 wcscat( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49662 CHANGE HISTORY 49663 First released in Issue 4. Derived from the MSE working draft. 49664 Issue 6 49665 The wcsncat( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2108 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcsncmp( ) 49666 NAME 49667 wcsncmp - compare part of two wide-character strings 49668 SYNOPSIS 49669 #include 49670 int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n); 49671 DESCRIPTION 49672 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49673 conflict between the requirements described here and the ISO C standard is unintentional. This 49674 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49675 The wcsncmp( ) function shall compare not more than n wide-character codes (wide-character 49676 codes that follow a null wide-character code are not compared) from the array pointed to by ws1 49677 to the array pointed to by ws2. 49678 The sign of a non-zero return value shall be determined by the sign of the difference between the | 49679 values of the first pair of wide-character codes that differ in the objects being compared. | 49680 RETURN VALUE 49681 Upon successful completion, wcsncmp( ) shall return an integer greater than, equal to, or less 49682 than 0, if the possibly null-terminated array pointed to by ws1 is greater than, equal to, or less 49683 than the possibly null-terminated array pointed to by ws2, respectively. 49684 ERRORS 49685 No errors are defined. 49686 EXAMPLES 49687 None. 49688 APPLICATION USAGE 49689 None. 49690 RATIONALE 49691 None. 49692 FUTURE DIRECTIONS 49693 None. 49694 SEE ALSO 49695 wcscmp( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49696 CHANGE HISTORY 49697 First released in Issue 4. Derived from the MSE working draft. System Interfaces, Issue 6 2109 wcsncpy( ) System Interfaces 49698 NAME 49699 wcsncpy - copy part of a wide-character string 49700 SYNOPSIS 49701 #include 49702 wchar_t *wcsncpy(wchar_t *restrict ws1, const wchar_t *restrict ws2, 49703 size_t n); 49704 DESCRIPTION 49705 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49706 conflict between the requirements described here and the ISO C standard is unintentional. This 49707 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49708 The wcsncpy( ) function shall copy not more than n wide-character codes (wide-character codes 49709 that follow a null wide-character code are not copied) from the array pointed to by ws2 to the 49710 array pointed to by ws1. If copying takes place between objects that overlap, the behavior is 49711 undefined. 49712 If the array pointed to by ws2 is a wide-character string that is shorter than n wide-character | 49713 codes, null wide-character codes shall be appended to the copy in the array pointed to by ws1, | 49714 until n wide-character codes in all are written. 49715 RETURN VALUE 49716 The wcsncpy( ) function shall return ws1; no return value is reserved to indicate an error. 49717 ERRORS 49718 No errors are defined. 49719 EXAMPLES 49720 None. 49721 APPLICATION USAGE 49722 If there is no null wide-character code in the first n wide-character codes of the array pointed to 49723 by ws2, the result is not null-terminated. 49724 RATIONALE 49725 None. 49726 FUTURE DIRECTIONS 49727 None. 49728 SEE ALSO 49729 wcscpy( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49730 CHANGE HISTORY 49731 First released in Issue 4. Derived from the MSE working draft. 49732 Issue 6 49733 The wcsncpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2110 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcspbrk( ) 49734 NAME 49735 wcspbrk - scan wide-character string for a wide-character code 49736 SYNOPSIS 49737 #include 49738 wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2); 49739 DESCRIPTION 49740 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49741 conflict between the requirements described here and the ISO C standard is unintentional. This 49742 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49743 The wcspbrk( ) function shall locate the first occurrence in the wide-character string pointed to by 49744 ws1 of any wide-character code from the wide-character string pointed to by ws2. 49745 RETURN VALUE 49746 Upon successful completion, wcspbrk( ) shall return a pointer to the wide-character code or a null 49747 pointer if no wide-character code from ws2 occurs in ws1. 49748 ERRORS 49749 No errors are defined. 49750 EXAMPLES 49751 None. 49752 APPLICATION USAGE 49753 None. 49754 RATIONALE 49755 None. 49756 FUTURE DIRECTIONS 49757 None. 49758 SEE ALSO 49759 wcschr( ), wcsrchr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49760 CHANGE HISTORY 49761 First released in Issue 4. Derived from the MSE working draft. System Interfaces, Issue 6 2111 wcsrchr( ) System Interfaces 49762 NAME 49763 wcsrchr - wide-character string scanning operation 49764 SYNOPSIS 49765 #include 49766 wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc); 49767 DESCRIPTION 49768 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49769 conflict between the requirements described here and the ISO C standard is unintentional. This 49770 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49771 The wcsrchr( ) function shall locate the last occurrence of wc in the wide-character string pointed 49772 to by ws. The application shall ensure that the value of wc is a character representable as a type 49773 wchar_t and a wide-character code corresponding to a valid character in the current locale. The | 49774 terminating null wide-character code shall be considered to be part of the wide-character string. | 49775 RETURN VALUE 49776 Upon successful completion, wcsrchr( ) shall return a pointer to the wide-character code or a null 49777 pointer if wc does not occur in the wide-character string. 49778 ERRORS 49779 No errors are defined. 49780 EXAMPLES 49781 None. 49782 APPLICATION USAGE 49783 None. 49784 RATIONALE 49785 None. 49786 FUTURE DIRECTIONS 49787 None. 49788 SEE ALSO 49789 wcschr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49790 CHANGE HISTORY 49791 First released in Issue 4. Derived from the MSE working draft. 49792 Issue 6 49793 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2112 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcsrtombs( ) 49794 NAME 49795 wcsrtombs - convert a wide-character string to a character string (restartable) 49796 SYNOPSIS 49797 #include 49798 size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src, 49799 size_t len, mbstate_t *restrict ps); 49800 DESCRIPTION 49801 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49802 conflict between the requirements described here and the ISO C standard is unintentional. This 49803 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49804 The wcsrtombs( ) function shall convert a sequence of wide characters from the array indirectly 49805 pointed to by src into a sequence of corresponding characters, beginning in the conversion state 49806 described by the object pointed to by ps. If dst is not a null pointer, the converted characters | 49807 shall then be stored into the array pointed to by dst. Conversion continues up to and including a | 49808 terminating null wide character, which shall also be stored. Conversion shall stop earlier in the | 49809 following cases: | 49810 * When a code is reached that does not correspond to a valid character 49811 * When the next character would exceed the limit of len total bytes to be stored in the array 49812 pointed to by dst (and dst is not a null pointer) 49813 Each conversion shall take place as if by a call to the wcrtomb( ) function. | 49814 If dst is not a null pointer, the pointer object pointed to by src shall be assigned either a null | 49815 pointer (if conversion stopped due to reaching a terminating null wide character) or the address | 49816 just past the last wide character converted (if any). If conversion stopped due to reaching a 49817 terminating null wide character, the resulting state described shall be the initial conversion state. | 49818 If ps is a null pointer, the wcsrtombs( ) function shall use its own internal mbstate_t object, which | 49819 is initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object 49820 pointed to by ps shall be used to completely describe the current conversion state of the | 49821 associated character sequence. The implementation shall behave as if no function defined in this | 49822 volume of IEEE Std 1003.1-200x calls wcsrtombs( ). | 49823 CX If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS 49824 functions, the application shall ensure that the wcsrtombs( ) function is called with a non-NULL 49825 ps argument. 49826 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. | 49827 RETURN VALUE 49828 If conversion stops because a code is reached that does not correspond to a valid character, an 49829 encoding error occurs. In this case, the wcsrtombs( ) function shall store the value of the macro 49830 [EILSEQ] in errno and return (size_t)-1; the conversion state is undefined. Otherwise, it shall 49831 return the number of bytes in the resulting character sequence, not including the terminating 49832 null (if any). 49833 ERRORS 49834 The wcsrtombs( ) function may fail if: 49835 CX [EINVAL] ps points to an object that contains an invalid conversion state. 49836 [EILSEQ] A wide-character code does not correspond to a valid character. System Interfaces, Issue 6 2113 wcsrtombs( ) System Interfaces 49837 EXAMPLES 49838 None. 49839 APPLICATION USAGE 49840 None. 49841 RATIONALE 49842 None. 49843 FUTURE DIRECTIONS 49844 None. 49845 SEE ALSO 49846 mbsinit( ), wcrtomb( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49847 CHANGE HISTORY 49848 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 49849 (E). 49850 Issue 6 49851 In the DESCRIPTION, a note on using this function in a threaded application is added. 49852 Extensions beyond the ISO C standard are now marked. 49853 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 49854 The wcsrtombs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2114 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcsspn( ) 49855 NAME 49856 wcsspn - get length of a wide substring 49857 SYNOPSIS 49858 #include 49859 size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2); 49860 DESCRIPTION 49861 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49862 conflict between the requirements described here and the ISO C standard is unintentional. This 49863 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49864 The wcsspn( ) function shall compute the length (in wide characters) of the maximum initial | 49865 segment of the wide-character string pointed to by ws1 which consists entirely of wide-character | 49866 codes from the wide-character string pointed to by ws2. 49867 RETURN VALUE 49868 The wcsspn( ) function shall return the length of the initial substring of ws1; no return value is 49869 reserved to indicate an error. 49870 ERRORS 49871 No errors are defined. 49872 EXAMPLES 49873 None. 49874 APPLICATION USAGE 49875 None. 49876 RATIONALE 49877 None. 49878 FUTURE DIRECTIONS 49879 None. 49880 SEE ALSO 49881 wcscspn( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49882 CHANGE HISTORY 49883 First released in Issue 4. Derived from the MSE working draft. 49884 Issue 5 49885 The RETURN VALUE section is updated to indicate that wcsspn( ) returns the length of ws1 49886 rather that ws1 itself. System Interfaces, Issue 6 2115 wcsstr( ) System Interfaces 49887 NAME 49888 wcsstr - find a wide-character substring 49889 SYNOPSIS 49890 #include 49891 wchar_t *wcsstr(const wchar_t *restrict ws1, const wchar_t *restrict ws2); 49892 DESCRIPTION 49893 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49894 conflict between the requirements described here and the ISO C standard is unintentional. This 49895 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49896 The wcsstr( ) function shall locate the first occurrence in the wide-character string pointed to by 49897 ws1 of the sequence of wide characters (excluding the terminating null wide character) in the 49898 wide-character string pointed to by ws2. 49899 RETURN VALUE 49900 Upon successful completion, wcsstr( ) shall return a pointer to the located wide-character string, 49901 or a null pointer if the wide-character string is not found. 49902 If ws2 points to a wide-character string with zero length, the function shall return ws1. 49903 ERRORS 49904 No errors are defined. 49905 EXAMPLES 49906 None. 49907 APPLICATION USAGE 49908 None. 49909 RATIONALE 49910 None. 49911 FUTURE DIRECTIONS 49912 None. 49913 SEE ALSO 49914 wcschr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 49915 CHANGE HISTORY 49916 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 49917 (E). 49918 Issue 6 49919 The wcsstr( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2116 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstod( ) 49920 NAME 49921 wcstod, wcstof, wcstold - convert a wide-character string to a double-precision number 49922 SYNOPSIS 49923 #include 49924 double wcstod(const wchar_t *restrict nptr, wchar_t **restrict endptr); 49925 float wcstof(const wchar_t *restrict nptr, wchar_t **restrict endptr); 49926 long double wcstold(const wchar_t *restrict nptr, 49927 wchar_t **restrict endptr); 49928 DESCRIPTION 49929 CX The functionality described on this reference page is aligned with the ISO C standard. Any 49930 conflict between the requirements described here and the ISO C standard is unintentional. This 49931 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 49932 These functions shall convert the initial portion of the wide-character string pointed to by nptr to 49933 double, float, and long double representation, respectively. First, they shall decompose the | 49934 input wide-character string into three parts: | 49935 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 49936 iswspace( )) 49937 2. A subject sequence interpreted as a floating-point constant or representing infinity or NaN 49938 3. A final wide-character string of one or more unrecognized wide-character codes, including 49939 the terminating null wide-character code of the input wide-character string 49940 Then they shall attempt to convert the subject sequence to a floating-point number, and return | 49941 the result. | 49942 The expected form of the subject sequence is an optional plus or minus sign, then one of the 49943 following: 49944 * A non-empty sequence of decimal digits optionally containing a radix character, then an 49945 optional exponent part 49946 * A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally containing a radix 49947 character, then an optional binary exponent part 49948 * One of INF or INFINITY, or any other wide string equivalent except for case 49949 * One of NAN or NAN(n-wchar-sequenceopt), or any other wide string ignoring case in the NAN 49950 part, where: 49951 n-wchar-sequence: 49952 digit 49953 nondigit 49954 n-wchar-sequence digit 49955 n-wchar-sequence nondigit 49956 The subject sequence is defined as the longest initial subsequence of the input wide string, 49957 starting with the first non-white-space wide character, that is of the expected form. The subject 49958 sequence contains no wide characters if the input wide string is not of the expected form. 49959 If the subject sequence has the expected form for a floating-point number, the sequence of wide 49960 characters starting with the first digit or the radix character (whichever occurs first) shall be | 49961 interpreted as a floating constant according to the rules of the C language, except that the radix | 49962 character shall be used in place of a period, and that if neither an exponent part nor a radix | 49963 character appears in a decimal floating-point number, or if a binary exponent part does not | System Interfaces, Issue 6 2117 wcstod( ) System Interfaces 49964 appear in a hexadecimal floating-point number, an exponent part of the appropriate type with | 49965 value zero shall be assumed to follow the last digit in the string. If the subject sequence begins | 49966 with a minus sign, the sequence shall be interpreted as negated. A wide-character sequence INF | 49967 or INFINITY shall be interpreted as an infinity, if representable in the return type, else as if it | 49968 were a floating constant that is too large for the range of the return type. A wide-character | 49969 sequence NAN or NAN(n-wchar-sequenceopt) shall be interpreted as a quiet NaN, if supported in | 49970 the return type, else as if it were a subject sequence part that does not have the expected form; | 49971 the meaning of the n-wchar sequences is implementation-defined. A pointer to the final wide | 49972 string shall be stored in the object pointed to by endptr, provided that endptr is not a null pointer. | 49973 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the | 49974 conversion shall be rounded in an implementation-defined manner. | 49975 CX The radix character shall be as defined in the program's locale (category LC_NUMERIC). In the | 49976 POSIX locale, or in a locale where the radix character is not defined, the radix character shall 49977 default to a period ('.'). 49978 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 49979 accepted. 49980 If the subject sequence is empty or does not have the expected form, no conversion shall be | 49981 performed; the value of nptr shall be stored in the object pointed to by endptr, provided that | 49982 endptr is not a null pointer. 49983 CX The wcstod( ) function shall not change the setting of errno if successful. 49984 Since 0 is returned on error and is also a valid return on success, an application wishing to check | 49985 for error situations should set errno to 0, then call wcstod( ), wcstof( ), or wcstold( ), then check 49986 errno. 49987 RETURN VALUE 49988 Upon successful completion, these functions shall return the converted value. If no conversion 49989 CX could be performed, 0 shall be returned and errno may be set to [EINVAL]. 49990 If the correct value is outside the range of representable values, plus or minus HUGE_VAL, 49991 HUGE_VALF, or HUGE_VALL shall be returned (according to the sign of the value), and errno 49992 shall be set to [ERANGE]. 49993 If the correct value would cause underflow, a value whose magnitude is no greater than the 49994 smallest normalized positive number in the return type shall be returned and errno set to 49995 [ERANGE]. 49996 ERRORS 49997 The wcstod( ) function shall fail if: 49998 [ERANGE] The value to be returned would cause overflow or underflow. 49999 The wcstod( ) function may fail if: 50000 CX [EINVAL] No conversion could be performed. 2118 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstod( ) 50001 EXAMPLES 50002 None. 50003 APPLICATION USAGE 50004 If the subject sequence has the hexadecimal form and FLT_RADIX is not a power of 2, and the | 50005 result is not exactly representable, the result should be one of the two numbers in the | 50006 appropriate internal format that are adjacent to the hexadecimal floating source value, with the | 50007 extra stipulation that the error should have a correct sign for the current rounding direction. | 50008 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in ) 50009 significant digits, the result should be correctly rounded. If the subject sequence D has the 50010 decimal form and more than DECIMAL_DIG significant digits, consider the two bounding, 50011 adjacent decimal strings L and U, both having DECIMAL_DIG significant digits, such that the 50012 values of L, D, and U satisfy "L <= D <= U". The result should be one of the (equal or 50013 adjacent) values that would be obtained by correctly rounding L and U according to the current 50014 rounding direction, with the extra stipulation that the error with respect to D should have a 50015 correct sign for the current rounding direction. 50016 RATIONALE 50017 None. 50018 FUTURE DIRECTIONS 50019 None. 50020 SEE ALSO 50021 iswspace( ), localeconv( ), scanf( ), setlocale( ), wcstol( ), the Base Definitions volume of 50022 IEEE Std 1003.1-200x, , , the Base Definitions volume of 50023 IEEE Std 1003.1-200x, Chapter 7, Locale 50024 CHANGE HISTORY 50025 First released in Issue 4. Derived from the MSE working draft. 50026 Issue 5 50027 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 50028 Issue 6 50029 Extensions beyond the ISO C standard are now marked. 50030 The following new requirements on POSIX implementations derive from alignment with the 50031 Single UNIX Specification: 50032 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 50033 added if no conversion could be performed. 50034 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 50035 * The wcstod( ) prototype is updated. 50036 * The wcstof( ) and wcstold( ) functions are added. 50037 * If the correct value for wcstod( ) would cause underflow, the return value changed from 0 (as 50038 specified in Issue 5) to the smallest normalized positive number. 50039 * The DESCRIPTION, RETURN VALUE, and APPLICATION USAGE sections are extensively 50040 updated. 50041 ISO/IEC 9899: 1999 standard, Technical Corrigendum No. 1 is incorporated. | System Interfaces, Issue 6 2119 wcstof( ) System Interfaces 50042 NAME 50043 wcstof - convert a wide-character string to a double-precision number 50044 SYNOPSIS 50045 #include 50046 float wcstof(const wchar_t *restrict nptr, wchar_t **restrict endptr); 50047 DESCRIPTION 50048 Refer to wcstod( ). 2120 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstoimax( ) 50049 NAME 50050 wcstoimax, wcstoumax - convert wide-character string to integer type 50051 SYNOPSIS 50052 #include 50053 #include 50054 intmax_t wcstoimax(const wchar_t *restrict nptr, 50055 wchar_t **restrict endptr, int base); 50056 uintmax_t wcstoumax(const wchar_t *restrict nptr, 50057 wchar_t **restrict endptr, int base); 50058 DESCRIPTION 50059 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50060 conflict between the requirements described here and the ISO C standard is unintentional. This 50061 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50062 These functions shall be equivalent to the wcstol( ), wcstoll( ), wcstoul( ), and wcstoull( ) functions, 50063 respectively, except that the initial portion of the wide string shall be converted to intmax_t and 50064 uintmax_t representation, respectively. 50065 RETURN VALUE 50066 These functions shall return the converted value, if any. 50067 If no conversion could be performed, zero shall be returned. If the correct value is outside the 50068 range of representable values, {INTMAX_MAX}, {INTMAX_MIN}, or {UINTMAX_MAX} shall 50069 be returned (according to the return type and sign of the value, if any), and errno shall be set to 50070 [ERANGE]. 50071 ERRORS 50072 These functions shall fail if: 50073 [EINVAL] The value of base is not supported. 50074 [ERANGE] The value to be returned is not representable. 50075 These functions may fail if: 50076 [EINVAL] No conversion could be performed. 50077 EXAMPLES 50078 None. 50079 APPLICATION USAGE 50080 None. 50081 RATIONALE 50082 None. 50083 FUTURE DIRECTIONS 50084 None. 50085 SEE ALSO 50086 wcstol( ), wcstoul( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 50087 50088 CHANGE HISTORY 50089 First released in Issue 6. Derived from the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2121 wcstok( ) System Interfaces 50090 NAME 50091 wcstok - split wide-character string into tokens 50092 SYNOPSIS 50093 #include 50094 wchar_t *wcstok(wchar_t *restrict ws1, const wchar_t *restrict ws2, 50095 wchar_t **restrict ptr); 50096 DESCRIPTION 50097 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50098 conflict between the requirements described here and the ISO C standard is unintentional. This 50099 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50100 A sequence of calls to wcstok( ) shall break the wide-character string pointed to by ws1 into a | 50101 sequence of tokens, each of which shall be delimited by a wide-character code from the wide- | 50102 character string pointed to by ws2. The ptr argument points to a caller-provided wchar_t pointer | 50103 into which the wcstok( ) function shall store information necessary for it to continue scanning the | 50104 same wide-character string. | 50105 The first call in the sequence has ws1 as its first argument, and is followed by calls with a null 50106 pointer as their first argument. The separator string pointed to by ws2 may be different from call 50107 to call. 50108 The first call in the sequence shall search the wide-character string pointed to by ws1 for the first | 50109 wide-character code that is not contained in the current separator string pointed to by ws2. If no 50110 such wide-character code is found, then there are no tokens in the wide-character string pointed 50111 to by ws1 and wcstok( ) shall return a null pointer. If such a wide-character code is found, it shall | 50112 be the start of the first token. | 50113 The wcstok( ) function shall then search from there for a wide-character code that is contained in | 50114 the current separator string. If no such wide-character code is found, the current token extends 50115 to the end of the wide-character string pointed to by ws1, and subsequent searches for a token | 50116 shall return a null pointer. If such a wide-character code is found, it shall be overwritten by a | 50117 null wide character, which terminates the current token. The wcstok( ) function shall save a | 50118 pointer to the following wide-character code, from which the next search for a token shall start. | 50119 Each subsequent call, with a null pointer as the value of the first argument, shall start searching | 50120 from the saved pointer and behave as described above. | 50121 The implementation shall behave as if no function calls wcstok( ). 50122 RETURN VALUE 50123 Upon successful completion, the wcstok( ) function shall return a pointer to the first wide- 50124 character code of a token. Otherwise, if there is no token, wcstok( ) shall return a null pointer. 50125 ERRORS 50126 No errors are defined. 2122 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstok( ) 50127 EXAMPLES 50128 None. 50129 APPLICATION USAGE 50130 None. 50131 RATIONALE 50132 None. 50133 FUTURE DIRECTIONS 50134 None. 50135 SEE ALSO 50136 The Base Definitions volume of IEEE Std 1003.1-200x, 50137 CHANGE HISTORY 50138 First released in Issue 4. 50139 Issue 5 50140 Aligned with ISO/IEC 9899: 1990/Amendment 1: 1995 (E). Specifically, a third argument is 50141 added to the definition of this function in the SYNOPSIS. 50142 Issue 6 50143 The wcstok( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2123 wcstol( ) System Interfaces 50144 NAME 50145 wcstol, wcstoll - convert a wide-character string to a long integer 50146 SYNOPSIS 50147 #include 50148 long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr, 50149 int base); 50150 long long wcstoll(const wchar_t *restrict nptr, 50151 wchar_t **restrict endptr, int base); 50152 DESCRIPTION 50153 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50154 conflict between the requirements described here and the ISO C standard is unintentional. This 50155 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50156 These functions shall convert the initial portion of the wide-character string pointed to by nptr to 50157 long, long long, unsigned long, and unsigned long long representation, respectively. First, they | 50158 shall decompose the input string into three parts: | 50159 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 50160 iswspace( )) 50161 2. A subject sequence interpreted as an integer represented in some radix determined by the 50162 value of base 50163 3. A final wide-character string of one or more unrecognized wide-character codes, including 50164 the terminating null wide-character code of the input wide-character string 50165 Then they shall attempt to convert the subject sequence to an integer, and return the result. | 50166 If base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, 50167 or hexadecimal constant, any of which may be preceded by a '+' or '-' sign. A decimal 50168 constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal 50169 constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to '7' 50170 only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the 50171 decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively. 50172 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 50173 of letters and digits representing an integer with the radix specified by base, optionally preceded 50174 by a '+' or '-' sign, but not including an integer suffix. The letters from 'a' (or 'A') to 'z' 50175 (or 'Z') inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less 50176 than that of base shall be permitted. If the value of base is 16, the wide-character code | 50177 representations of 0x or 0X may optionally precede the sequence of letters and digits, following 50178 the sign if present. 50179 The subject sequence is defined as the longest initial subsequence of the input wide-character 50180 string, starting with the first non-white-space wide-character code that is of the expected form. 50181 The subject sequence contains no wide-character codes if the input wide-character string is 50182 empty or consists entirely of white-space wide-character code, or if the first non-white-space 50183 wide-character code is other than a sign or a permissible letter or digit. 50184 If the subject sequence has the expected form and base is 0, the sequence of wide-character codes 50185 starting with the first digit shall be interpreted as an integer constant. If the subject sequence has | 50186 the expected form and the value of base is between 2 and 36, it shall be used as the base for | 50187 conversion, ascribing to each letter its value as given above. If the subject sequence begins with a | 50188 minus sign, the value resulting from the conversion shall be negated. A pointer to the final | 50189 wide-character string shall be stored in the object pointed to by endptr, provided that endptr is | 2124 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstol( ) 50190 not a null pointer. 50191 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 50192 accepted. 50193 If the subject sequence is empty or does not have the expected form, no conversion shall be | 50194 performed; the value of nptr shall be stored in the object pointed to by endptr, provided that | 50195 endptr is not a null pointer. 50196 CX These functions shall not change the setting of errno if successful. 50197 Since 0, {LONG_MIN} or {LLONG_MIN} and {LONG_MAX} or {LLONG_MAX} are returned on | 50198 error and are also valid returns on success, an application wishing to check for error situations 50199 should set errno to 0, then call wcstol( ) or wcstoll( ), then check errno. 50200 RETURN VALUE 50201 Upon successful completion, these functions shall return the converted value, if any. If no 50202 CX conversion could be performed, 0 shall be returned and errno may be set to indicate the error. If 50203 the correct value is outside the range of representable values, {LONG_MIN}, {LONG_MAX}, 50204 {LLONG_MIN}, or {LLONG_MAX} shall be returned (according to the sign of the value), and 50205 errno set to [ERANGE]. 50206 ERRORS 50207 These functions shall fail if: 50208 CX [EINVAL] The value of base is not supported. 50209 [ERANGE] The value to be returned is not representable. 50210 These functions may fail if: 50211 CX [EINVAL] No conversion could be performed. 50212 EXAMPLES 50213 None. 50214 APPLICATION USAGE 50215 None. 50216 RATIONALE 50217 None. 50218 FUTURE DIRECTIONS 50219 None. 50220 SEE ALSO 50221 iswalpha( ), scanf( ), wcstod( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50222 CHANGE HISTORY 50223 First released in Issue 4. Derived from the MSE working draft. 50224 Issue 5 50225 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 50226 Issue 6 50227 Extensions beyond the ISO C standard are now marked. 50228 The following new requirements on POSIX implementations derive from alignment with the 50229 Single UNIX Specification: 50230 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 50231 added if no conversion could be performed. System Interfaces, Issue 6 2125 wcstol( ) System Interfaces 50232 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 50233 * The wcstol( ) prototype is updated. 50234 * The wcstoll( ) function is added. 2126 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstold( ) 50235 NAME 50236 wcstold - convert a wide-character string to a double-precision number 50237 SYNOPSIS 50238 #include 50239 long double wcstold(const wchar_t *restrict nptr, 50240 wchar_t **restrict endptr); 50241 DESCRIPTION 50242 Refer to wcstod( ). System Interfaces, Issue 6 2127 wcstoll( ) System Interfaces 50243 NAME 50244 wcstoll - convert a wide-character string to a long integer 50245 SYNOPSIS 50246 #include 50247 long long wcstoll(const wchar_t *restrict nptr, 50248 wchar_t **restrict endptr, int base); 50249 DESCRIPTION 50250 Refer to wcstol( ). 2128 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstombs( ) 50251 NAME 50252 wcstombs - convert a wide-character string to a character string 50253 SYNOPSIS 50254 #include 50255 size_t wcstombs(char *restrict s, const wchar_t *restrict pwcs, 50256 size_t n); 50257 DESCRIPTION 50258 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50259 conflict between the requirements described here and the ISO C standard is unintentional. This 50260 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50261 The wcstombs( ) function shall convert the sequence of wide-character codes that are in the array 50262 pointed to by pwcs into a sequence of characters that begins in the initial shift state and store | 50263 these characters into the array pointed to by s, stopping if a character would exceed the limit of n | 50264 total bytes or if a null byte is stored. Each wide-character code shall be converted as if by a call to | 50265 wctomb( ), except that the shift state of wctomb( ) shall not be affected. | 50266 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 50267 No more than n bytes shall be modified in the array pointed to by s. If copying takes place 50268 CX between objects that overlap, the behavior is undefined. If s is a null pointer, wcstombs( ) shall 50269 return the length required to convert the entire array regardless of the value of n, but no values 50270 are stored. 50271 The wcstombs( ) function need not be reentrant. A function that is not required to be reentrant is 50272 not required to be thread-safe. 50273 RETURN VALUE 50274 If a wide-character code is encountered that does not correspond to a valid character (of one or 50275 more bytes each), wcstombs( ) shall return (size_t)-1. Otherwise, wcstombs( ) shall return the 50276 number of bytes stored in the character array, not including any terminating null byte. The array 50277 shall not be null-terminated if the value returned is n. 50278 ERRORS 50279 The wcstombs( ) function may fail if: 50280 CX [EILSEQ] A wide-character code does not correspond to a valid character. 50281 EXAMPLES 50282 None. 50283 APPLICATION USAGE 50284 None. 50285 RATIONALE 50286 None. 50287 FUTURE DIRECTIONS 50288 None. 50289 SEE ALSO 50290 mblen( ), mbtowc( ), mbstowcs( ), wctomb( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50291 System Interfaces, Issue 6 2129 wcstombs( ) System Interfaces 50292 CHANGE HISTORY 50293 First released in Issue 4. Derived from the ISO C standard. 50294 Issue 6 50295 The following new requirements on POSIX implementations derive from alignment with the 50296 Single UNIX Specification: 50297 * The DESCRIPTION states the effect of when s is a null pointer. 50298 * The [EILSEQ] error condition is added. 50299 The wcstombs( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. 2130 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstoul( ) 50300 NAME 50301 wcstoul, wcstoull - convert a wide-character string to an unsigned long 50302 SYNOPSIS 50303 #include 50304 unsigned long wcstoul(const wchar_t *restrict nptr, 50305 wchar_t **restrict endptr, int base); 50306 unsigned long long wcstoull(const wchar_t *restrict nptr, 50307 wchar_t **restrict endptr, int base); 50308 DESCRIPTION 50309 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50310 conflict between the requirements described here and the ISO C standard is unintentional. This 50311 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50312 The wcstoul( ) and wcstoull( ) functions shall convert the initial portion of the wide-character 50313 string pointed to by nptr to unsigned long and unsigned long long representation, respectively. | 50314 First, they shall decompose the input wide-character string into three parts: | 50315 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 50316 iswspace( )) 50317 2. A subject sequence interpreted as an integer represented in some radix determined by the 50318 value of base 50319 3. A final wide-character string of one or more unrecognized wide-character codes, including 50320 the terminating null wide-character code of the input wide-character string 50321 Then they shall attempt to convert the subject sequence to an unsigned integer, and return the | 50322 result. | 50323 If base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, 50324 or hexadecimal constant, any of which may be preceded by a '+' or '-' sign. A decimal 50325 constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal 50326 constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to '7' 50327 only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the 50328 decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively. 50329 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 50330 of letters and digits representing an integer with the radix specified by base, optionally preceded 50331 by a '+' or '-' sign, but not including an integer suffix. The letters from 'a' (or 'A') to 'z' 50332 (or 'Z') inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less 50333 than that of base shall be permitted. If the value of base is 16, the wide-character codes 0x or 0X | 50334 may optionally precede the sequence of letters and digits, following the sign if present. 50335 The subject sequence is defined as the longest initial subsequence of the input wide-character 50336 string, starting with the first wide-character code that is not white space and is of the expected 50337 form. The subject sequence contains no wide-character codes if the input wide-character string is 50338 empty or consists entirely of white-space wide-character codes, or if the first wide-character 50339 code that is not white space is other than a sign or a permissible letter or digit. 50340 If the subject sequence has the expected form and base is 0, the sequence of wide-character codes 50341 starting with the first digit shall be interpreted as an integer constant. If the subject sequence has | 50342 the expected form and the value of base is between 2 and 36, it shall be used as the base for | 50343 conversion, ascribing to each letter its value as given above. If the subject sequence begins with a | 50344 minus sign, the value resulting from the conversion shall be negated. A pointer to the final | 50345 wide-character string shall be stored in the object pointed to by endptr, provided that endptr is | System Interfaces, Issue 6 2131 wcstoul( ) System Interfaces 50346 not a null pointer. 50347 CX In other than the C or POSIX locales, other implementation-defined subject sequences may be 50348 accepted. 50349 If the subject sequence is empty or does not have the expected form, no conversion shall be | 50350 performed; the value of nptr shall be stored in the object pointed to by endptr, provided that | 50351 endptr is not a null pointer. 50352 CX The wcstoul( ) function shall not change the setting of errno if successful. 50353 Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and 0 is also a valid return | 50354 on success, an application wishing to check for error situations should set errno to 0, then call 50355 wcstoul( ) or wcstoull( ), then check errno. 50356 RETURN VALUE 50357 Upon successful completion, the wcstoul( ) and wcstoull( ) functions shall return the converted 50358 CX value, if any. If no conversion could be performed, 0 shall be returned and errno may be set to 50359 indicate the error. If the correct value is outside the range of representable values, 50360 {ULONG_MAX} or {ULLONG_MAX} respectively shall be returned and errno set to [ERANGE]. 50361 ERRORS 50362 These functions shall fail if: 50363 CX [EINVAL] The value of base is not supported. 50364 [ERANGE] The value to be returned is not representable. 50365 These functions may fail if: 50366 CX [EINVAL] No conversion could be performed. 50367 EXAMPLES 50368 None. 50369 APPLICATION USAGE 50370 None. 50371 RATIONALE 50372 None. 50373 FUTURE DIRECTIONS 50374 None. 50375 SEE ALSO 50376 iswalpha( ), scanf( ), wcstod( ), wcstol( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50377 50378 CHANGE HISTORY 50379 First released in Issue 4. Derived from the MSE working draft. 50380 Issue 5 50381 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 50382 Issue 6 50383 Extensions beyond the ISO C standard are now marked. 50384 The following new requirements on POSIX implementations derive from alignment with the 50385 Single UNIX Specification: 50386 * The [EINVAL] error condition is added for when the value of base is not supported. 2132 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstoul( ) 50387 In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 50388 added if no conversion could be performed. 50389 The following changes are made for alignment with the ISO/IEC 9899: 1999 standard: 50390 * The wcstoul( ) prototype is updated. 50391 * The wcstoull( ) function is added. System Interfaces, Issue 6 2133 wcstoull( ) System Interfaces 50392 NAME 50393 wcstoull - convert a wide-character string to an unsigned long 50394 SYNOPSIS 50395 #include 50396 unsigned long long wcstoull(const wchar_t *restrict nptr, 50397 wchar_t **restrict endptr, int base); 50398 DESCRIPTION 50399 Refer to wcstoul( ). 2134 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcstoumax( ) 50400 NAME 50401 wcstoumax - convert wide-character string to integer type 50402 SYNOPSIS 50403 #include 50404 #include 50405 uintmax_t wcstoumax(const wchar_t *restrict nptr, 50406 wchar_t **restrict endptr, int base); 50407 DESCRIPTION 50408 Refer to wcstoimax( ). System Interfaces, Issue 6 2135 wcswcs( ) System Interfaces 50409 NAME 50410 wcswcs - find a wide substring (LEGACY) 50411 SYNOPSIS 50412 XSI #include 50413 wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2); 50414 50415 DESCRIPTION 50416 The wcswcs( ) function shall locate the first occurrence in the wide-character string pointed to by 50417 ws1 of the sequence of wide-character codes (excluding the terminating null wide-character 50418 code) in the wide-character string pointed to by ws2. 50419 RETURN VALUE 50420 Upon successful completion, wcswcs( ) shall return a pointer to the located wide-character string 50421 or a null pointer if the wide-character string is not found. 50422 If ws2 points to a wide-character string with zero length, the function shall return ws1. 50423 ERRORS 50424 No errors are defined. 50425 EXAMPLES 50426 None. 50427 APPLICATION USAGE 50428 This function was not included in the final ISO/IEC 9899: 1990/Amendment 1: 1995 (E). 50429 Application developers are strongly encouraged to use the wcsstr( ) function instead. 50430 RATIONALE 50431 None. 50432 FUTURE DIRECTIONS 50433 This function may be withdrawn in a future version. 50434 SEE ALSO 50435 wcschr( ), wcsstr( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50436 CHANGE HISTORY 50437 First released in Issue 4. Derived from the MSE working draft. 50438 Issue 5 50439 Marked EX. 50440 Issue 6 50441 This function is marked LEGACY. 2136 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcswidth( ) 50442 NAME 50443 wcswidth - number of column positions of a wide-character string 50444 SYNOPSIS 50445 XSI #include 50446 int wcswidth(const wchar_t *pwcs, size_t n); 50447 50448 DESCRIPTION 50449 The wcswidth( ) function shall determine the number of column positions required for n wide- 50450 character codes (or fewer than n wide-character codes if a null wide-character code is 50451 encountered before n wide-character codes are exhausted) in the string pointed to by pwcs. 50452 RETURN VALUE 50453 The wcswidth( ) function either shall return 0 (if pwcs points to a null wide-character code), or 50454 return the number of column positions to be occupied by the wide-character string pointed to by 50455 pwcs, or return -1 (if any of the first n wide-character codes in the wide-character string pointed 50456 to by pwcs is not a printable wide-character code). | 50457 ERRORS 50458 No errors are defined. 50459 EXAMPLES 50460 None. 50461 APPLICATION USAGE 50462 This function was removed from the final ISO/IEC 9899: 1990/Amendment 1: 1995 (E), and the 50463 return value for a non-printable wide character is not specified. 50464 RATIONALE 50465 None. 50466 FUTURE DIRECTIONS 50467 None. 50468 SEE ALSO 50469 wcwidth( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Base Definitions 50470 volume of IEEE Std 1003.1-200x, Section 3.103, Column Position 50471 CHANGE HISTORY 50472 First released in Issue 4. Derived from the MSE working draft. 50473 Issue 6 50474 The Open Group Corrigendum U021/11 is applied. The function is marked as an extension. System Interfaces, Issue 6 2137 wcsxfrm( ) System Interfaces 50475 NAME 50476 wcsxfrm - wide-character string transformation 50477 SYNOPSIS 50478 #include 50479 size_t wcsxfrm(wchar_t *restrict ws1, const wchar_t *restrict ws2, 50480 size_t n); 50481 DESCRIPTION 50482 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50483 conflict between the requirements described here and the ISO C standard is unintentional. This 50484 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50485 The wcsxfrm( ) function shall transform the wide-character string pointed to by ws2 and place the 50486 resulting wide-character string into the array pointed to by ws1. The transformation shall be | 50487 such that if wcscmp( ) is applied to two transformed wide strings, it shall return a value greater | 50488 than, equal to, or less than 0, corresponding to the result of wcscoll( ) applied to the same two 50489 original wide-character strings. No more than n wide-character codes shall be placed into the | 50490 resulting array pointed to by ws1, including the terminating null wide-character code. If n is 0, | 50491 ws1 is permitted to be a null pointer. If copying takes place between objects that overlap, the 50492 behavior is undefined. 50493 CX The wcsxfrm( ) function shall not change the setting of errno if successful. 50494 Since no return value is reserved to indicate an error, an application wishing to check for error | 50495 situations should set errno to 0, then call wcsxfrm( ), then check errno. 50496 RETURN VALUE 50497 The wcsxfrm( ) function shall return the length of the transformed wide-character string (not 50498 including the terminating null wide-character code). If the value returned is n or more, the 50499 contents of the array pointed to by ws1 are unspecified. | 50500 CX On error, the wcsxfrm( ) function may set errno, but no return value is reserved to indicate an 50501 error. 50502 ERRORS 50503 The wcsxfrm( ) function may fail if: 50504 CX [EINVAL] The wide-character string pointed to by ws2 contains wide-character codes 50505 outside the domain of the collating sequence. 50506 EXAMPLES 50507 None. 50508 APPLICATION USAGE 50509 The transformation function is such that two transformed wide-character strings can be ordered 50510 by wcscmp( ) as appropriate to collating sequence information in the program's locale (category 50511 LC_COLLATE). 50512 The fact that when n is 0 ws1 is permitted to be a null pointer is useful to determine the size of 50513 the ws1 array prior to making the transformation. 50514 RATIONALE 50515 None. 2138 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wcsxfrm( ) 50516 FUTURE DIRECTIONS 50517 None. 50518 SEE ALSO 50519 wcscmp( ), wcscoll( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50520 CHANGE HISTORY 50521 First released in Issue 4. Derived from the MSE working draft. 50522 Issue 5 50523 Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 50524 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 50525 Issue 6 50526 In previous versions, this function was required to return -1 on error. 50527 Extensions beyond the ISO C standard are now marked. 50528 The following new requirements on POSIX implementations derive from alignment with the 50529 Single UNIX Specification: 50530 * In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 50531 added if no conversion could be performed. 50532 The wcsxfrm( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2139 wctob( ) System Interfaces 50533 NAME 50534 wctob - wide-character to single-byte conversion 50535 SYNOPSIS 50536 #include 50537 #include 50538 int wctob(wint_t c); 50539 DESCRIPTION 50540 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50541 conflict between the requirements described here and the ISO C standard is unintentional. This 50542 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50543 The wctob( ) function shall determine whether c corresponds to a member of the extended 50544 character set whose character representation is a single byte when in the initial shift state. 50545 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 50546 RETURN VALUE 50547 The wctob( ) function shall return EOF if c does not correspond to a character with length one in 50548 the initial shift state. Otherwise, it shall return the single-byte representation of that character as 50549 an unsigned char converted to int. 50550 ERRORS 50551 No errors are defined. 50552 EXAMPLES 50553 None. 50554 APPLICATION USAGE 50555 None. 50556 RATIONALE 50557 None. 50558 FUTURE DIRECTIONS 50559 None. 50560 SEE ALSO 50561 btowc( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50562 CHANGE HISTORY 50563 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50564 (E). 2140 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wctomb( ) 50565 NAME 50566 wctomb - convert a wide-character code to a character 50567 SYNOPSIS 50568 #include 50569 int wctomb(char *s, wchar_t wchar); 50570 DESCRIPTION 50571 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50572 conflict between the requirements described here and the ISO C standard is unintentional. This 50573 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50574 The wctomb( ) function shall determine the number of bytes needed to represent the character 50575 corresponding to the wide-character code whose value is wchar (including any change in the | 50576 shift state). It shall store the character representation (possibly multiple bytes and any special | 50577 bytes to change shift state) in the array object pointed to by s (if s is not a null pointer). At most 50578 {MB_CUR_MAX} bytes shall be stored. If wchar is 0, a null byte shall be stored, preceded by any | 50579 shift sequence needed to restore the initial shift state, and wctomb( ) shall be left in the initial shift | 50580 state. | 50581 CX The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 50582 state-dependent encoding, this function shall be placed into its initial state by a call for which its | 50583 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null | 50584 pointer shall cause the internal state of the function to be altered as necessary. A call with s as a | 50585 null pointer shall cause this function to return a non-zero value if encodings have state | 50586 dependency, and 0 otherwise. Changing the LC_CTYPE category causes the shift state of this | 50587 function to be unspecified. | 50588 The wctomb( ) function need not be reentrant. A function that is not required to be reentrant is 50589 not required to be thread-safe. 50590 The implementation shall behave as if no function defined in this volume of 50591 IEEE Std 1003.1-200x calls wctomb( ). 50592 RETURN VALUE 50593 If s is a null pointer, wctomb( ) shall return a non-zero or 0 value, if character encodings, 50594 respectively, do or do not have state-dependent encodings. If s is not a null pointer, wctomb( ) 50595 shall return -1 if the value of wchar does not correspond to a valid character, or return the 50596 number of bytes that constitute the character corresponding to the value of wchar. 50597 In no case shall the value returned be greater than the value of the {MB_CUR_MAX} macro. 50598 ERRORS 50599 No errors are defined. 50600 EXAMPLES 50601 None. 50602 APPLICATION USAGE 50603 None. 50604 RATIONALE 50605 None. 50606 FUTURE DIRECTIONS 50607 None. System Interfaces, Issue 6 2141 wctomb( ) System Interfaces 50608 SEE ALSO 50609 mblen( ), mbtowc( ), mbstowcs( ), wcstombs( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50610 50611 CHANGE HISTORY 50612 First released in Issue 4. Derived from the ANSI C standard. 50613 Issue 6 50614 Extensions beyond the ISO C standard are now marked. 50615 In the DESCRIPTION, a note about reentrancy and thread-safety is added. 2142 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wctrans( ) 50616 NAME 50617 wctrans - define character mapping 50618 SYNOPSIS 50619 #include 50620 wctrans_t wctrans(const char *charclass); 50621 DESCRIPTION 50622 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50623 conflict between the requirements described here and the ISO C standard is unintentional. This 50624 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50625 The wctrans( ) function is defined for valid character mapping names identified in the current 50626 locale. The charclass is a string identifying a generic character mapping name for which codeset- 50627 specific information is required. The following character mapping names are defined in all 50628 locales: tolower and toupper. 50629 The function shall return a value of type wctrans_t, which can be used as the second argument 50630 to subsequent calls of towctrans( ). The wctrans( ) function shall determine values of wctrans_t | 50631 according to the rules of the coded character set defined by character mapping information in 50632 the program's locale (category LC_CTYPE). The values returned by wctrans( ) shall be valid until | 50633 a call to setlocale( ) that modifies the category LC_CTYPE. | 50634 RETURN VALUE 50635 CX The wctrans( ) function shall return 0 and may set errno to indicate the error if the given | 50636 character mapping name is not valid for the current locale (category LC_CTYPE); otherwise, it | 50637 shall return a non-zero object of type wctrans_t that can be used in calls to towctrans( ). 50638 ERRORS 50639 The wctrans( ) function may fail if: 50640 CX [EINVAL] The character mapping name pointed to by charclass is not valid in the current 50641 locale. 50642 EXAMPLES 50643 None. 50644 APPLICATION USAGE 50645 None. 50646 RATIONALE 50647 None. 50648 FUTURE DIRECTIONS 50649 None. 50650 SEE ALSO 50651 towctrans( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50652 CHANGE HISTORY 50653 First released in Issue 5. Derived from ISO/IEC 9899: 1990/Amendment 1: 1995 (E). System Interfaces, Issue 6 2143 wctype( ) System Interfaces 50654 NAME 50655 wctype - define character class 50656 SYNOPSIS 50657 #include 50658 wctype_t wctype(const char *property); 50659 DESCRIPTION 50660 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50661 conflict between the requirements described here and the ISO C standard is unintentional. This 50662 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50663 The wctype( ) function is defined for valid character class names as defined in the current locale. 50664 The property argument is a string identifying a generic character class for which codeset-specific | 50665 type information is required. The following character class names shall be defined in all locales: | 50666 alnum digit punct 50667 alpha graph space 50668 blank lower upper 50669 cntrl print xdigit 50670 Additional character class names defined in the locale definition file (category LC_CTYPE) can 50671 also be specified. 50672 The function shall return a value of type wctype_t, which can be used as the second argument to 50673 subsequent calls of iswctype( ). The wctype( ) function shall determine values of wctype_t | 50674 according to the rules of the coded character set defined by character type information in the 50675 program's locale (category LC_CTYPE). The values returned by wctype( ) shall be valid until a | 50676 call to setlocale( ) that modifies the category LC_CTYPE. | 50677 RETURN VALUE 50678 The wctype( ) function shall return 0 if the given character class name is not valid for the current 50679 locale (category LC_CTYPE); otherwise, it shall return an object of type wctype_t that can be 50680 used in calls to iswctype( ). 50681 ERRORS 50682 No errors are defined. 50683 EXAMPLES 50684 None. 50685 APPLICATION USAGE 50686 None. 50687 RATIONALE 50688 None. 50689 FUTURE DIRECTIONS 50690 None. 50691 SEE ALSO 50692 iswctype( ), the Base Definitions volume of IEEE Std 1003.1-200x, , 50693 CHANGE HISTORY 50694 First released in Issue 4. 2144 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wctype( ) 50695 Issue 5 50696 The following change has been made in this issue for alignment with 50697 ISO/IEC 9899: 1990/Amendment 1: 1995 (E): 50698 * The SYNOPSIS has been changed to indicate that this function and associated data types are 50699 now made visible by inclusion of the header rather than . System Interfaces, Issue 6 2145 wcwidth( ) System Interfaces 50700 NAME 50701 wcwidth - number of column positions of a wide-character code 50702 SYNOPSIS 50703 XSI #include 50704 int wcwidth(wchar_t wc); 50705 50706 DESCRIPTION 50707 The wcwidth( ) function shall determine the number of column positions required for the wide 50708 character wc. The application shall ensure that the value of wc is a character representable as a 50709 wchar_t, and is a wide-character code corresponding to a valid character in the current locale. | 50710 RETURN VALUE 50711 The wcwidth( ) function shall either return 0 (if wc is a null wide-character code), or return the 50712 number of column positions to be occupied by the wide-character code wc, or return -1 (if wc | 50713 does not correspond to a printable wide-character code). | 50714 ERRORS 50715 No errors are defined. 50716 EXAMPLES 50717 None. 50718 APPLICATION USAGE 50719 This function was removed from the final ISO/IEC 9899: 1990/Amendment 1: 1995 (E), and the 50720 return value for a non-printable wide character is not specified. 50721 RATIONALE 50722 None. 50723 FUTURE DIRECTIONS 50724 None. 50725 SEE ALSO 50726 wcswidth( ), the Base Definitions volume of IEEE Std 1003.1-200x, 50727 CHANGE HISTORY 50728 First released as a World-wide Portability Interface in Issue 4. Derived from MSE working draft. 50729 Issue 6 50730 The Open Group Corrigendum U021/12 is applied. This function is marked as an extension. 50731 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2146 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wmemchr( ) 50732 NAME 50733 wmemchr - find a wide character in memory 50734 SYNOPSIS 50735 #include 50736 wchar_t *wmemchr(const wchar_t *ws, wchar_t wc, size_t n); 50737 DESCRIPTION 50738 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50739 conflict between the requirements described here and the ISO C standard is unintentional. This 50740 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50741 The wmemchr( ) function shall locate the first occurrence of wc in the initial n wide characters of 50742 the object pointed to by ws. This function shall not be affected by locale and all wchar_t values | 50743 shall be treated identically. The null wide character and wchar_t values not corresponding to | 50744 valid characters shall not be treated specially. | 50745 If n is zero, the application shall ensure that ws is a valid pointer and the function behaves as if 50746 no valid occurrence of wc is found. 50747 RETURN VALUE 50748 The wmemchr( ) function shall return a pointer to the located wide character, or a null pointer if 50749 the wide character does not occur in the object. 50750 ERRORS 50751 No errors are defined. 50752 EXAMPLES 50753 None. 50754 APPLICATION USAGE 50755 None. 50756 RATIONALE 50757 None. 50758 FUTURE DIRECTIONS 50759 None. 50760 SEE ALSO 50761 wmemcmp( ), wmemcpy( ), wmemmove( ), wmemset( ), the Base Definitions volume of 50762 IEEE Std 1003.1-200x, 50763 CHANGE HISTORY 50764 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50765 (E). 50766 Issue 6 50767 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 2147 wmemcmp( ) System Interfaces 50768 NAME 50769 wmemcmp - compare wide characters in memory 50770 SYNOPSIS 50771 #include 50772 int wmemcmp(const wchar_t *ws1, const wchar_t *ws2, size_t n); 50773 DESCRIPTION 50774 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50775 conflict between the requirements described here and the ISO C standard is unintentional. This 50776 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50777 The wmemcmp( ) function shall compare the first n wide characters of the object pointed to by 50778 ws1 to the first n wide characters of the object pointed to by ws2. This function shall not be | 50779 affected by locale and all wchar_t values shall be treated identically. The null wide character and | 50780 wchar_t values not corresponding to valid characters shall not be treated specially. | 50781 If n is zero, the application shall ensure that ws1 and ws2 are valid pointers, and the function | 50782 shall behave as if the two objects compare equal. | 50783 RETURN VALUE 50784 The wmemcmp( ) function shall return an integer greater than, equal to, or less than zero, 50785 respectively, as the object pointed to by ws1 is greater than, equal to, or less than the object 50786 pointed to by ws2. 50787 ERRORS 50788 No errors are defined. 50789 EXAMPLES 50790 None. 50791 APPLICATION USAGE 50792 None. 50793 RATIONALE 50794 None. 50795 FUTURE DIRECTIONS 50796 None. 50797 SEE ALSO 50798 wmemchr( ), wmemcpy( ), wmemmove( ), wmemset( ), the Base Definitions volume of 50799 IEEE Std 1003.1-200x, 50800 CHANGE HISTORY 50801 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50802 (E). 50803 Issue 6 50804 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2148 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wmemcpy( ) 50805 NAME 50806 wmemcpy - copy wide characters in memory 50807 SYNOPSIS 50808 #include 50809 wchar_t *wmemcpy(wchar_t *restrict ws1, const wchar_t *restrict ws2, 50810 size_t n); 50811 DESCRIPTION 50812 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50813 conflict between the requirements described here and the ISO C standard is unintentional. This 50814 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50815 The wmemcpy( ) function shall copy n wide characters from the object pointed to by ws2 to the 50816 object pointed to by ws1. This function shall not be affected by locale and all wchar_t values | 50817 shall be treated identically. The null wide character and wchar_t values not corresponding to | 50818 valid characters shall not be treated specially. | 50819 If n is zero, the application shall ensure that ws1 and ws2 are valid pointers, and the function | 50820 shall copy zero wide characters. | 50821 RETURN VALUE 50822 The wmemcpy( ) function shall return the value of ws1. 50823 ERRORS 50824 No errors are defined. 50825 EXAMPLES 50826 None. 50827 APPLICATION USAGE 50828 None. 50829 RATIONALE 50830 None. 50831 FUTURE DIRECTIONS 50832 None. 50833 SEE ALSO 50834 wmemchr( ), wmemcmp( ), wmemmove( ), wmemset( ), the Base Definitions volume of 50835 IEEE Std 1003.1-200x, 50836 CHANGE HISTORY 50837 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50838 (E). 50839 Issue 6 50840 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 50841 The wmemcpy( ) prototype is updated for alignment with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2149 wmemmove( ) System Interfaces 50842 NAME 50843 wmemmove - copy wide characters in memory with overlapping areas 50844 SYNOPSIS 50845 #include 50846 wchar_t *wmemmove(wchar_t *ws1, const wchar_t *ws2, size_t n); 50847 DESCRIPTION 50848 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50849 conflict between the requirements described here and the ISO C standard is unintentional. This 50850 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50851 The wmemmove( ) function shall copy n wide characters from the object pointed to by ws2 to the 50852 object pointed to by ws1. Copying shall take place as if the n wide characters from the object | 50853 pointed to by ws2 are first copied into a temporary array of n wide characters that does not 50854 overlap the objects pointed to by ws1 or ws2, and then the n wide characters from the temporary 50855 array are copied into the object pointed to by ws1. 50856 This function shall not be affected by locale and all wchar_t values shall be treated identically. | 50857 The null wide character and wchar_t values not corresponding to valid characters shall not be | 50858 treated specially. | 50859 If n is zero, the application shall ensure that ws1 and ws2 are valid pointers, and the function | 50860 shall copy zero wide characters. | 50861 RETURN VALUE 50862 The wmemmove( ) function shall return the value of ws1. 50863 ERRORS 50864 No errors are defined 50865 EXAMPLES 50866 None. 50867 APPLICATION USAGE 50868 None. 50869 RATIONALE 50870 None. 50871 FUTURE DIRECTIONS 50872 None. 50873 SEE ALSO 50874 wmemchr( ), wmemcmp( ), wmemcpy( ), wmemset( ), the Base Definitions volume of 50875 IEEE Std 1003.1-200x, 50876 CHANGE HISTORY 50877 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50878 (E). 50879 Issue 6 50880 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 2150 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wmemset( ) 50881 NAME 50882 wmemset - set wide characters in memory 50883 SYNOPSIS 50884 #include 50885 wchar_t *wmemset(wchar_t *ws, wchar_t wc, size_t n); 50886 DESCRIPTION 50887 CX The functionality described on this reference page is aligned with the ISO C standard. Any 50888 conflict between the requirements described here and the ISO C standard is unintentional. This 50889 volume of IEEE Std 1003.1-200x defers to the ISO C standard. 50890 The wmemset( ) function shall copy the value of wc into each of the first n wide characters of the 50891 object pointed to by ws. This function shall not be affected by locale and all wchar_t values shall | 50892 be treated identically. The null wide character and wchar_t values not corresponding to valid | 50893 characters shall not be treated specially. | 50894 If n is zero, the application shall ensure that ws is a valid pointer, and the function shall copy | 50895 zero wide characters. | 50896 RETURN VALUE 50897 The wmemset( ) functions shall return the value of ws. 50898 ERRORS 50899 No errors are defined. 50900 EXAMPLES 50901 None. 50902 APPLICATION USAGE 50903 None. 50904 RATIONALE 50905 None. 50906 FUTURE DIRECTIONS 50907 None. 50908 SEE ALSO 50909 wmemchr( ), wmemcmp( ), wmemcpy( ), wmemmove( ), the Base Definitions volume of 50910 IEEE Std 1003.1-200x, 50911 CHANGE HISTORY 50912 First released in Issue 5. Included for alignment with ISO/IEC 9899: 1990/Amendment 1: 1995 50913 (E). 50914 Issue 6 50915 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. System Interfaces, Issue 6 2151 wordexp( ) System Interfaces 50916 NAME 50917 wordexp, wordfree - perform word expansions 50918 SYNOPSIS 50919 #include 50920 int wordexp(const char *restrict words, wordexp_t *restrict pwordexp, 50921 int flags); 50922 void wordfree(wordexp_t *pwordexp); 50923 DESCRIPTION 50924 The wordexp( ) function shall perform word expansions as described in the Shell and Utilities | 50925 volume of IEEE Std 1003.1-200x, Section 2.6, Word Expansions, subject to quoting as in the Shell | 50926 and Utilities volume of IEEE Std 1003.1-200x, Section 2.2, Quoting, and place the list of expanded | 50927 words into the structure pointed to by pwordexp. | 50928 The words argument is a pointer to a string containing one or more words to be expanded. The 50929 expansions shall be the same as would be performed by the command line interpreter if words 50930 were the part of a command line representing the arguments to a utility. Therefore, the 50931 application shall ensure that words does not contain an unquoted or any of the 50932 unquoted shell special characters '|', '&', ';', '<', '>' except in the context of command 50933 substitution as specified in the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 2.6.3, 50934 Command Substitution. It also shall not contain unquoted parentheses or braces, except in the 50935 context of command or variable substitution. The application shall ensure that every member of 50936 words which it expects to have expanded by wordexp( ) does not contain an unquoted initial 50937 comment character. The application shall also ensure that any words which it intends to be 50938 ignored (because they begin or continue a comment) are deleted from words. If the argument 50939 words contains an unquoted comment character (number sign) that is the beginning of a token, 50940 wordexp( ) shall either treat the comment character as a regular character, or interpret it as a 50941 comment indicator and ignore the remainder of words. 50942 The structure type wordexp_t is defined in the header and includes at least the | 50943 following members: | 50944 ____________________________________________________________________________________ 50945 _ Member Type Member Name Description ___________________________________________________________________________________ 50946 size_t we_wordc Count of words matched by words. 50947 char ** we_wordv Pointer to list of expanded words. 50948 _ size_t we_offs Slots to reserve at the beginning of pwordexp->we_wordv. ___________________________________________________________________________________ 50949 The wordexp( ) function shall store the number of generated words into pwordexp->we_wordc and | 50950 a pointer to a list of pointers to words in pwordexp->we_wordv. Each individual field created | 50951 during field splitting (see the Shell and Utilities volume of IEEE Std 1003.1-200x, Section 2.6.5, | 50952 Field Splitting) or pathname expansion (see the Shell and Utilities volume of | 50953 IEEE Std 1003.1-200x, Section 2.6.6, Pathname Expansion) shall be a separate word in the | 50954 pwordexp->we_wordv list. The words shall be in order as described in the Shell and Utilities | 50955 volume of IEEE Std 1003.1-200x, Section 2.6, Word Expansions. The first pointer after the last | 50956 word pointer shall be a null pointer. The expansion of special parameters described in the Shell | 50957 and Utilities volume of IEEE Std 1003.1-200x, Section 2.5.2, Special Parameters is unspecified. | 50958 It is the caller's responsibility to allocate the storage pointed to by pwordexp. The wordexp( ) | 50959 function shall allocate other space as needed, including memory pointed to by pwordexp- | 50960 >we_wordv. The wordfree( ) function frees any memory associated with pwordexp from a previous | 50961 call to wordexp( ). 2152 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wordexp( ) 50962 The flags argument is used to control the behavior of wordexp( ). The value of flags is the 50963 bitwise-inclusive OR of zero or more of the following constants, which are defined in 50964 : 50965 WRDE_APPEND Append words generated to the ones from a previous call to wordexp( ). 50966 WRDE_DOOFFS Make use of pwordexp->we_offs. If this flag is set, pwordexp->we_offs is used 50967 to specify how many null pointers to add to the beginning of pwordexp- 50968 >we_wordv. In other words, pwordexp->we_wordv shall point to pwordexp- 50969 >we_offs null pointers, followed by pwordexp->we_wordc word pointers, 50970 followed by a null pointer. 50971 WRDE_NOCMD If the implementation supports the utilities defined in the Shell and 50972 Utilities volume of IEEE Std 1003.1-200x, fail if command substitution, as 50973 specified in the Shell and Utilities volume of IEEE Std 1003.1-200x, 50974 Section 2.6.3, Command Substitution, is requested. 50975 WRDE_REUSE The pwordexp argument was passed to a previous successful call to 50976 wordexp( ), and has not been passed to wordfree( ). The result shall be the 50977 same as if the application had called wordfree( ) and then called wordexp( ) 50978 without WRDE_REUSE. 50979 WRDE_SHOWERR Do not redirect stderr to /dev/null. 50980 WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. 50981 The WRDE_APPEND flag can be used to append a new set of words to those generated by a 50982 previous call to wordexp( ). The following rules apply to applications when two or more calls to 50983 wordexp( ) are made with the same value of pwordexp and without intervening calls to wordfree( ): 50984 1. The first such call shall not set WRDE_APPEND. All subsequent calls shall set it. 50985 2. All of the calls shall set WRDE_DOOFFS, or all shall not set it. 50986 3. After the second and each subsequent call, pwordexp->we_wordv shall point to a list 50987 containing the following: 50988 a. Zero or more null pointers, as specified by WRDE_DOOFFS and pwordexp->we_offs 50989 b. Pointers to the words that were in the pwordexp->we_wordv list before the call, in the 50990 same order as before 50991 c. Pointers to the new words generated by the latest call, in the specified order 50992 4. The count returned in pwordexp->we_wordc shall be the total number of words from all of 50993 the calls. 50994 5. The application can change any of the fields after a call to wordexp( ), but if it does it shall 50995 reset them to the original value before a subsequent call, using the same pwordexp value, to 50996 wordfree( ) or wordexp( ) with the WRDE_APPEND or WRDE_REUSE flag. 50997 If the implementation supports the utilities defined in the Shell and Utilities volume of 50998 IEEE Std 1003.1-200x, and words contains an unquoted character-, '|', '&', ';', 50999 '<', '>', '(', ')', '{', '}'-in an inappropriate context, wordexp( ) shall fail, and the number 51000 of expanded words shall be 0. 51001 Unless WRDE_SHOWERR is set in flags, wordexp( ) shall redirect stderr to /dev/null for any 51002 utilities executed as a result of command substitution while expanding words. If 51003 WRDE_SHOWERR is set, wordexp( ) may write messages to stderr if syntax errors are detected 51004 while expanding words. System Interfaces, Issue 6 2153 wordexp( ) System Interfaces 51005 The application shall ensure that if WRDE_DOOFFS is set, then pwordexp->we_offs has the same 51006 value for each wordexp( ) call and wordfree( ) call using a given pwordexp. 51007 The following constants are defined as error return values: 51008 WRDE_BADCHAR One of the unquoted characters-, '|', '&', ';', '<', '>', 51009 '(', ')', '{', '}'-appears in words in an inappropriate context. 51010 WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags. 51011 WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. 51012 WRDE_NOSPACE Attempt to allocate memory failed. 51013 WRDE_SYNTAX Shell syntax error, such as unbalanced parentheses or unterminated 51014 string. 51015 RETURN VALUE 51016 Upon successful completion, wordexp( ) shall return 0. Otherwise, a non-zero value, as described 51017 in , shall be returned to indicate an error. If wordexp( ) returns the value 51018 WRDE_NOSPACE, then pwordexp->we_wordc and pwordexp->we_wordv shall be updated to 51019 reflect any words that were successfully expanded. In other cases, they shall not be modified. 51020 The wordfree( ) function shall not return a value. 51021 ERRORS 51022 No errors are defined. 51023 EXAMPLES 51024 None. 51025 APPLICATION USAGE 51026 The wordexp( ) function is intended to be used by an application that wants to do all of the shell's 51027 expansions on a word or words obtained from a user. For example, if the application prompts 51028 for a filename (or list of filenames) and then uses wordexp( ) to process the input, the user could 51029 respond with anything that would be valid as input to the shell. 51030 The WRDE_NOCMD flag is provided for applications that, for security or other reasons, want to 51031 prevent a user from executing shell commands. Disallowing unquoted shell special characters 51032 also prevents unwanted side effects, such as executing a command or writing a file. 51033 RATIONALE 51034 This function was included as an alternative to glob( ). There had been continuing controversy 51035 over exactly what features should be included in glob( ). It is hoped that by providing wordexp( ) 51036 (which provides all of the shell word expansions, but which may be slow to execute) and glob( ) | 51037 (which is faster, but which only performs pathname expansion, without tilde or parameter | 51038 expansion) this will satisfy the majority of applications. 51039 While wordexp( ) could be implemented entirely as a library routine, it is expected that most 51040 implementations run a shell in a subprocess to do the expansion. 51041 Two different approaches have been proposed for how the required information might be 51042 presented to the shell and the results returned. They are presented here as examples. 51043 One proposal is to extend the echo utility by adding a -q option. This option would cause echo to 51044 add a backslash before each backslash and that occurs within an argument. The 51045 wordexp( ) function could then invoke the shell as follows: 51046 (void) strcpy(buffer, "echo -q"); 51047 (void) strcat(buffer, words); 51048 if ((flags & WRDE_SHOWERR) == 0) 2154 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wordexp( ) 51049 (void) strcat(buffer, "2>/dev/null"); 51050 f = popen(buffer, "r"); 51051 The wordexp( ) function would read the resulting output, remove unquoted backslashes, and 51052 break into words at unquoted s. If the WRDE_NOCMD flag was set, wordexp( ) would 51053 have to scan words before starting the subshell to make sure that there would be no command 51054 substitution. In any case, it would have to scan words for unquoted special characters. 51055 Another proposal is to add the following options to sh: 51056 -w wordlist 51057 This option provides a wordlist expansion service to applications. The words in wordlist 51058 shall be expanded and the following written to standard output: 51059 1. The count of the number of words after expansion, in decimal, followed by a null byte 51060 2. The number of bytes needed to represent the expanded words (not including null 51061 separators), in decimal, followed by a null byte 51062 3. The expanded words, each terminated by a null byte 51063 If an error is encountered during word expansion, sh exits with a non-zero status after 51064 writing the former to report any words successfully expanded 51065 -P Run in ``protected'' mode. If specified with the -w option, no command substitution shall 51066 be performed. 51067 With these options, wordexp( ) could be implemented fairly simply by creating a subprocess 51068 using fork( ) and executing sh using the line: 51069 execl(, "sh", "-P", "-w", words, (char *)0); 51070 after directing standard error to /dev/null. 51071 It seemed objectionable for a library routine to write messages to standard error, unless 51072 explicitly requested, so wordexp( ) is required to redirect standard error to /dev/null to ensure 51073 that no messages are generated, even for commands executed for command substitution. The 51074 WRDE_SHOWERR flag can be specified to request that error messages be written. 51075 The WRDE_REUSE flag allows the implementation to avoid the expense of freeing and 51076 reallocating memory, if that is possible. A minimal implementation can call wordfree( ) when 51077 WRDE_REUSE is set. 51078 FUTURE DIRECTIONS 51079 None. 51080 SEE ALSO 51081 fnmatch( ), glob( ), the Base Definitions volume of IEEE Std 1003.1-200x, , the Shell 51082 and Utilities volume of IEEE Std 1003.1-200x 51083 CHANGE HISTORY 51084 First released in Issue 4. Derived from the ISO POSIX-2 standard. 51085 Issue 5 51086 Moved from POSIX2 C-language Binding to BASE. 51087 Issue 6 51088 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 51089 The restrict keyword is added to the wordexp( ) prototype for alignment with the 51090 ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2155 wprintf( ) System Interfaces 51091 NAME 51092 wprintf - print formatted wide-character output 51093 SYNOPSIS 51094 #include 51095 #include 51096 int wprintf(const wchar_t *restrict format, ...); | 51097 DESCRIPTION | 51098 Refer to fwprintf( ). 2156 Technical Standard (2001) (Draft April 16, 2001) System Interfaces write( ) 51099 NAME 51100 pwrite, write - write on a file | 51101 SYNOPSIS 51102 #include 51103 XSI ssize_t pwrite(int fildes, const void *buf, size_t nbyte, 51104 off_t offset); 51105 ssize_t write(int fildes, const void *buf, size_t nbyte); 51106 DESCRIPTION | 51107 The write( ) function shall attempt to write nbyte bytes from the buffer pointed to by buf to the 51108 file associated with the open file descriptor, fildes. 51109 Before any action described below is taken, and if nbyte is zero and the file is a regular file, the 51110 write( ) function may detect and return errors as described below. In the absence of errors, or if 51111 error detection is not performed, the write( ) function shall return zero and have no other results. 51112 If nbyte is zero and the file is not a regular file, the results are unspecified. 51113 On a regular file or other file capable of seeking, the actual writing of data shall proceed from the | 51114 position in the file indicated by the file offset associated with fildes. Before successful return | 51115 from write( ), the file offset shall be incremented by the number of bytes actually written. On a | 51116 regular file, if this incremented file offset is greater than the length of the file, the length of the 51117 file shall be set to this file offset. 51118 On a file not capable of seeking, writing shall always take place starting at the current position. | 51119 The value of a file offset associated with such a device is undefined. | 51120 If the O_APPEND flag of the file status flags is set, the file offset shall be set to the end of the file 51121 prior to each write and no intervening file modification operation shall occur between changing 51122 the file offset and the write operation. 51123 XSI If a write( ) requests that more bytes be written than there is room for (for example, the process' 51124 file size limit or the physical end of a medium), only as many bytes as there is room for shall be 51125 written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A 51126 write of 512 bytes will return 20. The next write of a non-zero number of bytes would give a 51127 failure return (except as noted below). 51128 XSI If the request would cause the file size to exceed the soft file size limit for the process and there | 51129 is no room for any bytes to be written, the request shall fail and the implementation shall | 51130 generate the SIGXFSZ signal for the thread. | 51131 If write( ) is interrupted by a signal before it writes any data, it shall return -1 with errno set to 51132 [EINTR]. 51133 If write( ) is interrupted by a signal after it successfully writes some data, it shall return the 51134 number of bytes written. 51135 If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-defined. 51136 After a write( ) to a regular file has successfully returned: 51137 * Any successful read( ) from each byte position in the file that was modified by that write shall 51138 return the data specified by the write( ) for that position until such byte positions are again 51139 modified. 51140 * Any subsequent successful write( ) to the same byte position in the file shall overwrite that 51141 file data. System Interfaces, Issue 6 2157 write( ) System Interfaces 51142 Write requests to a pipe or FIFO shall be handled in the same way as a regular file with the | 51143 following exceptions: | 51144 * There is no file offset associated with a pipe, hence each write request shall append to the 51145 end of the pipe. 51146 * Write requests of {PIPE_BUF} bytes or less shall not be interleaved with data from other 51147 processes doing writes on the same pipe. Writes of greater than {PIPE_BUF} bytes may have 51148 data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the 51149 O_NONBLOCK flag of the file status flags is set. 51150 * If the O_NONBLOCK flag is clear, a write request may cause the thread to block, but on 51151 normal completion it shall return nbyte. 51152 * If the O_NONBLOCK flag is set, write( ) requests shall be handled differently, in the 51153 following ways: 51154 - The write( ) function shall not block the thread. 51155 - A write request for {PIPE_BUF} or fewer bytes shall have the following effect: if there is 51156 sufficient space available in the pipe, write( ) shall transfer all the data and return the 51157 number of bytes requested. Otherwise, write( ) shall transfer no data and return -1 with 51158 errno set to [EAGAIN]. 51159 - A write request for more than {PIPE_BUF} bytes shall cause one of the following: 51160 - When at least one byte can be written, transfer what it can and return the number of 51161 bytes written. When all data previously written to the pipe is read, it shall transfer at 51162 least {PIPE_BUF} bytes. 51163 - When no data can be written, transfer no data, and return -1 with errno set to 51164 [EAGAIN]. 51165 When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non- 51166 blocking writes and cannot accept the data immediately: 51167 * If the O_NONBLOCK flag is clear, write( ) shall block the calling thread until the data can be 51168 accepted. 51169 * If the O_NONBLOCK flag is set, write( ) shall not block the thread. If some data can be 51170 written without blocking the thread, write( ) shall write what it can and return the number of 51171 bytes written. Otherwise, it shall return -1 and set errno to [EAGAIN]. 51172 Upon successful completion, where nbyte is greater than 0, write( ) shall mark for update the 51173 st_ctime and st_mtime fields of the file, and if the file is a regular file, the S_ISUID and S_ISGID 51174 bits of the file mode may be cleared. 51175 For regular files, no data transfer shall occur past the offset maximum established in the open 51176 file description associated with fildes. 51177 If fildes refers to a socket, write( ) shall be equivalent to send( ) with no flags set. 51178 SIO If the O_DSYNC bit has been set, write I/O operations on the file descriptor shall complete as | 51179 defined by synchronized I/O data integrity completion. | 51180 If the O_SYNC bit has been set, write I/O operations on the file descriptor shall complete as | 51181 defined by synchronized I/O file integrity completion. | 51182 SHM If fildes refers to a shared memory object, the result of the write( ) function is unspecified. 51183 TYM If fildes refers to a typed memory object, the result of the write( ) function is unspecified. 2158 Technical Standard (2001) (Draft April 16, 2001) System Interfaces write( ) 51184 XSR If fildes refers to a STREAM, the operation of write( ) shall be determined by the values of the 51185 minimum and maximum nbyte range (packet size) accepted by the STREAM. These values are 51186 determined by the topmost STREAM module. If nbyte falls within the packet size range, nbyte 51187 bytes shall be written. If nbyte does not fall within the range and the minimum packet size value 51188 is 0, write( ) shall break the buffer into maximum packet size segments prior to sending the data 51189 downstream (the last segment may contain less than the maximum packet size). If nbyte does not 51190 fall within the range and the minimum value is non-zero, write( ) shall fail with errno set to 51191 [ERANGE]. Writing a zero-length buffer (nbyte is 0) to a STREAMS device sends 0 bytes with 0 51192 returned. However, writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no 51193 message and 0 is returned. The process may issue I_SWROPT ioctl( ) to enable zero-length 51194 messages to be sent across the pipe or FIFO. 51195 When writing to a STREAM, data messages are created with a priority band of 0. When writing 51196 to a STREAM that is not a pipe or FIFO: 51197 * If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is 51198 full due to internal flow control conditions), write( ) shall block until data can be accepted. 51199 * If O_NONBLOCK is set and the STREAM cannot accept data, write( ) shall return -1 and set 51200 errno to [EAGAIN]. 51201 * If O_NONBLOCK is set and part of the buffer has been written while a condition in which 51202 the STREAM cannot accept additional data occurs, write( ) shall terminate and return the 51203 number of bytes written. 51204 In addition, write( ) shall fail if the STREAM head has processed an asynchronous error before | 51205 the call. In this case, the value of errno does not reflect the result of write( ), but reflects the prior | 51206 error. 51207 XSI The pwrite( ) function shall be equivalent to write( ), except that it writes into a given position | 51208 without changing the file pointer. The first three arguments to pwrite( ) are the same as write( ) 51209 with the addition of a fourth argument offset for the desired position inside the file. | 51210 RETURN VALUE 51211 XSI Upon successful completion, write( ) and pwrite( ) shall return the number of bytes actually 51212 written to the file associated with fildes. This number shall never be greater than nbyte. 51213 Otherwise, -1 shall be returned and errno set to indicate the error. | 51214 ERRORS 51215 XSI The write( ) andpwrite( )functions shall fail if: | 51216 [EAGAIN] The O_NONBLOCK flag is set for the file descriptor and the thread would be 51217 delayed in the write( ) operation. 51218 [EBADF] The fildes argument is not a valid file descriptor open for writing. 51219 [EFBIG] An attempt was made to write a file that exceeds the implementation-defined 51220 XSI maximum file size or the process' file size limit, and there was no room for | 51221 any bytes to be written. | 51222 [EFBIG] The file is a regular file, nbyte is greater than 0, and the starting position is 51223 greater than or equal to the offset maximum established in the open file 51224 description associated with fildes. 51225 [EINTR] The write operation was terminated due to the receipt of a signal, and no data 51226 was transferred. 51227 [EIO] The process is a member of a background process group attempting to write 51228 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor System Interfaces, Issue 6 2159 write( ) System Interfaces 51229 blocking SIGTTOU, and the process group of the process is orphaned. This 51230 error may also be returned under implementation-defined conditions. 51231 [ENOSPC] There was no free space remaining on the device containing the file. 51232 [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 51233 any process, or that only has one end open. A SIGPIPE signal shall also be sent 51234 to the thread. 51235 XSR [ERANGE] The transfer request size was outside the range supported by the STREAMS 51236 file associated with fildes. 51237 The write( ) function shall fail if: 51238 [EAGAIN] or [EWOULDBLOCK] 51239 The file descriptor is for a socket, is marked O_NONBLOCK, and write would 51240 block. 51241 [ECONNRESET] A write was attempted on a socket that is not connected. 51242 [EPIPE] A write was attempted on a socket that is shut down for writing, or is no 51243 longer connected. In the latter case, if the socket is of type SOCK_STREAM, 51244 the SIGPIPE signal is generated to the calling process. 51245 XSI The write( ) andpwrite( )functions may fail if: | 51246 XSR [EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or 51247 indirectly) downstream from a multiplexer. 51248 [EIO] A physical I/O error has occurred. 51249 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 51250 [ENXIO] A request was made of a nonexistent device, or the request was outside the 51251 capabilities of the device. 51252 XSR [ENXIO] A hangup occurred on the STREAM being written to. 51253 XSR A write to a STREAMS file may fail if an error message has been received at the STREAM head. 51254 In this case, errno is set to the value included in the error message. 51255 The write( ) function may fail if: 51256 [EACCES] A write was attempted on a socket and the calling process does not have 51257 appropriate privileges. 51258 [ENETDOWN] A write was attempted on a socket and the local network interface used to 51259 reach the destination is down. 51260 [ENETUNREACH] A write was attempted on a socket and no route to the network is present. 51261 XSI The pwrite( ) function shall fail and the file pointer remain unchanged if: | 51262 XSI [EINVAL] The offset argument is invalid. The value is negative. 51263 XSI [ESPIPE] fildes is associated with a pipe or FIFO. 2160 Technical Standard (2001) (Draft April 16, 2001) System Interfaces write( ) 51264 EXAMPLES 51265 Writing from a Buffer 51266 The following example writes data from the buffer pointed to by buf to the file associated with 51267 the file descriptor fd. 51268 #include 51269 #include 51270 ... 51271 char buf[20]; 51272 size_t nbytes; 51273 ssize_t bytes_written; 51274 int fd; 51275 ... 51276 strcpy(buf, "This is a test\n"); 51277 nbytes = strlen(buf); 51278 bytes_written = write(fd, buf, nbytes); 51279 ... 51280 APPLICATION USAGE | 51281 None. 51282 RATIONALE 51283 See also the RATIONALE section in read( ). 51284 An attempt to write to a pipe or FIFO has several major characteristics: 51285 * Atomic/non-atomic: A write is atomic if the whole amount written in one operation is not 51286 interleaved with data from any other process. This is useful when there are multiple writers 51287 sending data to a single reader. Applications need to know how large a write request can be 51288 expected to be performed atomically. This maximum is called {PIPE_BUF}. This volume of 51289 IEEE Std 1003.1-200x does not say whether write requests for more than {PIPE_BUF} bytes 51290 are atomic, but requires that writes of {PIPE_BUF} or fewer bytes shall be atomic. 51291 * Blocking/immediate: Blocking is only possible with O_NONBLOCK clear. If there is enough 51292 space for all the data requested to be written immediately, the implementation should do so. 51293 Otherwise, the process may block; that is, pause until enough space is available for writing. 51294 The effective size of a pipe or FIFO (the maximum amount that can be written in one 51295 operation without blocking) may vary dynamically, depending on the implementation, so it 51296 is not possible to specify a fixed value for it. 51297 * Complete/partial/deferred: A write request: 51298 int fildes; 51299 size_t nbyte; 51300 ssize_t ret; 51301 char *buf; 51302 ret = write(fildes, buf, nbyte); 51303 may return: 51304 complete ret=nbyte 51305 partial ret{PIPE_BUF}), this volume of IEEE Std 1003.1-200x does not guarantee System Interfaces, Issue 6 2161 write( ) System Interfaces 51308 atomicity, even if ret {PIPE_BUF}, because atomicity is guaranteed according 51309 to the amount requested, not the amount written. 51310 deferred: ret=-1, errno=[EAGAIN] 51311 This error indicates that a later request may succeed. It does not indicate that it 51312 shall succeed, even if nbyte {PIPE_BUF}, because if no process reads from the 51313 pipe or FIFO, the write never succeeds. An application could usefully count the 51314 number of times [EAGAIN] is caused by a particular value of 51315 nbyte>{PIPE_BUF} and perhaps do later writes with a smaller value, on the 51316 assumption that the effective size of the pipe may have decreased. 51317 Partial and deferred writes are only possible with O_NONBLOCK set. 51318 The relations of these properties are shown in the following tables: 51319 _______________________________________________________________________ 51320 _ Write to a Pipe or FIFO with O_NONBLOCK clear ______________________________________________________________________ 51321 _Immediately Writable: None Some nbyte ______________________________________________________________________ 51322 nbyte {PIPE_BUF} Atomic blocking Atomic blocking Atomic immediate 51323 _ nbyte nbyte nbyte ______________________________________________________________________ 51324 _ nbyte>{PIPE_BUF} Blocking nbyte Blocking nbyte Blocking nbyte ______________________________________________________________________ 51325 If the O_NONBLOCK flag is clear, a write request shall block if the amount writable 51326 immediately is less than that requested. If the flag is set (by fcntl( )), a write request shall never 51327 block. 51328 ______________________________________________________________ 51329 _ Write to a Pipe or FIFO with O_NONBLOCK set _____________________________________________________________ 51330 _Immediately Writable: None Some nbyte _____________________________________________________________ 51331 _ nbyte {PIPE_BUF} -1, [EAGAIN] -1, [EAGAIN] Atomic nbyte _____________________________________________________________ 51332 nbyte>{PIPE_BUF} -1, [EAGAIN] , , , 51381 CHANGE HISTORY 51382 First released in Issue 1. Derived from Issue 1 of the SVID. 51383 Issue 5 51384 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 51385 Threads Extension. 51386 Large File Summit extensions are added. 51387 The pwrite( ) function is added. 51388 Issue 6 51389 The DESCRIPTION states that the write( ) function does not block the thread. Previously this 51390 said ``process'' rather than ``thread''. 51391 The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are 51392 marked as part of the XSI STREAMS Option Group. 51393 The following new requirements on POSIX implementations derive from alignment with the 51394 Single UNIX Specification: System Interfaces, Issue 6 2163 write( ) System Interfaces 51395 * The DESCRIPTION now states that if write( ) is interrupted by a signal after it has 51396 successfully written some data, it returns the number of bytes written. In earlier versions of 51397 this volume of IEEE Std 1003.1-200x, it was optional whether write( ) returned the number of 51398 bytes written, or whether it returned -1 with errno set to [EINTR]. This is a FIPS requirement. 51399 * The following changes are made to support large files: 51400 - For regular files, no data transfer occurs past the offset maximum established in the open 51401 file description associated with the fildes. 51402 - A second [EFBIG] error condition is added. 51403 * The [EIO] error condition is added. 51404 * The [EPIPE] error condition is added for when a pipe has only one end open. 51405 * The [ENXIO] optional error condition is added. 51406 Text referring to sockets is added to the DESCRIPTION. 51407 The following changes were made to align with the IEEE P1003.1a draft standard: 51408 * The effect of reading zero bytes is clarified. 51409 The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by specifying that 51410 write( ) results are unspecified for typed memory objects. 51411 The following error conditions are added for operations on sockets: [EAGAIN], 51412 [EWOULDBLOCK], [ECONNRESET], [ENOTCONN], and [EPIPE]. 51413 The [EIO] error is changed to ``may fail''. 51414 The [ENOBUFS] error is added for sockets. 51415 The following error conditions are added for operations on sockets: [EACCES], [ENETDOWN], 51416 and [ENETUNREACH]. || 51417 The writev( ) function is split out into a separate reference page. | 2164 Technical Standard (2001) (Draft April 16, 2001) System Interfaces writev( ) 51418 NAME | 51419 writev - write a vector | 51420 SYNOPSIS | 51421 XSI #include | 51422 ssize_t writev(int fildes, const struct iovec *iov, int iovcnt); | 51423 | 51424 DESCRIPTION | 51425 The writev( ) function shall be equivalent to write( ), except as described below. The writev( ) | 51426 function shall gather output data from the iovcnt buffers specified by the members of the iov | 51427 array: iov[0], iov[1], . . ., iov[iovcnt-1]. The iovcnt argument is valid if greater than 0 and less than | 51428 or equal to {IOV_MAX}, defined in . | 51429 Each iovec entry specifies the base address and length of an area in memory from which data | 51430 should be written. The writev( ) function shall always write a complete area before proceeding to | 51431 the next. | 51432 If fildes refers to a regular file and all of the iov_len members in the array pointed to by iov are 0, | 51433 writev( ) shall return 0 and have no other effect. For other file types, the behavior is unspecified. | 51434 If the sum of the iov_len values is greater than {SSIZE_MAX}, the operation shall fail and no data | 51435 shall be transferred. | 51436 RETURN VALUE | 51437 Upon successful completion, writev( ) shall return the number of bytes actually written. | 51438 Otherwise, it shall return a value of -1, the file-pointer shall remain unchanged, and errno shall | 51439 be set to indicate an error. | 51440 ERRORS | 51441 Refer to write( ). | 51442 In addition, the writev( ) function shall fail if: | 51443 [EINVAL] The sum of the iov_len values in the iov array would overflow an ssize_t. | 51444 The writev( ) function may fail and set errno to: | 51445 [EINVAL] The iovcnt argument was less than or equal to 0, or greater than {IOV_MAX}. | 51446 EXAMPLES | 51447 Writing Data from an Array | 51448 The following example writes data from the buffers specified by members of the iov array to the | 51449 file associated with the file descriptor fd. | 51450 #include | 51451 #include | 51452 #include | 51453 ... | 51454 ssize_t bytes_written; | 51455 int fd; | 51456 char *buf0 = "short string\n"; | 51457 char *buf1 = "This is a longer string\n"; | 51458 char *buf2 = "This is the longest string in this example\n"; | 51459 int iovcnt; | 51460 struct iovec iov[3]; | System Interfaces, Issue 6 2165 writev( ) System Interfaces 51461 iov[0].iov_base = buf0; | 51462 iov[0].iov_len = strlen(buf0); | 51463 iov[1].iov_base = buf1; | 51464 iov[1].iov_len = strlen(buf1); | 51465 iov[2].iov_base = buf2; | 51466 iov[2].iov_len = strlen(buf2); | 51467 ... | 51468 iovcnt = sizeof(iov) / sizeof(struct iovec); | 51469 bytes_written = writev(fd, iov, iovcnt); | 51470 ... | 51471 APPLICATION USAGE | 51472 None. | 51473 RATIONALE | 51474 Refer to write( ). | 51475 FUTURE DIRECTIONS | 51476 None. | 51477 SEE ALSO | 51478 readv( ), write( ), the Base Definitions volume of IEEE Std 1003.1-200x, , | 51479 CHANGE HISTORY | 51480 First released in Issue 4, Version 2. | 51481 Issue 6 || 51482 Split out from the write( ) reference page. | 2166 Technical Standard (2001) (Draft April 16, 2001) System Interfaces wscanf( ) 51483 NAME 51484 wscanf - convert formatted wide-character input 51485 SYNOPSIS 51486 #include 51487 #include 51488 int wscanf(const wchar_t *restrict format, ... ); | 51489 DESCRIPTION | 51490 Refer to fwscanf( ). System Interfaces, Issue 6 2167 y0( ) System Interfaces 51491 NAME 51492 y0, y1, yn - Bessel functions of the second kind 51493 SYNOPSIS 51494 XSI #include 51495 double y0(double x); 51496 double y1(double x); 51497 double yn(int n, double x); 51498 51499 DESCRIPTION 51500 The y0( ), y1( ), and yn( ) functions shall compute Bessel functions of x of the second kind of 51501 orders 0, 1, and n, respectively. | 51502 An application wishing to check for error situations should set errno to zero and call 51503 feclearexcept(FE_ALL_EXCEPT) before calling these functions. On return, if errno is non-zero or 51504 fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non- 51505 zero, an error has occurred. 51506 RETURN VALUE 51507 Upon successful completion, these functions shall return the relevant Bessel value of x of the 51508 second kind. 51509 If x is NaN, NaN shall be returned. 51510 If the x argument to these functions is negative, -HUGE_VAL or NaN shall be returned, and a 51511 domain error may occur. 51512 If x is 0.0, -HUGE_VAL shall be returned and a range error may occur. 51513 If the correct result would cause underflow, 0.0 shall be returned and a range error may occur. 51514 If the correct result would cause overflow, -HUGE_VAL or 0.0 shall be returned and a range 51515 error may occur. 51516 ERRORS 51517 These functions may fail if: 51518 Domain Error The value of x is negative. 51519 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 51520 then errno shall be set to [EDOM]. If the integer expression (math_errhandling | 51521 & MATH_ERREXCEPT) is non-zero, then the invalid floating-point exception | 51522 shall be raised. | 51523 Range Error The value of x is 0.0, or the correct result would cause overflow. 51524 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 51525 then errno shall be set to [ERANGE]. If the integer expression | 51526 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the overflow | 51527 floating-point exception shall be raised. | 51528 Range Error The value of x is too large in magnitude, or the correct result would cause 51529 underflow. 51530 If the integer expression (math_errhandling & MATH_ERRNO) is non-zero, | 51531 then errno shall be set to [ERANGE]. If the integer expression | 51532 (math_errhandling & MATH_ERREXCEPT) is non-zero, then the underflow | 51533 floating-point exception shall be raised. | 2168 Technical Standard (2001) (Draft April 16, 2001) System Interfaces y0( ) 51534 EXAMPLES 51535 None. 51536 APPLICATION USAGE 51537 On error, the expressions (math_errhandling & MATH_ERRNO) and (math_errhandling & 51538 MATH_ERREXCEPT) are independent of each other, but at least one of them must be non-zero. 51539 RATIONALE 51540 None. 51541 FUTURE DIRECTIONS 51542 None. 51543 SEE ALSO 51544 feclearexcept( ), fetestexcept( ), isnan( ), j0( ), the Base Definitions volume of IEEE Std 1003.1-200x, | 51545 Section 4.18, Treatment of Error Conditions for Mathematical Functions, | 51546 CHANGE HISTORY 51547 First released in Issue 1. Derived from Issue 1 of the SVID. 51548 Issue 5 51549 The DESCRIPTION is updated to indicate how an application should check for an error. This 51550 text was previously published in the APPLICATION USAGE section. 51551 Issue 6 51552 The DESCRIPTION is updated to avoid use of the term ``must'' for application requirements. 51553 The RETURN VALUE and ERRORS sections are reworked for alignment of the error handling | 51554 with the ISO/IEC 9899: 1999 standard. System Interfaces, Issue 6 2169 System Interfaces 2170 Technical Standard (2001) (Draft April 16, 2001) 1 Index 2 _CS_PATH ...............................................................670 _PC_REC_XFER_ALIGN......................................856 3 _CS_XBS5_ILP32_OFF32_CFLAGS....................670 _PC_SYMLINK_MAX ...........................................856 4 _CS_XBS5_ILP32_OFF32_LDFLAGS.................670 _PC_SYNC_IO ........................................................856 5 _CS_XBS5_ILP32_OFF32_LIBS............................670 _PC_VDISABLE......................................................856 6 _CS_XBS5_ILP32_OFF32_LINTFLAGS.............670 _POSIX2 constants 7 _CS_XBS5_ILP32_OFFBIG_CFLAGS.................670 in sysconf ...........................................................1969 8 _CS_XBS5_ILP32_OFFBIG_LDFLAGS ..............670 _POSIX2_CHAR_TERM .....................................1971 9 _CS_XBS5_ILP32_OFFBIG_LIBS.........................670 _POSIX2_C_BIND................................................1971 10 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS..........670 _POSIX2_C_DEV..................................................1971 11 _CS_XBS5_LP64_OFF64_CFLAGS .....................670 _POSIX2_C_VERSION........................................1971 12 _CS_XBS5_LP64_OFF64_LDFLAGS ..................670 _POSIX2_FORT_DEV..........................................1971 13 _CS_XBS5_LP64_OFF64_LIBS.............................670 _POSIX2_FORT_RUN.........................................1971 14 _CS_XBS5_LP64_OFF64_LINTFLAGS ..............670 _POSIX2_LOCALEDEF.......................................1971 15 _CS_XBS5_LPBIG_OFFBIG_CFLAGS ...............670 _POSIX2_PBS ........................................................1971 16 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS.............670 _POSIX2_PBS_ACCOUNTING ........................1971 17 _CS_XBS5_LPBIG_OFFBIG_LIBS .......................670 _POSIX2_PBS_LOCATE......................................1971 18 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS ........670 _POSIX2_PBS_MESSAGE...................................1971 19 _exit ...........................................................................535 _POSIX2_PBS_TRACK........................................1971 20 _Exit...........................................................................764 _POSIX2_SW_DEV ..............................................1971 21 _exit.................................................................764, 2091 _POSIX2_UPE .......................................................1971 22 _Exit( ) .......................................................................535 _POSIX2_VERSION.............................................1971 23 _FILE_ .......................................................................581 _POSIX_....................................................................465 24 _IOFBF..........................................................1779, 1821 _POSIX_ADVISORY_INFO ...............................1970 25 _IOLBF............................................................833, 1821 _POSIX_ASYNCHRONOUS_IO ......................1970 26 _IONBF.........................................................1779, 1821 _POSIX_ASYNC_IO ..............................................856 27 _LINE_......................................................................581 _POSIX_BARRIERS .............................................1970 28 _longjmp( ) ...............................................................536 _POSIX_BASE .......................................................1970 29 _LVL ..........................................................................467 _POSIX_CHOWN_RESTRICTED......646, 856, 858 30 _MAX ........................................................................466 _POSIX_CLOCK_SELECTION .........................1970 31 _PC constants _POSIX_CPUTIME...............................................1970 32 used in pathconf .................................................856 _POSIX_C_LANG_SUPPORT...........................1970 33 _PC_ALLOC_SIZE_MIN......................................856 _POSIX_C_LANG_SUPPORT_R......................1970 34 _PC_ASYNC_IO.....................................................856 _POSIX_C_SOURCE..............................................464 35 _PC_CHOWN_RESTRICTED .............................856 _POSIX_DEVICE_IO ...........................................1970 36 _PC_FILESIZEBITS ................................................856 _POSIX_DEVICE_SPECIFIC..............................1970 37 _PC_LINK_MAX....................................................856 _POSIX_DEVICE_SPECIFIC_R.........................1970 38 _PC_MAX_CANON..............................................856 _POSIX_FD_MGMT ............................................1970 39 _PC_MAX_INPUT .................................................856 _POSIX_FIFO ........................................................1970 40 _PC_NAME_MAX .................................................856 _POSIX_FILE_ATTRIBUTES..............................1970 41 _PC_NO_TRUNC ..................................................856 _POSIX_FILE_LOCKING...................................1970 42 _PC_PATH_MAX ...................................................856 _POSIX_FILE_SYSTEM.......................................1970 43 _PC_PIPE_BUF .......................................................856 _POSIX_FSYNC....................................................1970 44 _PC_PRIO_IO..........................................................856 _POSIX_JOB_CONTROL ...................................1970 45 _PC_REC_INCR_XFER_SIZE..............................856 _POSIX_MAPPED_FILES...................................1970 46 _PC_REC_MAX_XFER_SIZE...............................856 _POSIX_MEMLOCK............................................1970 47 _PC_REC_MIN_XFER_SIZE................................856 _POSIX_MEMLOCK_RANGE ..........................1970 System Interfaces, Issue 6 2171 Index 48 _POSIX_MEMORY_PROTECTION.................1970 _POSIX_USER_GROUPS_R...............................1971 49 _POSIX_MESSAGE_PASSING..........................1970 _POSIX_V6_ILP32_OFF32..................................1971 50 _POSIX_MONOTONIC_CLOCK.....................1970 _POSIX_V6_ILP32_OFFBIG...............................1971 51 _POSIX_NETWORKING....................................1970 _POSIX_V6_LP64_OFF64...................................1971 52 _POSIX_NO_TRUNC............................................856 _POSIX_V6_LPBIG_OFFBIG .............................1971 53 _POSIX_OPEN_MAX..........................................1017 _POSIX_VDISABLE ...............................................856 54 _POSIX_PIPE.........................................................1970 _POSIX_VERSION.....................................1971, 2056 55 _POSIX_PRIORITIZED_IO........................492, 1970 _PROCESS................................................................467 56 _POSIX_PRIORITY_SCHEDULING .......492, 1970 _PTHREAD_THREADS_MAX..........................1557 57 _POSIX_PRIO_IO...................................................856 _REGEX_VERSION .............................................1971 58 _POSIX_READER_WRITER_LOCKS ..............1970 _SC constants 59 _POSIX_REALTIME_SIGNALS ........................1970 in sysconf ...........................................................1969 60 _POSIX_REGEXP .................................................1970 _SC_2_CHAR_TERM..........................................1971 61 _POSIX_SAVED_IDS...........................................1970 _SC_2_C_BIND.....................................................1971 62 _POSIX_SEMAPHORES.....................................1970 _SC_2_C_DEV.......................................................1971 63 _POSIX_SHARED_MEMORY_OBJECTS .......1970 _SC_2_C_VERSION.............................................1971 64 _POSIX_SHELL ....................................................1970 _SC_2_FORT_DEV...............................................1971 65 _POSIX_SIGNALS ...............................................1970 _SC_2_FORT_RUN..............................................1971 66 _POSIX_SINGLE_PROCESS..............................1970 _SC_2_LOCALEDEF ...........................................1971 67 _POSIX_SPAWN ..................................................1970 _SC_2_PBS_ACCOUNTING .............................1971 68 _POSIX_SPIN_LOCKS........................................1970 _SC_2_PBS_LOCATE ..........................................1971 69 _POSIX_SPORADIC_SERVER ..........................1970 _SC_2_PBS_MESSAGE .......................................1971 70 _POSIX_SYNCHRONIZED_IO ........................1970 _SC_2_PBS_TRACK.............................................1971 71 _POSIX_SYNC_IO .................................................856 _SC_2_SW_DEV ...................................................1971 72 _POSIX_SYSTEM_DATABASE .........................1970 _SC_2_UPE ............................................................1971 73 _POSIX_SYSTEM_DATABASE_R.....................1970 _SC_2_VERSION .......................................1342, 1971 74 _POSIX_THREADS...........................700, 1971, 2031 _SC_ADVISORY_INFO ......................................1970 75 _POSIX_THREAD_ATTR_STACKADDR.......1971 _SC_AIO_LISTIO_MAX .....................................1969 76 _POSIX_THREAD_ATTR_STACKSIZE ..........1971 _SC_AIO_MAX.....................................................1969 77 _POSIX_THREAD_CPUTIME...........................1971 _SC_AIO_PRIO_DELTA_MAX .........................1969 78 _POSIX_THREAD_PRIORITY_SCHEDULING .... _SC_ARG_MAX ...................................................1969 79 ..............................................................................1971 _SC_ASYNCHRONOUS_IO .............................1970 80 _POSIX_THREAD_PRIO_INHERIT................1971 _SC_ATEXIT_MAX..............................................1969 81 _POSIX_THREAD_PRIO_PROTECT ..............1971 _SC_BARRIERS ....................................................1970 82 _POSIX_THREAD_PROCESS_SHARED........1583 _SC_BASE ..............................................................1970 83 ..............................................................................1971 _SC_BC_BASE_MAX...........................................1969 84 _POSIX_THREAD_SAFE_FUNCTIONS...........700 _SC_BC_DIM_MAX.............................................1969 85 ...................................................................1971, 2031 _SC_BC_SCALE_MAX........................................1969 86 _POSIX_THREAD_SPORADIC_SERVER ......1971 _SC_BC_STRING_MAX .....................................1969 87 _POSIX_TIMEOUTS............................................1971 _SC_CHILD_MAX...............................................1969 88 _POSIX_TIMERS ..................................................1971 _SC_CLK_TCK...........................................1969, 2027 89 _POSIX_TRACE....................................................1971 _SC_CLOCK_SELECTION ................................1970 90 _POSIX_TRACE_EVENT_FILTER ...................1971 _SC_COLL_WEIGHTS_MAX............................1969 91 _POSIX_TRACE_EVENT_NAME_MAX ........1426 _SC_CPUTIME......................................................1970 92 ..............................................................................1428 _SC_C_LANG_SUPPORT..................................1970 93 _POSIX_TRACE_INHERIT................................1971 _SC_C_LANG_SUPPORT_R.............................1970 94 _POSIX_TRACE_LOG ........................................1971 _SC_DELAYTIMER_MAX..................................1969 95 _POSIX_TRACE_SYS_MAX ..............................1423 _SC_DEVICE_IO ..................................................1970 96 _POSIX_TRACE_USER_EVENT_MAX...........1428 _SC_DEVICE_SPECIFIC.....................................1970 97 _POSIX_TYPED_MEMORY_OBJECTS ...........1971 _SC_DEVICE_SPECIFIC_R................................1970 98 _POSIX_USER_GROUPS....................................1971 _SC_EXPR_NEST_MAX .....................................1969 2172 Technical Standard (2001) (Draft April 16, 2001) Index 99 _SC_FD_MGMT ...................................................1970 _SC_THREAD_ATTR_STACKADDR..............1971 100 _SC_FIFO ...............................................................1970 _SC_THREAD_ATTR_STACKSIZE .................1971 101 _SC_FILE_ATTRIBUTES.....................................1970 _SC_THREAD_CPUTIME..................................1971 102 _SC_FILE_LOCKING..........................................1970 _SC_THREAD_DESTRUCTOR_ITERATIONS...... 103 _SC_FILE_SYSTEM..............................................1970 ..............................................................................1972 104 _SC_FSYNC...........................................................1970 _SC_THREAD_KEYS_MAX ..............................1972 105 _SC_GETGR_R_SIZE_MAX..............964, 967, 1969 _SC_THREAD_PRIORITY_SCHEDULING...1971 106 _SC_GETPW_R_SIZE_MAX.........1009, 1012, 1969 _SC_THREAD_PRIO_INHERIT.......................1971 107 _SC_IOV_MAX.....................................................1969 _SC_THREAD_PRIO_PROTECT .....................1971 108 _SC_JOB_CONTROL ..........................................1970 _SC_THREAD_PROCESS_SHARED...............1971 109 _SC_LINE_MAX...................................................1969 _SC_THREAD_SAFE_FUNCTIONS ...............1971 110 _SC_LOGIN_NAME_MAX................................1969 _SC_THREAD_SPORADIC_SERVER .............1971 111 _SC_MEMLOCK...................................................1970 _SC_THREAD_STACK_MIN ............................1972 112 _SC_MEMLOCK_RANGE .................................1970 _SC_THREAD_THREADS_MAX.....................1972 113 _SC_MEMORY_PROTECTION........................1970 _SC_TIMEOUTS...................................................1971 114 _SC_MESSAGE_PASSING.................................1970 _SC_TIMERS .........................................................1971 115 _SC_MONOTONIC_CLOCK............................1970 _SC_TIMER_MAX ...............................................1972 116 _SC_MQ_OPEN_MAX........................................1969 _SC_TRACE...........................................................1971 117 _SC_MQ_PRIO_MAX .........................................1969 _SC_TRACE_EVENT_FILTER ..........................1971 118 _SC_NETWORKING...........................................1970 _SC_TRACE_INHERIT.......................................1971 119 _SC_NGROUPS_MAX........................................1969 _SC_TRACE_LOG ...............................................1971 120 _SC_OPEN_MAX.................................................1969 _SC_TTY_NAME_MAX .....................................1972 121 _SC_PAGESIZE................................1253, 1348, 1971 _SC_TYPED_MEMORY_OBJECTS ..................1971 122 _SC_PAGE_SIZE........................................1253, 1971 _SC_TZNAME_MAX ..........................................1972 123 _SC_PIPE................................................................1970 _SC_USER_GROUPS...........................................1971 124 _SC_PRIORITIZED_IO .......................................1970 _SC_USER_GROUPS_R......................................1971 125 _SC_PRIORITY_SCHEDULING.......................1970 _SC_V6_ILP32_OFF32.........................................1971 126 _SC_READER_WRITER_LOCKS .....................1970 _SC_V6_ILP32_OFFBIG......................................1971 127 _SC_REALTIME_SIGNALS ...............................1970 _SC_V6_LP64_OFF64..........................................1971 128 _SC_REGEXP ........................................................1970 _SC_V6_LPBIG_OFFBIG ....................................1971 129 _SC_REGEX_VERSION......................................1971 _SC_VERSION......................................................1971 130 _SC_RE_DUP_MAX ............................................1972 _SC_XBS5_ILP32_OFF32 ....................................1972 131 _SC_RTSIG_MAX ................................................1972 _SC_XBS5_ILP32_OFFBIG .................................1972 132 _SC_SAVED_IDS..................................................1970 _SC_XBS5_LP64_OFF64......................................1972 133 _SC_SEMAPHORES............................................1970 _SC_XBS5_LPBIG_OFFBIG................................1972 134 _SC_SEM_NSEMS_MAX....................................1972 _SC_XOPEN_CRYPT ..........................................1972 135 _SC_SEM_VALUE_MAX....................................1972 _SC_XOPEN_ENH_I18N ...................................1972 136 _SC_SHARED_MEMORY_OBJECTS ..............1970 _SC_XOPEN_LEGACY.......................................1972 137 _SC_SHELL ...........................................................1970 _SC_XOPEN_REALTIME...................................1972 138 _SC_SIGNALS ......................................................1970 _SC_XOPEN_REALTIME_THREADS.............1972 139 _SC_SIGQUEUE_MAX .......................................1972 _SC_XOPEN_SHM ..............................................1972 140 _SC_SINGLE_PROCESS.....................................1970 _SC_XOPEN_UNIX.............................................1972 141 _SC_SPAWN .........................................................1970 _SC_XOPEN_VERSION .....................................1972 142 _SC_SPIN_LOCKS...............................................1970 _SC_XOPEN_XCU_VERSION ..........................1972 143 _SC_SPORADIC_SERVER .................................1970 _setjmp......................................................................536 144 _SC_STREAM_MAX ...........................................1972 _setjmp( ) ..................................................................538 145 _SC_SYMLOOP_MAX ........................................1972 _TIME........................................................................467 146 _SC_SYNCHRONIZED_IO ...............................1970 _tolower( ) ................................................................539 147 _SC_SYSTEM_DATABASE ................................1970 _toupper( )................................................................540 148 _SC_SYSTEM_DATABASE_R............................1970 _XBS5_ILP32_OFF32 ...........................................1972 149 _SC_THREADS.....................................................1971 _XBS5_ILP32_OFFBIG.........................................1972 System Interfaces, Issue 6 2173 Index 150 _XBS5_LP64_OFF64.............................................1972 aio_read( ).................................................................561 151 _XBS5_LPBIG_OFFBIG.......................................1972 aio_return( ) .............................................................564 152 _XOPEN_CRYPT..................................................1972 aio_suspend( ) .........................................................565 153 _XOPEN_ENH_I18N...........................................1972 aio_write( ) ...............................................................567 154 _XOPEN_LEGACY..............................................1972 alarm( )......................................................................570 155 _XOPEN_REALTIME..................................794, 1972 anycast ......................................................................517 156 _XOPEN_REALTIME_THREADS....................1972 ANYMARK............................................................1087 157 _XOPEN_SHM......................................................1972 appropriate privileges...................................548, 857 158 _XOPEN_SOURCE ................................................464 argc ............................................................................760 159 _XOPEN_UNIX ....................................................1972 ARG_MAX............................472, 755, 758, 761, 1969 160 _XOPEN_VERSION.............................................1972 asctime( )...................................................................572 161 _XOPEN_XCU_VERSION .................................1972 asctime_r ..................................................................572 162 a64l( ) .........................................................................541 asin( ) .........................................................................574 163 ABDAY_1 ...............................................................1312 asinf ...........................................................................574 164 abort( ).......................................................................543 asinf( )........................................................................576 165 abs( ) ..........................................................................544 asinfh.........................................................................578 166 accept( ).....................................................................545 asinfh( ) .....................................................................577 167 access( ) .....................................................................547 asinfl ..................................................................577-578 168 acos( ).........................................................................550 asinh( ).......................................................................578 169 acosf...........................................................................550 asinl ...........................................................................574 170 acosf( ) .......................................................................552 asinl( )........................................................................580 171 acosh( ) ......................................................................553 assert( )......................................................................581 172 acoshf ........................................................................553 async-signal-safe ..................................................1468 173 acoshl ........................................................................553 atan( ).........................................................................582 174 acosl...........................................................................550 atan2( ).......................................................................584 175 acosl( ) .......................................................................555 atan2f.........................................................................584 176 ACTION.................................................................1047 atan2l.........................................................................584 177 address information...............................................883 atanf...........................................................................582 178 address string ..........................................................883 atanf( ) .......................................................................586 179 addrinfo structure ..................................................883 atanh( ) ......................................................................587 180 ADV...........................................................................453 atanhf ........................................................................587 181 ADVANCED REALTIME.........652, 656, 1277-1278 atanhl.........................................................................587 182 ...............1344, 1346, 1348, 1350, 1352, 1355, 1363 atanl...........................................................................582 183 ................1366, 1368-1371, 1373, 1375, 1377, 1379 atanl( ) .......................................................................589 184 ................1381, 1383, 1385-1392, 1453, 1455, 1534 atexit( ) ......................................................................590 185 ...................................................................1579, 1753 ATEXIT_MAX...............................................590, 1969 186 ADVANCED REALTIME THREADS 1500, 1502-1503 atof( ) .........................................................................591 187 ......1505, 1507, 1509-1510, 1551, 1633, 1635-1636 atoi( )..........................................................................592 188 ....................................................................1638-1639 atol( )..........................................................................594 189 AF_.............................................................................468 atoll............................................................................594 190 AIO ............................................................................453 attributes, clock-resolution ........................526, 1395 191 AIO_ ..........................................................................466 attributes, creation-time .............................526, 1395 192 AIO_ALLDONE .....................................................556 attributes, generation-version ...................525, 1395 193 aio_cancel( ) .............................................................556 attributes, inheritance .................................526, 1399 194 AIO_CANCELED...................................................556 attributes, log-full-policy.........524, 526, 1399, 1403 195 aio_error( )................................................................558 attributes, log-max-size....................526, 1400, 1403 196 aio_fsync( ) ...............................................................559 attributes, max-data-size ..................526, 1403-1404 197 AIO_LISTIO_MAX ....................................1163, 1969 attributes, stream-full-policy.....522-523, 526, 1400 198 AIO_MAX....................................................1163, 1969 attributes, stream-min-size ........................526, 1404 199 AIO_NOTCANCELED .........................................556 attributes, trace-name .................................526, 1395 200 AIO_PRIO_DELTA_MAX ..........................492, 1969 attributes, truncation-status...............................1426 2174 Technical Standard (2001) (Draft April 16, 2001) Index 201 background............................................................1799 carg( ).........................................................................614 202 background process.............................................2002 cargf...........................................................................614 203 BAR............................................................................453 cargl...........................................................................614 204 basename( ) ..............................................................595 casin( ) .......................................................................615 205 baud rate functions ................................................636 casinf .........................................................................615 206 bcmp( ) ......................................................................597 casinf( )......................................................................616 207 bcopy( ) .....................................................................598 casinh( ).....................................................................617 208 BC_ constants casinhf.......................................................................617 209 in sysconf ...........................................................1969 casinhl .......................................................................617 210 BC_BASE_MAX....................................................1969 casinl..........................................................................615 211 BC_DIM_MAX......................................................1969 casinl( )......................................................................618 212 BC_SCALE_MAX.................................................1969 catan( ).......................................................................619 213 BC_STRING_MAX...............................................1969 catanf.........................................................................619 214 BE ...............................................................................454 catanf( ) .....................................................................620 215 bind( ) ........................................................................599 catanh( ) ....................................................................621 216 BOOT_TIME ....................................................742-743 catanhf ......................................................................621 217 broadcasting a condition ....................................1519 catanhl.......................................................................621 218 BSD...................................570, 647, 767, 791, 800, 858 catanl.........................................................................619 219 ..................998, 1145, 1233, 1300, 1670, 1710, 1718 catanl( )......................................................................622 220 ...............1799, 1842, 1868, 1994, 2017, 2056, 2091 catclose( )..................................................................623 221 bsd_signal( ).............................................................601 catgets( )....................................................................624 222 bsearch( )...................................................................603 catopen( )..................................................................626 223 btowc( ) .....................................................................605 cbrt( ) .........................................................................628 224 buffer cache..............................................................909 cbrtf............................................................................628 225 BUFSIZ....................................................................1779 cbrtl............................................................................628 226 BUS_ ..........................................................................468 ccos( ).........................................................................629 227 byte-oriented stream..............................................486 ccosf...........................................................................629 228 byte-stream mode.................................................1667 ccosf( ) .......................................................................630 229 bzero( ) ......................................................................606 ccosh( ) ......................................................................631 230 cabs( ).........................................................................607 ccoshf ........................................................................631 231 cabsf...........................................................................607 ccoshl.........................................................................631 232 cabsl...........................................................................607 ccosl...........................................................................629 233 cacos( ).......................................................................608 ccosl( )........................................................................632 234 cacosf.........................................................................608 CD..............................................................................454 235 cacosf( ) .....................................................................609 ceil( ) ..........................................................................633 236 cacosh( ) ....................................................................610 ceilf ............................................................................633 237 cacoshf ......................................................................610 ceill.............................................................................633 238 cacoshl.......................................................................610 cexp( )........................................................................635 239 cacosl.........................................................................608 cexpf ..........................................................................635 240 cacosl( ) .....................................................................611 cexpl ..........................................................................635 241 calloc( )......................................................................612 cfgetispeed( )............................................................636 242 can..............................................................................451 cfgetospeed( )...........................................................638 243 cancel-safe..............................................................1625 cfsetispeed( ) ............................................................639 244 cancelability state.......................................1558, 1625 cfsetospeed( )...........................................................640 245 cancelability states .................................................504 change current working directory ......................642 246 cancelability type .......................................1558, 1625 change file modes...................................................645 247 cancelation cleanup handler ..............................1516 change owner and group of file...........................647 248 .........................................................1528, 1547, 1562 CHAR_MAX ...............................................1173, 1175 249 cancelation points...................................................505 chdir( ).......................................................................641 250 canceling execution of a thread.........................1511 CHILD_MAX ................................................852, 1969 251 canonical name .......................................................884 chmod( )....................................................................643 System Interfaces, Issue 6 2175 Index 252 chown( ) ....................................................................646 conversion specifier 253 cimag( ) .....................................................................649 modified.............................................................1937 254 cimagf........................................................................649 copysign( )................................................................677 255 cimagl........................................................................649 copysignf..................................................................677 256 CLD_ .........................................................................468 copysignl ..................................................................677 257 clearerr( )...................................................................650 core ..........................................................................2092 258 clock tick..............................................570, 1973, 2027 core file......................................................................766 259 clock ticks/second................................................1969 cos( )...........................................................................678 260 clock( ).......................................................................651 cosf.............................................................................678 261 clock-resolution attribute ...........................526, 1395 cosf( ) .........................................................................680 262 CLOCKS_PER_SEC ...............................................651 cosh( ) ........................................................................681 263 CLOCK_ ...................................................................467 coshf ..........................................................................681 264 clock_getcpuclockid( )...........................................652 coshl...........................................................................681 265 clock_getres( )..........................................................653 cosl.............................................................................678 266 clock_gettime ..........................................................653 cosl( ) .........................................................................683 267 CLOCK_MONOTONIC ...............................499, 657 covert channel.......................................................1145 268 clock_nanosleep( ) ..................................................656 cpow( ) ......................................................................684 269 CLOCK_PROCESS_CPUTIME_ID.....................500 cpowf.........................................................................684 270 CLOCK_REALTIME..............................499, 653, 657 cpowl.........................................................................684 271 ...............................................1300, 1579, 1753, 2019 cproj( ) .......................................................................685 272 clock_settime...........................................................653 cprojf .........................................................................685 273 clock_settime( ) .......................................................659 cprojl..........................................................................685 274 CLOCK_THREAD_CPUTIME_ID......................500 CPT ............................................................................454 275 clog( ).........................................................................660 creal( )........................................................................686 276 clogf...........................................................................660 crealf..........................................................................686 277 clogl ...........................................................................660 creall ..........................................................................686 278 close a file.................................................................663 creat( )........................................................................687 279 close( ) .......................................................................661 create a per-process timer...................................2020 280 closedir( ) ..................................................................664 create an interprocess channel...........................1335 281 closelog( )..................................................................666 create session and set process group ID..........1811 282 CMSG_......................................................................468 creation-time attribute ................................526, 1395 283 COLL_WEIGHTS_MAX.....................................1969 CRYPT....................................................689, 728, 1792 284 command interpreter crypt( ).......................................................................689 285 portable ..............................................................2091 CS...............................................................................454 286 compare thread IDs..............................................1546 csin( ) .........................................................................691 287 compilation environment .....................................463 csinf ...........................................................................691 288 condition variable initialization attributes .....1532 csinf( )........................................................................692 289 conforming application.......................................1886 csinh( ).......................................................................693 290 conforming application, strictly..................570, 760 csinhf.........................................................................693 291 confstr( )....................................................................670 csinhl .........................................................................693 292 conj( ).........................................................................673 csinl............................................................................691 293 conjf ...........................................................................673 csinl( ) ........................................................................694 294 conjl ...........................................................................673 csqrt( )........................................................................695 295 connect( ) ..................................................................674 csqrtf..........................................................................695 296 control data..............................................................488 csqrtl..........................................................................695 297 control-normal ......................................................1667 ctan( ).........................................................................696 298 conversion descriptor................755, 760, 1056-1059 ctanf...........................................................................696 299 conversion specification...............861, 892, 925, 934 ctanf( ) .......................................................................697 300 .........................................................1919, 1924, 1936 ctanh( ) ......................................................................698 301 modified.............................................................1926 ctanhf.........................................................................698 302 ctanhl.........................................................................698 2176 Technical Standard (2001) (Draft April 16, 2001) Index 303 ctanl ...........................................................................696 dup2...........................................................................723 304 ctanl( )........................................................................699 dynamic package initialization .........................1600 305 ctermid( ) ..................................................................700 E2BIG ........................................................................472 306 ctime( ) ......................................................................702 EACCES....................................................................472 307 ctime_r ......................................................................702 EADDRINUSE ........................................................472 308 CX ..............................................................................454 EADDRNOTAVAIL................................................472 309 data key creation ..................................................1562 EAFNOSUPPORT ..................................................472 310 data messages..........................................................488 EAGAIN...........................................................472, 478 311 data type...................................................................530 EALREADY .............................................................472 312 DATEMSK................................................................952 EBADF ......................................................................472 313 daylight ..........................................................704, 2048 EBADMSG ...............................................................472 314 DBL_MANT_DIG ..........................................633, 834 EBUSY.......................................................................473 315 DBL_MAX_EXP..............................................633, 834 ECANCELED ..........................................................473 316 DBM...................................................................705-706 ECHILD....................................................................473 317 DBM_ ........................................................................468 ECONNABORTED ................................................473 318 dbm_clearerr( )........................................................705 ECONNREFUSED..................................................473 319 dbm_close ................................................................705 ECONNRESET........................................................473 320 dbm_delete ..............................................................705 ecvt( ).........................................................................726 321 dbm_error ................................................................705 EDEADLK................................................................473 322 dbm_fetch ................................................................705 EDESTADDRREQ ..................................................473 323 dbm_firstkey............................................................705 EDOM .......................................................................473 324 DBM_INSERT .........................................................705 EDQUOT ..................................................................473 325 dbm_nextkey...........................................................705 EEXIST ......................................................................473 326 dbm_open ................................................................705 EFAULT ....................................................................473 327 DBM_REPLACE .....................................................705 EFBIG ........................................................................473 328 dbm_store ................................................................705 effective group ID..................................647, 761, 970 329 DEAD_PROCESS............................................742-743 effective user ID ...................................548, 761, 1145 330 deferred cancelability ..........................................1558 EHOSTUNREACH ................................................473 331 delay process execution ......................................1885 EIDRM ......................................................................473 332 DELAYTIMER_MAX...........................................1969 Eighth Edition UNIX ...........................................2162 333 dependency ordering.............................................717 EILSEQ .............................................................474, 488 334 descriptive name ....................................................883 EINPROGRESS...............................................474, 492 335 destroying a mutex ..............................................1568 EINTR.....................................................474, 507, 1420 336 destroying condition variables..........................1523 EINVAL................................................474, 1404, 1420 337 destructor functions.............................................1562 EIO.............................................................................474 338 detaching a thread................................................1544 EISCONN.................................................................474 339 difftime( )..................................................................708 EISDIR.......................................................................474 340 DIR......530, 664, 1324, 1673, 1675, 1713, 1740, 2010 ELOOP......................................................................474 341 directive.................................861, 892, 925, 934, 1936 ELSIZE ....................................................................1203 342 directory operations.............................................1325 EMFILE.....................................................................474 343 dirent structure .....................................................1325 EMLINK ...................................................................474 344 dirname( ) .................................................................709 EMPTY......................................................................743 345 div( )...........................................................................711 EMSGSIZE ...............................................................474 346 dlclose( )....................................................................712 EMULTIHOP...........................................................474 347 dlerror( )....................................................................714 ENAMETOOLONG...............................................475 348 dlopen( )....................................................................716 encrypt( )...................................................................728 349 dlsym( ) .....................................................................719 endgrent( )................................................................730 350 dot .................................................................1325, 1710 endhostent( )............................................................732 351 dot-dot..........................................................1325, 1710 endnetent( ) ..............................................................734 352 drand48( ) .................................................................721 endprotoent( )..........................................................736 353 dup( ) .........................................................................723 endpwent( )..............................................................738 System Interfaces, Issue 6 2177 Index 354 endservent( ) ............................................................740 additional.............................................................478 355 endutxent( )..............................................................742 ESPIPE.......................................................................477 356 ENETDOWN...........................................................475 ESRCH ......................................................................477 357 ENETRESET ............................................................475 establishing cancelation handlers.....................1516 358 ENETUNREACH ...................................................475 ESTALE.....................................................................477 359 ENFILE .....................................................................475 ETIME .......................................................................477 360 ENOBUFS.................................................................475 ETIMEDOUT...........................................................477 361 ENODATA ...............................................................475 ETXTBSY ..................................................................477 362 ENODEV ..................................................................475 EWOULDBLOCK...................................................477 363 ENOENT ..................................................................475 examine and change blocked signals...............1632 364 ENOEXEC ................................................................475 examine and change signal action....................1842 365 ENOLCK ..................................................................475 EXDEV ......................................................................478 366 ENOLINK ................................................................475 exec ............................................................................754 367 ENOMEM.................................................................475 of shell scripts .....................................................760 368 ENOMSG..................................................................475 exec family..............................548, 663, 790, 831, 854 369 ENOPROTOOPT....................................................475 .........................................................1468, 1800, 2091 370 ENOSPC ...................................................................476 execl...........................................................................754 371 ENOSR......................................................................476 execle.........................................................................754 372 ENOSTR ...................................................................476 execlp ........................................................................754 373 ENOSYS....................................................................476 execute a file ............................................................760 374 ENOTCONN...........................................................476 execution time monitoring ...................................500 375 ENOTDIR.................................................................476 execv..........................................................................754 376 ENOTEMPTY..........................................................476 execve........................................................................754 377 ENOTSOCK.............................................................476 execvp .......................................................................754 378 ENOTSUP ................................................................476 exit( )..........................................................................764 379 ENOTTY...................................................................476 EXIT_FAILURE.......................................................764 380 ENTRY....................................................................1047 EXIT_SUCCESS ..............................................764, 767 381 environ..............................................................745, 760 exp( )..........................................................................769 382 envp...........................................................................760 exp2( )........................................................................771 383 ENXIO.......................................................................476 exp2f..........................................................................771 384 EOPNOTSUPP........................................................476 exp2l ..........................................................................771 385 EOVERFLOW..........................................................476 expf............................................................................769 386 EPERM......................................................................476 expl ............................................................................769 387 EPIPE.........................................................................476 expm1( ) ....................................................................773 388 EPROTO ...................................................................477 expm1f ......................................................................773 389 EPROTONOSUPPORT .........................................477 expm1l ......................................................................773 390 EPROTOTYPE.........................................................477 EXPR_NEST_MAX...............................................1969 391 erand48 .....................................................................721 extension 392 erand48( )..................................................................746 CX ..........................................................................454 393 ERANGE ..................................................................477 OH .........................................................................456 394 erf( )............................................................................747 XSI..........................................................................460 395 erfc( )..........................................................................749 extensions to setlocale.........................................1794 396 erfcf............................................................................749 fabs( ).........................................................................775 397 erfcl............................................................................749 fabsf ...........................................................................775 398 erff..............................................................................747 fabsl ...........................................................................775 399 erff( ) ..........................................................................751 fattach( )....................................................................776 400 erfl......................................................................747, 751 fchdir( )......................................................................779 401 EROFS.......................................................................477 fchmod( ) ..................................................................780 402 errno ..........................................................................752 fchown( )...................................................................782 403 error descriptions ...................................................940 fclose( )......................................................................784 404 error numbers..........................................................471 fcntl( ) ........................................................................786 2178 Technical Standard (2001) (Draft April 16, 2001) Index 405 fcvt.............................................................................726 file 406 fcvt( )..........................................................................793 locking ..................................................................789 407 FD...............................................................................454 file accessibility.......................................................548 408 fdatasync( )...............................................................794 file control ................................................................789 409 fdetach( )...................................................................795 FILE object................................................................484 410 fdim( )........................................................................797 file permission bits .................................................548 411 fdimf..........................................................................797 file permissions ....................................548, 858, 1901 412 fdiml ..........................................................................797 file position indicator.............................................484 413 fdopen( )....................................................................799 fileno( ) ......................................................................831 414 FD_CLOEXEC......................485, 626, 755, 786, 1059 FILESIZEBITS..........................................................856 415 ..........................1317, 1325, 1335, 1356, 1363, 1823 FIND........................................................................1047 416 FD_CLR ..................................................................1463 find string token ...................................................1950 417 FD_CLR( ).................................................................534 flockfile( )..................................................................832 418 FD_ISSET .......................................................534, 1463 floor( )........................................................................834 419 FD_SET...........................................................534, 1463 floorf..........................................................................834 420 FD_ZERO.......................................................534, 1463 floorl ..........................................................................834 421 feature test macro...........................................463, 945 FLT_RADIX ...........................................................1192 422 _POSIX_C_SOURCE .........................................464 FLT_ROUNDS.........................................................836 423 _XOPEN_SOURCE ............................................464 FLUSH ......................................................................468 424 feclearexcept( ) ........................................................801 FLUSHR..................................................................1081 425 fegetenv( ).................................................................802 FLUSHRW .............................................................1081 426 fegetexceptflag( ).....................................................803 FLUSHW ................................................................1081 427 fegetround( ) ............................................................804 fma( ) .........................................................................836 428 feholdexcept( ).........................................................806 fmaf............................................................................836 429 feof( )..........................................................................807 fmal............................................................................836 430 feraiseexcept( ).........................................................808 fmax( ) .......................................................................838 431 ferror( ) ......................................................................809 fmaxf .........................................................................838 432 fesetenv.....................................................................802 fmaxl..........................................................................838 433 fesetenv( ) .................................................................810 fmin( )........................................................................839 434 fesetexceptflag.........................................................803 fminf..........................................................................839 435 fesetexceptflag( ).....................................................811 fminl ..........................................................................839 436 fesetround ................................................................804 FMNAMESZ..........................................................1080 437 fesetround( ).............................................................812 fmod( ).......................................................................840 438 fetestexcept( )...........................................................813 fmodf.........................................................................840 439 feupdateenv( ) .........................................................815 fmodl.........................................................................840 440 fflush( )......................................................................817 fmtmsg( ) ..................................................................842 441 ffs( )............................................................................820 fnmatch( ) .................................................................845 442 fgetc( )........................................................................821 FNM_ ........................................................................468 443 fgetpos( )...................................................................823 FNM_NOESCAPE..................................................845 444 fgets( )........................................................................825 FNM_NOMATCH..................................................845 445 fgetwc( ) ....................................................................827 FNM_PATHNAME................................................845 446 fgetws( ) ....................................................................829 FNM_PERIOD.........................................................845 447 FIFO ..........................................1235-1236, 1321, 2161 fopen( )......................................................................847 448 FILE..................................530, 650, 784, 799, 807, 809 FOPEN_MAX.............................799, 848, 1341, 2029 449 ......................817, 821, 823, 825, 827, 829, 831-832 foreground .............................................................1799 450 ......................847, 861, 873, 875, 877, 879-880, 887 fork handler ...........................................................1469 451 ......................892, 899, 902, 911, 923-925, 932, 934 fork( ).........................................................................851 452 .....................943-944, 1036, 1331, 1341, 1642-1643 forkall........................................................................854 453 ..........................1656, 1712, 1779, 1821, 1904, 2029 format of entries......................................................461 454 ................2058-2059, 2076, 2078, 2080, 2082, 2084 fpathconf( )...............................................................856 455 ..............................................................................2086 fpclassify( )...............................................................860 System Interfaces, Issue 6 2179 Index 456 FPE_...........................................................................468 fwrite( )......................................................................932 457 fprintf( ).....................................................................861 fwscanf( ) ..................................................................934 458 fputc( ).......................................................................873 F_DUPFD.........................................723, 786, 788-789 459 fputs( ).......................................................................875 F_GETFD..................................................786, 788-789 460 fputwc( ) ...................................................................877 F_GETFL...................................................786, 788-789 461 fputws( )....................................................................879 F_GETLK ..........................................................787-789 462 FQDN........................................................................986 F_GETOWN ....................................................786, 788 463 FR...............................................................................454 F_LOCK..................................................................1181 464 fread( ).......................................................................880 F_RDLCK .................................................................789 465 free( )..........................................................................882 F_SETFD...................................................786, 788-790 466 freeaddrinfo( )..........................................................883 F_SETFL....................................................786, 788-789 467 freopen( ) ..................................................................887 F_SETLK ...........................................................787-789 468 frexp( ).......................................................................890 F_SETLKW...............................................505, 787-789 469 frexpf.........................................................................890 F_SETOWN .....................................................786, 789 470 frexpl .........................................................................890 F_TEST....................................................................1181 471 FSC.............................................................................455 F_TLOCK ...............................................................1181 472 fscanf( )......................................................................892 F_ULOCK...............................................................1181 473 fseek( ) .......................................................................899 F_UNLCK.................................................................787 474 fseeko ........................................................................899 F_WRLCK ................................................................789 475 fsetpos( ) ...................................................................902 gai_strerror( )...........................................................940 476 fstat( ).........................................................................904 gcvt ............................................................................726 477 fstatvfs( )...................................................................906 gcvt( ).........................................................................941 478 fsync( ).......................................................................909 generation-version attribute......................525, 1395 479 ftell( ) .........................................................................911 get configurable path name variables................858 480 ftello...........................................................................911 get configurable system variables ....................1973 481 ftime( ).......................................................................913 get file status..........................................................1901 482 ftok( ) .........................................................................915 get process times ..................................................2027 483 ftruncate( )................................................................917 get supplementary group IDs..............................969 484 ftrylockfile................................................................832 get system time.....................................................2017 485 ftrylockfile( ) ............................................................919 get thread ID..........................................................1623 486 FTW.......................................................468, 1307-1308 get user name ..........................................................980 487 ftw( ) ..........................................................................920 getaddrinfo ..............................................................883 488 FTW_CHDIR.........................................................1307 getaddrinfo( )...........................................................942 489 FTW_D ...........................................................920, 1307 GETALL..................................................................1760 490 FTW_DEPTH.........................................................1307 getc( ).........................................................................943 491 FTW_DNR ...........................................920, 1307-1308 getchar( )...................................................................946 492 FTW_DP .................................................................1307 getchar_unlocked ...................................................944 493 FTW_F ............................................................920, 1307 getchar_unlocked( )................................................947 494 FTW_MOUNT ......................................................1307 getcontext( ) .............................................................948 495 FTW_NS...............................................920, 1307-1308 getcwd( )...................................................................950 496 FTW_PHYS............................................................1307 getc_unlocked( )......................................................944 497 FTW_SL..........................................................920, 1307 getdate( )...................................................................952 498 FTW_SLN...............................................................1307 getdate_err ...............................................................952 499 fully-qualified domain name ...............................986 getegid( )...................................................................957 500 functions...................................................................463 getenv........................................................................760 501 implementation ..................................................463 getenv( ) ....................................................................958 502 use..........................................................................463 geteuid( )...................................................................961 503 funlockfile ................................................................832 getgid( ).....................................................................962 504 funlockfile( ).............................................................923 getgrent.....................................................................730 505 fwide( )......................................................................924 getgrent( ) .................................................................963 506 fwprintf( ) .................................................................925 getgrgid( ).................................................................964 2180 Technical Standard (2001) (Draft April 16, 2001) Index 507 getgrgid_r.................................................................964 getservbyport( ).....................................................1022 508 getgrnam( )...............................................................967 getservent.................................................................740 509 getgrnam_r...............................................................967 getservent( ) ...........................................................1023 510 getgroups( )..............................................................969 getsid( ) ...................................................................1024 511 gethostbyaddr( )......................................................971 getsockname( ) ......................................................1025 512 gethostbyname........................................................971 getsockopt( ) ..........................................................1026 513 gethostbyname( ) ....................................................973 getsubopt( )............................................................1029 514 gethostent.................................................................732 gettimeofday( )......................................................1033 515 gethostent( ) .............................................................974 getuid( )...................................................................1034 516 gethostid( ) ...............................................................975 getutxent...................................................................742 517 gethostname( ).........................................................976 getutxent( ).............................................................1035 518 getitimer( )................................................................977 getutxid ..........................................................742, 1035 519 getlogin( )..................................................................979 getutxline .......................................................742, 1035 520 getlogin_r .................................................................979 GETVAL........................................................1760-1761 521 getmsg( ) ...................................................................982 getwc( ) ...................................................................1036 522 getnameinfo( ) .........................................................986 getwchar( ) .............................................................1037 523 GETNCNT ...................................................1760-1761 getwd ........................................................................951 524 getnetbyaddr ...........................................................734 getwd( )...................................................................1038 525 getnetbyaddr( )........................................................988 GETZCNT ....................................................1760-1761 526 getnetbyname..........................................................734 glob( ) ......................................................................1039 527 getnetbyname( ) ......................................................989 globfree...................................................................1039 528 getnetent...................................................................734 GLOB_.......................................................................468 529 getnetent( ) ...............................................................990 GLOB_ constants 530 getopt( ).....................................................................991 error returns of glob.........................................1041 531 getpeername( ).........................................................996 used in glob .......................................................1039 532 getpgid( ) ..................................................................997 GLOB_ABORTED ................................................1041 533 getpgrp( )..................................................................998 GLOB_APPEND .........................................1039-1040 534 GETPID.........................................................1760-1761 GLOB_DOOFFS..........................................1039-1040 535 getpid( ).....................................................................999 GLOB_ERR..................................................1039, 1041 536 getpmsg ....................................................................982 GLOB_MARK........................................................1040 537 getpmsg( )...............................................................1000 GLOB_NOCHECK.....................................1040-1041 538 getppid( ) ................................................................1001 GLOB_NOESCAPE..............................................1040 539 getpriority( )...........................................................1002 GLOB_NOMATCH..............................................1041 540 getprotobyname......................................................736 GLOB_NOSORT...................................................1040 541 getprotobyname( )................................................1005 GLOB_NOSPACE ................................................1041 542 getprotobynumber .................................................736 gmtime( ) ................................................................1043 543 getprotobynumber( )............................................1006 gmtime_r................................................................1043 544 getprotoent...............................................................736 grantpt( ).................................................................1045 545 getprotoent( ).........................................................1007 granularity of clock ................................................913 546 getpwent...................................................................738 HALT.........................................................................843 547 getpwent( ).............................................................1008 hcreate.....................................................................1047 548 getpwnam( )...........................................................1009 hcreate( ) .................................................................1047 549 getpwnam_r ..........................................................1009 hdestroy..................................................................1047 550 getpwuid( ).............................................................1012 hdestroy( ) ..............................................................1050 551 getpwuid_r ............................................................1012 high resolution sleep............................................1300 552 getrlimit( )...............................................................1015 host name.................................................................883 553 getrusage( ).............................................................1018 hsearch( ) ................................................................1051 554 gets( ).......................................................................1020 htonl( ).....................................................................1052 555 getservbyname........................................................740 htons........................................................................1052 556 getservbyname( ) ..................................................1021 htons( ) ....................................................................1053 557 getservbyport ..........................................................740 HUGE_VAL....................587, 633, 681, 769, 771, 773 System Interfaces, Issue 6 2181 Index 558 ....................797, 834, 1054, 1153, 1157, 1184, 1188 INT_MAX...............................................................1065 559 ...............1190, 1302, 1304, 1458, 1715, 1720, 1724 INT_MIN..................................................................544 560 ....................................1882, 1944, 1982, 2014, 2118 IN_ .............................................................................468 561 HUGE_VALF ..............................................1944, 2118 ioctl( ).......................................................................1080 562 HUGE_VALL ..............................................1944, 2118 IOV_ ..........................................................................468 563 hypot( )....................................................................1054 IOV_MAX ..............................................................1969 564 hypotf......................................................................1054 IP6 ..............................................................................455 565 hypotl......................................................................1054 IPC....................................489, 1283, 1285, 1288, 1290 566 h_errno....................................................................1046 ...............................................1765, 1769, 1833, 1835 567 iconv( ) ....................................................................1056 IPC_ ...........................................................................468 568 iconv_close( ).........................................................1058 IPC_ constants 569 iconv_open( ).........................................................1059 used in semctl ...................................................1760 570 IEEE Std 754-1985...................................................453 used in shmctl...................................................1831 571 IEEE Std 854-1987...................................................453 IPC_CREAT.......................................1284, 1763, 1834 572 IF_ ..............................................................................468 IPC_EXCL....................................................1284, 1763 573 if_freenameindex( ) ..............................................1061 IPC_NOWAIT...............1286-1287, 1289-1290, 1766 574 if_indextoname( )..................................................1062 IPC_PRIVATE...................................1284, 1763, 1834 575 if_nameindex( ) .....................................................1063 IPC_RMID.........................................1282, 1761, 1831 576 if_nametoindex( )..................................................1064 IPC_SET.............................................1282, 1761, 1831 577 ILL_............................................................................468 IPC_STAT ..........................................1282, 1760, 1831 578 ilogb( ) .....................................................................1065 IPPORT_...................................................................468 579 ilogbf .......................................................................1065 IPPROTO_................................................................468 580 ilogbl........................................................................1065 IPv4............................................................................517 581 imaxabs( ) ...............................................................1067 IPv4-compatible address.......................................518 582 imaxdiv( ) ...............................................................1068 IPv4-mapped address............................................518 583 implementation-defined .......................................451 IPv6............................................................................517 584 IMPLINK_................................................................468 compatibility with IPv4 ....................................518 585 INADDR_.................................................................468 interface identification ......................................518 586 index( ) ....................................................................1069 options..................................................................519 587 inet_addr( ).............................................................1070 IPv6 address 588 inet_ntoa.................................................................1070 anycast..................................................................517 589 inet_ntoa( ) .............................................................1072 loopback...............................................................518 590 inet_ntop( ).............................................................1073 multicast...............................................................517 591 inet_pton ................................................................1073 unicast...................................................................517 592 Inf...............................................................................574 unspecified...........................................................518 593 INF.....................................................................864, 928 IP_ ..............................................................................468 594 INFINITY.........................................................864, 928 isalnum( )................................................................1092 595 INFO..........................................................................843 isalpha( ) .................................................................1093 596 inheritance attribute ....................................526, 1399 isascii( ) ...................................................................1094 597 init....................................................................767, 1145 isastream( ).............................................................1095 598 initialize a named semaphore............................1749 isatty( ) ....................................................................1096 599 initialize an unnamed semaphore.....................1746 isblank( ) .................................................................1097 600 initializing a mutex ..............................................1568 iscntrl( )...................................................................1098 601 initializing condition variables..........................1523 isdigit( )...................................................................1099 602 initstate( )................................................................1075 isfinite( )..................................................................1100 603 INIT_PROCESS...............................................742-743 isgraph( ).................................................................1101 604 input and output rationale .................................1669 isgreater( )...............................................................1102 605 insque( ) ..................................................................1077 isgreaterequal( ) ....................................................1103 606 INT.............................................................................468 isinf( ).......................................................................1104 607 international environment..................................1794 isless( ).....................................................................1105 608 Internet Protocols ...................................................516 islessequal( )...........................................................1106 2182 Technical Standard (2001) (Draft April 16, 2001) Index 609 islessgreater( )........................................................1107 I_SENDFD....................................................1085-1086 610 islower( ).................................................................1108 I_SETCLTIME ...............................................661, 1087 611 isnan( ).....................................................................1110 I_SETSIG.......................................................1081-1082 612 isnormal( ) ..............................................................1111 I_SRDOPT..........................................1082-1083, 1667 613 ISO C standard.......................453, 570, 760, 789, 945 I_STR.......................................................................1084 614 ...............1205, 1663, 1710, 1794, 1842, 1868, 2017 I_SWROPT...................................................1085, 2159 615 isprint( ) ..................................................................1112 I_UNLINK .............................................................1088 616 ispunct( ).................................................................1113 j0( ) ...........................................................................1141 617 isspace( ) .................................................................1114 j1...............................................................................1141 618 isunordered( ) ........................................................1115 jn ..............................................................................1141 619 isupper( ) ................................................................1116 job control ....767, 998, 1145, 1799, 1811, 1973, 2091 620 iswalnum( ) ............................................................1117 jrand48 ......................................................................721 621 iswalpha( )..............................................................1119 jrand48( ).................................................................1143 622 iswblank( )..............................................................1121 kill( ).........................................................................1144 623 iswcntrl( )................................................................1122 killpg( )....................................................................1147 624 iswctype( )..............................................................1124 l64a.............................................................................541 625 iswdigit( ) ...............................................................1126 l64a( ).......................................................................1148 626 iswgraph( ) .............................................................1127 labs( ) .......................................................................1149 627 iswlower( ) .............................................................1129 LANG........................................................................626 628 iswprint( )...............................................................1131 last close .................................................................1827 629 iswpunct( ) .............................................................1133 LASTMARK...........................................................1087 630 iswspace( )..............................................................1135 lchown( ).................................................................1150 631 iswupper( ).............................................................1137 lcong48......................................................................721 632 iswxdigit( ) .............................................................1139 lcong48( ) ................................................................1152 633 isxdigit( ).................................................................1140 LC_ALL...........................755, 1175, 1312, 1793, 1795 634 ITIMER_PROF.........................................................977 LC_COLLATE...............1039-1040, 1793-1794, 1911 635 ITIMER_REAL ........................................................977 .........................................................1960, 2102, 2138 636 ITIMER_VIRTUAL.................................................977 LC_CTYPE......................605, 1124, 1213, 1215, 1217 637 I_ ................................................................................468 .......1219-1220, 1222, 1224, 1793-1794, 2034-2038 638 I_ATMARK ..................................................1086-1087 .................2097, 2113, 2129, 2140-2141, 2143-2144 639 I_CANPUT.............................................................1087 LC_MESSAGES........................626, 1793-1794, 1917 640 I_CKBAND ............................................................1087 LC_MONETARY....................1175, 1793-1794, 1920 641 I_FDINSERT ..........................................................1083 LC_NUMERIC .......................726, 862, 892, 925, 934 642 I_FIND ....................................................................1082 ..........................1175, 1793-1794, 1920, 1944, 2118 643 I_FLUSH.................................................................1080 LC_TIME....................................953, 1312, 1793-1794 644 I_FLUSHBAND ....................................................1081 ldexp( ) ....................................................................1153 645 I_GETBAND..........................................................1087 ldexpf ......................................................................1153 646 I_GETCLTIME.......................................................1087 ldexpl ......................................................................1153 647 I_GETSIG ...............................................................1082 ldiv( ) .......................................................................1155 648 I_GRDOPT...................................................1083, 1667 legacy ........................................................................451 649 I_GWROPT............................................................1085 LEGACY.................................................................2071 650 I_LINK ....................................................................1088 lfind .........................................................................1203 651 I_LIST......................................................................1086 lfind( )......................................................................1156 652 I_LOOK ..................................................................1080 lgamma( ) ...............................................................1157 653 I_NREAD ...............................................................1083 lgammaf..................................................................1157 654 I_PEEK....................................................................1082 lgammal..................................................................1157 655 I_PLINK..................................................................1089 LIFO...........................................................................507 656 I_POP ......................................................................1080 LINE_MAX ............................................................1969 657 I_PUNLINK...........................................................1089 link to a file ............................................................1161 658 I_PUSH ...................................................................1080 link( ) .......................................................................1159 659 I_RECVFD .....................................................472, 1086 LINK_MAX.................................474, 856, 1159, 1709 System Interfaces, Issue 6 2183 Index 660 LIO_...........................................................................466 logl...........................................................................1184 661 lio_listio( )...............................................................1162 logl( )........................................................................1195 662 LIO_NOP ...............................................................1162 LOG_.........................................................................468 663 LIO_NOWAIT.......................................................1162 LOG_ constants in syslog .....................................666 664 LIO_READ.............................................................1162 LOG_ALERT ...........................................................666 665 LIO_WAIT..............................................................1162 LOG_CONS.............................................................667 666 LIO_WRITE ...........................................................1162 LOG_CRIT ...............................................................666 667 list directed I/O ....................................................1164 LOG_DEBUG ..........................................................666 668 listen( ).....................................................................1165 LOG_EMERG ..........................................................666 669 llabs .........................................................................1149 LOG_ERR.................................................................666 670 llabs( )......................................................................1167 LOG_INFO...............................................................666 671 lldiv..........................................................................1155 LOG_LOCAL...........................................................666 672 lldiv( )......................................................................1168 LOG_NDELAY........................................................667 673 LLONG_MAX.............................................1953, 2125 LOG_NOTICE.........................................................666 674 LLONG_MIN ........................................................1953 LOG_NOWAIT .......................................................667 675 ,.............................................................................2125 LOG_ODELAY........................................................667 676 llrint( )......................................................................1169 LOG_PID..................................................................667 677 llrintf........................................................................1169 LOG_USER.......................................................666-667 678 llrintl........................................................................1169 LOG_WARNING ...................................................666 679 llround( ).................................................................1171 longjmp( ) ...............................................................1196 680 llroundf...................................................................1171 LONG_MAX ...............................................1953, 2125 681 llroundl ...................................................................1171 LONG_MIN ................................................1953, 2125 682 load ordering ...........................................................717 lrand48 ......................................................................721 683 localeconv( )...........................................................1173 lrand48( ).................................................................1198 684 localtime( )..............................................................1178 lrint( ).......................................................................1199 685 localtime_r .............................................................1178 lrintf.........................................................................1199 686 lockf( ) .....................................................................1181 lrintl.........................................................................1199 687 locking.......................................................................789 lround( )..................................................................1201 688 advisory................................................................790 lroundf ....................................................................1201 689 mandatory............................................................790 lroundl ....................................................................1201 690 locking and unlocking a mutex .........................1576 lsearch( )..................................................................1203 691 log( ).........................................................................1184 lseek( ) .....................................................................1205 692 log-full-policy attribute .524, 526, 1399, 1403, 1424 lstat( ).......................................................................1207 693 log-max-size attribute.......................526, 1400, 1403 L_ctermid .................................................................700 694 log10( ).....................................................................1186 l_sysid .......................................................................790 695 log10f.......................................................................1186 makecontext( ).......................................................1209 696 log10l.......................................................................1186 malloc( ) ..................................................................1211 697 log1p( ) ....................................................................1188 manipulate signal sets.........................................1848 698 log1pf ......................................................................1188 mappings................................................................1256 699 log1pl ......................................................................1188 MAP_ ................................................................466, 468 700 log2( ).......................................................................1190 MAP_FAILED .......................................................1256 701 log2f.........................................................................1190 MAP_FIXED................................................1252, 1255 702 log2l.........................................................................1190 MAP_PRIVATE..............851, 1252, 1256, 1260, 1292 703 logb( ) ......................................................................1192 MAP_SHARED...................................854, 1252-1253 704 logbf.........................................................................1192 max-data-size attribute.....................526, 1403-1404 705 logbl.........................................................................1192 MAXPATHLEN ......................................................709 706 logf...........................................................................1184 MAX_CANON........................................................856 707 logf( ) .......................................................................1194 MAX_INPUT...........................................................856 708 login shell .................................................................760 may............................................................................452 709 LOGIN_NAME_MAX.................................979, 1969 mblen( )...................................................................1213 710 LOGIN_PROCESS..........................................742-743 mbrlen( ) .................................................................1215 2184 Technical Standard (2001) (Draft April 16, 2001) Index 711 mbrtowc( )..............................................................1217 MM_NOTOK...........................................................843 712 mbsinit( ).................................................................1219 MM_NRECOV ........................................................842 713 mbsrtowcs( ) ..........................................................1220 MM_NULLMC........................................................842 714 mbstowcs( )............................................................1222 MM_OK....................................................................843 715 mbtowc( ) ...............................................................1224 MM_OPSYS .............................................................842 716 MB_CUR_MAX.1213, 1215, 1217, 1224, 2097, 2141 MM_PRINT .....................................................842, 844 717 MC1 ...........................................................................455 MM_RECOVER ......................................................842 718 MC2 ...........................................................................455 MM_SOFT................................................................842 719 MCL_.........................................................................466 MM_UTIL.................................................................842 720 MCL_CURRENT ..................................................1249 MM_WARNING.....................................................843 721 MCL_FUTURE......................................................1249 modf( ).....................................................................1258 722 memccpy( ).............................................................1226 modff.......................................................................1258 723 memchr( ) ...............................................................1227 modfl.......................................................................1258 724 memcmp( ).............................................................1228 MON .........................................................................456 725 memcpy( ) ..............................................................1229 MORECTL................................................................983 726 MEMLOCK_FUTURE .........................................1256 MOREDATA ............................................................983 727 memmove( )...........................................................1230 MPR...........................................................................456 728 memory management ...........................................493 mprotect( )..............................................................1260 729 memory protection option .................................1255 mq_close( ) .............................................................1262 730 memset( )................................................................1231 mq_getattr( ) ..........................................................1263 731 message catalog descriptor..................755, 760, 764 mq_notify( ) ...........................................................1265 732 message parts..........................................................489 mq_open( ) .............................................................1267 733 message priority .....................................................488 MQ_OPEN_MAX.................................................1969 734 high-priority ........................................................488 MQ_PRIO_MAX...............................1273-1274, 1969 735 normal...................................................................488 mq_receive( ) .........................................................1270 736 priority..................................................................488 mq_send( )..............................................................1273 737 message-discard mode........................................1667 mq_setattr( )...........................................................1275 738 message-nondiscard mode.................................1667 mq_timedreceive..................................................1270 739 MF..............................................................................455 mq_timedreceive( )...............................................1277 740 MINSIGSTKSZ......................................................1845 mq_timedsend ......................................................1273 741 mkdir( ) ...................................................................1232 mq_timedsend( )...................................................1278 742 mkfifo( ) ..................................................................1235 mq_unlink( ) ..........................................................1279 743 mknod( ) .................................................................1238 mrand48....................................................................721 744 mkstemp( ) .............................................................1241 mrand48( )..............................................................1281 745 mktemp( )...............................................................1243 MSG...................................................................456, 468 746 mktime( ) ................................................................1245 msgctl( ) ..................................................................1282 747 ML..............................................................................455 msgget( ).................................................................1284 748 mlock( ) ...................................................................1247 msgrcv( ).................................................................1286 749 mlockall( )...............................................................1249 msgsnd( )................................................................1289 750 MLR...........................................................................455 MSGVERB ........................................................843-844 751 mmap( )...................................................................1251 MSG_.........................................................................468 752 MM_APPL................................................................842 MSG_ANY ...............................................................982 753 MM_CONSOLE......................................................842 MSG_BAND..................................................982, 1648 754 MM_ERROR ....................................................843-844 MSG_EOR....................................................1888, 1890 755 mm_FIRM ................................................................842 MSG_HIPRI...................................................982, 1648 756 MM_HALT...............................................................843 MSG_NOERROR........................................1286-1287 757 MM_HARD..............................................................842 msg_perm ................................................................490 758 MM_INFO................................................................843 msqid.........................................................................490 759 MM_NOCON..........................................................843 msync( ) ..................................................................1292 760 MM_NOMSG ..........................................................843 MS_....................................................................466, 468 761 MM_NOSEV............................................................843 MS_ASYNC.................................................1253, 1292 System Interfaces, Issue 6 2185 Index 762 MS_INVALIDATE ......................................1292-1293 nl_langinfo( )..........................................................1312 763 MS_SYNC....................................................1253, 1292 nohup utility............................................................761 764 multicast...................................................................517 non-local jumps ....................................................1868 765 munlock..................................................................1247 non-volatile storage ...............................................909 766 munlock( ) ..............................................................1295 nrand48.....................................................................721 767 munlockall .............................................................1249 nrand48( ) ...............................................................1314 768 munlockall( )..........................................................1296 ntohl ........................................................................1052 769 munmap( )..............................................................1297 ntohl( ).....................................................................1315 770 mutex attributes....................................................1583 ntohs........................................................................1052 771 mutex initialization attributes ...........................1582 ntohs( ) ....................................................................1316 772 mutex performance..............................................1583 NULL ..................671, 700, 707, 714, 719, 1256, 1675 773 MUXID_ALL ...............................................1088-1089 NUM_EMPL..........................................................1048 774 MUXID_R.................................................................468 NZERO.........................................................1002, 1310 775 MX .............................................................................456 OB ..............................................................................456 776 M_ ..............................................................................468 obsolescent...............................................................636 777 name information...................................................986 OF...............................................................................456 778 name space...............................................................464 OH .............................................................................456 779 NAME_MAX..........................475, 547, 626, 641, 643 OLD_TIME.......................................................742-743 780 ......................646, 758, 776, 795, 848, 856, 887, 906 open a file...............................................................1321 781 ..................915, 1150, 1159, 1207, 1232, 1235, 1239 open a named semaphore...................................1749 782 ...............1268, 1279, 1308, 1319, 1324, 1456, 1673 open a shared memory object............................1824 783 ...............1677, 1684, 1709, 1717, 1749, 1757, 1824 open( ) .....................................................................1317 784 ...............1827, 1899, 1966, 2040, 2061, 2069, 2071 opendir( )................................................................1324 785 NaN...........................................................................574 openlog .....................................................................666 786 NAN..........................................................................864 openlog( )................................................................1327 787 NaN...........................................................................864 OPEN_MAX ...........................474, 626, 723, 738, 789 788 NAN..........................................................................928 ..................848, 887, 920, 964, 967, 979, 1012, 1059 789 NaN...........................................................................928 ...............1267, 1308, 1319, 1324, 1335, 1363, 1366 790 nan( )........................................................................1299 ...................................................................1969, 2029 791 nanf..........................................................................1299 optarg..............................................................991, 1328 792 nanl..........................................................................1299 opterr ..............................................................991, 1328 793 nanosleep( )............................................................1300 optind .............................................................991, 1328 794 NDEBUG..........................................................471, 581 option 795 nearbyint( ).............................................................1302 ADV.......................................................................453 796 nearbyintf...............................................................1302 AIO........................................................................453 797 nearbyintl ...............................................................1302 BAR .......................................................................453 798 network interfaces..................................................509 BE...........................................................................454 799 NEW_TIME......................................................742-743 CD..........................................................................454 800 nextafter( )..............................................................1304 CPT........................................................................454 801 nextafterf ................................................................1304 CS...........................................................................454 802 nextafterl ................................................................1304 FD ..........................................................................454 803 nexttoward.............................................................1304 FR...........................................................................454 804 nexttoward( ) .........................................................1306 FSC ........................................................................455 805 nexttowardf.................................................1304, 1306 IP6..........................................................................455 806 nexttowardl.................................................1304, 1306 MC1.......................................................................455 807 nftw( )......................................................................1307 MC2.......................................................................455 808 NGROUPS_MAX.........................................970, 1969 MF..........................................................................455 809 nice( ).......................................................................1310 ML..........................................................................455 810 NLSPATH.................................................................626 MLR.......................................................................455 811 NL_ARGMAX................................861, 892, 925, 934 MON .....................................................................456 812 NL_CAT_LOCALE.................................................626 MPR.......................................................................456 2186 Technical Standard (2001) (Draft April 16, 2001) Index 813 MSG.......................................................................456 ..............................................................................1825 814 MX .........................................................................456 O_RDWR ..............779, 1181, 1267, 1317-1321, 1353 815 PIO.........................................................................457 ...................................................................1823, 1825 816 PS ...........................................................................457 O_RSYNC....................................................1318, 1667 817 RS...........................................................................457 O_SYNC ....................................559, 1318, 1667, 2158 818 RTS ........................................................................457 O_TRUNC ............687, 1318, 1320, 1322, 1824-1825 819 SD...........................................................................457 O_WRONLY...........687, 779, 1181, 1267, 1317-1320 820 SEM .......................................................................457 ..............................................................................1322 821 SHM ......................................................................457 PAGESIZE............493, 1247, 1293, 1297, 1475, 1971 822 SIO.........................................................................457 PAGE_SIZE............................................................1971 823 SPI..........................................................................458 PATH.........................................................................671 824 SPN........................................................................458 PATH environment variable ................................762 825 SS............................................................................458 pathconf....................................................................856 826 TCT........................................................................458 pathconf( ) ..............................................................1329 827 TEF.........................................................................458 PATH_MAX ...................475, 547, 626, 641, 643, 646 828 THR.......................................................................458 ......................758, 776, 795, 848, 856, 887, 906, 915 829 TMO ......................................................................458 ..................951, 1038, 1150, 1159, 1207, 1232, 1235 830 TMR.......................................................................459 ...............1239, 1268, 1279, 1308, 1319, 1324, 1456 831 TPI .........................................................................459 ...............1677, 1684, 1709, 1717, 1749, 1757, 1824 832 TPP ........................................................................459 ...............1827, 1899, 1966, 1974, 2040, 2061, 2069 833 TPS.........................................................................459 ..............................................................................2071 834 TRC........................................................................459 pause( )....................................................................1330 835 TRI .........................................................................459 pclose( )...................................................................1331 836 TRL........................................................................459 perror( )...................................................................1333 837 TSA........................................................................459 persistent connection (I_PLINK).......................1089 838 TSF.........................................................................460 PF_ .............................................................................468 839 TSH........................................................................460 physical write..........................................................909 840 TSP.........................................................................460 PIO.............................................................................457 841 TSS.........................................................................460 pipe .......................................................853, 1322, 2161 842 TYM.......................................................................460 pipe( ) ......................................................................1335 843 UP ..........................................................................460 PIPE_BUF ............................................856, 2158, 2161 844 XSR ........................................................................461 PIPE_MAX .............................................................2163 845 optopt.....................................................991, 994, 1328 plain characters.....................................................1919 846 optstring ...................................................................994 POLL .........................................................................468 847 orphaned process group .......................................767 poll( ) .......................................................................1337 848 O_ constants POLLERR ...............................................................1337 849 used in open( )...................................................1317 POLLHUP..............................................................1337 850 used in posix_openpt( )...................................1353 POLLIN ..................................................................1337 851 O_ACCMODE.........................................................786 POLLNVAL ...........................................................1338 852 O_APPEND................491, 567, 705, 800, 1317, 2157 POLLOUT ..............................................................1337 853 O_CREAT ..............687, 1267-1268, 1279, 1317-1319 POLLPRI.................................................................1337 854 ...............................................1743, 1748, 1823-1825 POLLRDBAND.....................................................1337 855 O_DSYNC .......................559, 1317-1318, 1667, 2158 POLLRDNORM....................................................1337 856 O_EXCL...............1268, 1317-1318, 1748, 1823-1824 POLLWRBAND....................................................1337 857 O_NDELAY ...........................................................2162 POLLWRNORM...................................................1337 858 O_NOCTTY......................................1318, 1322, 1353 POLL_ .......................................................................468 859 O_NONBLOCK.............474, 661, 784, 817, 821, 827 popen( )...................................................................1341 860 ................873, 877, 900, 902, 983, 1084, 1086, 1268 portability.................................................................453 861 ................1270, 1273, 1275, 1318-1320, 1335, 1338 POSIX........................................................................726 862 ...............................................1649, 1666, 2158, 2161 POSIX.1 symbols ....................................................463 863 O_RDONLY..........709, 1267, 1317-1319, 1322, 1823 POSIX_......................................................................465 System Interfaces, Issue 6 2187 Index 864 posix_........................................................................465 posix_spawn_file_actions_destroy( )...............1369 865 POSIX_ALLOC_SIZE_MIN .................................856 posix_spawn_file_actions_init ..........................1369 866 posix_fadvise( ).....................................................1344 posix_spawn_file_actions_init( ).......................1370 867 POSIX_FADV_DONTNEED..............................1344 POSIX_SPAWN_RESETIDS.....................1356, 1373 868 POSIX_FADV_NOREUSE..................................1344 POSIX_SPAWN_SETPGROUP ...............1356, 1373 869 POSIX_FADV_NORMAL...................................1344 POSIX_SPAWN_SETSCHEDPARAM .............1373 870 POSIX_FADV_RANDOM ..................................1344 POSIX_SPAWN_SETSCHEDULER .......1356, 1373 871 POSIX_FADV_SEQUENTIAL ...........................1344 POSIX_SPAWN_SETSIGDEF ............................1373 872 POSIX_FADV_WILLNEED................................1344 POSIX_SPAWN_SETSIGMASK........................1373 873 posix_fallocate( )...................................................1346 POSIX_TRACE_ADD_EVENTSET ..................1438 874 posix_madvise( )...................................................1348 POSIX_TRACE_ALL_EVENTS.........................1432 875 POSIX_MADV_DONTNEED............................1348 POSIX_TRACE_APPEND........................1400, 1424 876 POSIX_MADV_NORMAL .................................1348 posix_trace_attr_destroy( ).................................1393 877 POSIX_MADV_RANDOM ................................1348 posix_trace_attr_getclockres( )..........................1395 878 POSIX_MADV_SEQUENTIAL .........................1348 posix_trace_attr_getcreatetime .........................1395 879 POSIX_MADV_WILLNEED..............................1348 posix_trace_attr_getcreatetime( )......................1397 880 posix_memalign( )................................................1352 posix_trace_attr_getgenversion ........................1395 881 posix_mem_offset( ).............................................1350 posix_trace_attr_getgenversion( ).....................1398 882 posix_openpt( ) .....................................................1353 posix_trace_attr_getinherited( ) ........................1399 883 POSIX_REC_INCR_XFER_SIZE .........................856 posix_trace_attr_getlogfullpolicy.....................1399 884 POSIX_REC_MAX_XFER_SIZE..........................856 posix_trace_attr_getlogfullpolicy( )..................1402 885 POSIX_REC_MIN_XFER_SIZE ...........................856 posix_trace_attr_getlogsize( ) ............................1403 886 POSIX_REC_XFER_ALIGN .................................856 posix_trace_attr_getmaxdatasize .....................1403 887 posix_spawn( ) ......................................................1355 posix_trace_attr_getmaxdatasize( )..................1406 888 posix_spawnattr_destroy( )................................1371 posix_trace_attr_getmaxsystemeventsize ......1403 889 posix_spawnattr_getflags( )...............................1373 ..............................................................................1406 890 posix_spawnattr_getpgroup( ) ..........................1375 posix_trace_attr_getmaxusereventsize ...........1403 891 posix_spawnattr_getschedparam( ) .................1377 ..............................................................................1406 892 posix_spawnattr_getschedpolicy( )..................1379 posix_trace_attr_getname ..................................1395 893 posix_spawnattr_getsigdefault( ) .....................1381 posix_trace_attr_getname( )...............................1407 894 posix_spawnattr_getsigmask( ).........................1383 posix_trace_attr_getstreamfullpolicy ..............1399 895 posix_spawnattr_init...........................................1371 posix_trace_attr_getstreamfullpolicy( )...........1408 896 posix_spawnattr_init( ) .......................................1385 posix_trace_attr_getstreamsize.........................1403 897 posix_spawnattr_setflags...................................1373 posix_trace_attr_getstreamsize( ) .....................1409 898 posix_spawnattr_setflags( )................................1386 posix_trace_attr_init ............................................1393 899 posix_spawnattr_setpgroup ..............................1375 posix_trace_attr_init( ).........................................1410 900 posix_spawnattr_setpgroup( )...........................1387 posix_trace_attr_setinherited ............................1399 901 posix_spawnattr_setschedparam .....................1377 posix_trace_attr_setinherited( ).........................1411 902 posix_spawnattr_setschedparam( )..................1388 posix_trace_attr_setlogfullpolicy......................1399 903 posix_spawnattr_setschedpolicy......................1379 posix_trace_attr_setlogfullpolicy( )..................1412 904 posix_spawnattr_setschedpolicy( ) ..................1389 posix_trace_attr_setlogsize ................................1403 905 posix_spawnattr_setsigdefault .........................1381 posix_trace_attr_setlogsize( ).............................1413 906 posix_spawnattr_setsigdefault( )......................1390 posix_trace_attr_setmaxdatasize......................1403 907 posix_spawnattr_setsigmask.............................1383 posix_trace_attr_setmaxdatasize( ) ..................1414 908 posix_spawnattr_setsigmask( ) .........................1391 posix_trace_attr_setname...................................1395 909 posix_spawnp .......................................................1355 posix_trace_attr_setname( ) ...............................1415 910 posix_spawnp( )....................................................1392 posix_trace_attr_setstreamfullpolicy...............1399 911 posix_spawn_file_actions_addclose( ).............1363 posix_trace_attr_setstreamfullpolicy( ) ...........1416 912 posix_spawn_file_actions_adddup2( ) ............1366 posix_trace_attr_setstreamsize .........................1403 913 posix_spawn_file_actions_addopen ................1363 posix_trace_attr_setstreamsize( )......................1417 914 posix_spawn_file_actions_addopen( ).............1368 posix_trace_clear( )...............................................1418 2188 Technical Standard (2001) (Draft April 16, 2001) Index 915 posix_trace_close( ) ..............................................1420 posix_trace_start( )...............................................1448 916 POSIX_TRACE_CLOSE_FOR_CHILD............1399 posix_trace_status_info structure.......................521 917 posix_trace_create( ) ............................................1422 posix_trace_stop...................................................1448 918 posix_trace_create_withlog ...............................1422 POSIX_TRACE_STOP trace event ...........527, 1448 919 POSIX_TRACE_ERROR trace event ..................527 POSIX_TRACE_SUB_EVENTSET ....................1438 920 posix_trace_event( ) .............................................1426 POSIX_TRACE_SUSPENDED...........522-523, 1448 921 posix_trace_eventid_equal( ) .............................1428 POSIX_TRACE_SYSTEM_EVENTS.................1432 922 posix_trace_eventid_get_name.........................1428 posix_trace_timedgetnext_event ......................1441 923 posix_trace_eventid_get_name( ) .....................1430 posix_trace_timedgetnext_event( )...................1450 924 posix_trace_eventid_open..................................1426 posix_trace_trid_eventid_open.........................1428 925 posix_trace_eventid_open( ) ..............................1431 posix_trace_trid_eventid_open( ) .....................1451 926 posix_trace_eventset_add( )...............................1432 POSIX_TRACE_TRUNCATED_READ ...525, 1442 927 posix_trace_eventset_del....................................1432 POSIX_TRACE_TRUNCATED_RECORD........525 928 posix_trace_eventset_empty .............................1432 ..............................................................................1442 929 posix_trace_eventset_fill ....................................1432 posix_trace_trygetnext_event............................1441 930 posix_trace_eventset_ismember.......................1432 posix_trace_trygetnext_event( )........................1452 931 posix_trace_eventtypelist_getnext_id( )..........1434 POSIX_TRACE_UNTIL_FULL............................523 932 posix_trace_eventtypelist_rewind....................1434 ..........................................................1399-1400, 1424 933 posix_trace_event_info structure........................524 POSIX_TRACE_USER_EVENT_MAX.............1426 934 POSIX_TRACE_FILTER trace event ........527, 1438 POSIX_TRACE_WOPID_EVENTS...................1432 935 POSIX_TRACE_FLUSH......................................1400 POSIX_TYPED_MEM_ALLOCATE .......1251-1252 936 posix_trace_flush..................................................1422 .........................................................1350, 1453, 1455 937 posix_trace_flush( )..............................................1435 POSIX_TYPED_MEM_ALLOCATE_CONTIG....... 938 POSIX_TRACE_FLUSHING................................523 .....................................1251-1252, 1350, 1453, 1455 939 POSIX_TRACE_FULL ...................................522-524 posix_typed_mem_get_info( )...........................1453 940 posix_trace_getnext_event( ) .............................1441 POSIX_TYPED_MEM_MAP_ALLOCATABLE1297 941 posix_trace_get_attr( ).........................................1436 ..............................................................................1455 942 posix_trace_get_filter( ).......................................1438 posix_typed_mem_open( ).................................1455 943 posix_trace_get_status........................................1436 pow( ) ......................................................................1458 944 posix_trace_get_status( ).....................................1440 powf ........................................................................1458 945 POSIX_TRACE_INHERITED ............................1399 powl.........................................................................1458 946 POSIX_TRACE_LOOP ...........522, 1399-1400, 1424 pread .......................................................................1666 947 POSIX_TRACE_NOT_FLUSHING ....................523 pread( )....................................................................1461 948 POSIX_TRACE_NOT_FULL .......................522, 524 predefined stream 949 POSIX_TRACE_NOT_FULL..............................1418 standard error .....................................................487 950 POSIX_TRACE_NOT_TRUNCATED......525, 1442 standard input.....................................................487 951 POSIX_TRACE_NO_OVERRUN......523-524, 1436 standard output..................................................487 952 posix_trace_open..................................................1420 preempted thread.................................................1528 953 posix_trace_open( ) ..............................................1444 PRI .............................................................................468 954 POSIX_TRACE_OVERFLOW trace event.........527 printf..........................................................................861 955 POSIX_TRACE_OVERRUN.........................523-524 printf( )....................................................................1462 956 POSIX_TRACE_RESUME trace event ...............527 priority......................................................................488 957 posix_trace_rewind..............................................1420 PRIO_........................................................................468 958 posix_trace_rewind( ) ..........................................1445 PRIO_INHERIT ....................................................1579 959 POSIX_TRACE_RUNNING ......................522, 1448 PRIO_PGRP...........................................................1002 960 POSIX_TRACE_SET_EVENTSET.....................1438 PRIO_PROCESS ...................................................1002 961 posix_trace_set_filter...........................................1438 PRIO_USER ...........................................................1002 962 posix_trace_set_filter( ) .......................................1446 process 963 posix_trace_shutdown........................................1422 concurrent execution.........................................853 964 posix_trace_shutdown( ).....................................1447 setting real and effective user IDs ................1807 965 POSIX_TRACE_START trace event.........527, 1448 single-threaded ...................................................853 System Interfaces, Issue 6 2189 Index 966 process creation ......................................................853 pthread_barrierattr_destroy( )...........................1505 967 process group pthread_barrierattr_getpshared( ) ....................1507 968 orphaned ..............................................................767 pthread_barrierattr_init ......................................1505 969 process group ID................................998, 1799, 1811 pthread_barrierattr_init( )...................................1509 970 process ID, 1.............................................................767 pthread_barrierattr_setpshared ........................1507 971 process lifetime.....................................................1146 pthread_barrierattr_setpshared( ).....................1510 972 process scheduling.................................................494 pthread_barrier_destroy( )..................................1500 973 process shared memory ......................................1583 pthread_barrier_init.............................................1500 974 process synchronization .....................................1583 pthread_barrier_init( ) .........................................1502 975 process termination................................................766 PTHREAD_BARRIER_SERIAL_THREAD.....1503 976 PROT_...............................................................466, 468 pthread_barrier_wait( ) .......................................1503 977 PROT_EXEC................................................1251, 1260 pthread_cancel( ) ..................................................1511 978 PROT_NONE .....................................494, 1251, 1260 PTHREAD_CANCELED............................507, 1548 979 PROT_READ...............................................1251, 1260 PTHREAD_CANCEL_ASYNCHRONOUS .....504 980 PROT_WRITE........................1251, 1253, 1255, 1260 ..............................................................................1624 981 PS ...............................................................................457 PTHREAD_CANCEL_DEFERRED ....................504 982 pselect( )..................................................................1463 ...................................................................1526, 1624 983 pseudo-random sequence generation functions.... PTHREAD_CANCEL_DISABLE..............504, 1624 984 ..............................................................................1663 PTHREAD_CANCEL_ENABLE...............504, 1624 985 PTHREAD_..............................................................466 pthread_cleanup_pop( )......................................1513 986 pthread_atfork( )...................................................1468 pthread_cleanup_push........................................1513 987 pthread_attr_destroy( ) .......................................1470 pthread_condattr_destroy( ) ..............................1532 988 pthread_attr_getdetachstate( )...........................1473 pthread_condattr_getclock( ).............................1534 989 pthread_attr_getguardsize( )..............................1475 pthread_condattr_getpshared( )........................1536 990 pthread_attr_getinheritsched( ).........................1477 pthread_condattr_init..........................................1532 991 pthread_attr_getschedparam( ).........................1479 pthread_condattr_init( )......................................1538 992 pthread_attr_getschedpolicy( )..........................1481 pthread_condattr_setclock.................................1534 993 pthread_attr_getscope( ) .....................................1483 pthread_condattr_setclock( ) .............................1539 994 pthread_attr_getstack( ) ......................................1485 pthread_condattr_setpshared............................1536 995 pthread_attr_getstackaddr( ) .............................1487 pthread_condattr_setpshared( ) ........................1540 996 pthread_attr_getstacksize( )...............................1489 pthread_cond_broadcast( ).................................1518 997 pthread_attr_init...................................................1470 pthread_cond_destroy( ).....................................1521 998 pthread_attr_init( ) ...............................................1490 pthread_cond_init ................................................1521 999 pthread_attr_setdetachstate...............................1473 pthread_cond_init( ).............................................1524 1000 pthread_attr_setdetachstate( ) ...........................1491 PTHREAD_COND_INITIALIZER.........1521, 1524 1001 pthread_attr_setguardsize..................................1475 pthread_cond_signal ...........................................1518 1002 pthread_attr_setguardsize( ) ..............................1492 pthread_cond_signal( )........................................1525 1003 pthread_attr_setinheritsched.............................1477 pthread_cond_timedwait( )................................1526 1004 pthread_attr_setinheritsched( ) .........................1493 pthread_cond_wait ..............................................1526 1005 pthread_attr_setschedparam .............................1479 pthread_cond_wait( )...........................................1531 1006 pthread_attr_setschedparam( )..........................1494 pthread_create( )...................................................1541 1007 pthread_attr_setschedpolicy..............................1481 PTHREAD_CREATE_DETACHED..........480, 1473 1008 pthread_attr_setschedpolicy( ) ..........................1495 PTHREAD_CREATE_JOINABLE ..480, 1473, 1558 1009 pthread_attr_setscope .........................................1483 PTHREAD_DESTRUCTOR_ITERATIONS ....1555 1010 pthread_attr_setscope( )......................................1496 ...................................................................1560, 1972 1011 pthread_attr_setstack ..........................................1485 pthread_detach( )..................................................1544 1012 pthread_attr_setstack( ).......................................1497 pthread_equal( )....................................................1546 1013 pthread_attr_setstackaddr .................................1487 pthread_exit( ) .......................................................1547 1014 pthread_attr_setstackaddr( )..............................1498 PTHREAD_EXPLICIT_SCHED ........................1477 1015 pthread_attr_setstacksize ...................................1489 pthread_getconcurrency( ) .................................1549 1016 pthread_attr_setstacksize( )................................1499 pthread_getcpuclockid( )....................................1551 2190 Technical Standard (2001) (Draft April 16, 2001) Index 1017 pthread_getschedparam( )..................................1552 pthread_rwlockattr_init( ) ..................................1621 1018 pthread_getspecific( ) ..........................................1555 pthread_rwlockattr_setpshared........................1619 1019 PTHREAD_INHERIT_SCHED .........................1477 pthread_rwlockattr_setpshared( ) ....................1622 1020 pthread_join( ) .......................................................1557 pthread_rwlock_destroy( ) .................................1602 1021 PTHREAD_KEYS_MAX...........................1560, 1972 pthread_rwlock_init ............................................1602 1022 pthread_key_create( ) ..........................................1560 pthread_rwlock_init( ).........................................1604 1023 pthread_key_delete( ) ..........................................1564 pthread_rwlock_rdlock( ) ...................................1605 1024 pthread_kill( ) ........................................................1566 pthread_rwlock_timedrdlock( ) ........................1607 1025 pthread_mutexattr_destroy( )............................1582 pthread_rwlock_timedwrlock( ) .......................1609 1026 pthread_mutexattr_getprioceiling( ) ................1587 pthread_rwlock_tryrdlock .................................1605 1027 pthread_mutexattr_getprotocol( ) ....................1589 pthread_rwlock_tryrdlock( )..............................1611 1028 pthread_mutexattr_getpshared( ).....................1591 pthread_rwlock_trywrlock( ).............................1612 1029 pthread_mutexattr_gettype( )............................1593 pthread_rwlock_unlock( ) ..................................1614 1030 pthread_mutexattr_init.......................................1582 pthread_rwlock_wrlock......................................1612 1031 pthread_mutexattr_init( ) ...................................1595 pthread_rwlock_wrlock( ) ..................................1616 1032 pthread_mutexattr_setprioceiling ....................1587 PTHREAD_SCOPE_PROCESS..........502-503, 1483 1033 pthread_mutexattr_setprioceiling( ).................1596 PTHREAD_SCOPE_SYSTEM............502-503, 1483 1034 pthread_mutexattr_setprotocol ........................1589 pthread_self( )........................................................1623 1035 pthread_mutexattr_setprotocol( ).....................1597 pthread_setcancelstate( ).....................................1624 1036 pthread_mutexattr_setpshared.........................1591 pthread_setcanceltype.........................................1624 1037 pthread_mutexattr_setpshared( ) .....................1598 pthread_setconcurrency .....................................1549 1038 pthread_mutexattr_settype................................1593 pthread_setconcurrency( )..................................1626 1039 pthread_mutexattr_settype( ) ............................1599 pthread_setschedparam......................................1552 1040 PTHREAD_MUTEX_DEFAULT .............1575, 1593 pthread_setschedparam( ) ..................................1627 1041 pthread_mutex_destroy( ) ..................................1567 pthread_setschedprio( ).......................................1628 1042 PTHREAD_MUTEX_ERRORCHECK...1575, 1593 pthread_setspecific ..............................................1555 1043 pthread_mutex_getprioceiling( ).......................1572 pthread_setspecific( )...........................................1630 1044 pthread_mutex_init .............................................1567 pthread_sigmask( )...............................................1631 1045 pthread_mutex_init( )..........................................1574 pthread_spin_destroy( )......................................1633 1046 PTHREAD_MUTEX_INITIALIZER.......1567, 1574 pthread_spin_init .................................................1633 1047 pthread_mutex_lock( ) ........................................1575 pthread_spin_init( )..............................................1635 1048 PTHREAD_MUTEX_NORMAL.............1575, 1593 pthread_spin_lock( ) ............................................1636 1049 PTHREAD_MUTEX_RECURSIVE1575, 1593-1594 pthread_spin_trylock ..........................................1636 1050 pthread_mutex_setprioceiling...........................1572 pthread_spin_trylock( ).......................................1638 1051 pthread_mutex_setprioceiling( ) .......................1578 pthread_spin_unlock( ) .......................................1639 1052 pthread_mutex_timedlock( )..............................1579 PTHREAD_STACK_MIN....1485, 1487, 1489, 1972 1053 pthread_mutex_trylock.......................................1575 pthread_testcancel ...............................................1624 1054 pthread_mutex_trylock( ) ...................................1581 pthread_testcancel( )............................................1640 1055 pthread_mutex_unlock.............................1575, 1581 PTHREAD_THREADS_MAX .................1541, 1972 1056 pthread_once( ) .....................................................1600 ptsname( )...............................................................1641 1057 PTHREAD_ONCE_INIT ....................................1600 putc( ) ......................................................................1642 1058 PTHREAD_PRIO_INHERIT..............................1589 putchar( ) ................................................................1644 1059 PTHREAD_PRIO_NONE...................................1589 putchar_unlocked...................................................944 1060 PTHREAD_PRIO_PROTECT..................1576, 1589 putchar_unlocked( ).............................................1645 1061 PTHREAD_PROCESS_PRIVATE ...........1507, 1536 putc_unlocked.........................................................944 1062 ...............................................1583, 1591, 1619, 1633 putc_unlocked( )...................................................1643 1063 PTHREAD_PROCESS_SHARED ...........1507, 1536 putenv( ) .................................................................1646 1064 ...............................................1583, 1591, 1619, 1633 putmsg( ) ................................................................1648 1065 pthread_rwlockattr_destroy( )...........................1617 putpmsg .................................................................1648 1066 pthread_rwlockattr_getpshared( )....................1619 putpmsg( )..............................................................1652 1067 pthread_rwlockattr_init......................................1617 puts( ) ......................................................................1653 System Interfaces, Issue 6 2191 Index 1068 pututxline.................................................................742 REG_EBRACK ......................................................1696 1069 pututxline( ) ...........................................................1655 REG_ECOLLATE..................................................1696 1070 putwc( )...................................................................1656 REG_ECTYPE........................................................1696 1071 putwchar( ).............................................................1657 REG_EESCAPE.....................................................1696 1072 pwrite......................................................................2157 REG_EPAREN.......................................................1696 1073 pwrite( ) ..................................................................1658 REG_ERANGE......................................................1696 1074 P_ALL .....................................................................2094 REG_ESPACE........................................................1696 1075 P_PGID ...................................................................2094 REG_ESUBREG.....................................................1696 1076 P_PID ......................................................................2094 REG_EXTENDED.................................................1694 1077 qsort( ) .....................................................................1659 REG_ICASE ...........................................................1694 1078 queue a signal to a process.................................1865 REG_NEWLINE ...................................................1694 1079 raise( )......................................................................1660 REG_NOMATCH.................................................1696 1080 rand( )......................................................................1662 REG_NOSUB.........................................................1694 1081 random ...................................................................1075 REG_NOTBOL......................................................1695 1082 random( )................................................................1665 REG_NOTEOL......................................................1695 1083 RAND_MAX .........................................................1662 remainder( ) ...........................................................1701 1084 rand_r......................................................................1662 remainderf..............................................................1701 1085 read from a file......................................................1669 remainderl..............................................................1701 1086 read( ) ......................................................................1666 remove a directory ...............................................1718 1087 readdir( ) .................................................................1673 remove directory entries.....................................2063 1088 readdir_r.................................................................1673 remove( ).................................................................1703 1089 readlink( ) ...............................................................1677 remque....................................................................1077 1090 readv( )....................................................................1680 remque( ) ................................................................1705 1091 real user ID ....................................................548, 1145 remquo( ) ................................................................1706 1092 realloc( ) ..................................................................1682 remquof ..................................................................1706 1093 realpath( ) ...............................................................1684 remquol ..................................................................1706 1094 REALTIME.......................556, 558-559, 561, 564-565 rename a file ..........................................................1710 1095 ........................567, 653, 659, 794, 1162, 1247, 1249 rename( ).................................................................1708 1096 ................1262-1263, 1265, 1267, 1270, 1273, 1275 rewind( ) .................................................................1712 1097 .................1279, 1300, 1728-1732, 1735, 1743-1746 rewinddir( )............................................................1713 1098 ...............1748, 1751, 1755, 1757, 1759, 1823, 1827 RE_DUP_MAX......................................................1972 1099 ..........................1864, 1872, 1878, 2019, 2022-2023 rindex( )...................................................................1714 1100 REALTIME THREADS.........1477, 1481, 1483, 1493 rint( )........................................................................1715 1101 ................1495-1496, 1552, 1572, 1578, 1587, 1589 RLIMIT_ ...................................................................468 1102 ..........................................................1596-1597, 1627 RLIMIT_AS............................................................1016 1103 recv( ).......................................................................1686 RLIMIT_CORE......................................................1015 1104 recvfrom( )..............................................................1688 RLIMIT_CPU.........................................................1015 1105 recvmsg( )...............................................................1691 RLIMIT_DATA......................................................1015 1106 regcomp( ) ..............................................................1694 RLIMIT_FSIZE ......................................................1015 1107 regerror...................................................................1694 RLIMIT_NOFILE .......................................1015, 1017 1108 regexec ....................................................................1694 RLIMIT_STACK....................................................1015 1109 regfree .....................................................................1694 RLIM_ .......................................................................468 1110 register fork handlers...........................................1468 RLIM_INFINITY.........................................1015-1016 1111 REG_..........................................................................468 RLIM_SAVED_CUR.............................................1016 1112 REG_ constants RLIM_SAVED_MAX............................................1016 1113 error return values of regcomp .....................1696 rmdir( )....................................................................1717 1114 used in regcomp ...............................................1694 RMSGD...................................................................1083 1115 REG_BADBR .........................................................1696 RMSGN ..................................................................1083 1116 REG_BADPAT.......................................................1696 RNORM..................................................................1083 1117 REG_BADRPT.......................................................1696 round robin..............................................................496 1118 REG_EBRACE.......................................................1696 round( ) ...................................................................1720 2192 Technical Standard (2001) (Draft April 16, 2001) Index 1119 roundf .....................................................................1720 ...................................................................1733, 1751 1120 roundl......................................................................1720 sched_rr_get_interval( ) ......................................1731 1121 routing ......................................................................509 sched_setparam( ).................................................1732 1122 RPROTDAT ...........................................................1083 sched_setscheduler( )...........................................1735 1123 RPROTDIS .............................................................1083 SCHED_SPORADIC492, 495, 497, 1605, 1733, 1751 1124 RPROTNORM.......................................................1083 sched_yield( ).........................................................1738 1125 RS ...............................................................................457 SCM_.........................................................................468 1126 RS_HIPRI.............................................982, 1082, 1648 SCN ...........................................................................468 1127 RTLD_GLOBAL .............................712, 716-717, 720 SD...............................................................................457 1128 RTLD_LAZY ...................................................716, 719 security considerations..647, 766, 1145, 1799, 1901 1129 RTLD_LOCAL ........................................................717 seed48........................................................................721 1130 RTLD_NEXT....................................................719-720 seed48( )..................................................................1739 1131 RTLD_NOW ....................................................716-717 seekdir( ) .................................................................1740 1132 RTS.............................................................................457 SEEK_CUR ............................................787, 899, 1205 1133 RTSIG_MAX..........................................................1972 SEEK_END............................................787, 899, 1205 1134 RUSAGE_.................................................................468 SEEK_GET .............................................................1712 1135 RUSAGE_CHILDREN ........................................1018 SEEK_SET.....................492, 561, 567, 787, 899, 1205 1136 RUSAGE_SELF .....................................................1018 SEGV_ .......................................................................468 1137 SA_.............................................................................468 select........................................................................1463 1138 SA_NOCLDSTOP....................481, 1838-1839, 1842 select( ) ....................................................................1742 1139 SA_NOCLDWAIT ...........764-765, 1018, 1840, 2088 SEM............................................................................457 1140 SA_NODEFER ......................................................1840 semctl( )...................................................................1760 1141 SA_ONSTACK..............................................755, 1839 semget( ) .................................................................1763 1142 SA_RESETHAND ..............................601, 1839-1840 semid.........................................................................490 1143 SA_RESTART ...........................601, 1466, 1839, 1854 semop( ) ..................................................................1766 1144 SA_SIGINFO...........................1838-1839, 1842, 1864 SEM_ .................................................................466, 468 1145 scalb( ) .....................................................................1722 sem_close( )............................................................1743 1146 scalbln( )..................................................................1724 sem_destroy( ).......................................................1744 1147 scalblnf....................................................................1724 SEM_FAILED ........................................................1749 1148 scalblnl....................................................................1724 sem_getvalue( ).....................................................1745 1149 scalbn ......................................................................1724 sem_init( )...............................................................1746 1150 scalbn( )...................................................................1726 SEM_NSEMS_MAX...................................1746, 1972 1151 scalbnf...........................................................1724, 1726 sem_open( )............................................................1748 1152 scalbnl...........................................................1724, 1726 sem_perm.................................................................490 1153 scanf...........................................................................892 sem_post( ).............................................................1751 1154 scanf( ).....................................................................1727 sem_timedwait( )..................................................1753 1155 schedule alarm ........................................................570 sem_trywait( ) .......................................................1755 1156 scheduling documentation...................................504 SEM_UNDO ..........................................................1766 1157 scheduling policy sem_unlink( ).........................................................1757 1158 round robin..........................................................496 SEM_VALUE_MAX...................................1748, 1972 1159 SCHED_....................................................................466 ..............................................................................1746 1160 SCHED_FIFO .........................492, 495, 503, 756, 851 sem_wait ................................................................1755 1161 ..........................1002, 1310, 1479, 1481, 1552, 1587 sem_wait( ).............................................................1759 1162 .........................................................1605, 1733, 1751 send( )......................................................................1771 1163 sched_getparam( ) ................................................1729 sendmsg( )..............................................................1773 1164 sched_getscheduler( ) ..........................................1730 sendto( ) ..................................................................1776 1165 sched_get_priority_max( )..................................1728 service name............................................................883 1166 sched_get_priority_min ......................................1728 session........................................767, 1145, 1799, 1811 1167 SCHED_OTHER .............495, 498, 1481, 1552, 1733 set cancelability state...........................................1624 1168 SCHED_RR .....................492, 495-496, 503, 756, 851 set file creation mask ...........................................2054 1169 ..........................1002, 1310, 1479, 1481, 1552, 1605 set process group ID for job control .................1799 System Interfaces, Issue 6 2193 Index 1170 set-group-ID ...................................645, 761, 766, 791 shell scripts 1171 set-user-ID.....................................761, 766, 951, 1145 exec........................................................................760 1172 SETALL ........................................................1760, 1763 shell, login ................................................................760 1173 setbuf( ) ...................................................................1779 SHM ..................................................................457, 468 1174 setcontext .................................................................948 shmat( ) ...................................................................1829 1175 setcontext( )............................................................1780 shmctl( ) ..................................................................1831 1176 setegid( ) .................................................................1781 shmdt( )...................................................................1833 1177 setenv( )...................................................................1782 shmget( ).................................................................1834 1178 seteuid( ) .................................................................1784 shmid.........................................................................490 1179 setgid( ) ...................................................................1785 SHMLBA ................................................................1829 1180 setgrent .....................................................................730 SHM_ ........................................................................468 1181 setgrent( )................................................................1787 shm_open( ) ...........................................................1823 1182 sethostent .................................................................732 shm_perm ................................................................490 1183 sethostent( )............................................................1788 SHM_RDONLY.....................................................1829 1184 setitimer....................................................................977 SHM_RND.............................................................1829 1185 setitimer( ) ..............................................................1789 shm_unlink( ).........................................................1827 1186 setjmp( ) ..................................................................1790 should .......................................................................452 1187 setkey( )...................................................................1792 shutdown( )............................................................1836 1188 setlocale( )...............................................................1793 SHUT_.......................................................................468 1189 setlogmask ...............................................................666 SIGABRT ..................................................................543 1190 setlogmask( )..........................................................1797 sigaction( )..............................................................1838 1191 setnetent ...................................................................734 sigaddset( ).............................................................1844 1192 setnetent( )..............................................................1798 SIGALRM .........................570, 977, 1885, 2050, 2067 1193 setpgid( ).................................................................1799 sigaltstack( )...........................................................1845 1194 setpgrp( ) ................................................................1801 SIGBUS ......................................494, 1253, 1256, 1631 1195 setpriority...............................................................1002 SIGCANCEL..........................................................1511 1196 setpriority( ) ...........................................................1802 SIGCHLD..................667, 764-765, 1018, 1045, 1839 1197 setprotoent ...............................................................736 ....................................1842, 1851, 1977, 2088, 2094 1198 setprotoent( ) .........................................................1803 SIGCLD...................................................................1842 1199 setpwent ...................................................................738 SIGCONT ............................484, 765, 767, 1144-1145 1200 setpwent( )..............................................................1804 sigdelset( ) ..............................................................1847 1201 setregid( )................................................................1805 sigemptyset( ) ........................................................1848 1202 setreuid( )................................................................1807 SIGEV_......................................................................466 1203 setrlimit...................................................................1015 SIGEV_NONE.................................................479, 492 1204 setrlimit( ) ...............................................................1809 SIGEV_SIGNAL ...........................................479, 2019 1205 setservent .................................................................740 SIGEV_THREAD ............................................479-480 1206 setservent( )............................................................1810 sigfillset( )...............................................................1850 1207 setsid( )....................................................................1811 SIGFPE..........................................................1631, 1858 1208 setsockopt( )...........................................................1813 sighold( ).................................................................1851 1209 setstate ....................................................................1075 SIGHUP....................................................661, 765, 767 1210 setstate( ).................................................................1816 sigignore.................................................................1851 1211 setuid( ) ...................................................................1817 sigignore( ) .............................................................1853 1212 setutxent ...................................................................742 SIGILL ..........................................................1631, 1858 1213 setutxent( ) .............................................................1820 SIGINT ...........................................................853, 1977 1214 SETVAL........................................................1760, 1763 siginterrupt( ).........................................................1854 1215 setvbuf( ).................................................................1821 sigismember( ).......................................................1856 1216 shall ...........................................................................452 SIGKILL...................................1145, 1838, 1842, 1851 1217 shell ...................760, 767, 980, 998, 1145, 1800, 2091 siglongjmp( )..........................................................1857 1218 job ........................................................................1145 signal generation and delivery ............................478 1219 login.......................................................................980 realtime.................................................................479 1220 signal handler........................................................1858 2194 Technical Standard (2001) (Draft April 16, 2001) Index 1221 signal( )....................................................................1858 sinhf.........................................................................1882 1222 signaling a condition ...........................................1519 sinhl.........................................................................1882 1223 signals .......................................................................478 sinl ...........................................................................1879 1224 signbit( )..................................................................1860 sinl( )........................................................................1884 1225 sigpause..................................................................1851 SIO .............................................................................457 1226 sigpause( ) ..............................................................1861 SI_ ..............................................................................468 1227 sigpending( )..........................................................1862 SI_ASYNCIO...........................................................482 1228 SIGPIPE ......784, 817, 873, 877, 900, 903, 1649, 2160 SI_MESGQ ...............................................................482 1229 SIGPOLL ..............................................661, 1081-1082 SI_QUEUE................................................................482 1230 sigprocmask...........................................................1631 SI_TIMER .................................................................482 1231 sigprocmask( ) .......................................................1863 SI_USER....................................................................482 1232 SIGPROF ..................................................................977 sleep( ).....................................................................1885 1233 sigqueue( )..............................................................1864 SND ...........................................................................468 1234 SIGQUEUE_MAX ......................................1864, 1972 SNDZERO..............................................................1085 1235 SIGQUIT.................................................................1977 snprintf .....................................................................861 1236 sigrelse ....................................................................1851 snprintf( )................................................................1887 1237 sigrelse( ).................................................................1866 SO...............................................................................468 1238 SIGRTMAX .......................479-480, 1864, 1872, 1876 socket I/O mode.....................................................510 1239 SIGRTMIN ........................479-480, 1864, 1872, 1876 socket out-of-band data ........................................511 1240 SIGSEGV.........................494, 1016, 1297, 1631, 1858 socket owner............................................................510 1241 sigset........................................................................1851 socket queue limits.................................................510 1242 sigset( ) ....................................................................1867 socket receive queue..............................................511 1243 sigsetjmp( ).............................................................1868 socket types .............................................................509 1244 SIGSTKSZ ..............................................................1845 socket( )...................................................................1888 1245 SIGSTOP....................................479, 1838, 1842, 1851 socketpair( ) ...........................................................1890 1246 sigsuspend( )..........................................................1870 sockets.......................................................................508 1247 sigtimedwait( ) ......................................................1872 addressing............................................................509 1248 SIGTSTP ...................................................................479 asynchronous errors ..........................................512 1249 SIGTTIN ........................................479, 821, 827, 1668 connection indication queue............................512 1250 SIGTTOU ........................479, 784, 817, 873, 877, 900 Internet Protocols ...............................................516 1251 ..................902, 1988, 1990, 1992, 1999, 2002, 2160 IPv4........................................................................517 1252 SIGURG ..................................................................1082 IPv6........................................................................517 1253 SIGVTALRM............................................................977 local UNIX connections ....................................516 1254 sigwait( ) .................................................................1876 options..................................................................513 1255 sigwaitinfo .............................................................1872 pending error.......................................................510 1256 sigwaitinfo( )..........................................................1878 signals ...................................................................512 1257 SIGXCPU................................................................1015 SOCK_.......................................................................468 1258 SIGXFSZ.......................................................1015, 2040 SOCK_DGRAM .................................516, 1888, 1890 1259 SIG_...................................................................466, 468 SOCK_RAW.............................................................516 1260 SIG_BLOCK...........................................................1631 SOCK_SEQPACKET .........................516, 1888, 1890 1261 SIG_DFL .................480, 755, 1016, 1838, 1840, 1858 SOCK_STREAM.................................516, 1888, 1890 1262 SIG_ERR.........................................................601, 1858 SPI..............................................................................458 1263 SIG_HOLD.............................................................1851 SPN............................................................................458 1264 SIG_IGN...........................480-481, 755, 761, 764-765 sporadic server policy 1265 ...............................................1018, 1838, 1858, 2088 execution capacity..............................................497 1266 SIG_SETMASK......................................................1631 replenishment period ........................................497 1267 SIG_UNBLOCK ....................................................1631 sprintf........................................................................861 1268 sin( ) .........................................................................1879 sprintf( ) ..................................................................1892 1269 sinf ...........................................................................1879 spurious wakeup..................................................1519 1270 sinf( )........................................................................1881 sqrt( ) .......................................................................1893 1271 sinh( ).......................................................................1882 sqrtf..........................................................................1893 System Interfaces, Issue 6 2195 Index 1272 sqrtl..........................................................................1893 streams 1273 srand........................................................................1662 stream orientation..............................................486 1274 srand( ) ....................................................................1895 STREAM_MAX..........................799, 848, 1341, 1972 1275 srand48......................................................................721 strerror( ).................................................................1917 1276 srand48( )................................................................1896 strerror_r ................................................................1917 1277 srandom..................................................................1075 strfmon( )................................................................1919 1278 srandom( ) ..............................................................1897 strftime( )................................................................1924 1279 SS................................................................................458 strlen( ) ....................................................................1929 1280 sscanf.........................................................................892 strncasecmp...........................................................1906 1281 sscanf( ) ...................................................................1898 strncasecmp( ) .......................................................1931 1282 SSIZE_MAX.......1270, 1286, 1666, 1677, 1920, 2157 strncat( )..................................................................1932 1283 SS_..............................................................................468 strncmp( ) ...............................................................1933 1284 SS_DISABLE ................................................1845-1846 strncpy( ).................................................................1934 1285 SS_ONSTACK .......................................................1845 strpbrk( ).................................................................1935 1286 stack size ................................................................1470 strptime( )...............................................................1936 1287 stat( )........................................................................1899 strrchr( ) ..................................................................1940 1288 statvfs........................................................................906 strspn( )...................................................................1941 1289 statvfs( ) ..................................................................1903 strstr( ).....................................................................1942 1290 stderr .......................................................................1904 strtod( )....................................................................1943 1291 STDERR_FILENO ................................................1904 strtof ........................................................................1943 1292 stdin.........................................................................1904 strtof( ).....................................................................1947 1293 STDIN_FILENO .........................................1341, 1904 strtoimax( ).............................................................1948 1294 stdio locking functions ..........................................832 strtok( )....................................................................1949 1295 stdio with explicit client locking .........................944 strtok_r....................................................................1949 1296 stdout ......................................................................1904 strtol( ).....................................................................1952 1297 STDOUT_FILENO.....................................1341, 1904 strtold......................................................................1943 1298 STR.............................................................................468 strtold( ) ..................................................................1954 1299 strcasecmp( )..........................................................1906 strtoll .......................................................................1952 1300 strcat( ) ....................................................................1907 strtoll( )....................................................................1955 1301 strchr( )....................................................................1908 strtoul( ) ..................................................................1956 1302 strcmp( )..................................................................1909 strtoull.....................................................................1956 1303 strcoll( ) ...................................................................1911 strtoumax ...............................................................1948 1304 strcpy( ) ...................................................................1913 strtoumax( )............................................................1959 1305 strcspn( ) .................................................................1915 strxfrm( ).................................................................1960 1306 strdup( ) ..................................................................1916 ST_NOSUID ....................................................755, 906 1307 STREAM.............1084, 1086, 1648, 1652, 1667, 2159 ST_RDONLY ...........................................................906 1308 stream superuser.....................................548, 647, 1161, 2063 1309 byte-oriented .......................................................486 supplementary groups..................................647, 969 1310 wide-oriented......................................................486 SVID ........................................................................1868 1311 STREAM head/tail.................................................488 SVR4..............................................................1255, 1300 1312 stream-full-policy attribute........522-523, 526, 1400 SV_.............................................................................468 1313 stream-min-size attribute ...........................526, 1404 swab( ).....................................................................1962 1314 streams......................................................................484 swapcontext...........................................................1209 1315 STREAMS .....................472, 661, 776, 795, 982, 1080 swapcontext( ).......................................................1963 1316 .....................................1095, 1319-1320, 1337, 1463 swprintf ....................................................................925 1317 access ....................................................................489 swprintf( )...............................................................1964 1318 streams swscanf .....................................................................934 1319 interaction with file descriptors ......................485 swscanf( )................................................................1965 1320 STREAMS symbols 1321 multiplexed .......................................................1088 POSIX.1.................................................................463 1322 overview...............................................................488 symlink( )................................................................1966 2196 Technical Standard (2001) (Draft April 16, 2001) Index 1323 SYMLINK_MAX ..........................................856, 1966 tan( ).........................................................................1982 1324 SYMLOOP_MAX ..................600, 676, 777, 795, 848 tanf...........................................................................1982 1325 ........................888, 907, 915, 921, 1150, 1239, 1308 tanf( ) .......................................................................1984 1326 ..........................1684, 1775, 1778, 1972, 2041, 2071 tanh( ) ......................................................................1985 1327 sync( ) ......................................................................1968 tanhf ........................................................................1985 1328 synchronously accept a signal...........................1873 tanhl.........................................................................1985 1329 sysconf( ).................................................................1969 tanl...........................................................................1982 1330 syslog ........................................................................666 tanl( ) .......................................................................1987 1331 syslog( )...................................................................1976 tcdrain( ) .................................................................1988 1332 system crash ............................................................909 tcflow( )...................................................................1990 1333 System III .......................................................647, 2056 tcflush( )..................................................................1992 1334 system interfaces ....................................................533 tcgetattr( )...............................................................1994 1335 system name..........................................................2056 tcgetpgrp( ).............................................................1996 1336 system trace event type definitions....................526 tcgetsid( )................................................................1998 1337 System V..........................570, 647, 762, 767, 789-790 TCIFLUSH .............................................................1992 1338 ....................858, 998, 1145, 1233, 1718, 1811, 1842 TCIOFF ...................................................................1990 1339 .........................................................1868, 1994, 2056 TCIOFLUSH..........................................................1992 1340 system( )..................................................................1977 TCION ....................................................................1990 1341 S_................................................................................468 TCOFLUSH ...........................................................1992 1342 S_BANDURG ........................................................1082 TCOOFF .................................................................1990 1343 S_ERROR................................................................1081 TCOON ..................................................................1990 1344 S_HANGUP...........................................................1082 TCP_..........................................................................468 1345 S_HIPRI ..................................................................1081 TCSADRAIN.........................................................2001 1346 S_IFBLK ..................................................................1238 TCSAFLUSH .........................................................2001 1347 S_IFCHR.................................................................1238 TCSANOW............................................................2001 1348 S_IFDIR...................................................................1238 tcsendbreak( ) ........................................................1999 1349 S_IFIFO ...................................................................1238 tcsetattr( )................................................................2001 1350 S_IFREG..................................................................1238 tcsetpgrp( ) .............................................................2004 1351 S_INPUT.................................................................1081 TCT............................................................................458 1352 S_IRGRP ................................................780, 904, 1238 tdelete( )..................................................................2006 1353 S_IROTH................................................780, 904, 1238 TEF.............................................................................458 1354 S_IRUSR.................................................780, 904, 1238 telldir( ) ...................................................................2010 1355 S_IRWXG ...............................................................1238 tempnam( ).............................................................2011 1356 S_IRWXO ...............................................................1238 terminal access control .............................1994, 2002 1357 S_IRWXU ...............................................................1238 terminal device name ..........................................2044 1358 S_ISGID..............................643-645, 1238, 2040, 2158 terminate a process ................................................766 1359 S_ISUID..............................643-644, 1238, 2040, 2158 terminology .............................................................451 1360 S_ISVTX ..........................643, 1238, 1709, 1718, 2061 termios structure ..................................................1994 1361 S_IWGRP ...............................................780, 904, 1238 tfind .........................................................................2006 1362 S_IWOTH ..............................................780, 904, 1238 tfind( )......................................................................2013 1363 S_IWUSR ...............................................780, 904, 1238 tgamma( ) ...............................................................2014 1364 S_IXGRP .................................................................1238 tgammaf .................................................................2014 1365 S_IXOTH ................................................................1238 tgammal..................................................................2014 1366 S_IXUSR .................................................................1238 THR ...........................................................................458 1367 S_MSG ....................................................................1081 thread cancelation 1368 S_OUTPUT ............................................................1081 cleanup handlers ................................................507 1369 S_RDBAND..................................................1081-1082 thread creation ......................................................1542 1370 S_RDNORM ..........................................................1081 thread creation attributes ...................................1470 1371 S_WRBAND ..........................................................1081 thread ID ................................................................1546 1372 S_WRNORM .........................................................1081 thread IDs.................................................................501 1373 TABSIZE.........................................................603, 1203 thread mutexes........................................................501 System Interfaces, Issue 6 2197 Index 1374 thread scheduling...................................................502 TRC............................................................................459 1375 thread termination ...............................................1547 TRI .............................................................................459 1376 thread-safety ...................................................500, 832 TRL ............................................................................459 1377 thread-specific data key creation ......................1562 trunc( ).....................................................................2039 1378 thread-specific data key deletion ......................1564 truncate( ) ...............................................................2040 1379 thread-specific data management.....................1556 truncation-status attribute..................................1426 1380 threads ......................................................................500 truncf.......................................................................2039 1381 regular file operations .......................................508 truncf( ) ...................................................................2042 1382 time( ) ......................................................................2016 truncl.............................................................2039, 2042 1383 timer ID...................................................................2021 TSA ............................................................................459 1384 TIMER_ .............................................................467-468 tsearch.....................................................................2006 1385 TIMER_ABSTIME................................499, 656, 2023 tsearch( ) .................................................................2043 1386 timer_create( )........................................................2019 TSF.............................................................................460 1387 timer_delete( ) .......................................................2022 TSH............................................................................460 1388 timer_getoverrun( ) ..............................................2023 TSP.............................................................................460 1389 timer_gettime ........................................................2023 TSS .............................................................................460 1390 TIMER_MAX.........................................................1972 ttyname( ) ...............................................................2044 1391 timer_settime.........................................................2023 ttyname_r...............................................................2044 1392 times( ) ....................................................................2026 TTY_NAME_MAX ....................................1972, 2044 1393 timezone( ) .............................................................2028 twalk........................................................................2006 1394 TMO ..........................................................................458 twalk( )....................................................................2046 1395 tmpfile( ) .................................................................2029 TYM...........................................................................460 1396 tmpnam( )...............................................................2031 tzname...........................................................2047-2048 1397 TMP_MAX.........................................2011, 2030-2031 TZNAME_MAX....................................................1972 1398 TMR...........................................................................459 tzset .........................................................................2048 1399 toascii( )...................................................................2033 tzset( )......................................................................2048 1400 tolower( ) ................................................................2034 t_uscalar_t..............................................................1083 1401 TOSTOP................784, 817, 873, 877, 900, 902, 2159 ualarm( ) .................................................................2050 1402 toupper( )................................................................2035 UINT .........................................................................468 1403 towctrans( ) ............................................................2036 UINT_MAX...................................................570, 1886 1404 towlower( ).............................................................2037 ulimit( ) ...................................................................2052 1405 towupper( ) ............................................................2038 ULLONG_MAX....................................................1957 1406 TPI..............................................................................459 ULONG_MAX............................................1957, 2132 1407 TPP.............................................................................459 UL_GETFSIZE.......................................................2052 1408 TPS.............................................................................459 UL_SETFSIZE........................................................2052 1409 trace event, POSIX_TRACE_ERROR .................527 umask( ) ..................................................................2054 1410 trace event, POSIX_TRACE_FILTER .......527, 1438 uname( )..................................................................2056 1411 trace event, POSIX_TRACE_OVERFLOW........527 undefined .................................................................452 1412 trace event, POSIX_TRACE_RESUME ..............527 underlying function ...............................................486 1413 trace event, POSIX_TRACE_START........527, 1448 ungetc( )..................................................................2058 1414 trace event, POSIX_TRACE_STOP ..........527, 1448 ungetwc( )...............................................................2059 1415 trace functions.........................................................529 unicast.......................................................................517 1416 trace-name attribute ....................................526, 1395 unlink( )...................................................................2061 1417 TRACE_EVENT_NAME_MAX ..............1426, 1428 unlockpt( )..............................................................2065 1418 TRACE_SYS_MAX...............................................1423 unsetenv( )..............................................................2066 1419 TRACE_USER_EVENT_MAX.................1426, 1428 unspecified...............................................................452 1420 TRACING................................1393, 1395, 1397-1399 UP ..............................................................................460 1421 .................1402-1403, 1406-1412, 1414-1418, 1420 US-ASCII................................................................1094 1422 .................1422, 1426, 1428, 1430-1432, 1434-1436 user ID 1423 .................1438, 1440-1441, 1444-1448, 1450-1452 real and effective ..............................................1807 1424 TRAP_.......................................................................468 setting real and effective.................................1807 2198 Technical Standard (2001) (Draft April 16, 2001) Index 1425 user trace event type definitions .........................529 wcscpy( ).................................................................2103 1426 USER_PROCESS .............................................742-743 wcscspn( )...............................................................2104 1427 usleep( )...................................................................2067 wcsftime( )..............................................................2105 1428 UTC .........................................................................2048 wcslen( )..................................................................2107 1429 utime( )....................................................................2069 wcsncat( )................................................................2108 1430 utimes( )..................................................................2071 wcsncmp( ).............................................................2109 1431 va_arg( )..................................................................2073 wcsncpy( ) ..............................................................2110 1432 va_copy ..................................................................2073 wcspbrk( )...............................................................2111 1433 va_end.....................................................................2073 wcsrchr( )................................................................2112 1434 va_start ...................................................................2073 wcsrtombs( ) ..........................................................2113 1435 Version 7......................................570, 647, 1145, 2056 wcsspn( ).................................................................2115 1436 vfork( ).....................................................................2074 wcsstr( )...................................................................2116 1437 vfprintf( ) ................................................................2076 wcstod( ) .................................................................2117 1438 vfscanf( ) .................................................................2077 wcstof......................................................................2117 1439 vfwprintf( ).............................................................2078 wcstof( ) ..................................................................2120 1440 vfwscanf( )..............................................................2079 wcstoimax( ) ..........................................................2121 1441 VISIT .............................................................2006, 2046 wcstok( ) .................................................................2122 1442 vprintf .....................................................................2076 wcstol( ) ..................................................................2124 1443 vprintf( )..................................................................2080 wcstold ...................................................................2117 1444 vscanf ......................................................................2077 wcstold( )................................................................2127 1445 vscanf( )...................................................................2081 wcstoll.....................................................................2124 1446 vsnprintf.................................................................2076 wcstoll( ) .................................................................2128 1447 vsnprintf( ) .............................................................2082 wcstombs( )............................................................2129 1448 vsprintf.........................................................2076, 2082 wcstoul( )................................................................2131 1449 vsscanf ....................................................................2077 wcstoull( )...............................................................2134 1450 vsscanf( ).................................................................2083 wcstoumax.............................................................2121 1451 vswprintf................................................................2078 wcstoumax( ) .........................................................2135 1452 vswprintf( ) ............................................................2084 wcswcs( ) ................................................................2136 1453 vswscanf.................................................................2079 wcswidth( ) ............................................................2137 1454 vswscanf( ) .............................................................2085 wcsxfrm( ) ..............................................................2138 1455 vwprintf..................................................................2078 wctob( ) ...................................................................2140 1456 vwprintf( ) ..............................................................2086 wctomb( ) ...............................................................2141 1457 vwscanf...................................................................2079 wctrans( )................................................................2143 1458 vwscanf( ) ...............................................................2087 wctype( ).................................................................2144 1459 wait for process termination..............................2091 wcwidth( ) ..............................................................2146 1460 wait for thread termination................................1558 WEOF ..............................532, 1117, 1119, 1122, 1124 1461 wait( ) ......................................................................2088 ..........................1126-1127, 1129, 1131, 1133, 1135 1462 waitid( )...................................................................2094 .....................................1137, 1139, 2037-2038, 2059 1463 waiting on a condition.........................................1527 WEXITED...............................................................2094 1464 waitpid....................................................................2088 WEXITSTATUS .....................................................2089 1465 waitpid( ) ................................................................2096 wide-oriented stream.............................................486 1466 WARNING...............................................................843 WIFCONTINUED................................................2089 1467 warning WIFEXITED ...........................................................2089 1468 OB ..........................................................................456 WIFSIGNALED ....................................................2089 1469 OF ..........................................................................456 WIFSTOPPED.............................................2089, 2092 1470 WCONTINUED .........................................2088, 2094 wmemchr( )............................................................2147 1471 wcrtomb( )..............................................................2097 wmemcmp( )..........................................................2148 1472 wcscat( )..................................................................2099 wmemcpy( )...........................................................2149 1473 wcschr( ) .................................................................2100 wmemmove( ) .......................................................2150 1474 wcscmp( ) ...............................................................2101 wmemset( ) ............................................................2151 1475 wcscoll( ).................................................................2102 WNOHANG.....................................1842, 2088, 2094 System Interfaces, Issue 6 2199 Index 1476 WNOWAIT............................................................2094 1477 wordexp( )..............................................................2152 1478 wordfree .................................................................2152 1479 wprintf ......................................................................925 1480 wprintf( ).................................................................2156 1481 WRDE_ .....................................................................468 1482 WRDE_APPEND..................................................2153 1483 WRDE_BADCHAR..............................................2154 1484 WRDE_BADVAL..................................................2154 1485 WRDE_CMDSUB .................................................2154 1486 WRDE_DOOFFS...................................................2153 1487 WRDE_NOCMD ..................................................2153 1488 WRDE_NOSPACE ...............................................2154 1489 WRDE_REUSE......................................................2153 1490 WRDE_SHOWERR..............................................2153 1491 WRDE_SYNTAX ..................................................2154 1492 WRDE_UNDEF.....................................................2153 1493 write to a file..........................................................2161 1494 write( ).....................................................................2157 1495 writev( ) ..................................................................2165 1496 wscanf .......................................................................934 1497 wscanf( ) .................................................................2167 1498 WSTOPPED ...........................................................2094 1499 WSTOPSIG ............................................................2089 1500 WTERMSIG ...........................................................2089 1501 WUNTRACED ...........................................2088, 2091 1502 XSI..............................................................................460 1503 XSI interprocess communication ........................489 1504 XSR ............................................................................461 1505 X_OK.........................................................................548 1506 y0( ) ..........................................................................2168 1507 y1..............................................................................2168 1508 yn .............................................................................2168 1509 zombie process........................................................764 1510 2200 Technical Standard (2001) (Draft April 16, 2001) ||||||||||| 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 Change History | 12 Change history is described in the Rationale (Informative) volume of IEEE Std 1003.1-200x, and | 13 in the CHANGE HISTORY section of reference pages. | 14 1.5 Terminology 15 This section appears in the Base Definitions volume of IEEE Std 1003.1-200x, but is repeated here 16 for convenience: 17 For the purposes of IEEE Std 1003.1-200x, the following terminology definitions apply: 18 can 19 Describes a permissible optional feature or behavior available to the user or application. The 20 feature or behavior is mandatory for an implementation that conforms to 21 IEEE Std 1003.1-200x. An application can rely on the existence of the feature or behavior. 22 implementation-defined 23 Describes a value or behavior that is not defined by IEEE Std 1003.1-200x but is selected by 24 an implementor. The value or behavior may vary among implementations that conform to 25 IEEE Std 1003.1-200x. An application should not rely on the existence of the value or 26 behavior. An application that relies on such a value or behavior cannot be assured to be 27 portable across conforming implementations. 28 The implementor shall document such a value or behavior so that it can be used correctly 29 by an application. 30 legacy 31 Describes a feature or behavior that is being retained for compatibility with older 32 applications, but which has limitations which make it inappropriate for developing portable Shell and Utilities, Issue 6 2201 Terminology Introduction 33 applications. New applications should use alternative means of obtaining equivalent 34 functionality. 35 may 36 Describes a feature or behavior that is optional for an implementation that conforms to 37 IEEE Std 1003.1-200x. An application should not rely on the existence of the feature or 38 behavior. An application that relies on such a feature or behavior cannot be assured to be 39 portable across conforming implementations. 40 To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. 41 shall 42 For an implementation that conforms to IEEE Std 1003.1-200x, describes a feature or 43 behavior that is mandatory. An application can rely on the existence of the feature or 44 behavior. 45 For an application or user, describes a behavior that is mandatory. 46 should 47 For an implementation that conforms to IEEE Std 1003.1-200x, describes a feature or 48 behavior that is recommended but not mandatory. An application should not rely on the 49 existence of the feature or behavior. An application that relies on such a feature or behavior 50 cannot be assured to be portable across conforming implementations. 51 For an application, describes a feature or behavior that is recommended programming 52 practice for optimum portability. 53 undefined 54 Describes the nature of a value or behavior not defined by IEEE Std 1003.1-200x which 55 results from use of an invalid program construct or invalid data input. 56 The value or behavior may vary among implementations that conform to 57 IEEE Std 1003.1-200x. An application should not rely on the existence or validity of the 58 value or behavior. An application that relies on any particular value or behavior cannot be 59 assured to be portable across conforming implementations. 60 unspecified 61 Describes the nature of a value or behavior not specified by IEEE Std 1003.1-200x which 62 results from use of a valid program construct or valid data input. 63 The value or behavior may vary among implementations that conform to 64 IEEE Std 1003.1-200x. An application should not rely on the existence or validity of the 65 value or behavior. An application that relies on any particular value or behavior cannot be 66 assured to be portable across conforming implementations. 2202 Technical Standard (2001) (Draft April 16, 2001) Introduction Definitions 67 1.6 Definitions 68 Concepts and definitions are defined in the Base Definitions volume of IEEE Std 1003.1-200x. 69 1.7 Relationship to Other Documents 70 1.7.1 System Interfaces | 71 This subsection describes some of the features provided by the System Interfaces volume of | 72 IEEE Std 1003.1-200x that are assumed to be globally available by all systems conforming to this 73 volume of IEEE Std 1003.1-200x. This subsection does not attempt to detail all of the features 74 defined in the System Interfaces volume of IEEE Std 1003.1-200x that are required by all of the 75 utilities defined in this volume of IEEE Std 1003.1-200x; the utility and function descriptions 76 point out additional functionality required to provide the corresponding specific features 77 needed by each. 78 The following subsections describe frequently used concepts. Many of these concepts are 79 described in the Base Definitions volume of IEEE Std 1003.1-200x. Utility and function 80 description statements override these defaults when appropriate. 81 1.7.1.1 Process Attributes 82 The following process attributes, as described in the System Interfaces volume of 83 IEEE Std 1003.1-200x, are assumed to be supported for all processes in this volume of 84 IEEE Std 1003.1-200x: 85 Controlling Terminal Real Group ID 86 Current Working Directory Real User ID 87 Effective Group ID Root Directory 88 Effective User ID Saved Set-Group-ID 89 File Descriptors Saved Set-User-ID 90 File Mode Creation Mask Session Membership 91 Process Group ID Supplementary Group IDs 92 Process ID 93 A conforming implementation may include additional process attributes. 94 1.7.1.2 Concurrent Execution of Processes 95 The following functionality of the fork( ) function defined in the System Interfaces volume of 96 IEEE Std 1003.1-200x shall be available on all systems conforming to this volume of 97 IEEE Std 1003.1-200x: 98 1. Independent processes shall be capable of executing independently without either process 99 terminating. 100 2. A process shall be able to create a new process with all of the attributes referenced in 101 Section 1.7.1.1, determined according to the semantics of a call to the fork( ) function 102 defined in the System Interfaces volume of IEEE Std 1003.1-200x followed by a call in the 103 child process to one of the exec functions defined in the System Interfaces volume of 104 IEEE Std 1003.1-200x. Shell and Utilities, Issue 6 2203 Relationship to Other Documents Introduction 105 1.7.1.3 File Access Permissions 106 The file access control mechanism described by the Base Definitions volume of | 107 IEEE Std 1003.1-200x, Section 4.4, File Access Permissions shall apply to all files on an | 108 implementation conforming to this volume of IEEE Std 1003.1-200x. | 109 1.7.1.4 File Read, Write, and Creation 110 If a file that does not exist is to be written, it shall be created as described below, unless the 111 utility description states otherwise. 112 When a file that does not exist is created, the following features defined in the System Interfaces 113 volume of IEEE Std 1003.1-200x shall apply unless the utility or function description states 114 otherwise: 115 1. The user ID of the file shall be set to the effective user ID of the calling process. | 116 2. The group ID of the file shall be set to the effective group ID of the calling process or the | 117 group ID of the directory in which the file is being created. 118 3. If the file is a regular file, the permission bits of the file shall be set to: | 119 S_IROTH | S_IWOTH | S_IRGRP | S_IWGRP | S_IRUSR | S_IWUSR 120 (see the description of File Modes in the Base Definitions volume of IEEE Std 1003.1-200x, 121 Chapter 13, Headers, ) except that the bits specified by the file mode creation 122 mask of the process shall be cleared. If the file is a directory, the permission bits shall be set | 123 to: | 124 S_IRWXU | S_IRWXG | S_IRWXO 125 except that the bits specified by the file mode creation mask of the process shall be cleared. | 126 4. The st_atime, st_ctime, and st_mtime fields of the file shall be updated as specified in the 127 System Interfaces volume of IEEE Std 1003.1-200x, Section 2.5, Standard I/O Streams. 128 5. If the file is a directory, it shall be an empty directory; otherwise, the file shall have length 129 zero. 130 6. If the file is a symbolic link, the effect shall be undefined unless the {POSIX2_SYMLINKS} 131 variable is in effect for the directory in which the symbolic link would be created. 132 7. Unless otherwise specified, the file created shall be a regular file. 133 When an attempt is made to create a file that already exists, the action shall depend on the type | 134 of the file the utility is trying to create and on the type of the existing file as shown in Table 1-1 | 135 (on page 2205). | 2204 Technical Standard (2001) (Draft April 16, 2001) Introduction Relationship to Other Documents 136 Table 1-1 Actions when Creating a File that Already Exists | ________________________________________________________________________________ || 137 New Type Function || 138 _ Existing Type A B C D F L M P Q R S T Creating New _______________________________________________________________________________ |||| 139 A fattach( )-ed STREAM - - - - - - - - - OF - - fattach( ) || 140 B Block Special - - - - - - - - - OF - - mknod( )** || 141 C Character Special - - - - - - - - - OF - - mknod( )** || 142 D Directory - - - F F - - - - OD - - mkdir( ) || 143 F FIFO Special File - - - F F - - - - O - - mkfifo( ) || 144 L Symbolic Link FL FL FL FL FL FL FL FL FL FL FL FL symlink( ) || 145 M Shared Memory - - - - - - - - - - - - shm_open( ) || 146 P Semaphore - - - - - - - - - - - - sem_open( ) || 147 Q Message Queue - - - - - - - - - - - - mq_open( ) || 148 R Regular File - - - F F - - - - RF - - open( ) || 149 S Socket - - - - - - - - - - - - bind( ) || 150 T Typed Memory - - - - - - - - - - - - * || 151 _ None. - - - NF NF NF - - - CF NF - _______________________________________________________________________________ |||||||||||| 152 The following codes are used in Table 1-1: | 153 CF Create a new file as defined in Section 1.7.1.4 (on page 2204), items 1 through 7. | 154 F Fail. When attempting to create a directory or FIFO special file, and the existing file is a | 155 directory, FIFO special file, or regular file, the attempt shall fail and the utility shall either 156 continue with its operation or exit immediately with a non-zero exit status, depending on 157 the description of the utility. | 158 FL Follow link. Unless otherwise specified, the symbolic links shall be followed as specified for | 159 pathname resolution, and the operation performed shall be as if the target of the symbolic | 160 link (after all resolution) had been named. If the target of the symbolic link does not exist, it | 161 shall be as if that nonexistent target had been named directly. | 162 NF Create a new file as described by the appropriate function. | 163 O Open FIFO. When attempting to create a regular file, and the existing file is a FIFO special | 164 file: | 165 1. If the FIFO is not already open for reading, the attempt shall block until the FIFO is | 166 opened for reading. | 167 2. Once the FIFO is open for reading, the utility shall open the FIFO for writing and | 168 continue with its operation. | 169 OD The directory shall be opened. | 170 OF The named file shall be opened with the consequences defined for that file type. | 171 RF Regular file. When attempting to create a regular file, and the existing file is a regular file: | 172 1. The user ID, group ID, and permission bits of the file shall not be changed. | 173 2. The file shall be truncated to zero length. 174 3. The st_ctime and st_mtime fields shall be marked for update. 175 - The effect is implementation-defined unless specified by the utility description. | 176 * There is no portable way to create a file of this type. | 177 ** Not portable. | Shell and Utilities, Issue 6 2205 Relationship to Other Documents Introduction 178 When a file is to be appended, the file shall be opened in a manner equivalent to using the | 179 O_APPEND flag, without the O_TRUNC flag, in the open( ) function defined in the System 180 Interfaces volume of IEEE Std 1003.1-200x. 181 When a file is to be read or written, the file shall be opened with an access mode corresponding 182 to the operation to be performed. If file access permissions deny access, the requested operation 183 shall fail. 184 1.7.1.5 File Removal 185 When a directory that is the root directory or current working directory of any process is 186 removed, the effect is implementation-defined. If file access permissions deny access, the | 187 requested operation shall fail. Otherwise, when a file is removed: | 188 1. Its directory entry shall be removed from the file system. | 189 2. The link count of the file shall be decremented. | 190 3. If the file is an empty directory (see the Base Definitions volume of IEEE Std 1003.1-200x, 191 Section 3.143, Empty Directory): 192 a. If no process has the directory open, the space occupied by the directory shall be | 193 freed and the directory shall no longer be accessible. | 194 b. If one or more processes have the directory open, the directory contents shall be | 195 preserved until all references to the file have been closed. | 196 4. If the file is a directory that is not empty, the st_ctime field shall be marked for update. | 197 5. If the file is not a directory: 198 a. If the link count becomes zero: 199 i. If no process has the file open, the space occupied by the file shall be freed and | 200 the file shall no longer be accessible. | 201 ii. If one or more processes have the file open, the file contents shall be preserved | 202 until all references to the file have been closed. | 203 b. If the link count is not reduced to zero, the st_ctime field shall be marked for update. | 204 6. The st_ctime and st_mtime fields of the containing directory shall be marked for update. | 205 1.7.1.6 File Time Values 206 All files shall have the three time values described by the Base Definitions volume of 207 IEEE Std 1003.1-200x, Section 4.7, File Times Update. 208 1.7.1.7 File Contents 209 When a reference is made to the contents of a file, pathname, this means the equivalent of all of 210 the data placed in the space pointed to by buf when performing the read( ) function calls in the 211 following operations defined in the System Interfaces volume of IEEE Std 1003.1-200x: 212 while (read (fildes, buf, nbytes) > 0) | 213 ; | 214 If the file is indicated by a pathname pathname, the file descriptor shall be determined by the 215 equivalent of the following operation defined in the System Interfaces volume of 216 IEEE Std 1003.1-200x: 2206 Technical Standard (2001) (Draft April 16, 2001) Introduction Relationship to Other Documents 217 fildes = open (pathname, O_RDONLY); | 218 The value of nbytes in the above sequence is unspecified; if the file is of a type where the data 219 returned by read( ) would vary with different values, the value shall be one that results in the | 220 most data being returned. | 221 If the read( ) function calls would return an error, it is unspecified whether the contents of the file 222 are considered to include any data from offsets in the file beyond where the error would be 223 returned. 224 1.7.1.8 Pathname Resolution 225 The pathname resolution algorithm, described by the Base Definitions volume of | 226 IEEE Std 1003.1-200x, Section 4.11, Pathname Resolution, shall be used by implementations | 227 conforming to this volume of IEEE Std 1003.1-200x; see also the Base Definitions volume of | 228 IEEE Std 1003.1-200x, Section 4.5, File Hierarchy. | 229 1.7.1.9 Changing the Current Working Directory 230 When the current working directory (see the Base Definitions volume of IEEE Std 1003.1-200x, 231 Section 3.436, Working Directory) is to be changed, unless the utility or function description 232 states otherwise, the operation shall succeed unless a call to the chdir( ) function defined in the 233 System Interfaces volume of IEEE Std 1003.1-200x would fail when invoked with the new 234 working directory pathname as its argument. 235 1.7.1.10 Establish the Locale 236 The functionality of the setlocale( ) function defined in the System Interfaces volume of | 237 IEEE Std 1003.1-200x shall be available on all systems conforming to this volume of | 238 IEEE Std 1003.1-200x; that is, utilities that require the capability of establishing an international 239 operating environment shall be permitted to set the specified category of the international 240 environment. 241 1.7.1.11 Actions Equivalent to Functions 242 Some utility descriptions specify that a utility performs actions equivalent to a function defined | 243 in the System Interfaces volume of IEEE Std 1003.1-200x. Such specifications require only that 244 the external effects be equivalent, not that any effect within the utility and visible only to the 245 utility be equivalent. | 246 1.7.2 Concepts Derived from the ISO C Standard | 247 Some of the standard utilities perform complex data manipulation using their own procedure | 248 and arithmetic languages, as defined in their EXTENDED DESCRIPTION or OPERANDS | 249 sections. Unless otherwise noted, the arithmetic and semantic concepts (precision, type | 250 conversion, control flow, and so on) shall be equivalent to those defined in the ISO C standard, | 251 as described in the following sections. Note that there is no requirement that the standard | 252 utilities be implemented in any particular programming language. | 253 1.7.2.1 Arithmetic Precision and Operations | 254 Integer variables and constants, including the values of operands and option-arguments, used | 255 by the standard utilities listed in this volume of IEEE Std 1003.1-200x shall be implemented as | 256 equivalent to the ISO C standard signed long data type; floating point shall be implemented as | 257 equivalent to the ISO C standard double type. Conversions between types shall be as described | 258 in the ISO C standard. All variables shall be initialized to zero if they are not otherwise assigned | Shell and Utilities, Issue 6 2207 Relationship to Other Documents Introduction 259 by the input to the application. | 260 Arithmetic operators and functions shall be implemented as equivalent to those in the cited | 261 ISO C standard section, as listed in Table 1-2 (on page 2209). | 2208 Technical Standard (2001) (Draft April 16, 2001) Introduction Relationship to Other Documents 262 Table 1-2 ISO C Standard Operators and Functions | 263 _________________________________________________________________________________ | 264 _ Operation ISO C Standard Equivalent Reference ________________________________________________________________________________ || 265 _( ) Section 6.5.1, Primary Expressions ________________________________________________________________________________ | | 266 postfix ++ Section 6.5.2, Postfix Operators | 267 _ postfix - - ________________________________________________________________________________ || 268 unary + Section 6.5.3, Unary Operators | 269 unary - | 270 prefix ++ | 271 prefix - - | 272 ~ | 273 ! | 274 _sizeof( ) ________________________________________________________________________________ | | 275 * Section 6.5.5, Multiplicative Operators | 276 / | 277 _% ________________________________________________________________________________ || 278 + Section 6.5.6, Additive Operators | 279 _ - ________________________________________________________________________________ || 280 << Section 6.5.7, Bitwise Shift Operators | 281 _>> ________________________________________________________________________________ | | 282 <, <= Section 6.5.8, Relational Operators | 283 _ >, >= ________________________________________________________________________________ || 284 = = Section 6.5.9, Equality Operators | 285 _ != ________________________________________________________________________________ || 286 _ & Section 6.5.10, Bitwise AND Operator ________________________________________________________________________________ || 287 _^ Section 6.5.11, Bitwise Exclusive OR Operator ________________________________________________________________________________ | | 288 _ | Section 6.5.12, Bitwise Inclusive OR Operator ________________________________________________________________________________ || 289 _&& Section 6.5.13, Logical AND Operator ________________________________________________________________________________ || 290 _ | | Section 6.5.14, Logical OR Operator ________________________________________________________________________________ || 291 _ expr?expr:expr Section 6.5.15, Conditional Operator ________________________________________________________________________________ || 292 =, *=, /=, %=, +=, -= Section 6.5.16, Assignment Operators | 293 _ <<=, >>=, &=, =, |= ________________________________________________________________________________ || 294 if ( ) Section 6.8.4, Selection Statements | 295 if ( ) . . . else | 296 _switch ( ) ________________________________________________________________________________ | | 297 while ( ) Section 6.8.5, Iteration Statements | 298 do ... while ( ) | 299 _for ( ) ________________________________________________________________________________ || 300 goto Section 6.8.6, Jump Statements | 301 continue | 302 break | 303 _ return ________________________________________________________________________________ ||||| 304 The evaluation of arithmetic expressions shall be equivalent to that described in Section 6.5, | 305 Expressions, of the ISO C standard. | Shell and Utilities, Issue 6 2209 Relationship to Other Documents Introduction 306 1.7.2.2 Mathematical Functions | 307 Any mathematical functions with the same names as those in the following sections of the ISO C | 308 standard: | 309 * Section 7.12, Mathematics, | 310 * Section 7.20.2, Pseudo-Random Sequence Generation Functions | 311 shall be implemented to return the results equivalent to those returned from a call to the | 312 corresponding function described in the ISO C standard. | 313 1.8 Portability 314 Some of the utilities in the Shell and Utilities volume of IEEE Std 1003.1-200x and functions in 315 the System Interfaces volume of IEEE Std 1003.1-200x describe functionality that might not be 316 fully portable to systems meeting the requirements for POSIX conformance (see the Base 317 Definitions volume of IEEE Std 1003.1-200x, Chapter 2, Conformance). 318 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in 319 the margin identifies the nature of the option, extension, or warning (see Section 1.8.1). For 320 maximum portability, an application should avoid such functionality. 321 Unless the primary task of a utility is to produce textual material on its standard output, 322 application developers should not rely on the format or content of any such material that may be 323 produced. Where the primary task is to provide such material, but the output format is 324 incompletely specified, the description is marked with the OF margin code and shading. 325 Application developers are warned not to expect that the output of such an interface on one 326 system is any guide to its behavior on another system. 327 1.8.1 Codes 328 Codes and their meanings are listed in the Base Definitions volume of IEEE Std 1003.1-200x, but 329 are repeated here for convenience: 330 ADV Advisory Information 331 The functionality described is optional. The functionality described is also an extension to the 332 ISO C standard. 333 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. 334 Where additional semantics apply to a function, the material is identified by use of the ADV 335 margin legend. 336 AIO Asynchronous Input and Output 337 The functionality described is optional. The functionality described is also an extension to the 338 ISO C standard. 339 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. 340 Where additional semantics apply to a function, the material is identified by use of the AIO 341 margin legend. 342 BAR Barriers 343 The functionality described is optional. The functionality described is also an extension to the 344 ISO C standard. 345 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. 346 Where additional semantics apply to a function, the material is identified by use of the BAR 347 margin legend. 2210 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 348 BE Batch Environment Services and Utilities 349 The functionality described is optional. 350 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. 351 Where additional semantics apply to a utility, the material is identified by use of the BE margin 352 legend. 353 CD C-Language Development Utilities 354 The functionality described is optional. 355 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. 356 Where additional semantics apply to a utility, the material is identified by use of the CD margin 357 legend. 358 CPT Process CPU-Time Clocks 359 The functionality described is optional. The functionality described is also an extension to the 360 ISO C standard. 361 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. 362 Where additional semantics apply to a function, the material is identified by use of the CPT 363 margin legend. 364 CS Clock Selection 365 The functionality described is optional. The functionality described is also an extension to the 366 ISO C standard. 367 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. 368 Where additional semantics apply to a function, the material is identified by use of the CS 369 margin legend. 370 CX Extension to the ISO C standard 371 The functionality described is an extension to the ISO C standard. Application writers may make 372 use of an extension as it is supported on all IEEE Std 1003.1-200x-conforming systems. 373 With each function or header from the ISO C standard, a statement to the effect that ``any 374 conflict is unintentional'' is included. That is intended to refer to a direct conflict. 375 IEEE Std 1003.1-200x acts in part as a profile of the ISO C standard, and it may choose to further 376 constrain behaviors allowed to vary by the ISO C standard. Such limitations are not considered 377 conflicts. 378 FD FORTRAN Development Utilities 379 The functionality described is optional. 380 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. 381 Where additional semantics apply to a utility, the material is identified by use of the FD margin 382 legend. 383 FR FORTRAN Runtime Utilities 384 The functionality described is optional. 385 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. 386 Where additional semantics apply to a utility, the material is identified by use of the FR margin 387 legend. 388 FSC File Synchronization 389 The functionality described is optional. The functionality described is also an extension to the 390 ISO C standard. 391 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. 392 Where additional semantics apply to a function, the material is identified by use of the FSC Shell and Utilities, Issue 6 2211 Portability Introduction 393 margin legend. 394 IP6 IPV6 395 The functionality described is optional. The functionality described is also an extension to the 396 ISO C standard. 397 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. 398 Where additional semantics apply to a function, the material is identified by use of the IP6 399 margin legend. | 400 MC1 Advisory Information and either Memory Mapped Files or Shared Memory Objects 401 The functionality described is optional. The functionality described is also an extension to the 402 ISO C standard. 403 This is a shorthand notation for combinations of multiple option codes. 404 Where applicable, functions are marked with the MC1 margin legend in the SYNOPSIS section. 405 Where additional semantics apply to a function, the material is identified by use of the MC1 406 margin legend. 407 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, Section 1.5.2, Margin Code 408 Notation. 409 MC2 Memory Mapped Files, Shared Memory Objects, or Memory Protection 410 The functionality described is optional. The functionality described is also an extension to the 411 ISO C standard. 412 This is a shorthand notation for combinations of multiple option codes. 413 Where applicable, functions are marked with the MC2 margin legend in the SYNOPSIS section. 414 Where additional semantics apply to a function, the material is identified by use of the MC2 415 margin legend. 416 Refer to the Base Definitions volume of IEEE Std 1003.1-200x, Section 1.5.2, Margin Code 417 Notation. 418 MF Memory Mapped Files 419 The functionality described is optional. The functionality described is also an extension to the 420 ISO C standard. 421 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. 422 Where additional semantics apply to a function, the material is identified by use of the MF 423 margin legend. 424 ML Process Memory Locking 425 The functionality described is optional. The functionality described is also an extension to the 426 ISO C standard. 427 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. 428 Where additional semantics apply to a function, the material is identified by use of the ML 429 margin legend. 430 MLR Range Memory Locking 431 The functionality described is optional. The functionality described is also an extension to the 432 ISO C standard. 433 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. 434 Where additional semantics apply to a function, the material is identified by use of the MLR 435 margin legend. 2212 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 436 MON Monotonic Clock 437 The functionality described is optional. The functionality described is also an extension to the 438 ISO C standard. 439 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. 440 Where additional semantics apply to a function, the material is identified by use of the MON 441 margin legend. 442 MPR Memory Protection 443 The functionality described is optional. The functionality described is also an extension to the 444 ISO C standard. 445 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. 446 Where additional semantics apply to a function, the material is identified by use of the MPR 447 margin legend. 448 MSG Message Passing 449 The functionality described is optional. The functionality described is also an extension to the 450 ISO C standard. 451 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. 452 Where additional semantics apply to a function, the material is identified by use of the MSG 453 margin legend. 454 MX IEC 60559 Floating-Point Option 455 The functionality described is optional. The functionality described is also an extension to the 456 ISO C standard. 457 Where applicable, functions are marked with the MX margin legend in the SYNOPSIS section. 458 Where additional semantics apply to a function, the material is identified by use of the MX 459 margin legend. 460 OB Obsolescent 461 The functionality described may be withdrawn in a future version of this volume of 462 IEEE Std 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI 463 Applications shall not use obsolescent features. 464 OF Output Format Incompletely Specified 465 The functionality described is an XSI extension. The format of the output produced by the utility 466 is not fully specified. It is therefore not possible to post-process this output in a consistent 467 fashion. Typical problems include unknown length of strings and unspecified field delimiters. 468 OH Optional Header 469 In the SYNOPSIS section of some interfaces in the System Interfaces volume of 470 IEEE Std 1003.1-200x an included header is marked as in the following example: 471 OH #include 472 #include 473 struct group *getgrnam(const char *name); 474 This indicates that the marked header is not required on XSI-conformant systems. 475 PIO Prioritized Input and Output 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 PIO margin legend in the SYNOPSIS section. 479 Where additional semantics apply to a function, the material is identified by use of the PIO 480 margin legend. Shell and Utilities, Issue 6 2213 Portability Introduction 481 PS Process Scheduling 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 PS margin legend in the SYNOPSIS section. 485 Where additional semantics apply to a function, the material is identified by use of the PS 486 margin legend. 487 RS Raw Sockets 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 RS margin legend in the SYNOPSIS section. 491 Where additional semantics apply to a function, the material is identified by use of the RS 492 margin legend. 493 RTS Realtime Signals Extension 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 RTS margin legend in the SYNOPSIS section. 497 Where additional semantics apply to a function, the material is identified by use of the RTS 498 margin legend. 499 SD Software Development Utilities 500 The functionality described is optional. 501 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. 502 Where additional semantics apply to a utility, the material is identified by use of the SD margin 503 legend. 504 SEM Semaphores 505 The functionality described is optional. The functionality described is also an extension to the 506 ISO C standard. 507 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. 508 Where additional semantics apply to a function, the material is identified by use of the SEM 509 margin legend. 510 SHM Shared Memory Objects 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 SHM margin legend in the SYNOPSIS section. 514 Where additional semantics apply to a function, the material is identified by use of the SHM 515 margin legend. 516 SIO Synchronized Input and Output 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 SIO margin legend in the SYNOPSIS section. 520 Where additional semantics apply to a function, the material is identified by use of the SIO 521 margin legend. 522 SPI Spin Locks 523 The functionality described is optional. The functionality described is also an extension to the 524 ISO C standard. 2214 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 525 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. 526 Where additional semantics apply to a function, the material is identified by use of the SPI 527 margin legend. 528 SPN Spawn 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 SPN margin legend in the SYNOPSIS section. 532 Where additional semantics apply to a function, the material is identified by use of the SPN 533 margin legend. 534 SS Process Sporadic Server 535 The functionality described is optional. The functionality described is also an extension to the 536 ISO C standard. 537 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. 538 Where additional semantics apply to a function, the material is identified by use of the SS 539 margin legend. 540 TCT Thread CPU-Time Clocks 541 The functionality described is optional. The functionality described is also an extension to the 542 ISO C standard. 543 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. 544 Where additional semantics apply to a function, the material is identified by use of the TCT 545 margin legend. 546 TEF Trace Event Filter 547 The functionality described is optional. The functionality described is also an extension to the 548 ISO C standard. 549 Where applicable, functions are marked with the TEF margin legend in the SYNOPSIS section. 550 Where additional semantics apply to a function, the material is identified by use of the TEF 551 margin legend. 552 THR Threads 553 The functionality described is optional. The functionality described is also an extension to the 554 ISO C standard. 555 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. 556 Where additional semantics apply to a function, the material is identified by use of the THR 557 margin legend. 558 TMO Timeouts 559 The functionality described is optional. The functionality described is also an extension to the 560 ISO C standard. 561 Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. 562 Where additional semantics apply to a function, the material is identified by use of the TMO 563 margin legend. 564 TMR Timers 565 The functionality described is optional. The functionality described is also an extension to the 566 ISO C standard. 567 Where applicable, functions are marked with the TMR margin legend in the SYNOPSIS section. 568 Where additional semantics apply to a function, the material is identified by use of the TMR 569 margin legend. Shell and Utilities, Issue 6 2215 Portability Introduction 570 TPI Thread Priority Inheritance 571 The functionality described is optional. The functionality described is also an extension to the 572 ISO C standard. 573 Where applicable, functions are marked with the TPI margin legend in the SYNOPSIS section. 574 Where additional semantics apply to a function, the material is identified by use of the TPI 575 margin legend. 576 TPP Thread Priority Protection 577 The functionality described is optional. The functionality described is also an extension to the 578 ISO C standard. 579 Where applicable, functions are marked with the TPP margin legend in the SYNOPSIS section. 580 Where additional semantics apply to a function, the material is identified by use of the TPP 581 margin legend. 582 TPS Thread Execution Scheduling 583 The functionality described is optional. The functionality described is also an extension to the 584 ISO C standard. 585 Where applicable, functions are marked with the TPS margin legend for the SYNOPSIS section. 586 Where additional semantics apply to a function, the material is identified by use of the TPS 587 margin legend. 588 TRC Trace 589 The functionality described is optional. The functionality described is also an extension to the 590 ISO C standard. 591 Where applicable, functions are marked with the TRC margin legend in the SYNOPSIS section. 592 Where additional semantics apply to a function, the material is identified by use of the TRC 593 margin legend. 594 TRI Trace Inherit 595 The functionality described is optional. The functionality described is also an extension to the 596 ISO C standard. 597 Where applicable, functions are marked with the TRI margin legend in the SYNOPSIS section. 598 Where additional semantics apply to a function, the material is identified by use of the TRI 599 margin legend. 600 TRL Trace Log 601 The functionality described is optional. The functionality described is also an extension to the 602 ISO C standard. 603 Where applicable, functions are marked with the TRL margin legend in the SYNOPSIS section. 604 Where additional semantics apply to a function, the material is identified by use of the TRL 605 margin legend. 606 TSA Thread Stack Address Attribute 607 The functionality described is optional. The functionality described is also an extension to the 608 ISO C standard. 609 Where applicable, functions are marked with the TSA margin legend for the SYNOPSIS section. 610 Where additional semantics apply to a function, the material is identified by use of the TSA 611 margin legend. 612 TSF Thread-Safe Functions 613 The functionality described is optional. The functionality described is also an extension to the 614 ISO C standard. 2216 Technical Standard (2001) (Draft April 16, 2001) Introduction Portability 615 Where applicable, functions are marked with the TSF margin legend in the SYNOPSIS section. 616 Where additional semantics apply to a function, the material is identified by use of the TSF 617 margin legend. 618 TSH Thread Process-Shared Synchronization 619 The functionality described is optional. The functionality described is also an extension to the 620 ISO C standard. 621 Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. 622 Where additional semantics apply to a function, the material is identified by use of the TSH 623 margin legend. 624 TSP Thread Sporadic Server 625 The functionality described is optional. The functionality described is also an extension to the 626 ISO C standard. 627 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. 628 Where additional semantics apply to a function, the material is identified by use of the TSP 629 margin legend. 630 TSS Thread Stack Address Size 631 The functionality described is optional. The functionality described is also an extension to the 632 ISO C standard. 633 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. 634 Where additional semantics apply to a function, the material is identified by use of the TSS 635 margin legend. 636 TYM Typed Memory Objects 637 The functionality described is optional. The functionality described is also an extension to the 638 ISO C standard. 639 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. 640 Where additional semantics apply to a function, the material is identified by use of the TYM 641 margin legend. | 642 UP User Portability Utilities 643 The functionality described is optional. 644 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. 645 Where additional semantics apply to a utility, the material is identified by use of the UP margin 646 legend. 647 XSI Extension 648 The functionality described is an XSI extension. Functionality marked XSI is also an extension to 649 the ISO C standard. Application writers may confidently make use of an extension on all 650 systems supporting the X/Open System Interfaces Extension. 651 If an entire SYNOPSIS section is shaded and marked XSI, all the functionality described in that 652 reference page is an extension. See the Base Definitions volume of IEEE Std 1003.1-200x, Section 653 3.439, XSI. 654 XSR XSI STREAMS 655 The functionality described is optional. The functionality described is also an extension to the 656 ISO C standard. 657 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. 658 Where additional semantics apply to a function, the material is identified by use of the XSR 659 margin legend. Shell and Utilities, Issue 6 2217 Utility Limits Introduction 660 1.9 Utility Limits 661 This section lists magnitude limitations imposed by a specific implementation. The braces 662 notation, {LIMIT}, is used in this volume of IEEE Std 1003.1-200x to indicate these values, but the 663 braces are not part of the name. 664 Table 1-3 Utility Limit Minimum Values 665 ______________________________________________________________________________________ 666 _ Name Description Value _____________________________________________________________________________________ 667 {POSIX2_BC_BASE_MAX} The maximum obase value allowed by the bc 99 668 utility. 669 {POSIX2_BC_DIM_MAX} The maximum number of elements permitted in 2048 670 an array by the bc utility. 671 {POSIX2_BC_SCALE_MAX} The maximum scale value allowed by the bc 99 672 utility. 673 {POSIX2_BC_STRING_MAX} The maximum length of a string constant 1000 674 accepted by the bc utility. 675 {POSIX2_COLL_WEIGHTS_MAX} The maximum number of weights that can be 2 676 assigned to an entry of the LC_COLLATE order 677 keyword in the locale definition file; see the 678 border_start keyword in the Base Definitions 679 volume of IEEE Std 1003.1-200x, Section 7.3.2, 680 LC_COLLATE. 681 {POSIX2_EXPR_NEST_MAX} The maximum number of expressions that can 32 682 be nested within parentheses by the expr utility. 683 {POSIX2_LINE_MAX} Unless otherwise noted, the maximum length, in 2048 684 bytes, of the input line of a utility (either 685 standard input or another file), when the utility 686 is described as processing text files. The length 687 includes room for the trailing newline. 688 {POSIX2_RE_DUP_MAX} The maximum number of repeated occurrences 255 689 of a BRE permitted when using the interval 690 notation \{m,n\}; see the Base Definitions 691 volume of IEEE Std 1003.1-200x, Section 9.3.6, 692 BREs Matching Multiple Characters. 693 {POSIX2_VERSION} This value indicates the version of the utilities in 200xxxL 694 this volume of IEEE Std 1003.1-200x that are 695 provided by the implementation. It changes 696 with each published version. _ _____________________________________________________________________________________ 697 The values specified in Table 1-3 represent the lowest values conforming implementations shall 698 provide and, consequently, the largest values on which an application can rely without further 699 enquiries, as described below. These values shall be accessible to applications via the getconf 700 utility (see getconf (on page 2683)) and through the sysconf( ) function defined in the System 701 Interfaces volume of IEEE Std 1003.1-200x. The literal names shown in Table 1-3 apply only to 702 the getconf utility; the high-level language binding describes the exact form of each name to be 703 used by the interfaces in that binding. 704 Implementations may provide more liberal, or less restrictive, values than shown in Table 1-3. 705 These possibly more liberal values are accessible using the symbols in Table 1-4 (on page 2219). 2218 Technical Standard (2001) (Draft April 16, 2001) Introduction Utility Limits 706 The sysconf( ) function defined in the System Interfaces volume of IEEE Std 1003.1-200x or the 707 getconf utility return the value of each symbol on each specific implementation. The value so 708 retrieved is the largest, or most liberal, value that is available throughout the session lifetime, as 709 determined at session creation. The literal names shown in the table apply only to the getconf 710 utility; the high-level language binding describes the exact form of each name to be used by the 711 interfaces in that binding. 712 All numeric limits defined by the System Interfaces volume of IEEE Std 1003.1-200x, such as 713 {PATH_MAX}, shall also apply to this volume of IEEE Std 1003.1-200x. All the utilities defined | 714 by this volume of IEEE Std 1003.1-200x are implicitly limited by these values, unless otherwise | 715 noted in the utility descriptions. | 716 It is not guaranteed that the application can actually reach the specified limit of an 717 implementation in any given case, or at all, as a lack of virtual memory or other resources may 718 prevent this. The limit value indicates only that the implementation does not specifically impose 719 any arbitrary, more restrictive limit. 720 Table 1-4 Symbolic Utility Limits 721 __________________________________________________________________________________ 722 _ Name Description Minimum Value _________________________________________________________________________________ 723 {BC_BASE_MAX} The maximum obase value {POSIX2_BC_BASE_MAX} 724 allowed by the bc utility. 725 {BC_DIM_MAX} The maximum number of {POSIX2_BC_DIM_MAX} 726 elements permitted in an 727 array by the bc utility. 728 {BC_SCALE_MAX} The maximum scale value {POSIX2_BC_SCALE_MAX} 729 allowed by the bc utility. 730 {BC_STRING_MAX} The maximum length of a {POSIX2_BC_STRING_MAX} 731 string constant accepted by 732 the bc utility. 733 {COLL_WEIGHTS_MAX} The maximum number of {POSIX2_COLL_WEIGHTS_MAX} 734 weights that can be 735 assigned to an entry of the 736 LC_COLLATE order 737 keyword in the locale 738 definition file; see the 739 order_start keyword in the 740 Base Definitions volume of 741 IEEE Std 1003.1-200x, 742 Section 7.3.2, LC_COLLATE. 743 {EXPR_NEST_MAX} The maximum number of {POSIX2_EXPR_NEST_MAX} 744 expressions that can be 745 nested within parentheses 746 by the expr utility. 747 {LINE_MAX} Unless otherwise noted, the {POSIX2_LINE_MAX} 748 maximum length, in bytes, 749 of the input line of a utility 750 (either standard input or 751 another file), when the 752 utility is described as 753 _ _________________________________________________________________________________ Shell and Utilities, Issue 6 2219 Utility Limits Introduction 754 __________________________________________________________________________________ 755 _ Name Description Minimum Value _________________________________________________________________________________ 756 processing text files. The 757 length includes room for the 758 trailing newline. 759 {RE_DUP_MAX} The maximum number of {POSIX2_RE_DUP_MAX} 760 repeated occurrences of a 761 BRE permitted when using 762 the interval notation 763 \{m,n\}; see the Base 764 Definitions volume of 765 IEEE Std 1003.1-200x, 766 Section 9.3.6, BREs 767 Matching Multiple 768 Characters. _ _________________________________________________________________________________ 769 The following value may be a constant within an implementation or may vary from one 770 pathname to another. 771 {POSIX2_SYMLINKS} 772 When referring to a directory, the system supports the creation of symbolic links within that 773 directory; for non-directory files, the meaning of {POSIX2_SYMLINKS} is undefined. 774 1.10 Grammar Conventions 775 Portions of this volume of IEEE Std 1003.1-200x are expressed in terms of a special grammar 776 notation. It is used to portray the complex syntax of certain program input. The grammar is 777 based on the syntax used by the yacc utility. However, it does not represent fully functional yacc 778 input, suitable for program use; the lexical processing and all semantic requirements are 779 described only in textual form. The grammar is not based on source used in any traditional 780 implementation and has not been tested with the semantic code that would normally be 781 required to accompany it. Furthermore, there is no implication that the partial yacc code 782 presented represents the most efficient, or only, means of supporting the complex syntax within 783 the utility. Implementations may use other programming languages or algorithms, as long as the 784 syntax supported is the same as that represented by the grammar. 785 The following typographical conventions are used in the grammar; they have no significance 786 except to aid in reading. 787 * The identifiers for the reserved words of the language are shown with a leading capital letter. 788 (These are terminals in the grammar; for example, While, Case.) 789 * The identifiers for terminals in the grammar are all named with uppercase letters and 790 underscores; for example, NEWLINE, ASSIGN_OP, NAME. 791 * The identifiers for non-terminals are all lowercase. 2220 Technical Standard (2001) (Draft April 16, 2001) Introduction Utility Description Defaults 792 1.11 Utility Description Defaults 793 This section describes all of the subsections used within the utility descriptions, including: 794 * Intended usage of the section 795 * Global defaults that affect all the standard utilities 796 * The meanings of notations used in this volume of IEEE Std 1003.1-200x that are specific to 797 individual utility sections 798 NAME | 799 This section gives the name or names of the utility and briefly states its purpose. 800 SYNOPSIS 801 The SYNOPSIS section summarizes the syntax of the calling sequence for the utility, 802 including options, option-arguments, and operands. Standards for utility naming are 803 described in the Base Definitions volume of IEEE Std 1003.1-200x, Section 12.2, Utility 804 Syntax Guidelines; for describing the utility's arguments in the Base Definitions volume 805 of IEEE Std 1003.1-200x, Section 12.1, Utility Argument Syntax. 806 DESCRIPTION 807 The DESCRIPTION section describes the actions of the utility. If the utility has a very 808 complex set of subcommands or its own procedural language, an EXTENDED 809 DESCRIPTION section is also provided. Most explanations of optional functionality are 810 omitted here, as they are usually explained in the OPTIONS section. 811 As stated in Section 1.7.1.11 (on page 2207), some functions are described in terms of | 812 equivalent functionality. When specific functions are cited, the implementation shall | 813 provide equivalent functionality including side effects associated with successful | 814 execution of the function. The treatment of errors and intermediate results from the | 815 individual functions cited is generally not specified by this volume of | 816 IEEE Std 1003.1-200x. See the utility's EXIT STATUS and CONSEQUENCES OF | 817 ERRORS sections for all actions associated with errors encountered by the utility. | 818 OPTIONS 819 The OPTIONS section describes the utility options and option-arguments, and how 820 they modify the actions of the utility. Standard utilities that have options either fully 821 comply with the Base Definitions volume of IEEE Std 1003.1-200x, Section 12.2, Utility 822 Syntax Guidelines or describe all deviations. Apparent disagreements between 823 functionality descriptions in the OPTIONS and DESCRIPTION (or EXTENDED 824 DESCRIPTION) sections are always resolved in favor of the OPTIONS section. 825 Each OPTIONS section that uses the phrase ``The . . . utility shall conform to the Utility 826 Syntax Guidelines . . .'' refers only to the use of the utility as specified by this volume of 827 IEEE Std 1003.1-200x; implementation extensions should also conform to the 828 guidelines, but may allow exceptions for historical practice. 829 Unless otherwise stated in the utility description, when given an option unrecognized 830 by the implementation, or when a required option-argument is not provided, standard 831 utilities shall issue a diagnostic message to standard error and exit with a non-zero exit 832 status. 833 All utilities in this volume of IEEE Std 1003.1-200x shall be capable of processing | 834 arguments using eight-bit transparency. | 835 Default Behavior: When this section is listed as ``None.'', it means that the 836 implementation need not support any options. Standard utilities that do not accept 837 options, but that do accept operands, shall recognize "- -" as a first argument to be Shell and Utilities, Issue 6 2221 Utility Description Defaults Introduction 838 discarded. 839 The requirement for recognizing "- -" is because conforming applications need a way | 840 to shield their operands from any arbitrary options that the implementation may | 841 provide as an extension. For example, if the standard utility foo is listed as taking no 842 options, and the application needed to give it a pathname with a leading hyphen, it 843 could safely do it as: 844 foo - - -myfile | 845 and avoid any problems with -m used as an extension. 846 OPERANDS 847 The OPERANDS section describes the utility operands, and how they affect the actions 848 of the utility. Apparent disagreements between functionality descriptions in the 849 OPERANDS and DESCRIPTION (or EXTENDED DESCRIPTION) sections shall be 850 resolved in favor of the OPERANDS section. 851 If an operand naming a file can be specified as '-', which means to use the standard 852 input instead of a named file, this is explicitly stated in this section. Unless otherwise 853 stated, the use of multiple instances of '-' to mean standard input in a single 854 command produces unspecified results. 855 Unless otherwise stated, the standard utilities that accept operands shall process those 856 operands in the order specified in the command line. 857 Default Behavior: When this section is listed as ``None.'', it means that the 858 implementation need not support any operands. 859 STDIN 860 The STDIN section describes the standard input of the utility. This section is frequently 861 merely a reference to the following section, as many utilities treat standard input and 862 input files in the same manner. Unless otherwise stated, all restrictions described in the 863 INPUT FILES section shall apply to this section as well. 864 Use of a terminal for standard input can cause any of the standard utilities that read 865 standard input to stop when used in the background. For this reason, applications 866 should not use interactive features in scripts to be placed in the background. 867 The specified standard input format of the standard utilities shall not depend on the 868 existence or value of the environment variables defined in this volume of 869 IEEE Std 1003.1-200x, except as provided by this volume of IEEE Std 1003.1-200x. 870 Default Behavior: When this section is listed as ``Not used.'', it means that the 871 standard input shall not be read when the utility is used as described by this volume of 872 IEEE Std 1003.1-200x. 873 INPUT FILES 874 The INPUT FILES section describes the files, other than the standard input, used as 875 input by the utility. It includes files named as operands and option-arguments as well 876 as other files that are referred to, such as start-up and initialization files, databases, and 877 so on. Commonly-used files are generally described in one place and cross-referenced 878 by other utilities. 879 All utilities in this volume of IEEE Std 1003.1-200x shall be capable of processing input | 880 files using eight-bit transparency. | 881 When a standard utility reads a seekable input file and terminates without an error 882 before it reaches end-of-file, the utility shall ensure that the file offset in the open file 2222 Technical Standard (2001) (Draft April 16, 2001) Introduction Utility Description Defaults 883 description is properly positioned just past the last byte processed by the utility. For 884 files that are not seekable, the state of the file offset in the open file description for that | 885 file is unspecified. A conforming application shall not assume that the following three | 886 commands are equivalent: 887 tail -n +2 file | 888 (sed -n 1q; cat) < file | 889 cat file | (sed -n 1q; cat) | 890 The second command is equivalent to the first only when the file is seekable. The third 891 command leaves the file offset in the open file description in an unspecified state. Other 892 utilities, such as head, read, and sh, have similar properties. 893 Some of the standard utilities, such as filters, process input files a line or a block at a 894 time and have no restrictions on the maximum input file size. Some utilities may have 895 size limitations that are not as obvious as file space or memory limitations. Such 896 limitations should reflect resource limitations of some sort, not arbitrary limits set by 897 implementors. Implementations shall document those utilities that are limited by 898 constraints other than file system space, available memory, and other limits specifically 899 cited by this volume of IEEE Std 1003.1-200x, and identify what the constraint is and 900 indicate a way of estimating when the constraint would be reached. Similarly, some 901 utilities descend the directory tree (recursively). Implementations shall also document 902 any limits that they may have in descending the directory tree that are beyond limits 903 cited by this volume of IEEE Std 1003.1-200x. 904 When an input file is described as a text file, the utility produces undefined results if 905 given input that is not from a text file, unless otherwise stated. Some utilities (for 906 example, make, read, sh) allow for continued input lines using an escaped 907 convention; unless otherwise stated, the utility need not be able to accumulate more 908 than {LINE_MAX} bytes from a set of multiple, continued input lines. Thus, for a | 909 conforming application the total of all the continued lines in a set cannot exceed | 910 {LINE_MAX}. If a utility using the escaped convention detects an end-of- 911 file condition immediately after an escaped , the results are unspecified. 912 Record formats are described in a notation similar to that used by the C-language 913 function, printf( ). See the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 5, 914 File Format Notation for a description of this notation. The format description is 915 intended to be sufficiently rigorous to allow other applications to generate these input 916 files. However, since s can legitimately be included in some of the fields 917 described by the standard utilities, particularly in locales other than the POSIX locale, 918 this intent is not always realized. 919 Default Behavior: When this section is listed as ``None.'', it means that no input files 920 are required to be supplied when the utility is used as described by this volume of 921 IEEE Std 1003.1-200x. 922 ENVIRONMENT VARIABLES 923 The ENVIRONMENT VARIABLES section lists what variables affect the utility's 924 execution. 925 The entire manner in which environment variables described in this volume of 926 IEEE Std 1003.1-200x affect the behavior of each utility is described in the 927 ENVIRONMENT VARIABLES section for that utility, in conjunction with the global 928 XSI effects of the LANG, LC_ALL, and NLSPATH environment variables described in the 929 Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables. 930 The existence or value of environment variables described in this volume of Shell and Utilities, Issue 6 2223 Utility Description Defaults Introduction 931 IEEE Std 1003.1-200x shall not otherwise affect the specified behavior of the standard 932 utilities. Any effects of the existence or value of environment variables not described by 933 this volume of IEEE Std 1003.1-200x upon the standard utilities are unspecified. 934 For those standard utilities that use environment variables as a means for selecting a 935 utility to execute (such as CC in make), the string provided to the utility is subjected to 936 the path search described for PATH in the Base Definitions volume of 937 IEEE Std 1003.1-200x, Chapter 8, Environment Variables. 938 All utilities in this volume of IEEE Std 1003.1-200x shall be capable of processing | 939 environment variable names and values using eight-bit transparency. | 940 Default Behavior: When this section is listed as ``None.'', it means that the behavior of 941 the utility is not directly affected by environment variables described by this volume of 942 IEEE Std 1003.1-200x when the utility is used as described by this volume of 943 IEEE Std 1003.1-200x. 944 ASYNCHRONOUS EVENTS 945 The ASYNCHRONOUS EVENTS section lists how the utility reacts to such events as 946 signals and what signals are caught. 947 Default Behavior: When this section is listed as ``Default.'', or it refers to ``the standard 948 action for all other signals; see Section 1.11 (on page 2221)'' it means that the action 949 taken as a result of the signal shall be one of the following: 950 1. The action shall be that inherited from the parent according to the rules of | 951 inheritance of signal actions defined in the System Interfaces volume of | 952 IEEE Std 1003.1-200x. | 953 2. When no action has been taken to change the default, the default action shall be | 954 that specified by the System Interfaces volume of IEEE Std 1003.1-200x. | 955 3. The result of the utility's execution is as if default actions had been taken. 956 A utility is permitted to catch a signal, perform some additional processing (such as 957 deleting temporary files), restore the default signal action (or action inherited from the 958 parent process), and resignal itself. 959 STDOUT 960 The STDOUT section completely describes the standard output of the utility. This 961 section is frequently merely a reference to the following section, OUTPUT FILES, 962 because many utilities treat standard output and output files in the same manner. | 963 Use of a terminal for standard output may cause any of the standard utilities that write 964 standard output to stop when used in the background. For this reason, applications 965 should not use interactive features in scripts to be placed in the background. 966 Record formats are described in a notation similar to that used by the C-language 967 function, printf( ). See the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 5, 968 File Format Notation for a description of this notation. 969 The specified standard output of the standard utilities shall not depend on the 970 existence or value of the environment variables defined in this volume of 971 IEEE Std 1003.1-200x, except as provided by this volume of IEEE Std 1003.1-200x. 972 Some of the standard utilities describe their output using the verb display, defined in 973 the Base Definitions volume of IEEE Std 1003.1-200x, Section 3.132, Display. Output 974 described in the STDOUT sections of such utilities may be produced using means other 975 than standard output. When standard output is directed to a terminal, the output 2224 Technical Standard (2001) (Draft April 16, 2001) Introduction Utility Description Defaults 976 described shall be written directly to the terminal. Otherwise, the results are undefined. 977 Default Behavior: When this section is listed as ``Not used.'', it means that the 978 standard output shall not be written when the utility is used as described by this 979 volume of IEEE Std 1003.1-200x. 980 STDERR 981 The STDERR section describes the standard error output of the utility. Only those 982 messages that are purposely sent by the utility are described. 983 Use of a terminal for standard error may cause any of the standard utilities that write 984 standard error output to stop when used in the background. For this reason, 985 applications should not use interactive features in scripts to be placed in the 986 background. 987 The format of diagnostic messages for most utilities is unspecified, but the language 988 and cultural conventions of diagnostic and informative messages whose format is 989 unspecified by this volume of IEEE Std 1003.1-200x should be affected by the setting of 990 XSI LC_MESSAGES andNLSPATH. 991 The specified standard error output of standard utilities shall not depend on the 992 existence or value of the environment variables defined in this volume of 993 IEEE Std 1003.1-200x, except as provided by this volume of IEEE Std 1003.1-200x. 994 Default Behavior: When this section is listed as ``Used only for diagnostic messages.'', 995 it means that, unless otherwise stated, the diagnostic messages shall be sent to the 996 standard error only when the exit status is non-zero and the utility is used as described 997 by this volume of IEEE Std 1003.1-200x. 998 When this section is listed as ``Not used.'', it means that the standard error shall not be 999 used when the utility is used as described in this volume of IEEE Std 1003.1-200x. 1000 OUTPUT FILES 1001 The OUTPUT FILES section completely describes the files created or modified by the 1002 utility. Temporary or system files that are created for internal usage by this utility or 1003 other parts of the implementation (for example, spool, log, and audit files) are not 1004 described in this, or any, section. The utilities creating such files and the names of such 1005 files are unspecified. If applications are written to use temporary or intermediate files, 1006 they should use the TMPDIR environment variable, if it is set and represents an 1007 accessible directory, to select the location of temporary files. 1008 Implementations shall ensure that temporary files, when used by the standard utilities, 1009 are named so that different utilities or multiple instances of the same utility can operate 1010 simultaneously without regard to their working directories, or any other process 1011 characteristic other than process ID. There are two exceptions to this rule: 1012 1. Resources for temporary files other than the name space (for example, disk space, 1013 available directory entries, or number of processes allowed) are not guaranteed. 1014 2. Certain standard utilities generate output files that are intended as input for other 1015 utilities (for example, lex generates lex.yy.c), and these cannot have unique 1016 names. These cases are explicitly identified in the descriptions of the respective 1017 utilities. 1018 Any temporary file created by the implementation shall be removed by the 1019 implementation upon a utility's successful exit, exit because of errors, or before 1020 termination by any of the SIGHUP, SIGINT, or SIGTERM signals, unless specified 1021 otherwise by the utility description. Shell and Utilities, Issue 6 2225 Utility Description Defaults Introduction 1022 Receipt of the SIGQUIT signal should generally cause termination (unless in some 1023 debugging mode) that would bypass any attempted recovery actions. 1024 Record formats are described in a notation similar to that used by the C-language 1025 function, printf( ); see the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 5, 1026 File Format Notation for a description of this notation. 1027 Default Behavior: When this section is listed as ``None.'', it means that no files are 1028 created or modified as a consequence of direct action on the part of the utility when the 1029 utility is used as described by this volume of IEEE Std 1003.1-200x. However, the 1030 utility may create or modify system files, such as log files, that are outside the utility's 1031 normal execution environment. 1032 EXTENDED DESCRIPTION 1033 The EXTENDED DESCRIPTION section provides a place for describing the actions of 1034 very complicated utilities, such as text editors or language processors, which typically 1035 have elaborate command languages. 1036 Default Behavior: When this section is listed as ``None.'', no further description is 1037 necessary. 1038 EXIT STATUS 1039 The EXIT STATUS section describes the values the utility shall return to the calling 1040 program, or shell, and the conditions that cause these values to be returned. Usually, 1041 utilities return zero for successful completion and values greater than zero for various 1042 error conditions. If specific numeric values are listed in this section, the system shall 1043 use those values for the errors described. In some cases, status values are listed more 1044 loosely, such as >0. A strictly conforming application shall not rely on any specific 1045 value in the range shown and shall be prepared to receive any value in the range. 1046 For example, a utility may list zero as a successful return, 1 as a failure for a specific 1047 reason, and >1 as ``an error occurred''. In this case, unspecified conditions may cause a 1048 2 or 3, or other value, to be returned. A conforming application should be written so | 1049 that it tests for successful exit status values (zero in this case), rather than relying upon | 1050 the single specific error value listed in this volume of IEEE Std 1003.1-200x. In that 1051 way, it has maximum portability, even on implementations with extensions. 1052 Unspecified error conditions may be represented by specific values not listed in this 1053 volume of IEEE Std 1003.1-200x. 1054 CONSEQUENCES OF ERRORS 1055 The CONSEQUENCES OF ERRORS section describes the effects on the environment, 1056 file systems, process state, and so on, when error conditions occur. It does not describe 1057 error messages produced or exit status values used. 1058 The many reasons for failure of a utility are generally not specified by the utility 1059 descriptions. Utilities may terminate prematurely if they encounter: invalid usage of 1060 options, arguments, or environment variables; invalid usage of the complex syntaxes 1061 expressed in EXTENDED DESCRIPTION sections; difficulties accessing, creating, 1062 reading, or writing files; or difficulties associated with the privileges of the process. 1063 The following shall apply to each utility, unless otherwise stated: 1064 * If the requested action cannot be performed on an operand representing a file, 1065 directory, user, process, and so on, the utility shall issue a diagnostic message to 1066 standard error and continue processing the next operand in sequence, but the final 1067 exit status shall be returned as non-zero. 2226 Technical Standard (2001) (Draft April 16, 2001) Introduction Utility Description Defaults 1068 For a utility that recursively traverses a file hierarchy (such as find or chown -R), if 1069 the requested action cannot be performed on a file or directory encountered in the 1070 hierarchy, the utility shall issue a diagnostic message to standard error and continue 1071 processing the remaining files in the hierarchy, but the final exit status shall be 1072 returned as non-zero. 1073 * If the requested action characterized by an option or option-argument cannot be 1074 performed, the utility shall issue a diagnostic message to standard error and the exit 1075 status returned shall be non-zero. 1076 * When an unrecoverable error condition is encountered, the utility shall exit with a 1077 non-zero exit status. 1078 * A diagnostic message shall be written to standard error whenever an error 1079 condition occurs. 1080 When a utility encounters an error condition several actions are possible, depending on 1081 the severity of the error and the state of the utility. Included in the possible actions of 1082 various utilities are: deletion of temporary or intermediate work files; deletion of 1083 incomplete files; validity checking of the file system or directory. 1084 Default Behavior: When this section is listed as ``Default.'', it means that any changes 1085 to the environment are unspecified. 1086 APPLICATION USAGE 1087 This section is non-normative. 1088 The APPLICATION USAGE section gives advice to the application programmer or user 1089 about the way the utility should be used. 1090 EXAMPLES 1091 This section is non-normative. 1092 The EXAMPLES section gives one or more examples of usage, where appropriate. In 1093 the event of conflict between an example and a normative part of the specification, the 1094 normative material is to be taken as correct. 1095 In all examples, quoting has been used, showing how sample commands (utility names 1096 combined with arguments) could be passed correctly to a shell (see sh) or as a string to 1097 the system( ) function defined in the System Interfaces volume of IEEE Std 1003.1-200x. 1098 Such quoting would not be used if the utility is invoked using one of the exec functions 1099 defined in the System Interfaces volume of IEEE Std 1003.1-200x. 1100 RATIONALE 1101 This section is non-normative. 1102 This section contains historical information concerning the contents of this volume of 1103 IEEE Std 1003.1-200x and why features were included or discarded by the standard 1104 developers. 1105 FUTURE DIRECTIONS 1106 This section is non-normative. 1107 The FUTURE DIRECTIONS section should be used as a guide to current thinking; there 1108 is not necessarily a commitment to implement all of these future directions in their 1109 entirety. 1110 SEE ALSO 1111 This section is non-normative. Shell and Utilities, Issue 6 2227 Utility Description Defaults Introduction 1112 The SEE ALSO section lists related entries. 1113 CHANGE HISTORY 1114 This section is non-normative. 1115 The CHANGE HISTORY section shows the derivation of the description used by this 1116 volume of IEEE Std 1003.1-200x and lists the functional differences between Issues 4 1117 and 6. 1118 Certain of the standard utilities describe how they can invoke other utilities or applications, such 1119 as by passing a command string to the command interpreter. The external influences (STDIN, 1120 ENVIRONMENT VARIABLES, and so on) and external effects (STDOUT, CONSEQUENCES OF 1121 ERRORS, and so on) of such invoked utilities are not described in the section concerning the 1122 standard utility that invokes them. 1123 1.12 Considerations for Utilities in Support of Files of Arbitrary Size 1124 The following utilities support files of any size up to the maximum that can be created by the 1125 implementation. This support includes correct writing of file size-related values (such as file 1126 sizes and offsets, line numbers, and block counts) and correct interpretation of command line 1127 arguments that contain such values. 1128 basename Return non-directory portion of pathname. 1129 cat Concatenate and print files. 1130 cd Change working directory. 1131 chgrp Change file group ownership. 1132 chmod Change file modes. 1133 chown Change file ownership. 1134 cksum Write file checksums and sizes. 1135 cmp Compare two files. 1136 cp Copy files. 1137 dd Convert and copy a file. 1138 df Report free disk space. 1139 dirname Return directory portion of pathname. 1140 du Estimate file space usage. 1141 find Find files. 1142 ln Link files. 1143 ls List directory contents. 1144 mkdir Make directories. 1145 mv Move files. 1146 pathchk Check pathnames. 1147 pwd Return working directory name. 2228 Technical Standard (2001) (Draft April 16, 2001) Introduction Considerations for Utilities in Support of Files of Arbitrary Size 1148 rm Remove directory entries. 1149 rmdir Remove directories. 1150 sh Shell, the standard command language interpreter. 1151 sum Print checksum and block or byte count of a file. 1152 test Evaluate expression. 1153 touch Change file access and modification times. 1154 ulimit Set or report file size limit. 1155 Exceptions to the requirement that utilities support files of any size up to the maximum are as 1156 follows: 1157 1. Uses of files as command scripts, or for configuration or control, are exempt. For example, 1158 it is not required that sh be able to read an arbitrarily large .profile. 1159 2. Shell input and output redirection are exempt. For example, it is not required that the 1160 redirections sum < file or echo foo > file succeed for an arbitrarily large existing file. 1161 1.13 Built-In Utilities | 1162 Any of the standard utilities may be implemented as regular built-in utilities within the | 1163 command language interpreter. This is usually done to increase the performance of frequently | 1164 used utilities or to achieve functionality that would be more difficult in a separate environment. | 1165 The utilities named in Table 1-5 are frequently provided in built-in form. All of the utilities | 1166 named in the table have special properties in terms of command search order within the shell, as | 1167 described in Section 2.9.1.1 (on page 2249). | 1168 Table 1-5 Regular Built-in Utilities | 1169 alias false jobs true |||||||||||||| 1170 bg fc kill umask |||||||||||| 1171 cd fg newgrp unalias |||||||||||| 1172 command getopts read wait |||||||||||| 1173 However, all of the standard utilities, including the regular built-ins in the table, but not the | 1174 special built-ins described in Section 2.14 (on page 2266), shall be implemented in a manner so | 1175 that they can be accessed via the exec family of functions as defined in the System Interfaces | 1176 volume of IEEE Std 1003.1-200x and can be invoked directly by those standard utilities that | 1177 require it (env, find, nice, nohup, time, xargs). | 1178 Since exec-able versions shall be provided for all utilities except for those listed in Section 2.14 | 1179 (on page 2266), an application running on a system that conforms to IEEE Std 1003.1-200x can | 1180 use the exec family of functions, in addition to the shell command interface provided by the | 1181 system( ) and popen( ) functions, to execute any of these utilities. | Shell and Utilities, Issue 6 2229 Introduction 1182 | 2230 Technical Standard (2001) (Draft April 16, 2001) Chapter 2 Shell Command Language 1183 1184 This chapter contains the definition of the Shell Command Language. 1185 2.1 Shell Introduction 1186 The shell is a command language interpreter. This chapter describes the syntax of that command 1187 language as it is used by the sh utility and the system( ) and popen( ) functions defined in the 1188 System Interfaces volume of IEEE Std 1003.1-200x. 1189 The shell operates according to the following general overview of operations. The specific 1190 details are included in the cited sections of this chapter. 1191 1. The shell reads its input from a file (see sh), from the -c option or from the system( ) and 1192 popen( ) functions defined in the System Interfaces volume of IEEE Std 1003.1-200x. If the 1193 first line of a file of shell commands starts with the characters "#!", the results are 1194 unspecified. 1195 2. The shell breaks the input into tokens: words and operators; see Section 2.3 (on page 2233). 1196 3. The shell parses the input into simple commands (see Section 2.9.1 (on page 2248)) and 1197 compound commands (see Section 2.9.4 (on page 2253)). 1198 4. The shell performs various expansions (separately) on different parts of each command, 1199 resulting in a list of pathnames and fields to be treated as a command and arguments; see 1200 Section 2.6 (on page 2238). 1201 5. The shell performs redirection (see Section 2.7 (on page 2244)) and removes redirection 1202 operators and their operands from the parameter list. 1203 6. The shell executes a function (see Section 2.9.5 (on page 2256)), built-in (see Section 2.14 1204 (on page 2266)), executable file, or script, giving the names of the arguments as positional 1205 parameters numbered 1 to n, and the name of the command (or in the case of a function 1206 within a script, the name of the script) as the positional parameter numbered 0 (see Section 1207 2.9.1.1 (on page 2249)). 1208 7. The shell optionally waits for the command to complete and collects the exit status (see 1209 Section 2.8.2 (on page 2248)). Shell and Utilities, Issue 6 2231 Quoting Shell Command Language 1210 2.2 Quoting 1211 Quoting is used to remove the special meaning of certain characters or words to the shell. 1212 Quoting can be used to preserve the literal meaning of the special characters in the next 1213 paragraph, prevent reserved words from being recognized as such, and prevent parameter 1214 expansion and command substitution within here-document processing (see Section 2.7.4 (on 1215 page 2246)). 1216 The application shall quote the following characters if they are to represent themselves: 1217 | & ; < > ( ) $ ` \ " ' | 1218 and the following may need to be quoted under certain circumstances. That is, these characters 1219 may be special depending on conditions described elsewhere in this volume of 1220 IEEE Std 1003.1-200x: 1221 * ? [ # ~ = % | 1222 The various quoting mechanisms are the escape character, single-quotes, and double-quotes. 1223 The here-document represents another form of quoting; see Section 2.7.4 (on page 2246). 1224 2.2.1 Escape Character (Backslash) 1225 A backslash that is not quoted shall preserve the literal value of the following character, with the 1226 exception of a . If a follows the backslash, the shell shall interpret this as 1227 line continuation. The backslash and s shall be removed before splitting the input into 1228 tokens. Since the escaped is removed entirely from the input and is not replaced by 1229 any white space, it cannot serve as a token separator. 1230 2.2.2 Single-Quotes 1231 Enclosing characters in single-quotes (' ') shall preserve the literal value of each character 1232 within the single-quotes. A single-quote cannot occur within single-quotes. 1233 2.2.3 Double-Quotes 1234 Enclosing characters in double-quotes (" ") shall preserve the literal value of all characters 1235 within the double-quotes, with the exception of the characters dollar sign, backquote, and 1236 backslash, as follows: 1237 $ The dollar sign shall retain its special meaning introducing parameter expansion (see 1238 Section 2.6.2 (on page 2239)), a form of command substitution (see Section 2.6.3 (on page 1239 2242)), and arithmetic expansion (see Section 2.6.4 (on page 2243)). 1240 The input characters within the quoted string that are also enclosed between "$(" and the 1241 matching ')' is not affected by the double-quotes, but rather shall define that command 1242 whose output replaces the "$(...)" when the word is expanded. The tokenizing rules in | 1243 Section 2.3 (on page 2233), not including the alias substitutions in Section 2.3.1 (on page | 1244 2234), shall be applied recursively to find the matching ')'. | 1245 Within the string of characters from an enclosed "${" to the matching '}', an even number 1246 of unescaped double-quotes or single-quotes, if any, shall occur. A preceding backslash 1247 character shall be used to escape a literal '{' or '}'. The rule in Section 2.6.2 (on page 1248 2239) shall be used to determine the matching '}'. 1249 ` The backquote shall retain its special meaning introducing the other form of command 1250 substitution (see Section 2.6.3 (on page 2242)). The portion of the quoted string from the 1251 initial backquote and the characters up to the next backquote that is not preceded by a 2232 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Quoting 1252 backslash, having escape characters removed, defines that command whose output replaces 1253 "`...`" when the word is expanded. Either of the following cases produces undefined 1254 results: 1255 * A single-quoted or double-quoted string that begins, but does not end, within the 1256 "`...`" sequence 1257 * A "`...`" sequence that begins, but does not end, within the same double-quoted 1258 string 1259 \ The backslash shall retain its special meaning as an escape character (see Section 2.2.1 (on 1260 page 2232)) only when followed by one of the following characters when considered special: 1261 $ ` " \ | 1262 The application shall ensure that a double-quote is preceded by a backslash to be included 1263 within double-quotes. The parameter '@' has special meaning inside double-quotes and is 1264 described in Section 2.5.2 (on page 2235). 1265 2.3 Token Recognition 1266 The shell shall read its input in terms of lines from a file, from a terminal in the case of an | 1267 interactive shell, or from a string in the case of sh -c or system( ). The input lines can be of | 1268 unlimited length. These lines shall be parsed using two major modes: ordinary token recognition | 1269 and processing of here-documents. 1270 When an io_here token has been recognized by the grammar (see Section 2.10 (on page 2257)), 1271 one or more of the subsequent lines immediately following the next NEWLINE token form the 1272 body of one or more here-documents and shall be parsed according to the rules of Section 2.7.4 1273 (on page 2246). 1274 When it is not processing an io_here, the shell shall break its input into tokens by applying the 1275 first applicable rule below to the next character in its input. The token shall be from the current 1276 position in the input until a token is delimited according to one of the rules below; the characters 1277 forming the token are exactly those in the input, including any quoting characters. If it is 1278 indicated that a token is delimited, and no characters have been included in a token, processing 1279 shall continue until an actual token is delimited. 1280 1. If the end of input is recognized, the current token shall be delimited. If there is no current 1281 token, the end-of-input indicator shall be returned as the token. 1282 2. If the previous character was used as part of an operator and the current character is not 1283 quoted and can be used with the current characters to form an operator, it shall be used as 1284 part of that (operator) token. | 1285 3. If the previous character was used as part of an operator and the current character cannot 1286 be used with the current characters to form an operator, the operator containing the 1287 previous character shall be delimited. 1288 4. If the current character is backslash, single-quote, or double-quote ('\\', '\'', or '"') 1289 and it is not quoted, it shall affect quoting for subsequent characters up to the end of the 1290 quoted text. The rules for quoting are as described in Section 2.2 (on page 2232). During 1291 token recognition no substitutions shall be actually performed, and the result token shall 1292 contain exactly the characters that appear in the input (except for joining), 1293 unmodified, including any embedded or enclosing quotes or substitution operators, 1294 between the quote mark and the end of the quoted text. The token shall not be delimited by 1295 the end of the quoted field. Shell and Utilities, Issue 6 2233 Token Recognition Shell Command Language 1296 5. If the current character is an unquoted '$' or '`', the shell shall identify the start of any 1297 candidates for parameter expansion (Section 2.6.2 (on page 2239)), command substitution 1298 (Section 2.6.3 (on page 2242)), or arithmetic expansion (Section 2.6.4 (on page 2243)) from 1299 their introductory unquoted character sequences: '$' or "${", "$(" or '`', and "$((", 1300 respectively. The shell shall read sufficient input to determine the end of the unit to be 1301 expanded (as explained in the cited sections). While processing the characters, if instances 1302 of expansions or quoting are found nested within the substitution, the shell shall 1303 recursively process them in the manner specified for the construct that is found. The 1304 characters found from the beginning of the substitution to its end, allowing for any 1305 recursion necessary to recognize embedded constructs, shall be included unmodified in the 1306 result token, including any embedded or enclosing substitution operators or quotes. The 1307 token shall not be delimited by the end of the substitution. 1308 6. If the current character is not quoted and can be used as the first character of a new 1309 operator, the current token (if any) shall be delimited. The current character shall be used 1310 as the beginning of the next (operator) token. 1311 7. If the current character is an unquoted , the current token shall be delimited. 1312 8. If the current character is an unquoted , any token containing the previous 1313 character is delimited and the current character shall be discarded. 1314 9. If the previous character was part of a word, the current character shall be appended to 1315 that word. 1316 10. If the current character is a '#', it and all subsequent characters up to, but excluding, the 1317 next shall be discarded as a comment. The that ends the line is not 1318 considered part of the comment. 1319 11. The current character is used as the start of a new word. 1320 Once a token is delimited, it is categorized as required by the grammar in Section 2.10 (on page 1321 2257). 1322 2.3.1 Alias Substitution 1323 UP XSI The processing of aliases shall be supported on all XSI-conformant systems or if the system 1324 supports the User Portability Utilities option (and the rest of this section is not further shaded for 1325 these options). 1326 After a token has been delimited, but before applying the grammatical rules in Section 2.10 (on 1327 page 2257), a resulting word that is identified to be the command name word of a simple 1328 command shall be examined to determine whether it is an unquoted, valid alias name. However, 1329 reserved words in correct grammatical context shall not be candidates for alias substitution. A 1330 valid alias name (see the Base Definitions volume of IEEE Std 1003.1-200x, Section 3.10, Alias 1331 Name) shall be one that has been defined by the alias utility and not subsequently undefined 1332 using unalias. Implementations also may provide predefined valid aliases that are in effect when 1333 the shell is invoked. To prevent infinite loops in recursive aliasing, if the shell is not currently 1334 processing an alias of the same name, the word shall be replaced by the value of the alias; 1335 otherwise, it shall not be replaced. 1336 If the value of the alias replacing the word ends in a , the shell shall check the next 1337 command word for alias substitution; this process shall continue until a word is found that is not 1338 a valid alias or an alias value does not end in a . 1339 When used as specified by this volume of IEEE Std 1003.1-200x, alias definitions shall not be 1340 inherited by separate invocations of the shell or by the utility execution environments invoked 1341 by the shell; see Section 2.12 (on page 2263). 2234 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Reserved Words 1342 2.4 Reserved Words 1343 Reserved words are words that have special meaning to the shell; see Section 2.9 (on page 2248). 1344 The following words shall be recognized as reserved words: 1345 ! do esac in ||||||||| 1346 { done fi then |||||||| 1347 } elif for until |||||||| 1348 case else if while |||||||| 1349 This recognition shall only occur when none of the characters is quoted and when the word is 1350 used as: 1351 * The first word of a command 1352 * The first word following one of the reserved words other than case, for, or in 1353 * The third word in a case or for command (only in is valid in this case) 1354 See the grammar in Section 2.10 (on page 2257). 1355 The following words may be recognized as reserved words on some implementations (when | 1356 none of the characters are quoted), causing unspecified results: | 1357 [ [ ] ] function select | 1358 Words that are the concatenation of a name and a colon (':') are reserved; their use produces | 1359 unspecified results. | 1360 2.5 Parameters and Variables 1361 A parameter can be denoted by a name, a number, or one of the special characters listed in 1362 Section 2.5.2. A variable is a parameter denoted by a name. 1363 A parameter is set if it has an assigned value (null is a valid value). Once a variable is set, it can 1364 only be unset by using the unset special built-in command. 1365 2.5.1 Positional Parameters 1366 A positional parameter is a parameter denoted by the decimal value represented by one or more 1367 digits, other than the single digit 0. The digits denoting the positional parameters shall always be 1368 interpreted as a decimal value, even if there is a leading zero. When a positional parameter with 1369 more than one digit is specified, the application shall enclose the digits in braces (see Section 1370 2.6.2 (on page 2239)). Positional parameters are initially assigned when the shell is invoked (see 1371 sh), temporarily replaced when a shell function is invoked (see Section 2.9.5 (on page 2256)), and 1372 can be reassigned with the set special built-in command. 1373 2.5.2 Special Parameters 1374 Listed below are the special parameters and the values to which they shall expand. Only the 1375 values of the special parameters are listed; see Section 2.6 (on page 2238) for a detailed summary 1376 of all the stages involved in expanding words. 1377 @ Expands to the positional parameters, starting from one. When the expansion occurs within 1378 double-quotes, and where field splitting (see Section 2.6.5 (on page 2243)) is performed, | 1379 each positional parameter shall expand as a separate field, with the provision that the | 1380 expansion of the first parameter shall still be joined with the beginning part of the original | 1381 word (assuming that the expanded parameter was embedded within a word), and the | Shell and Utilities, Issue 6 2235 Parameters and Variables Shell Command Language 1382 expansion of the last parameter shall still be joined with the last part of the original word. If | 1383 there are no positional parameters, the expansion of '@' shall generate zero fields, even | 1384 when '@' is double-quoted. | 1385 * Expands to the positional parameters, starting from one. When the expansion occurs within 1386 a double-quoted string (see Section 2.2.3 (on page 2232)), it shall expand to a single field | 1387 with the value of each parameter separated by the first character of the IFS variable, or by a | 1388 if IFS is unset. If IFS is set to a null string, this is not equivalent to unsetting it; its 1389 first character does not exist, so the parameter values are concatenated. 1390 # Expands to the decimal number of positional parameters. The command name (parameter | 1391 0) shall not be counted in the number given by '#' because it is a special parameter, not a | 1392 positional parameter. 1393 ? Expands to the decimal exit status of the most recent pipeline (see Section 2.9.2 (on page 1394 2250)). 1395 - (Hyphen.) Expands to the current option flags (the single-letter option names concatenated 1396 into a string) as specified on invocation by the set special built-in command or implicitly by 1397 the shell. 1398 $ Expands to the decimal process ID of the invoked shell. In a subshell (see Section 2.12 (on 1399 page 2263)), '$' shall expand to the same value as that of the current shell. 1400 ! Expands to the decimal process ID of the most recent background command (see Section 1401 2.9.3 (on page 2251)) executed from the current shell. (For example, background commands 1402 executed from subshells do not affect the value of "$!" in the current shell environment.) 1403 For a pipeline, the process ID is that of the last command in the pipeline. 1404 0 (Zero.) Expands to the name of the shell or shell script. See sh (on page 3048) for a detailed 1405 description of how this name is derived. 1406 See the description of the IFS variable in Section 2.5.3. 1407 2.5.3 Shell Variables 1408 Variables shall be initialized from the environment (as defined by the Base Definitions volume of 1409 IEEE Std 1003.1-200x, Chapter 8, Environment Variables and the exec function in the System 1410 Interfaces volume of IEEE Std 1003.1-200x) and can be given new values with variable 1411 assignment commands. If a variable is initialized from the environment, it shall be marked for 1412 export immediately; see the export special built-in. New variables can be defined and initialized 1413 with variable assignments, with the read or getopts utilities, with the name parameter in a for 1414 loop, with the ${name=word} expansion, or with other mechanisms provided as implementation 1415 extensions. 1416 The following variables shall affect the execution of the shell. 1417 UP XSI ENV The processing of the ENV shell variable shall be supported on all XSI- | 1418 conformant systems or if the system supports the User Portability Utilities | 1419 option. | 1420 This variable, when and only when an interactive shell is invoked, shall be | 1421 subjected to parameter expansion (see Section 2.6.2 (on page 2239)) by the 1422 shell and the resulting value shall be used as a pathname of a file containing 1423 shell commands to execute in the current environment. The file need not be 1424 executable. If the expanded value of ENV is not an absolute pathname, the 1425 results are unspecified. ENV shall be ignored if the user's real and effective 1426 user IDs or real and effective group IDs are different. | 2236 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Parameters and Variables 1427 HOME The pathname of the user's home directory. The contents of HOME are used in | 1428 tilde expansion (see Section 2.6.1 (on page 2239)). 1429 IFS (Input Field Separators.) A string treated as a list of characters that is used for 1430 field splitting and to split lines into fields with the read command. If IFS is not 1431 set, the shell shall behave as if the value of IFS is , , and 1432 ; see Section 2.6.5 (on page 2243). 1433 LANG The default value for the internationalization variables that are unset or null. | 1434 If LANG is unset or null, the corresponding value from the implementation- | 1435 defined default locale is used. If any of the internationalization variables 1436 contains an invalid setting, the utility behaves as if none of the variables had 1437 been defined. 1438 LC_ALL The default value for the LC_* variables, as described in the Base Definitions | 1439 volume of IEEE Std 1003.1-200x, Chapter 8, Environment Variables. 1440 LC_COLLATE Determine the behavior of range expressions, equivalence classes, and multi- | 1441 character collating elements within pattern matching. | 1442 LC_CTYPE Determine the interpretation of sequences of bytes of text data as characters | 1443 (for example, single-byte as opposed to multi-byte characters), which | 1444 characters are defined as letters (character class alpha) and s | 1445 (character class blank), and the behavior of character classes within pattern 1446 matching. Changing the value of LC_CTYPE after the shell has started shall 1447 not affect the lexical processing of shell commands in the current shell 1448 execution environment or its subshells. Invoking a shell script or performing 1449 exec sh subjects the new shell to the changes in LC_CTYPE. 1450 LC_MESSAGES Determine the language in which messages should be written. | 1451 LINENO Set by the shell to a decimal number representing the current sequential line | 1452 number (numbered starting with 1) within a script or function before it | 1453 executes each command. If the user unsets or resets LINENO, the variable may | 1454 lose its special meaning for the life of the shell. If the shell is not currently 1455 executing a script or function, the value of LINENO is unspecified. This 1456 volume of IEEE Std 1003.1-200x specifies the effects of the variable only for 1457 systems supporting the User Portability Utilities option. 1458 XSI NLSPATH Determine the location of message catalogs for the processing of | 1459 LC_MESSAGES. 1460 PATH A string formatted as described in the Base Definitions volume of | 1461 IEEE Std 1003.1-200x, Chapter 8, Environment Variables, used to effect | 1462 command interpretation; see Section 2.9.1.1 (on page 2249). | 1463 PPID Set by the shell to the decimal process ID of the process that invoked this shell. | 1464 In a subshell (see Section 2.12 (on page 2263)), PPID shall be set to the same | 1465 value as that of the parent of the current shell. For example, echo$PPID and 1466 (echo$PPID) would produce the same value. This volume of 1467 IEEE Std 1003.1-200x specifies the effects of the variable only for systems 1468 supporting the User Portability Utilities option. 1469 PS1 Each time an interactive shell is ready to read a command, the value of this 1470 variable shall be subjected to parameter expansion and written to standard 1471 error. The default value shall be "$ ". For users who have specific additional 1472 implementation-defined privileges, the default may be another, 1473 implementation-defined value. The shell shall replace each instance of the | Shell and Utilities, Issue 6 2237 Parameters and Variables Shell Command Language 1474 character '!' in PS1 with the history file number of the next command to be 1475 typed. Escaping the '!' with another '!' (that is, "!!") shall place the literal 1476 character '!' in the prompt. This volume of IEEE Std 1003.1-200x specifies 1477 the effects of the variable only for systems supporting the User Portability 1478 Utilities option. 1479 PS2 Each time the user enters a prior to completing a command line in 1480 an interactive shell, the value of this variable shall be subjected to parameter 1481 expansion and written to standard error. The default value is "> ". This 1482 volume of IEEE Std 1003.1-200x specifies the effects of the variable only for 1483 systems supporting the User Portability Utilities option. 1484 PS4 When an execution trace (set -x) is being performed in an interactive shell, 1485 before each line in the execution trace, the value of this variable shall be 1486 subjected to parameter expansion and written to standard error. The default 1487 value is "+ ". This volume of IEEE Std 1003.1-200x specifies the effects of the 1488 variable only for systems supporting the User Portability Utilities option. 1489 PWD Set by the shell to be an absolute pathname of the current working directory, | 1490 containing no components of type symbolic link, no components that are dot, | 1491 and no components that are dot-dot when the shell is initialized. If an | 1492 application sets or unsets the value of PWD, the behaviors of the cd and pwd | 1493 utilities are unspecified. 1494 2.6 Word Expansions 1495 This section describes the various expansions that are performed on words. Not all expansions 1496 are performed on every word, as explained in the following sections. 1497 Tilde expansions, parameter expansions, command substitutions, arithmetic expansions, and 1498 quote removals that occur within a single word expand to a single field. It is only field splitting 1499 or pathname expansion that can create multiple fields from a single word. The single exception 1500 to this rule is the expansion of the special parameter '@' within double-quotes, as described in 1501 Section 2.5.2 (on page 2235). 1502 The order of word expansion shall be as follows: 1503 1. Tilde expansion (see Section 2.6.1 (on page 2239)), parameter expansion (see Section 2.6.2 1504 (on page 2239)), command substitution (see Section 2.6.3 (on page 2242)), and arithmetic 1505 expansion (see Section 2.6.4 (on page 2243)) shall be performed, beginning to end. See item 1506 5 in Section 2.3 (on page 2233). 1507 2. Field splitting (see Section 2.6.5 (on page 2243)) shall be performed on the portions of the 1508 fields generated by step 1, unless IFS is null. 1509 3. Pathname expansion (see Section 2.6.6 (on page 2244)) shall be performed, unless set -f is 1510 in effect. 1511 4. Quote removal (see Section 2.6.7 (on page 2244)) shall always be performed last. 1512 The expansions described in this section shall occur in the same shell environment as that in 1513 which the command is executed. 1514 If the complete expansion appropriate for a word results in an empty field, that empty field shall 1515 be deleted from the list of fields that form the completely expanded command, unless the 1516 original word contained single-quote or double-quote characters. 2238 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Word Expansions 1517 The '$' character is used to introduce parameter expansion, command substitution, or 1518 arithmetic evaluation. If an unquoted '$' is followed by a character that is either not numeric, 1519 the name of one of the special parameters (see Section 2.5.2 (on page 2235)), a valid first 1520 character of a variable name, a left curly brace ('{') or a left parenthesis, the result is 1521 unspecified. 1522 2.6.1 Tilde Expansion 1523 A tilde-prefix consists of an unquoted tilde character at the beginning of a word, followed by all 1524 of the characters preceding the first unquoted slash in the word, or all the characters in the word 1525 if there is no slash. In an assignment (see the Base Definitions volume of IEEE Std 1003.1-200x, | 1526 Section 4.21, Variable Assignment), multiple tilde-prefixes can be used: at the beginning of the | 1527 word (that is, following the equal sign of the assignment), following any unquoted colon, or 1528 both. A tilde-prefix in an assignment is terminated by the first unquoted colon or slash. If none 1529 of the characters in the tilde-prefix are quoted, the characters in the tilde-prefix following the 1530 tilde are treated as a possible login name from the user database. A portable login name cannot 1531 contain characters outside the set given in the description of the LOGNAME environment 1532 variable in the Base Definitions volume of IEEE Std 1003.1-200x, Section 8.3, Other Environment 1533 Variables. If the login name is null (that is, the tilde-prefix contains only the tilde), the tilde- 1534 prefix is replaced by the value of the variable HOME. If HOME is unset, the results are | 1535 unspecified. Otherwise, the tilde-prefix shall be replaced by a pathname of the initial working | 1536 directory associated with the login name obtained using the getpwnam( ) function as defined in | 1537 the System Interfaces volume of IEEE Std 1003.1-200x. If the system does not recognize the login 1538 name, the results are undefined. 1539 2.6.2 Parameter Expansion 1540 The format for parameter expansion is as follows: 1541 ${expression} | 1542 where expression consists of all characters until the matching '}'. Any '}' escaped by a 1543 backslash or within a quoted string, and characters in embedded arithmetic expansions, 1544 command substitutions, and variable expansions, shall not be examined in determining the 1545 matching '}'. 1546 The simplest form for parameter expansion is: 1547 ${parameter} | 1548 The value, if any, of parameter shall be substituted. 1549 The parameter name or symbol can be enclosed in braces, which are optional except for 1550 positional parameters with more than one digit or when parameter is followed by a character that 1551 could be interpreted as part of the name. The matching closing brace shall be determined by 1552 counting brace levels, skipping over enclosed quoted strings, and command substitutions. 1553 If the parameter name or symbol is not enclosed in braces, the expansion shall use the longest 1554 valid name (see the Base Definitions volume of IEEE Std 1003.1-200x, Section 3.230, Name), 1555 whether or not the symbol represented by that name exists. 1556 If a parameter expansion occurs inside double-quotes: 1557 * Pathname expansion shall not be performed on the results of the expansion. 1558 * Field splitting shall not be performed on the results of the expansion, with the exception of 1559 '@'; see Section 2.5.2 (on page 2235). Shell and Utilities, Issue 6 2239 Word Expansions Shell Command Language 1560 In addition, a parameter expansion can be modified by using one of the following formats. In 1561 each case that a value of word is needed (based on the state of parameter, as described below), 1562 word shall be subjected to tilde expansion, parameter expansion, command substitution, and 1563 arithmetic expansion. If word is not needed, it shall not be expanded. The '}' character that 1564 delimits the following parameter expansion modifications shall be determined as described 1565 previously in this section and in Section 2.2.3 (on page 2232). (For example, ${foo-bar}xyz} 1566 would result in the expansion of foo followed by the string xyz} if foo is set, else the string 1567 "barxyz}"). 1568 ${parameter :-word} Use Default Values. If parameter is unset or null, the expansion of word 1569 shall be substituted; otherwise, the value of parameter shall be substituted. 1570 ${parameter :=word} Assign Default Values. If parameter is unset or null, the expansion of 1571 word shall be assigned to parameter. In all cases, the final value of 1572 parameter shall be substituted. Only variables, not positional parameters 1573 or special parameters, can be assigned in this way. 1574 ${parameter :?[word]} Indicate Error if Null or Unset. If parameter is unset or null, the 1575 expansion of word (or a message indicating it is unset if word is omitted) 1576 shall be written to standard error and the shell exits with a non-zero exit 1577 status. Otherwise, the value of parameter shall be substituted. An 1578 interactive shell need not exit. 1579 ${parameter :+word} Use Alternative Value. If parameter is unset or null, null shall be 1580 substituted; otherwise, the expansion of word shall be substituted. 1581 In the parameter expansions shown previously, use of the colon in the format shall result in a 1582 test for a parameter that is unset or null; omission of the colon shall result in a test for a 1583 parameter that is only unset. The following table summarizes the effect of the colon: ___________________________________________________________________________ | 1584 parameter parameter parameter | 1585 _ Set and Not Null Set But Null Unset __________________________________________________________________________ || 1586 ${parameter:-word} substitute parameter substitute word substitute word | 1587 ${parameter-word} substitute parameter substitute null substitute word | 1588 ${parameter:=word} substitute parameter assign word assign word | 1589 ${parameter=word} substitute parameter substitute parameter assign null | 1590 ${parameter:?word} substitute parameter error, exit error, exit | 1591 ${parameter?word} substitute parameter substitute null error, exit | 1592 ${parameter:+word} substitute word substitute null substitute null | 1593 _ ${parameter+word} substitute word substitute word substitute null __________________________________________________________________________ ||||||| 1594 In all cases shown with ``substitute'', the expression is replaced with the value shown. In all 1595 cases shown with ``assign'', parameter is assigned that value, which also replaces the expression. 1596 ${#parameter} String Length. The length in characters of the value of parameter shall be 1597 substituted. If parameter is '*' or '@', the result of the expansion is 1598 unspecified. 1599 The following four varieties of parameter expansion provide for substring processing. In each 1600 case, pattern matching notation (see Section 2.13 (on page 2264)), rather than regular expression 1601 notation, shall be used to evaluate the patterns. If parameter is '*' or '@', the result of the 1602 expansion is unspecified. Enclosing the full parameter expansion string in double-quotes shall 1603 not cause the following four varieties of pattern characters to be quoted, whereas quoting 1604 characters within the braces shall have this effect. 1605 ${parameter%word} Remove Smallest Suffix Pattern. The word shall be expanded to produce | 1606 a pattern. The parameter expansion shall then result in parameter, with the | 2240 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Word Expansions 1607 smallest portion of the suffix matched by the pattern deleted. 1608 ${parameter%%word} Remove Largest Suffix Pattern. The word shall be expanded to produce a | 1609 pattern. The parameter expansion shall then result in parameter, with the | 1610 largest portion of the suffix matched by the pattern deleted. 1611 ${parameter#word} Remove Smallest Prefix Pattern. The word shall be expanded to produce | 1612 a pattern. The parameter expansion shall then result in parameter, with the | 1613 smallest portion of the prefix matched by the pattern deleted. 1614 ${parameter##word} Remove Largest Prefix Pattern. The word shall be expanded to produce a | 1615 pattern. The parameter expansion shall then result in parameter, with the | 1616 largest portion of the prefix matched by the pattern deleted. 1617 Examples 1618 ${parameter :-word} 1619 In this example, ls is executed only if x is null or unset. (The $(ls) command substitution 1620 notation is explained in Section 2.6.3 (on page 2242).) 1621 ${x:-$(ls)} | 1622 ${parameter :=word} 1623 unset X 1624 echo ${X:=abc} 1625 abc 1626 ${parameter :?word} 1627 unset posix 1628 echo ${posix:?} 1629 sh: posix: parameter null or not set 1630 ${parameter :+word} 1631 set a b c 1632 echo ${3:+posix} 1633 posix 1634 ${#parameter} 1635 HOME=/usr/posix 1636 echo ${#HOME} 1637 10 1638 ${parameter%word} 1639 x=file.c 1640 echo ${x%.c}.o 1641 file.o 1642 ${parameter%%word} 1643 x=posix/src/std 1644 echo ${x%%/*} 1645 posix 1646 ${parameter#word} 1647 x=$HOME/src/cmd 1648 echo ${x#$HOME} 1649 /src/cmd 1650 ${parameter##word} 1651 x=/one/two/three Shell and Utilities, Issue 6 2241 Word Expansions Shell Command Language 1652 echo ${x##*/} 1653 three 1654 The double-quoting of patterns is different depending on where the double-quotes are placed: 1655 "${x#*}" The asterisk is a pattern character. 1656 ${x#"*"} The literal asterisk is quoted and not special. 1657 2.6.3 Command Substitution 1658 Command substitution allows the output of a command to be substituted in place of the 1659 command name itself. Command substitution shall occur when the command is enclosed as 1660 follows: 1661 $(command) | 1662 or (backquoted version): 1663 `command` | 1664 The shell shall expand the command substitution by executing command in a subshell 1665 environment (see Section 2.12 (on page 2263)) and replacing the command substitution (the text 1666 of command plus the enclosing "$()" or backquotes) with the standard output of the command, 1667 removing sequences of one or more s at the end of the substitution. Embedded 1668 s before the end of the output shall not be removed; however, they may be treated as 1669 field delimiters and eliminated during field splitting, depending on the value of IFS and quoting 1670 that is in effect. 1671 Within the backquoted style of command substitution, backslash shall retain its literal meaning, 1672 except when followed by: '$', '`', or '\\' (dollar sign, backquote, backslash). The search for 1673 the matching backquote shall be satisfied by the first backquote found without a preceding 1674 backslash; during this search, if a non-escaped backquote is encountered within a shell 1675 comment, a here-document, an embedded command substitution of the $(command) form, or a 1676 quoted string, undefined results occur. A single-quoted or double-quoted string that begins, but 1677 does not end, within the "`...`" sequence produces undefined results. 1678 With the $(command) form, all characters following the open parenthesis to the matching closing 1679 parenthesis constitute the command. Any valid shell script can be used for command, except: 1680 * A script consisting solely of redirections produces unspecified results 1681 * See the restriction on single subshells described below 1682 The results of command substitution shall not be processed for further tilde expansion, 1683 parameter expansion, command substitution, or arithmetic expansion. If a command 1684 substitution occurs inside double-quotes, it shall not be performed on the results of the 1685 substitution. 1686 Command substitution can be nested. To specify nesting within the backquoted version, the 1687 application shall precede the inner backquotes with backslashes, for example: 1688 \`command\` | 1689 If the command substitution consists of a single subshell, such as: 1690 $( (command) ) | 1691 a conforming application shall separate the "$(" and '(' into two tokens (that is, separate | 1692 them with white space). This is required to avoid any ambiguities with arithmetic expansion. 2242 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Word Expansions 1693 2.6.4 Arithmetic Expansion 1694 Arithmetic expansion provides a mechanism for evaluating an arithmetic expression and 1695 substituting its value. The format for arithmetic expansion shall be as follows: 1696 $((expression)) | 1697 The expression shall be treated as if it were in double-quotes, except that a double-quote inside 1698 the expression is not treated specially. The shell shall expand all tokens in the expression for | 1699 parameter expansion, command substitution, and quote removal. | 1700 Next, the shell shall treat this as an arithmetic expression and substitute the value of the | 1701 expression. The arithmetic expression shall be processed according to the rules given in Section | 1702 1.7.2.1 (on page 2207), with the following exceptions: | 1703 * Only signed long integer arithmetic is required. | 1704 * Only the decimal-constant, octal-constant, and hexadecimal-constant constants specified in | 1705 the ISO C standard, Subclause 6.4.4.1 are required to be recognized as constants. | 1706 * The sizeof( ) operator and the prefix and postfix "++" and "- -" operators are not required. | 1707 * Selection, iteration, and jump statements are not supported. 1708 As an extension, the shell may recognize arithmetic expressions beyond those listed. The shell | 1709 may use a signed integer type with a rank larger than the rank of signed long. The shell may use | 1710 a real-floating type instead of signed long as long as it does not affect the results in cases where | 1711 there is no overflow. If the expression is invalid, the expansion fails and the shell shall write a | 1712 message to standard error indicating the failure. 1713 Examples 1714 A simple example using arithmetic expansion: 1715 # repeat a command 100 times | 1716 x=100 | 1717 while [ $x -gt 0 ] | 1718 do | 1719 command | 1720 x=$(($x-1)) | 1721 done | 1722 2.6.5 Field Splitting 1723 After parameter expansion (Section 2.6.2 (on page 2239)), command substitution (Section 2.6.3 1724 (on page 2242)), and arithmetic expansion (Section 2.6.4), the shell shall scan the results of 1725 expansions and substitutions that did not occur in double-quotes for field splitting and multiple 1726 fields can result. 1727 The shell shall treat each character of the IFS as a delimiter and use the delimiters to split the | 1728 results of parameter expansion and command substitution into fields. | 1729 1. If the value of IFS is a , , and , or if it is unset, any sequence of 1730 s, s, or s at the beginning or end of the input shall be ignored and 1731 any sequence of those characters within the input shall delimit a field. For example, the 1732 input: 1733 foobar | Shell and Utilities, Issue 6 2243 Word Expansions Shell Command Language 1734 yields two fields, foo and bar. 1735 2. If the value of IFS is null, no field splitting shall be performed. 1736 3. Otherwise, the following rules shall be applied in sequence. The term ``IFS white space'' is 1737 used to mean any sequence (zero or more instances) of white space characters that are in 1738 the IFS value (for example, if IFS contains //, any sequence of 1739 s and s is considered IFS white space). 1740 a. IFS white space shall be ignored at the beginning and end of the input. 1741 b. Each occurrence in the input of an IFS character that is not IFS white space, along 1742 with any adjacent IFS white space, shall delimit a field, as described previously. 1743 c. Non-zero-length IFS white space shall delimit a field. 1744 2.6.6 Pathname Expansion 1745 After field splitting, if set -f is not in effect, each field in the resulting command line shall be 1746 expanded using the algorithm described in Section 2.13 (on page 2264), qualified by the rules in 1747 Section 2.13.3 (on page 2265). 1748 2.6.7 Quote Removal 1749 The quote characters: '\', '\'', and '"' (backslash, single-quote, double-quote) that were 1750 present in the original word shall be removed unless they have themselves been quoted. 1751 2.7 Redirection 1752 Redirection is used to open and close files for the current shell execution environment (see 1753 Section 2.12 (on page 2263)) or for any command. Redirection operators can be used with numbers 1754 representing file descriptors (see the Base Definitions volume of IEEE Std 1003.1-200x, Section 1755 3.165, File Descriptor) as described below. 1756 The overall format used for redirection is: 1757 [n]redir-op word | 1758 The number n is an optional decimal number designating the file descriptor number; the 1759 application shall ensure it is delimited from any preceding text and immediately precede the 1760 redirection operator redir-op. If n is quoted, the number shall not be recognized as part of the 1761 redirection expression. For example: 1762 echo \2>a | 1763 writes the character 2 into file a. If any part of redir-op is quoted, no redirection expression is 1764 recognized. For example: 1765 echo 2\>a | 1766 writes the characters 2>a to standard output. The optional number, redirection operator, and 1767 word shall not appear in the arguments provided to the command to be executed (if any). 1768 Open files are represented by decimal numbers starting with zero. The largest possible value is 1769 implementation-defined; however, all implementations shall support at least 0 to 9, inclusive, for 1770 use by the application. These numbers are called file descriptors. The values 0, 1, and 2 have 1771 special meaning and conventional uses and are implied by certain redirection operations; they 1772 are referred to as standard input, standard output, and standard error, respectively. Programs 1773 usually take their input from standard input, and write output on standard output. Error 2244 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Redirection 1774 messages are usually written on standard error. The redirection operators can be preceded by 1775 one or more digits (with no intervening s allowed) to designate the file descriptor 1776 number. 1777 If the redirection operator is "<<" or "<<-", the word that follows the redirection operator shall 1778 be subjected to quote removal; it is unspecified whether any of the other expansions occur. For 1779 the other redirection operators, the word that follows the redirection operator shall be subjected 1780 to tilde expansion, parameter expansion, command substitution, arithmetic expansion, and 1781 quote removal. Pathname expansion shall not be performed on the word by a non-interactive | 1782 shell; an interactive shell may perform it, but shall do so only when the expansion would result | 1783 in one word. | 1784 If more than one redirection operator is specified with a command, the order of evaluation is 1785 from beginning to end. 1786 A failure to open or create a file shall cause a redirection to fail. 1787 2.7.1 Redirecting Input 1788 Input redirection shall cause the file whose name results from the expansion of word to be 1789 opened for reading on the designated file descriptor, or standard input if the file descriptor is not 1790 specified. 1791 The general format for redirecting input is: 1792 [n]word | 1798 [n]>|word | 1799 where the optional n represents the file descriptor number. If the number is omitted, the 1800 redirection shall refer to standard output (file descriptor 1). 1801 Output redirection using the '>' format shall fail if the noclobber option is set (see the 1802 description of set -C) and the file named by the expansion of word exists and is a regular file. 1803 Otherwise, redirection using the '>' or ">|" formats shall cause the file whose name results 1804 from the expansion of word to be created and opened for output on the designated file 1805 descriptor, or standard output if none is specified. If the file does not exist, it shall be created; 1806 otherwise, it shall be truncated to be an empty file after being opened. 1807 2.7.3 Appending Redirected Output 1808 Appended output redirection shall cause the file whose name results from the expansion of 1809 word to be opened for output on the designated file descriptor. The file is opened as if the open( ) 1810 function as defined in the System Interfaces volume of IEEE Std 1003.1-200x was called with the 1811 O_APPEND flag. If the file does not exist, it shall be created. 1812 The general format for appending redirected output is as follows: 1813 [n]>>word | Shell and Utilities, Issue 6 2245 Redirection Shell Command Language 1814 where the optional n represents the file descriptor number. If the number is omitted, the 1815 redirection refers to standard output (file descriptor 1). 1816 2.7.4 Here-Document 1817 The redirection operators "<<" and "<<-" both allow redirection of lines contained in a shell 1818 input file, known as a here-document, to the input of a command. 1819 The here-document shall be treated as a single word that begins after the next and | 1820 continues until there is a line containing only the delimiter and a , with no s in | 1821 between. Then the next here-document starts, if there is one. The format is as follows: | 1822 [n]<&word | 1858 shall duplicate one output file descriptor from another, or shall close one. If word evaluates to | 1859 one or more digits, the file descriptor denoted by n, or standard output if n is not specified, shall 1860 be made to be a copy of the file descriptor denoted by word; if the digits in word do not represent 1861 a file descriptor already open for output, a redirection error shall result; see Section 2.8.1. If word 1862 evaluates to '-', file descriptor n, or standard output if n is not specified, is closed. If word 1863 evaluates to something else, the behavior is unspecified. 1864 2.7.7 Open File Descriptors for Reading and Writing 1865 The redirection operator: 1866 [n]<>word | 1867 shall cause the file whose name is the expansion of word to be opened for both reading and 1868 writing on the file descriptor denoted by n, or standard input if n is not specified. If the file does 1869 not exist, it shall be created. 1870 2.8 Exit Status and Errors 1871 2.8.1 Consequences of Shell Errors 1872 For a non-interactive shell, an error condition encountered by a special built-in (see Section 2.14 1873 (on page 2266)) or other type of utility shall cause the shell to write a diagnostic message to 1874 standard error and exit as shown in the following table: ___________________________________________________________________________ | 1875 _ Error Special Built-In Other Utilities __________________________________________________________________________ || 1876 Shell language syntax error Shall exit Shall exit | 1877 Utility syntax error (option or operand error) Shall exit Shall not exit | 1878 Redirection error Shall exit Shall not exit | 1879 Variable assignment error Shall exit Shall not exit | 1880 Expansion error Shall exit Shall exit | 1881 Command not found N/A May exit | 1882 _ Dot script not found Shall exit N/A __________________________________________________________________________ |||||| 1883 An expansion error is one that occurs when the shell expansions defined in Section 2.6 (on page 1884 2238) are carried out (for example, "${x!y}", because '!' is not a valid operator); an 1885 implementation may treat these as syntax errors if it is able to detect them during tokenization, 1886 rather than during expansion. 1887 If any of the errors shown as ``shall exit'' or ``(may) exit'' occur in a subshell, the subshell shall | 1888 (respectively may) exit with a non-zero status, but the script containing the subshell shall not | 1889 exit because of the error. | 1890 In all of the cases shown in the table, an interactive shell shall write a diagnostic message to 1891 standard error without exiting. Shell and Utilities, Issue 6 2247 Exit Status and Errors Shell Command Language 1892 2.8.2 Exit Status for Commands 1893 Each command has an exit status that can influence the behavior of other shell commands. The 1894 exit status of commands that are not utilities is documented in this section. The exit status of the 1895 standard utilities is documented in their respective sections. 1896 If a command is not found, the exit status shall be 127. If the command name is found, but it is 1897 not an executable utility, the exit status shall be 126. Applications that invoke utilities without 1898 using the shell should use these exit status values to report similar errors. 1899 If a command fails during word expansion or redirection, its exit status shall be greater than 1900 zero. 1901 Internally, for purposes of deciding whether a command exits with a non-zero exit status, the 1902 shell shall recognize the entire status value retrieved for the command by the equivalent of the 1903 wait( ) function WEXITSTATUS macro (as defined in the System Interfaces volume of 1904 IEEE Std 1003.1-200x). When reporting the exit status with the special parameter '?', the shell 1905 shall report the full eight bits of exit status available. The exit status of a command that 1906 terminated because it received a signal shall be reported as greater than 128. 1907 2.9 Shell Commands 1908 This section describes the basic structure of shell commands. The following command 1909 descriptions each describe a format of the command that is only used to aid the reader in 1910 recognizing the command type, and does not formally represent the syntax. Each description 1911 discusses the semantics of the command; for a formal definition of the command language, 1912 consult Section 2.10 (on page 2257). 1913 A command is one of the following: 1914 * Simple command (see Section 2.9.1) 1915 * Pipeline (see Section 2.9.2 (on page 2250)) 1916 * List or compound-list (see Section 2.9.3 (on page 2251)) 1917 * Compound command (see Section 2.9.4 (on page 2253)) 1918 * Function definition (see Section 2.9.5 (on page 2256)) 1919 Unless otherwise stated, the exit status of a command shall be that of the last simple command | 1920 executed by the command. There shall be no limit on the size of any shell command other than | 1921 that imposed by the underlying system (memory constraints, {ARG_MAX}, and so on). | 1922 2.9.1 Simple Commands 1923 A simple command is a sequence of optional variable assignments and redirections, in any 1924 sequence, optionally followed by words and redirections, terminated by a control operator. 1925 When a given simple command is required to be executed (that is, when any conditional 1926 construct such as an AND-OR list or a case statement has not bypassed the simple command), 1927 the following expansions, assignments, and redirections shall all be performed from the | 1928 beginning of the command text to the end: | 1929 1. The words that are recognized as variable assignments or redirections according to Section 1930 2.10.2 (on page 2257) are saved for processing in steps 3 and 4. 1931 2. The words that are not variable assignments or redirections shall be expanded. If any fields 1932 remain following their expansion, the first field shall be considered the command name 2248 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Commands 1933 and remaining fields are the arguments for the command. 1934 3. Redirections shall be performed as described in Section 2.7 (on page 2244). 1935 4. Each variable assignment shall be expanded for tilde expansion, parameter expansion, 1936 command substitution, arithmetic expansion, and quote removal prior to assigning the 1937 value. 1938 In the preceding list, the order of steps 3 and 4 may be reversed for the processing of special 1939 built-in utilities; see Section 2.14 (on page 2266). 1940 If no command name results, variable assignments shall affect the current execution 1941 environment. Otherwise, the variable assignments shall be exported for the execution 1942 environment of the command and shall not affect the current execution environment (except for 1943 special built-ins). If any of the variable assignments attempt to assign a value to a read-only | 1944 variable, a variable assignment error shall occur. See Section 2.8.1 (on page 2247) for the | 1945 consequences of these errors. 1946 If there is no command name, any redirections shall be performed in a subshell environment; it 1947 is unspecified whether this subshell environment is the same one as that used for a command 1948 substitution within the command. (To affect the current execution environment, see the exec (on 1949 page 2277) special built-in.) If any of the redirections performed in the current shell execution 1950 environment fail, the command shall immediately fail with an exit status greater than zero, and 1951 the shell shall write an error message indicating the failure. See Section 2.8.1 (on page 2247) for 1952 the consequences of these failures on interactive and non-interactive shells. 1953 If there is a command name, execution shall continue as described in Section 2.9.1.1. If there is 1954 no command name, but the command contained a command substitution, the command shall 1955 complete with the exit status of the last command substitution performed. Otherwise, the 1956 command shall complete with a zero exit status. 1957 2.9.1.1 Command Search and Execution 1958 If a simple command results in a command name and an optional list of arguments, the 1959 following actions shall be performed: 1960 1. If the command name does not contain any slashes, the first successful step in the 1961 following sequence shall occur: 1962 a. If the command name matches the name of a special built-in utility, that special 1963 built-in utility shall be invoked. 1964 b. If the command name matches the name of a function known to this shell, the 1965 function shall be invoked as described in Section 2.9.5 (on page 2256). If the 1966 implementation has provided a standard utility in the form of a function, it shall not 1967 be recognized at this point. It shall be invoked in conjunction with the path search in 1968 step 1d. 1969 c. If the command name matches the name of a utility listed in the following table, that 1970 utility shall be invoked. 1971 alias false jobs true | 1972 bg fc kill umask | 1973 cd fg newgrp unalias | 1974 command getopts read wait | 1975 d. Otherwise, the command shall be searched for using the PATH environment variable | 1976 as described in the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 8, 1977 Environment Variables: Shell and Utilities, Issue 6 2249 Shell Commands Shell Command Language 1978 i. If the search is successful: 1979 a. If the system has implemented the utility as a regular built-in or as a shell 1980 function, it shall be invoked at this point in the path search. 1981 b. Otherwise, the shell executes the utility in a separate utility environment 1982 (see Section 2.12 (on page 2263)) with actions equivalent to calling the 1983 execve( ) function as defined in the System Interfaces volume of 1984 IEEE Std 1003.1-200x with the path argument set to the pathname 1985 resulting from the search, arg0 set to the command name, and the 1986 remaining arguments set to the operands, if any. 1987 If the execve( ) function fails due to an error equivalent to the [ENOEXEC] 1988 error defined in the System Interfaces volume of IEEE Std 1003.1-200x, the 1989 shell shall execute a command equivalent to having a shell invoked with 1990 the command name as its first operand, with any remaining arguments | 1991 passed to the new shell. If the executable file is not a text file, the shell | 1992 may bypass this command execution. In this case, it shall write an error | 1993 message, and shall return an exit status of 126. | 1994 Once a utility has been searched for and found (either as a result of this specific 1995 search or as part of an unspecified shell start-up activity), an implementation 1996 may remember its location and need not search for the utility again unless the 1997 PATH variable has been the subject of an assignment. If the remembered 1998 location fails for a subsequent invocation, the shell shall repeat the search to 1999 find the new location for the utility, if any. 2000 ii. If the search is unsuccessful, the command shall fail with an exit status of 127 2001 and the shell shall write an error message. 2002 2. If the command name contains at least one slash, the shell shall execute the utility in a 2003 separate utility environment with actions equivalent to calling the execve( ) function 2004 defined in the System Interfaces volume of IEEE Std 1003.1-200x with the path and arg0 2005 arguments set to the command name, and the remaining arguments set to the operands, if 2006 any. 2007 If the execve( ) function fails due to an error equivalent to the [ENOEXEC] error, the shell 2008 shall execute a command equivalent to having a shell invoked with the command name as | 2009 its first operand, with any remaining arguments passed to the new shell. If the executable | 2010 file is not a text file, the shell may bypass this command execution. In this case, it shall | 2011 write an error message and shall return an exit status of 126. | 2012 2.9.2 Pipelines 2013 A pipeline is a sequence of one or more commands separated by the control operator '|'. The 2014 standard output of all but the last command shall be connected to the standard input of the next 2015 command. 2016 The format for a pipeline is: 2017 [!] command1 [ | command2 ...] | 2018 The standard output of command1 shall be connected to the standard input of command2. The 2019 standard input, standard output, or both of a command shall be considered to be assigned by the 2020 pipeline before any redirection specified by redirection operators that are part of the command 2021 (see Section 2.7 (on page 2244)). 2250 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Commands 2022 If the pipeline is not in the background (see Section 2.9.3.1 (on page 2252)), the shell shall wait for 2023 the last command specified in the pipeline to complete, and may also wait for all commands to 2024 complete. 2025 Exit Status 2026 If the reserved word ! does not precede the pipeline, the exit status shall be the exit status of the 2027 last command specified in the pipeline. Otherwise, the exit status shall be the logical NOT of the 2028 exit status of the last command. That is, if the last command returns zero, the exit status shall be 2029 1; if the last command returns greater than zero, the exit status shall be zero. 2030 2.9.3 Lists 2031 An AND-OR list is a sequence of one or more pipelines separated by the operators "&&" and 2032 "||". 2033 A list is a sequence of one or more AND-OR lists separated by the operators ';' and '&' and 2034 optionally terminated by ';', '&', or . 2035 The operators "&&" and "||" shall have equal precedence and shall be evaluated with left | 2036 associativity. For example, both of the following commands write solely bar to standard output: | 2037 false && echo foo || echo bar | 2038 true || echo foo && echo bar | 2039 A ';' or terminator shall cause the preceding AND-OR list to be executed 2040 sequentially; an '&' shall cause asynchronous execution of the preceding AND-OR list. 2041 The term compound-list is derived from the grammar in Section 2.10 (on page 2257); it is 2042 equivalent to a sequence of lists, separated by s, that can be preceded or followed by 2043 an arbitrary number of s. 2044 Examples 2045 The following is an example that illustrates s in compound-lists: 2046 while | 2047 # a couple of s | 2048 # a list | 2049 date && who || ls; cat file | 2050 # a couple of s | 2051 # another list | 2052 wc file > output & true | 2053 do | 2054 # 2 lists | 2055 ls | 2056 cat file | 2057 done | Shell and Utilities, Issue 6 2251 Shell Commands Shell Command Language 2058 2.9.3.1 Asynchronous Lists 2059 If a command is terminated by the control operator ampersand ('&'), the shell shall execute the 2060 command asynchronously in a subshell. This means that the shell shall not wait for the 2061 command to finish before executing the next command. 2062 The format for running a command in the background is: 2063 command1 & [command2 & ... ] | 2064 The standard input for an asynchronous list, before any explicit redirections are performed, shall 2065 be considered to be assigned to a file that has the same properties as /dev/null. If it is an 2066 interactive shell, this need not happen. In all cases, explicit redirection of standard input shall 2067 override this activity. 2068 When an element of an asynchronous list (the portion of the list ended by an ampersand, such as 2069 command1, above) is started by the shell, the process ID of the last command in the asynchronous 2070 list element shall become known in the current shell execution environment; see Section 2.12 (on 2071 page 2263). This process ID shall remain known until: 2072 1. The command terminates and the application waits for the process ID. 2073 2. Another asynchronous list invoked before "$!" (corresponding to the previous 2074 asynchronous list) is expanded in the current execution environment. 2075 The implementation need not retain more than the {CHILD_MAX} most recent entries in its list 2076 of known process IDs in the current shell execution environment. 2077 Exit Status 2078 The exit status of an asynchronous list shall be zero. 2079 2.9.3.2 Sequential Lists 2080 Commands that are separated by a semicolon (';') shall be executed sequentially. 2081 The format for executing commands sequentially shall be: 2082 command1 [; command2] ... | 2083 Each command shall be expanded and executed in the order specified. 2084 Exit Status 2085 The exit status of a sequential list shall be the exit status of the last command in the list. 2086 2.9.3.3 AND Lists 2087 The control operator "&&" denotes an AND list. The format shall be: 2088 command1 [ && command2] ... | 2089 First command1 shall be executed. If its exit status is zero, command2 shall be executed, and so on, 2090 until a command has a non-zero exit status or there are no more commands left to execute. The 2091 commands are expanded only if they are executed. 2252 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Commands 2092 Exit Status 2093 The exit status of an AND list shall be the exit status of the last command that is executed in the 2094 list. 2095 2.9.3.4 OR Lists 2096 The control operator "||" denotes an OR List. The format shall be: 2097 command1 [ || command2] ... | 2098 First, command1 shall be executed. If its exit status is non-zero, command2 shall be executed, and 2099 so on, until a command has a zero exit status or there are no more commands left to execute. 2100 Exit Status 2101 The exit status of an OR list shall be the exit status of the last command that is executed in the 2102 list. 2103 2.9.4 Compound Commands 2104 The shell has several programming constructs that are compound commands, which provide 2105 control flow for commands. Each of these compound commands has a reserved word or control 2106 operator at the beginning, and a corresponding terminator reserved word or operator at the end. 2107 In addition, each can be followed by redirections on the same line as the terminator. Each 2108 redirection shall apply to all the commands within the compound command that do not 2109 explicitly override that redirection. 2110 2.9.4.1 Grouping Commands 2111 The format for grouping commands is as follows: 2112 (compound-list) Execute compound-list in a subshell environment; see Section 2.12 (on page 2113 2263). Variable assignments and built-in commands that affect the 2114 environment shall not remain in effect after the list finishes. 2115 { compound-list;} Execute compound-list in the current process environment. The semicolon 2116 shown here is an example of a control operator delimiting the } reserved 2117 word. Other delimiters are possible, as shown in Section 2.10 (on page 2118 2257); a is frequently used. 2119 Exit Status 2120 The exit status of a grouping command shall be the exit status of list. 2121 2.9.4.2 For Loop 2122 The for loop shall execute a sequence of commands for each member in a list of items. The for | 2123 loop requires that the reserved words do and done be used to delimit the sequence of 2124 commands. 2125 The format for the for loop is as follows: 2126 for name [ in [word ... ]] | 2127 do | 2128 compound-list | 2129 done | Shell and Utilities, Issue 6 2253 Shell Commands Shell Command Language 2130 First, the list of words following in shall be expanded to generate a list of items. Then, the 2131 variable name shall be set to each item, in turn, and the compound-list executed each time. If no 2132 items result from the expansion, the compound-list shall not be executed. Omitting: 2133 in word ... | 2134 shall be equivalent to: | 2135 in "$@" | 2136 Exit Status 2137 The exit status of a for command shall be the exit status of the last command that executes. If 2138 there are no items, the exit status shall be zero. 2139 2.9.4.3 Case Conditional Construct 2140 The conditional construct case shall execute the compound-list corresponding to the first one of 2141 several patterns (see Section 2.13 (on page 2264)) that is matched by the string resulting from the 2142 tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote 2143 removal of the given word. The reserved word in shall denote the beginning of the patterns to be 2144 matched. Multiple patterns with the same compound-list shall be delimited by the '|' symbol. 2145 The control operator ')' terminates a list of patterns corresponding to a given action. The 2146 compound-list for each list of patterns, with the possible exception of the last, shall be terminated 2147 with ";;". The case construct terminates with the reserved word esac (case reversed). 2148 The format for the case construct is as follows: 2149 case word in | 2150 [(]pattern1) compound-list;; | 2151 [[(]pattern[ | pattern] ... ) compound-list;;] ... | 2152 [[(]pattern[ | pattern] ... ) compound-list] | 2153 esac | 2154 The ";;" is optional for the last compound-list. 2155 In order from the beginning to the end of the case statement, each pattern that labels a 2156 compound-list shall be subjected to tilde expansion, parameter expansion, command substitution, 2157 and arithmetic expansion, and the result of these expansions shall be compared against the 2158 expansion of word, according to the rules described in Section 2.13 (on page 2264) (which also 2159 describes the effect of quoting parts of the pattern). After the first match, no more patterns shall 2160 be expanded, and the compound-list shall be executed. The order of expansion and comparison of 2161 multiple patterns that label a compound-list statement is unspecified. 2162 Exit Status 2163 The exit status of case shall be zero if no patterns are matched. Otherwise, the exit status shall be 2164 the exit status of the last command executed in the compound-list. 2165 2.9.4.4 If Conditional Construct 2166 The if command shall execute a compound-list and use its exit status to determine whether to 2167 execute another compound-list. 2168 The format for the if construct is as follows: 2254 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Commands 2169 if compound-list | 2170 then | 2171 compound-list | 2172 [elif compound-list | 2173 then | 2174 compound-list] ... | 2175 [else | 2176 compound-list] | 2177 The if compound-list shall be executed; if its exit status is zero, the then compound-list shall be 2178 executed and the command shall complete. Otherwise, each elif compound-list shall be executed, 2179 in turn, and if its exit status is zero, the then compound-list shall be executed and the command 2180 shall complete. Otherwise, the else compound-list shall be executed. 2181 Exit Status 2182 The exit status of the if command shall be the exit status of the then or else compound-list that 2183 was executed, or zero, if none was executed. 2184 2.9.4.5 While Loop 2185 The while loop shall continuously execute one compound-list as long as another compound-list has 2186 a zero exit status. 2187 The format of the while loop is as follows: 2188 while compound-list-1 | 2189 do | 2190 compound-list-2 | 2191 done | 2192 The compound-list-1 shall be executed, and if it has a non-zero exit status, the while command 2193 shall complete. Otherwise, the compound-list-2 shall be executed, and the process shall repeat. 2194 Exit Status 2195 The exit status of the while loop shall be the exit status of the last compound-list-2 executed, or 2196 zero if none was executed. 2197 2.9.4.6 Until Loop 2198 The until loop shall continuously execute one compound-list as long as another compound-list has 2199 a non-zero exit status. 2200 The format of the until loop is as follows: 2201 until compound-list-1 | 2202 do | 2203 compound-list-2 | 2204 done | 2205 The compound-list-1 shall be executed, and if it has a zero exit status, the until command 2206 completes. Otherwise, the compound-list-2 shall be executed, and the process repeats. Shell and Utilities, Issue 6 2255 Shell Commands Shell Command Language 2207 Exit Status 2208 The exit status of the until loop shall be the exit status of the last compound-list-2 executed, or 2209 zero if none was executed. 2210 2.9.5 Function Definition Command 2211 A function is a user-defined name that is used as a simple command to call a compound 2212 command with new positional parameters. A function is defined with a function definition 2213 command. 2214 The format of a function definition command is as follows: 2215 fname() compound-command[io-redirect ...] | 2216 The function is named fname; the application shall ensure that it is a name (see the Base 2217 Definitions volume of IEEE Std 1003.1-200x, Section 3.230, Name). An implementation may 2218 allow other characters in a function name as an extension. The implementation shall maintain 2219 separate name spaces for functions and variables. 2220 The argument compound-command represents a compound command, as described in Section 2221 2.9.4 (on page 2253). 2222 When the function is declared, none of the expansions in Section 2.6 (on page 2238) shall be 2223 performed on the text in compound-command or io-redirect; all expansions shall be performed as 2224 normal each time the function is called. Similarly, the optional io-redirect redirections and any 2225 variable assignments within compound-command shall be performed during the execution of the 2226 function itself, not the function definition. See Section 2.8.1 (on page 2247) for the consequences 2227 of failures of these operations on interactive and non-interactive shells. 2228 When a function is executed, it shall have the syntax-error and variable-assignment properties 2229 described for special built-in utilities in the enumerated list at the beginning of Section 2.14 (on 2230 page 2266). 2231 The compound-command shall be executed whenever the function name is specified as the name 2232 of a simple command (see Section 2.9.1.1 (on page 2249)). The operands to the command 2233 temporarily shall become the positional parameters during the execution of the compound- 2234 command; the special parameter '#' also shall be changed to reflect the number of operands. The 2235 special parameter 0 shall be unchanged. When the function completes, the values of the 2236 positional parameters and the special parameter '#' shall be restored to the values they had 2237 before the function was executed. If the special built-in return is executed in the compound- 2238 command, the function completes and execution shall resume with the next command after the 2239 function call. 2240 Exit Status 2241 The exit status of a function definition shall be zero if the function was declared successfully; 2242 otherwise, it shall be greater than zero. The exit status of a function invocation shall be the exit 2243 status of the last command executed by the function. 2256 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Grammar 2244 2.10 Shell Grammar 2245 The following grammar defines the Shell Command Language. This formal syntax shall take 2246 precedence over the preceding text syntax description. 2247 2.10.1 Shell Grammar Lexical Conventions 2248 The input language to the shell must be first recognized at the character level. The resulting 2249 tokens shall be classified by their immediate context according to the following rules (applied in 2250 order). These rules shall be used to determine what a ``token'' is that is subject to parsing at the | 2251 token level. The rules for token recognition in Section 2.3 (on page 2233) shall apply. | 2252 1. A shall be returned as the token identifier NEWLINE. 2253 2. If the token is an operator, the token identifier for that operator shall result. 2254 3. If the string consists solely of digits and the delimiter character is one of '<' or '>', the 2255 token identifier IO_NUMBER shall be returned. 2256 4. Otherwise, the token identifier TOKEN results. 2257 Further distinction on TOKEN is context-dependent. It may be that the same TOKEN yields 2258 WORD, a NAME, an ASSIGNMENT, or one of the reserved words below, dependent upon the 2259 context. Some of the productions in the grammar below are annotated with a rule number from 2260 the following list. When a TOKEN is seen where one of those annotated productions could be 2261 used to reduce the symbol, the applicable rule shall be applied to convert the token identifier 2262 type of the TOKEN to a token identifier acceptable at that point in the grammar. The reduction 2263 shall then proceed based upon the token identifier type yielded by the rule applied. When more 2264 than one rule applies, the highest numbered rule shall apply (which in turn may refer to another 2265 rule). (Note that except in rule 7, the presence of an '=' in the token has no effect.) 2266 The WORD tokens shall have the word expansion rules applied to them immediately before the 2267 associated command is executed, not at the time the command is parsed. 2268 2.10.2 Shell Grammar Rules 2269 1. [Command Name] 2270 When the TOKEN is exactly a reserved word, the token identifier for that reserved word 2271 shall result. Otherwise, the token WORD shall be returned. Also, if the parser is in any 2272 state where only a reserved word could be the next correct token, proceed as above. 2273 Note: Because at this point quote marks are retained in the token, quoted strings cannot be 2274 recognized as reserved words. This rule also implies that reserved words are not 2275 recognized except in certain positions in the input, such as after a or 2276 semicolon; the grammar presumes that if the reserved word is intended, it is properly 2277 delimited by the user, and does not attempt to reflect that requirement directly. Also 2278 note that line joining is done before tokenization, as described in Section 2.2.1 (on page 2279 2232), so escaped s are already removed at this point. 2280 Rule 1 is not directly referenced in the grammar, but is referred to by other rules, or applies 2281 globally. 2282 2. [Redirection to or from filename] 2283 The expansions specified in Section 2.7 (on page 2244) shall occur. As specified there, 2284 exactly one field can result (or the result is unspecified), and there are additional 2285 requirements on pathname expansion. Shell and Utilities, Issue 6 2257 Shell Grammar Shell Command Language 2286 3. [Redirection from here-document] 2287 Quote removal shall be applied to the word to determine the delimiter that is used to find 2288 the end of the here-document that begins after the next . 2289 4. [Case statement termination] 2290 When the TOKEN is exactly the reserved word esac, the token identifier for esac shall 2291 result. Otherwise, the token WORD shall be returned. 2292 5. [NAME in for] 2293 When the TOKEN meets the requirements for a name (see the Base Definitions volume of 2294 IEEE Std 1003.1-200x, Section 3.230, Name), the token identifier NAME shall result. 2295 Otherwise, the token WORD shall be returned. 2296 6. [Third word of for and case] 2297 When the TOKEN is exactly the reserved word in, the token identifier for in shall result. 2298 Otherwise, the token WORD shall be returned. (As indicated in the grammar, a linebreak 2299 precedes the token in. If s are present at the indicated location, it is the token 2300 after them that is treated in this fashion.) 2301 7. [Assignment preceding command name] 2302 a. [When the first word] 2303 If the TOKEN does not contain the character '=', rule 1 is applied. Otherwise, 7b 2304 shall be applied. 2305 b. [Not the first word] 2306 If the TOKEN contains the equal sign character: 2307 - If it begins with '=', the token WORD shall be returned. 2308 - If all the characters preceding '=' form a valid name (see the Base Definitions 2309 volume of IEEE Std 1003.1-200x, Section 3.230, Name), the token 2310 ASSIGNMENT_WORD shall be returned. (Quoted characters cannot participate 2311 in forming a valid name.) 2312 - Otherwise, it is unspecified whether it is ASSIGNMENT_WORD or WORD that 2313 is returned. 2314 Assignment to the NAME shall occur as specified in Section 2.9.1 (on page 2248). 2315 8. [NAME in function] 2316 When the TOKEN is exactly a reserved word, the token identifier for that reserved word 2317 shall result. Otherwise, when the TOKEN meets the requirements for a name, the token 2318 identifier NAME shall result. Otherwise, rule 7 applies. 2319 9. [Body of function] 2320 Word expansion and assignment shall never occur, even when required by the rules above, 2321 when this rule is being parsed. Each TOKEN that might either be expanded or have 2322 assignment applied to it shall instead be returned as a single WORD consisting only of 2323 characters that are exactly the token described in Section 2.3 (on page 2233). 2258 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Grammar 2324 /* ------------------------------------------------------- | 2325 The grammar symbols 2326 ------------------------------------------------------- */ 2327 %token WORD 2328 %token ASSIGNMENT_WORD 2329 %token NAME 2330 %token NEWLINE 2331 %token IO_NUMBER 2332 /* The following are the operators mentioned above. */ 2333 %token AND_IF OR_IF DSEMI 2334 /* '&&' '||' ';;' */ 2335 %token DLESS DGREAT LESSAND GREATAND LESSGREAT DLESSDASH 2336 /* '<<' '>>' '<&' '>&' '<>' '<<-' */ 2337 %token CLOBBER 2338 /* '>|' */ 2339 /* The following are the reserved words. */ 2340 %token If Then Else Elif Fi Do Done 2341 /* 'if' 'then' 'else' 'elif' 'fi' 'do' 'done' */ 2342 %token Case Esac While Until For 2343 /* 'case' 'esac' 'while' 'until' 'for' */ 2344 /* These are reserved words, not operator tokens, and are 2345 recognized when reserved words are recognized. */ 2346 %token Lbrace Rbrace Bang 2347 /* '{' '}' '!' */ 2348 %token In 2349 /* 'in' */ 2350 /* ------------------------------------------------------- 2351 The Grammar 2352 ------------------------------------------------------- */ 2353 %start complete_command 2354 %% 2355 complete_command : list separator 2356 | list 2357 ; 2358 list : list separator_op and_or 2359 | and_or 2360 ; 2361 and_or : pipeline 2362 | and_or AND_IF linebreak pipeline 2363 | and_or OR_IF linebreak pipeline 2364 ; 2365 pipeline : pipe_sequence 2366 | Bang pipe_sequence 2367 ; 2368 pipe_sequence : command 2369 | pipe_sequence '|' linebreak command Shell and Utilities, Issue 6 2259 Shell Grammar Shell Command Language 2370 ; 2371 command : simple_command 2372 | compound_command 2373 | compound_command redirect_list 2374 | function_definition 2375 ; 2376 compound_command : brace_group 2377 | subshell 2378 | for_clause 2379 | case_clause 2380 | if_clause 2381 | while_clause 2382 | until_clause 2383 ; 2384 subshell : '(' compound_list ')' 2385 ; 2386 compound_list : term 2387 | newline_list term 2388 | term separator 2389 | newline_list term separator 2390 ; 2391 term : term separator and_or 2392 | and_or 2393 ; 2394 for_clause : For name linebreak do_group 2395 | For name linebreak in sequential_sep_do_group 2396 | For name linebreak in wordlist sequential_sep do_group 2397 ; 2398 name : NAME /* Apply rule 5 */ 2399 ; 2400 in : In /* Apply rule 6 */ 2401 ; 2402 wordlist : wordlist WORD 2403 | WORD 2404 ; 2405 case_clause : Case WORD linebreak in linebreak case_list Esac 2406 | Case WORD linebreak in linebreak case_list_ns Esac 2407 | Case WORD linebreak in linebreak Esac 2408 ; 2409 case_list_ns : case_list case_item_ns 2410 | case_item_ns 2411 ; 2412 case_list : case_list case_item 2413 | case_item 2414 ; 2415 case_item_ns : pattern ')' linebreak linebreak 2416 | pattern ')' compound_list linebreak 2417 | '(' pattern ')' linebreak linebreak 2418 | '(' pattern ')' compound_list linebreak 2419 ; 2420 case_item : pattern ')' linebreak DSEMI linebreak 2421 | pattern ')' compound_list linebreak 2260 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Grammar 2422 | '(' pattern ')' linebreak linebreak 2423 | '(' pattern ')' compound_list linebreak 2424 ; 2425 pattern : WORD /* Apply rule 4 */ 2426 | pattern '|' WORD /* Do not apply rule (4) */ 2427 ; 2428 if_clause : If compound_list Then compound_list else_part Fi 2429 | If compound_list Then compound_list Fi 2430 ; 2431 else_part : Elif compound_list Then else_part 2432 | Else compound_list 2433 ; 2434 while_clause : While compound_list do_group 2435 ; 2436 until_clause : Until compound_list do_group 2437 ; 2438 function_definition : fname '(' ')' linebreak function_body 2439 ; 2440 function_body : compound_command /* Apply rule 9 */ 2441 | compound_command redirect_list /* Apply rule 9 */ 2442 ; 2443 fname : NAME /* Apply rule 8 */ 2444 ; 2445 brace_group : Lbrace compound_list Rbrace 2446 ; 2447 do_group : Do compound_list Done 2448 ; 2449 simple_command : cmd_prefix cmd_word cmd_suffix 2450 | cmd_prefix cmd_word 2451 | cmd_prefix 2452 | cmd_name cmd_suffix 2453 | cmd_name 2454 ; 2455 cmd_name : WORD /* Apply rule 7a */ 2456 ; 2457 cmd_word : WORD /* Apply rule 7b */ 2458 ; 2459 cmd_prefix : io_redirect 2460 | cmd_prefix io_redirect 2461 | ASSIGNMENT_WORD 2462 | cmd_prefix ASSIGNMENT_WORD 2463 ; 2464 cmd_suffix : io_redirect 2465 | cmd_suffix io_redirect 2466 | WORD 2467 | cmd_suffix WORD 2468 ; 2469 redirect_list : io_redirect 2470 | redirect_list io_redirect 2471 ; 2472 io_redirect : io_file 2473 | IO_NUMBER io_file Shell and Utilities, Issue 6 2261 Shell Grammar Shell Command Language 2474 | io_here 2475 | IO_NUMBER io_here 2476 ; 2477 io_file : '<' filename 2478 | LESSAND filename 2479 | '>' filename 2480 | GREATAND filename 2481 | DGREAT filename 2482 | LESSGREAT filename 2483 | CLOBBER filename 2484 ; 2485 filename : WORD /* Apply rule 2 */ 2486 ; 2487 io_here : DLESS here_end 2488 | DLESSDASH here_end 2489 ; 2490 here_end : WORD /* Apply rule 3 */ 2491 ; 2492 newline_list : NEWLINE 2493 | newline_list NEWLINE 2494 ; 2495 linebreak : newline_list 2496 | /* empty */ 2497 ; 2498 separator_op : '&' 2499 | ';' 2500 ; 2501 separator : separator_op linebreak 2502 | newline_list 2503 ; 2504 sequential_sep : ';' linebreak 2505 | newline_list 2506 ; 2507 2.11 Signals and Error Handling 2508 When a command is in an asynchronous list, the shell shall prevent SIGQUIT and SIGINT 2509 signals from the keyboard from interrupting the command. Otherwise, signals shall have the 2510 values inherited by the shell from its parent (see also the trap (on page 2297) special built-in). 2511 When a signal for which a trap has been set is received while the shell is waiting for the 2512 completion of a utility executing a foreground command, the trap associated with that signal 2513 shall not be executed until after the foreground command has completed. When the shell is 2514 waiting, by means of the wait utility, for asynchronous commands to complete, the reception of a 2515 signal for which a trap has been set shall cause the wait utility to return immediately with an exit 2516 status >128, immediately after which the trap associated with that signal shall be taken. 2517 If multiple signals are pending for the shell for which there are associated trap actions, the order 2518 of execution of trap actions is unspecified. 2262 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Shell Execution Environment 2519 2.12 Shell Execution Environment 2520 A shell execution environment consists of the following: 2521 * Open files inherited upon invocation of the shell, plus open files controlled by exec 2522 * Working directory as set by cd 2523 * File creation mask set by umask 2524 * Current traps set by trap 2525 * Shell parameters that are set by variable assignment (see the set (on page 2287) special built- 2526 in) or from the System Interfaces volume of IEEE Std 1003.1-200x environment inherited by 2527 the shell when it begins (see the export (on page 2281) special built-in) 2528 * Shell functions; see Section 2.9.5 (on page 2256) 2529 * Options turned on at invocation or by set 2530 * Process IDs of the last commands in asynchronous lists known to this shell environment; see 2531 Section 2.9.3.1 (on page 2252) 2532 * Shell aliases; see Section 2.3.1 (on page 2234) 2533 Utilities other than the special built-ins (see Section 2.14 (on page 2266)) shall be invoked in a 2534 separate environment that consists of the following. The initial value of these objects shall be the 2535 same as that for the parent shell, except as noted below. 2536 * Open files inherited on invocation of the shell, open files controlled by the exec special built- 2537 in plus any modifications, and additions specified by any redirections to the utility 2538 * Current working directory 2539 * File creation mask 2540 * If the utility is a shell script, traps caught by the shell shall be set to the default values and 2541 traps ignored by the shell shall be set to be ignored by the utility; if the utility is not a shell 2542 script, the trap actions (default or ignore) shall be mapped into the appropriate signal 2543 handling actions for the utility 2544 * Variables with the export attribute, along with those explicitly exported for the duration of the 2545 command, shall be passed to the utility as System Interfaces volume of IEEE Std 1003.1-200x 2546 environment variables 2547 The environment of the shell process shall not be changed by the utility unless explicitly 2548 specified by the utility description (for example, cd and umask). 2549 A subshell environment shall be created as a duplicate of the shell environment, except that 2550 signal traps set by that shell environment shall be set to the default values. Changes made to the 2551 subshell environment shall not affect the shell environment. Command substitution, commands 2552 that are grouped with parentheses, and asynchronous lists shall be executed in a subshell 2553 environment. Additionally, each command of a multi-command pipeline is in a subshell 2554 environment; as an extension, however, any or all commands in a pipeline may be executed in 2555 the current environment. All other commands shall be executed in the current shell 2556 environment. Shell and Utilities, Issue 6 2263 Pattern Matching Notation Shell Command Language 2557 2.13 Pattern Matching Notation 2558 The pattern matching notation described in this section is used to specify patterns for matching 2559 strings in the shell. Historically, pattern matching notation is related to, but slightly different 2560 from, the regular expression notation described in the Base Definitions volume of 2561 IEEE Std 1003.1-200x, Chapter 9, Regular Expressions. For this reason, the description of the 2562 rules for this pattern matching notation are based on the description of regular expression 2563 notation, modified to include backslash escape processing. 2564 2.13.1 Patterns Matching a Single Character 2565 The following patterns matching a single character shall match a single character: ordinary | 2566 characters, special pattern characters, and pattern bracket expressions. The pattern bracket expression 2567 also shall match a single collating element. A backslash character shall escape the following 2568 character. The escaping backslash shall be discarded. 2569 An ordinary character is a pattern that shall match itself. It can be any character in the supported 2570 character set except for NUL, those special shell characters in Section 2.2 (on page 2232) that 2571 require quoting, and the following three special pattern characters. Matching shall be based on 2572 the bit pattern used for encoding the character, not on the graphic representation of the 2573 character. If any character (ordinary, shell special, or pattern special) is quoted, that pattern shall 2574 match the character itself. The shell special characters always require quoting. 2575 When unquoted and outside a bracket expression, the following three characters shall have 2576 special meaning in the specification of patterns: 2577 ? A question-mark is a pattern that shall match any character. 2578 * An asterisk is a pattern that shall match multiple characters, as described in Section 2.13.2. 2579 [ The open bracket shall introduce a pattern bracket expression. 2580 The description of basic regular expression bracket expressions in the Base Definitions volume 2581 of IEEE Std 1003.1-200x, Section 9.3.5, RE Bracket Expression shall also apply to the pattern 2582 bracket expression, except that the exclamation mark character ('!') shall replace the 2583 circumflex character (' ') in its role in a non-matching list in the regular expression notation. A 2584 bracket expression starting with an unquoted circumflex character produces unspecified results. 2585 When pattern matching is used where shell quote removal is not performed (such as in the 2586 argument to the find name primary when find is being called using one of the exec functions as 2587 defined in the System Interfaces volume of IEEE Std 1003.1-200x, or in the pattern argument to 2588 the fnmatch( ) function), special characters can be escaped to remove their special meaning by 2589 preceding them with a backslash character. This escaping backslash is discarded. The sequence 2590 "\\" represents one literal backslash. All of the requirements and effects of quoting on ordinary, 2591 shell special, and special pattern characters shall apply to escaping in this context. 2592 2.13.2 Patterns Matching Multiple Characters 2593 The following rules are used to construct patterns matching multiple characters from patterns 2594 matching a single character: 2595 1. The asterisk ('*') is a pattern that shall match any string, including the null string. 2596 2. The concatenation of patterns matching a single character is a valid pattern that shall match 2597 the concatenation of the single characters or collating elements matched by each of the 2598 concatenated patterns. 2264 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language Pattern Matching Notation 2599 3. The concatenation of one or more patterns matching a single character with one or more 2600 asterisks is a valid pattern. In such patterns, each asterisk shall match a string of zero or 2601 more characters, matching the greatest possible number of characters that still allows the 2602 remainder of the pattern to match the string. 2603 2.13.3 Patterns Used for Filename Expansion 2604 The rules described so far in Section 2.13.1 (on page 2264) and Section 2.13.2 (on page 2264) are 2605 qualified by the following rules that apply when pattern matching notation is used for filename 2606 expansion: 2607 1. The slash character in a pathname shall be explicitly matched by using one or more slashes | 2608 in the pattern; it shall neither be matched by the asterisk or question-mark special | 2609 characters nor by a bracket expression. Slashes in the pattern shall be identified before | 2610 bracket expressions; thus, a slash cannot be included in a pattern bracket expression used | 2611 for filename expansion. If a slash character is found following an unescaped open square | 2612 bracket character before a corresponding closing square bracket is found, the open bracket | 2613 shall be treated as an ordinary character. For example, the pattern "a[b/c]d" does not | 2614 match such pathnames as abd or a/d. It only matches a pathname of literally a[b/c]d. 2615 2. If a filename begins with a period ('.'), the period shall be explicitly matched by using a | 2616 period as the first character of the pattern or immediately following a slash character. The | 2617 leading period shall not be matched by: | 2618 * The asterisk or question-mark special characters 2619 * A bracket expression containing a non-matching list, such as "[!a]", a range 2620 expression, such as "[%-0]", or a character class expression, such as "[[:punct:]]" 2621 It is unspecified whether an explicit period in a bracket expression matching list, such as 2622 "[.abc]", can match a leading period in a filename. 2623 3. Specified patterns shall be matched against existing filenames and pathnames, as | 2624 appropriate. Each component that contains a pattern character shall require read | 2625 permission in the directory containing that component. Any component, except the last, | 2626 that does not contain a pattern character shall require search permission. For example, | 2627 given the pattern: | 2628 /foo/bar/x*/bam | 2629 search permission is needed for directories / and foo, search and read permissions are 2630 needed for directory bar, and search permission is needed for each x* directory. If the 2631 pattern matches any existing filenames or pathnames, the pattern shall be replaced with 2632 those filenames and pathnames, sorted according to the collating sequence in effect in the 2633 current locale. If the pattern contains an invalid bracket expression or does not match any 2634 existing filenames or pathnames, the pattern string shall be left unchanged. Shell and Utilities, Issue 6 2265 Special Built-In Utilities Shell Command Language 2635 2.14 Special Built-In Utilities 2636 The following special built-in utilities shall be supported in the shell command language. The 2637 output of each command, if any, shall be written to standard output, subject to the normal 2638 redirection and piping possible with all commands. 2639 The term built-in implies that the shell can execute the utility directly and does not need to | 2640 search for it. An implementation may choose to make any utility a built-in; however, the special | 2641 built-in utilities described here differ from regular built-in utilities in two respects: 2642 1. A syntax error in a special built-in utility may cause a shell executing that utility to abort, 2643 while a syntax error in a regular built-in utility shall not cause a shell executing that utility 2644 to abort. (See Section 2.8.1 (on page 2247) for the consequences of errors on interactive and 2645 non-interactive shells.) If a special built-in utility encountering a syntax error does not 2646 abort the shell, its exit value shall be non-zero. 2647 2. Variable assignments specified with special built-in utilities remain in effect after the 2648 built-in completes; this shall not be the case with a regular built-in or other utility. 2649 The special built-in utilities in this section need not be provided in a manner accessible via the 2650 exec family of functions defined in the System Interfaces volume of IEEE Std 1003.1-200x. 2651 Some of the special built-ins are described as conforming to the Base Definitions volume of 2652 IEEE Std 1003.1-200x, Section 12.2, Utility Syntax Guidelines. For those that are not, the 2653 requirement in Section 1.11 (on page 2221) that "- -" be recognized as a first argument to be 2654 discarded does not apply and a conforming application shall not use that argument. | 2266 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language break 2655 NAME 2656 break - exit from for, while, or until loop 2657 SYNOPSIS 2658 break [n] 2659 DESCRIPTION 2660 The break utility shall exit from the smallest enclosing for, while, or until loop, if any; or from the 2661 nth enclosing loop if n is specified. The value of n is an unsigned decimal integer greater than or 2662 equal to 1. The default shall be equivalent to n=1. If n is greater than the number of enclosing | 2663 loops, the outermost enclosing loop shall be exited. Execution shall continue with the command | 2664 immediately following the loop. 2665 OPTIONS 2666 None. 2667 OPERANDS 2668 None. 2669 STDIN 2670 None. 2671 INPUT FILES 2672 None. 2673 ENVIRONMENT VARIABLES 2674 None. 2675 ASYNCHRONOUS EVENTS 2676 None. 2677 STDOUT 2678 None. 2679 STDERR 2680 None. 2681 OUTPUT FILES 2682 None. 2683 EXTENDED DESCRIPTION 2684 None. 2685 EXIT STATUS 2686 0 Successful completion. 2687 >0 The n value was not an unsigned decimal integer greater than or equal to 1. 2688 CONSEQUENCES OF ERRORS 2689 None. Shell and Utilities, Issue 6 2267 break Shell Command Language 2690 APPLICATION USAGE 2691 None. 2692 EXAMPLES 2693 for i in * do 2694 if test -d "$i" then break fi done 2695 RATIONALE 2696 In early proposals, consideration was given to expanding the syntax of break and continue to refer 2697 to a label associated with the appropriate loop as a preferable alternative to the n method. 2698 However, this volume of IEEE Std 1003.1-200x does reserve the namespace of command names 2699 ending with a colon. It is anticipated that a future implementation could take advantage of this 2700 and provide something like: 2701 outofloop: for i in a b c d e 2702 do 2703 for j in 0 1 2 3 4 5 6 7 8 9 2704 do 2705 if test -r "${i}${j}" 2706 then break outofloop 2707 fi 2708 done 2709 done 2710 and that this might be standardized after implementation experience is achieved. 2711 FUTURE DIRECTIONS 2712 None. 2713 SEE ALSO 2714 Section 2.14 (on page 2266) 2715 CHANGE HISTORY 2716 None. 2268 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language colon 2717 NAME 2718 colon - null utility 2719 SYNOPSIS 2720 : [argument ...] 2721 DESCRIPTION 2722 This utility shall only expand command arguments. It is used when a command is needed, as in 2723 the then condition of an if command, but nothing is to be done by the command. 2724 OPTIONS 2725 None. 2726 OPERANDS 2727 None. 2728 STDIN 2729 None. 2730 INPUT FILES 2731 None. 2732 ENVIRONMENT VARIABLES 2733 None. 2734 ASYNCHRONOUS EVENTS 2735 None. 2736 STDOUT 2737 None. 2738 STDERR 2739 None. 2740 OUTPUT FILES 2741 None. 2742 EXTENDED DESCRIPTION 2743 None. 2744 EXIT STATUS 2745 Zero. 2746 CONSEQUENCES OF ERRORS 2747 None. 2748 APPLICATION USAGE 2749 None. 2750 EXAMPLES 2751 : ${X=abc} 2752 if false 2753 then : 2754 else echo $X 2755 fi 2756 abc 2757 As with any of the special built-ins, the null utility can also have variable assignments and 2758 redirections associated with it, such as: Shell and Utilities, Issue 6 2269 colon Shell Command Language 2759 x=y : > z 2760 which sets variable x to the value y (so that it persists after the null utility completes) and creates 2761 or truncates file z. 2762 RATIONALE 2763 None. 2764 FUTURE DIRECTIONS 2765 None. 2766 SEE ALSO 2767 Section 2.14 (on page 2266) 2768 CHANGE HISTORY 2769 None. 2270 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language continue 2770 NAME 2771 continue - continue for, while, or until loop 2772 SYNOPSIS 2773 continue [n] 2774 DESCRIPTION 2775 The continue utility shall return to the top of the smallest enclosing for, while, or until loop, or to 2776 the top of the nth enclosing loop, if n is specified. This involves repeating the condition list of a 2777 while or until loop or performing the next assignment of a for loop, and reexecuting the loop if 2778 appropriate. 2779 The value of n is a decimal integer greater than or equal to 1. The default shall be equivalent to | 2780 n=1. If n is greater than the number of enclosing loops, the outermost enclosing loop shall be | 2781 used. | 2782 OPTIONS 2783 None. 2784 OPERANDS 2785 None. 2786 STDIN 2787 None. 2788 INPUT FILES 2789 None. 2790 ENVIRONMENT VARIABLES 2791 None. 2792 ASYNCHRONOUS EVENTS 2793 None. 2794 STDOUT 2795 None. 2796 STDERR 2797 None. 2798 OUTPUT FILES 2799 None. 2800 EXTENDED DESCRIPTION 2801 None. 2802 EXIT STATUS 2803 0 Successful completion. 2804 >0 The n value was not an unsigned decimal integer greater than or equal to 1. 2805 CONSEQUENCES OF ERRORS 2806 None. Shell and Utilities, Issue 6 2271 continue Shell Command Language 2807 APPLICATION USAGE 2808 None. 2809 EXAMPLES 2810 for i in * 2811 do 2812 if test -d "$i" 2813 then continue 2814 fi 2815 echo "\"$i\"" is not a directory. 2816 done 2817 RATIONALE 2818 None. 2819 FUTURE DIRECTIONS 2820 None. 2821 SEE ALSO 2822 Section 2.14 (on page 2266) 2823 CHANGE HISTORY 2824 None. 2272 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language dot 2825 NAME 2826 dot - execute commands in current environment 2827 SYNOPSIS 2828 . file 2829 DESCRIPTION 2830 The shell shall execute commands from the file in the current environment. 2831 If file does not contain a slash, the shell shall use the search path specified by PATH to find the 2832 directory containing file. Unlike normal command search, however, the file searched for by the 2833 dot utility need not be executable. If no readable file is found, a non-interactive shell shall abort; 2834 an interactive shell shall write a diagnostic message to standard error, but this condition shall 2835 not be considered a syntax error. 2836 OPTIONS 2837 None. 2838 OPERANDS 2839 None. 2840 STDIN 2841 None. 2842 INPUT FILES 2843 None. 2844 ENVIRONMENT VARIABLES 2845 None. 2846 ASYNCHRONOUS EVENTS 2847 None. 2848 STDOUT 2849 None. 2850 STDERR 2851 None. 2852 OUTPUT FILES 2853 None. 2854 EXTENDED DESCRIPTION 2855 None. 2856 EXIT STATUS 2857 Returns the value of the last command executed, or a zero exit status if no command is executed. | 2858 CONSEQUENCES OF ERRORS 2859 None. | Shell and Utilities, Issue 6 2273 dot Shell Command Language 2860 APPLICATION USAGE | 2861 None. 2862 EXAMPLES 2863 cat foobar 2864 foo=hello bar=world 2865 . foobar 2866 echo $foo $bar 2867 hello world 2868 RATIONALE 2869 Some older implementations searched the current directory for the file, even if the value of PATH 2870 disallowed it. This behavior was omitted from this volume of IEEE Std 1003.1-200x due to 2871 concerns about introducing the susceptibility to trojan horses that the user might be trying to 2872 avoid by leaving dot out of PATH. 2873 The KornShell version of dot takes optional arguments that are set to the positional parameters. 2874 This is a valid extension that allows a dot script to behave identically to a function. 2875 FUTURE DIRECTIONS 2876 None. 2877 SEE ALSO 2878 Section 2.14 (on page 2266) 2879 CHANGE HISTORY 2880 None. 2274 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language eval 2881 NAME 2882 eval - construct command by concatenating arguments 2883 SYNOPSIS 2884 eval [argument ...] 2885 DESCRIPTION 2886 The eval utility shall construct a command by concatenating arguments together, separating each 2887 with a . The constructed command shall be read and executed by the shell. 2888 OPTIONS 2889 None. 2890 OPERANDS 2891 None. 2892 STDIN 2893 None. 2894 INPUT FILES 2895 None. 2896 ENVIRONMENT VARIABLES 2897 None. 2898 ASYNCHRONOUS EVENTS 2899 None. 2900 STDOUT 2901 None. 2902 STDERR 2903 None. 2904 OUTPUT FILES 2905 None. 2906 EXTENDED DESCRIPTION 2907 None. 2908 EXIT STATUS 2909 If there are no arguments, or only null arguments, eval shall return a zero exit status; otherwise, it 2910 shall return the exit status of the command defined by the string of concatenated arguments 2911 separated by spaces. 2912 CONSEQUENCES OF ERRORS 2913 None. 2914 APPLICATION USAGE 2915 None. 2916 EXAMPLES 2917 foo=10 x=foo 2918 y='$'$x 2919 echo $y 2920 $foo 2921 eval y='$'$x 2922 echo $y 2923 10 Shell and Utilities, Issue 6 2275 eval Shell Command Language 2924 RATIONALE 2925 None. 2926 FUTURE DIRECTIONS 2927 None. 2928 SEE ALSO 2929 Section 2.14 (on page 2266) 2930 CHANGE HISTORY 2931 None. 2276 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language exec 2932 NAME 2933 exec - execute commands and open, close, or copy file descriptors 2934 SYNOPSIS 2935 exec [command [argument ...]] 2936 DESCRIPTION 2937 The exec utility shall open, close, and/or copy file descriptors as specified by any redirections as 2938 part of the command. 2939 If exec is specified without command or arguments, and any file descriptors with numbers greater 2940 than 2 are opened with associated redirection statements, it is unspecified whether those file 2941 descriptors remain open when the shell invokes another utility. Scripts concerned that child 2942 shells could misuse open file descriptors can always close them explicitly, as shown in one of the 2943 following examples. 2944 If exec is specified with command, it shall replace the shell with command without creating a new 2945 process. If arguments are specified, they shall be arguments to command. Redirection affects the 2946 current shell execution environment. 2947 OPTIONS 2948 None. 2949 OPERANDS 2950 None. 2951 STDIN 2952 None. 2953 INPUT FILES 2954 None. 2955 ENVIRONMENT VARIABLES 2956 None. 2957 ASYNCHRONOUS EVENTS 2958 None. 2959 STDOUT 2960 None. 2961 STDERR 2962 None. 2963 OUTPUT FILES 2964 None. 2965 EXTENDED DESCRIPTION 2966 None. 2967 EXIT STATUS 2968 If command is specified, exec shall not return to the shell; rather, the exit status of the process shall 2969 be the exit status of the program implementing command, which overlaid the shell. If command is 2970 not found, the exit status shall be 127. If command is found, but it is not an executable utility, the 2971 exit status shall be 126. If a redirection error occurs (see Section 2.8.1 (on page 2247)), the shell 2972 shall exit with a value in the range 1-125. Otherwise, exec shall return a zero exit status. Shell and Utilities, Issue 6 2277 exec Shell Command Language 2973 CONSEQUENCES OF ERRORS 2974 None. 2975 APPLICATION USAGE 2976 None. 2977 EXAMPLES 2978 Open readfile as file descriptor 3 for reading: 2979 exec 3< readfile 2980 Open writefile as file descriptor 4 for writing: 2981 exec 4> writefile 2982 Make file descriptor 5 a copy of file descriptor 0: 2983 exec 5<&0 2984 Close file descriptor 3: 2985 exec 3<&- 2986 Cat the file maggie by replacing the current shell with the cat utility: 2987 exec cat maggie 2988 RATIONALE 2989 Most historical implementations were not conformant in that: 2990 foo=bar exec cmd 2991 did not pass foo to cmd. 2992 FUTURE DIRECTIONS 2993 None. 2994 SEE ALSO 2995 Section 2.14 (on page 2266) 2996 CHANGE HISTORY 2997 None. 2278 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language exit 2998 NAME 2999 exit - cause the shell to exit 3000 SYNOPSIS 3001 exit [n] 3002 DESCRIPTION 3003 The exit utility shall cause the shell to exit with the exit status specified by the unsigned decimal 3004 integer n. If n is specified, but its value is not between 0 and 255 inclusively, the exit status is 3005 undefined. 3006 A trap on EXIT shall be executed before the shell terminates, except when the exit utility is 3007 invoked in that trap itself, in which case the shell shall exit immediately. 3008 OPTIONS 3009 None. 3010 OPERANDS 3011 None. 3012 STDIN 3013 None. 3014 INPUT FILES 3015 None. 3016 ENVIRONMENT VARIABLES 3017 None. 3018 ASYNCHRONOUS EVENTS 3019 None. 3020 STDOUT 3021 None. 3022 STDERR 3023 None. 3024 OUTPUT FILES 3025 None. 3026 EXTENDED DESCRIPTION 3027 None. 3028 EXIT STATUS 3029 The exit status shall be n, if specified. Otherwise, the value shall be the exit value of the last 3030 command executed, or zero if no command was executed. When exit is executed in a trap action, 3031 the last command is considered to be the command that executed immediately preceding the 3032 trap action. | 3033 CONSEQUENCES OF ERRORS 3034 None. | Shell and Utilities, Issue 6 2279 exit Shell Command Language 3035 APPLICATION USAGE | 3036 None. 3037 EXAMPLES 3038 Exit with a true value: 3039 exit 0 3040 Exit with a false value: 3041 exit 1 3042 RATIONALE 3043 As explained in other sections, certain exit status values have been reserved for special uses and 3044 should be used by applications only for those purposes: 3045 126 A file to be executed was found, but it was not an executable utility. 3046 127 A utility to be executed was not found. 3047 >128 A command was interrupted by a signal. 3048 FUTURE DIRECTIONS 3049 None. 3050 SEE ALSO 3051 Section 2.14 (on page 2266) 3052 CHANGE HISTORY 3053 None. 2280 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language export 3054 NAME 3055 export - set export attribute for variables 3056 SYNOPSIS 3057 export name[=word]... 3058 export -p 3059 DESCRIPTION 3060 The shell shall give the export attribute to the variables corresponding to the specified names, 3061 which shall cause them to be in the environment of subsequently executed commands. 3062 The export special built-in shall support the Base Definitions volume of IEEE Std 1003.1-200x, 3063 Section 12.2, Utility Syntax Guidelines. 3064 When -p is specified, export shall write to the standard output the names and values of all 3065 exported variables, in the following format: 3066 "export %s=%s\n", , 3067 if name is set, and: | 3068 "export %s\n", | 3069 if name is unset. | 3070 The shell shall format the output, including the proper use of quoting, so that it is suitable for | 3071 reinput to the shell as commands that achieve the same exporting results, except: | 3072 1. Read-only variables with values cannot be reset. | 3073 2. Variables that were unset at the time they were output need not be reset to the unset state | 3074 if a value is assigned to the variable between the time the state was saved and the time at | 3075 which the saved output is reinput to the shell. | 3076 When no arguments are given, the results are unspecified. | 3077 OPTIONS 3078 None. 3079 OPERANDS 3080 None. 3081 STDIN 3082 None. 3083 INPUT FILES 3084 None. 3085 ENVIRONMENT VARIABLES 3086 None. 3087 ASYNCHRONOUS EVENTS 3088 None. 3089 STDOUT 3090 None. 3091 STDERR 3092 None. Shell and Utilities, Issue 6 2281 export Shell Command Language 3093 OUTPUT FILES 3094 None. 3095 EXTENDED DESCRIPTION 3096 None. 3097 EXIT STATUS 3098 Zero. | 3099 CONSEQUENCES OF ERRORS 3100 None. | 3101 APPLICATION USAGE | 3102 None. 3103 EXAMPLES 3104 Export PWD and HOME variables: 3105 export PWD HOME 3106 Set and export the PATH variable: 3107 export PATH=/local/bin:$PATH 3108 Save and restore all exported variables: 3109 export -p > temp-file 3110 unset a lot of variables 3111 ... processing 3112 . temp-file 3113 RATIONALE 3114 Some historical shells use the no-argument case as the functional equivalent of what is required 3115 here with -p. This feature was left unspecified because it is not historical practice in all shells, 3116 and some scripts may rely on the now-unspecified results on their implementations. Attempts to 3117 specify the -p output as the default case were unsuccessful in achieving consensus. The -p 3118 option was added to allow portable access to the values that can be saved and then later restored 3119 using; for example, a dot script. 3120 FUTURE DIRECTIONS 3121 None. 3122 SEE ALSO 3123 Section 2.14 (on page 2266) 3124 CHANGE HISTORY 3125 Issue 6 | 3126 IEEE PASC Interpretation 1003.2 #203 is applied, clarifying the format when a variable is unset. | 2282 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language readonly 3127 NAME 3128 readonly - set read-only attribute for variables 3129 SYNOPSIS 3130 readonly name[=word]... 3131 readonly -p 3132 DESCRIPTION 3133 The variables whose names are specified shall be given the readonly attribute. The values of 3134 variables with the readonly attribute cannot be changed by subsequent assignment, nor can those 3135 variables be unset by the unset utility. 3136 The readonly special built-in shall support the Base Definitions volume of IEEE Std 1003.1-200x, 3137 Section 12.2, Utility Syntax Guidelines. 3138 When -p is specified, readonly writes to the standard output the names and values of all read- 3139 only variables, in the following format: 3140 "readonly %s=%s\n", , 3141 if name is set, and | 3142 "readonly %s\n", | 3143 if name is unset. | 3144 The shell shall format the output, including the proper use of quoting, so that it is suitable for | 3145 reinput to the shell as commands that achieve the same value and read-only attribute-setting | 3146 results in a shell execution environment in which: | 3147 1. Variables with values at the time they were output do not have the read-only attribute set. | 3148 2. Variables that were unset at the time they were output do not have a value at the time at | 3149 which the saved output is reinput to the shell. | 3150 When no arguments are given, the results are unspecified. | 3151 OPTIONS 3152 None. 3153 OPERANDS 3154 None. 3155 STDIN 3156 None. 3157 INPUT FILES 3158 None. 3159 ENVIRONMENT VARIABLES 3160 None. 3161 ASYNCHRONOUS EVENTS 3162 None. 3163 STDOUT 3164 None. Shell and Utilities, Issue 6 2283 readonly Shell Command Language 3165 STDERR 3166 None. 3167 OUTPUT FILES 3168 None. 3169 EXTENDED DESCRIPTION 3170 None. 3171 EXIT STATUS 3172 Zero. | 3173 CONSEQUENCES OF ERRORS 3174 None. | 3175 APPLICATION USAGE | 3176 None. 3177 EXAMPLES 3178 readonly HOME PWD 3179 RATIONALE 3180 Some historical shells preserve the read-only attribute across separate invocations. This volume 3181 of IEEE Std 1003.1-200x allows this behavior, but does not require it. 3182 The -p option allows portable access to the values that can be saved and then later restored 3183 using; for example, a dot script. Also see the RATIONALE for export (on page 2281) for a 3184 description of the no-argument and -p output cases and a related example. 3185 Read-only functions were considered, but they were omitted as not being historical practice or 3186 particularly useful. Furthermore, functions must not be readonly across invocations to preclude 3187 spoofing (spoofing is the term for the practice of creating a program that acts like a well-known 3188 utility with the intent of subverting the real intent of the user) of administrative or security- 3189 relevant (or security-conscious) shell scripts. 3190 FUTURE DIRECTIONS 3191 None. 3192 SEE ALSO 3193 Section 2.14 (on page 2266) 3194 CHANGE HISTORY 3195 Issue 6 | 3196 IEEE PASC Interpretation 1003.2 #203 is applied, clarifying the format when a variable is unset. | 2284 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language return 3197 NAME 3198 return - return from a function 3199 SYNOPSIS 3200 return [n] 3201 DESCRIPTION 3202 The return utility shall cause the shell to stop executing the current function or dot script. If the 3203 shell is not currently executing a function or dot script, the results are unspecified. 3204 OPTIONS 3205 None. 3206 OPERANDS 3207 None. 3208 STDIN 3209 None. 3210 INPUT FILES 3211 None. 3212 ENVIRONMENT VARIABLES 3213 None. 3214 ASYNCHRONOUS EVENTS 3215 None. 3216 STDOUT 3217 None. 3218 STDERR 3219 None. 3220 OUTPUT FILES 3221 None. 3222 EXTENDED DESCRIPTION 3223 None. 3224 EXIT STATUS 3225 The value of the special parameter '?' shall be set to n, an unsigned decimal integer, or to the 3226 exit status of the last command executed if n is not specified. If the value of n is greater than 255, 3227 the results are undefined. When return is executed in a trap action, the last command is 3228 considered to be the command that executed immediately preceding the trap action. 3229 CONSEQUENCES OF ERRORS 3230 None. 3231 APPLICATION USAGE 3232 None. 3233 EXAMPLES 3234 None. 3235 RATIONALE 3236 The behavior of return when not in a function or dot script differs between the System V shell 3237 and the KornShell. In the System V shell this is an error, whereas in the KornShell, the effect is 3238 the same as exit. Shell and Utilities, Issue 6 2285 return Shell Command Language 3239 The results of returning a number greater than 255 are undefined because of differing practices 3240 in the various historical implementations. Some shells AND out all but the low-order 8 bits; 3241 others allow larger values, but not of unlimited size. 3242 See the discussion of appropriate exit status values under exit (on page 2279). 3243 FUTURE DIRECTIONS 3244 None. 3245 SEE ALSO 3246 Section 2.14 (on page 2266) 3247 CHANGE HISTORY 3248 None. 2286 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language set 3249 NAME 3250 set - set or unset options and positional parameters 3251 SYNOPSIS 3252 XSI set [-abCefmnuvx][-h][-o option][argument...] 3253 XSI set [+abCefmnuvx][+h][+o option][argument...] 3254 set - -[argument...] 3255 set -o 3256 set +o 3257 DESCRIPTION 3258 If no options or arguments are specified, set shall write the names and values of all shell variables 3259 in the collation sequence of the current locale. Each name shall start on a separate line, using the 3260 format: 3261 "%s=%s\n", , 3262 The value string shall be written with appropriate quoting so that it is suitable for reinput to the 3263 shell, setting or resetting, as far as possible, the variables that are currently set. Read-only 3264 variables cannot be reset; see the description of shell quoting in Section 2.2 (on page 2232). 3265 When options are specified, they shall set or unset attributes of the shell, as described below. 3266 When arguments are specified, they cause positional parameters to be set or unset, as described 3267 below. Setting or unsetting attributes and positional parameters are not necessarily related 3268 actions, but they can be combined in a single invocation of set. 3269 The set special built-in shall support the Base Definitions volume of IEEE Std 1003.1-200x, 3270 Section 12.2, Utility Syntax Guidelines except that options can be specified with either a leading 3271 hyphen (meaning enable the option) or plus sign (meaning disable it). 3272 Implementations shall support the options in the following list in both their hyphen and plus- 3273 sign forms. These options can also be specified as options to sh. 3274 -a When this option is on, the export attribute shall be set for each variable to which an | 3275 assignment is performed; see the Base Definitions volume of IEEE Std 1003.1-200x, Section | 3276 4.21, Variable Assignment. If the assignment precedes a utility name in a command, the | 3277 export attribute shall not persist in the current execution environment after the utility 3278 completes, with the exception that preceding one of the special built-in utilities causes the 3279 export attribute to persist after the built-in has completed. If the assignment does not 3280 precede a utility name in the command, or if the assignment is a result of the operation of 3281 the getopts or read utilities, the export attribute shall persist until the variable is unset. 3282 -b This option shall be supported if the implementation supports the User Portability Utilities | 3283 option. It shall cause the shell to notify the user asynchronously of background job | 3284 completions. The following message is written to standard error: | 3285 "[%d]%c %s%s\n", , , , 3286 where the fields shall be as follows: 3287 The character '+' identifies the job that would be used as a default for 3288 the fg or bg utilities; this job can also be specified using the job_id "%+" or 3289 "%%". The character '-' identifies the job that would become the default 3290 if the current default job were to exit; this job can also be specified using 3291 the job_id "%-". For other jobs, this field is a . At most one job 3292 can be identified with '+' and at most one job can be identified with '-'. Shell and Utilities, Issue 6 2287 set Shell Command Language 3293 If there is any suspended job, then the current job shall be a suspended 3294 job. If there are at least two suspended jobs, then the previous job also 3295 shall be a suspended job. 3296 A number that can be used to identify the process group to the wait, fg, bg, 3297 and kill utilities. Using these utilities, the job can be identified by 3298 prefixing the job number with '%'. 3299 Unspecified. 3300 Unspecified. 3301 When the shell notifies the user a job has been completed, it may remove the job's process 3302 ID from the list of those known in the current shell execution environment; see Section 3303 2.9.3.1 (on page 2252). Asynchronous notification shall not be enabled by default. 3304 -C (Uppercase C.) Prevent existing files from being overwritten by the shell's '>' redirection 3305 operator (see Section 2.7.2 (on page 2245)); the ">|" redirection operator shall override this 3306 noclobber option for an individual file. 3307 -e When this option is on, if a simple command fails for any of the reasons listed in Section 3308 2.8.1 (on page 2247) or returns an exit status value >0, and is not part of the compound list 3309 following a while, until, or if keyword, and is not a part of an AND or OR list, and is not a 3310 pipeline preceded by the ! reserved word, then the shell shall immediately exit. 3311 -f The shell shall disable pathname expansion. 3312 XSI -h Locate and remember utilities invoked by functions as those functions are defined (the 3313 utilities are normally located when the function is executed). 3314 -m This option shall be supported if the implementation supports the User Portability Utilities | 3315 option. All jobs shall be run in their own process groups. Immediately before the shell | 3316 issues a prompt after completion of the background job, a message reporting the exit status | 3317 of the background job shall be written to standard error. If a foreground job stops, the shell | 3318 shall write a message to standard error to that effect, formatted as described by the jobs | 3319 utility. In addition, if a job changes status other than exiting (for example, if it stops for 3320 input or output or is stopped by a SIGSTOP signal), the shell shall write a similar message 3321 immediately prior to writing the next prompt. This option is enabled by default for 3322 interactive shells. 3323 -n The shell shall read commands but does not execute them; this can be used to check for 3324 shell script syntax errors. An interactive shell may ignore this option. 3325 -o Write the current settings of the options to standard output in an unspecified format. 3326 +o Write the current option settings to standard output in a format that is suitable for reinput 3327 to the shell as commands that achieve the same options settings. 3328 -o option 3329 This option is supported if the system supports the User Portability Utilities option. It shall 3330 set various options, many of which shall be equivalent to the single option letters. The 3331 following values of option shall be supported: 3332 allexport Equivalent to -a. 3333 errexit Equivalent to -e. 3334 ignoreeof Prevent an interactive shell from exiting on end-of-file. This setting prevents 3335 accidental logouts when -D is entered. A user shall explicitly exit to 3336 leave the interactive shell. 2288 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language set 3337 monitor Equivalent to -m. This option is supported if the system supports the User 3338 Portability Utilities option. 3339 noclobber Equivalent to -C (uppercase C). 3340 noglob Equivalent to -f. 3341 noexec Equivalent to -n. 3342 nolog Prevent the entry of function definitions into the command history; see 3343 Command History List (on page 3052). 3344 notify Equivalent to -b. 3345 nounset Equivalent to -u. 3346 verbose Equivalent to -v. 3347 vi Allow shell command line editing using the built-in vi editor. Enabling vi 3348 mode shall disable any other command line editing mode provided as an 3349 implementation extension. 3350 It need not be possible to set vi mode on for certain block-mode terminals. 3351 xtrace Equivalent to -x. 3352 -u The shell shall write a message to standard error when it tries to expand a variable that is | 3353 not set and immediately exit. An interactive shell shall not exit. | 3354 -v The shell shall write its input to standard error as it is read. | 3355 -x The shell shall write to standard error a trace for each command after it expands the | 3356 command and before it executes it. It is unspecified whether the command that turns | 3357 tracing off is traced. 3358 The default for all these options shall be off (unset) unless the shell was invoked with them on; | 3359 see sh. | 3360 The remaining arguments shall be assigned in order to the positional parameters. The special 3361 parameter '#' shall be set to reflect the number of positional parameters. All positional 3362 parameters shall be unset before any new values are assigned. 3363 The special argument "- -" immediately following the set command name can be used to 3364 delimit the arguments if the first argument begins with '+' or '-', or to prevent inadvertent 3365 listing of all shell variables when there are no arguments. The command set- - without argument 3366 shall unset all positional parameters and set the special parameter '#' to zero. 3367 OPTIONS 3368 None. 3369 OPERANDS 3370 None. 3371 STDIN 3372 None. 3373 INPUT FILES 3374 None. Shell and Utilities, Issue 6 2289 set Shell Command Language 3375 ENVIRONMENT VARIABLES 3376 None. 3377 ASYNCHRONOUS EVENTS 3378 None. 3379 STDOUT 3380 None. 3381 STDERR 3382 None. 3383 OUTPUT FILES 3384 None. 3385 EXTENDED DESCRIPTION 3386 None. 3387 EXIT STATUS 3388 Zero. 3389 CONSEQUENCES OF ERRORS 3390 None. 3391 APPLICATION USAGE 3392 None. 3393 EXAMPLES 3394 Write out all variables and their values: 3395 set 3396 Set $1, $2, and $3 and set "$#" to 3: 3397 set c a b 3398 Turn on the -x and -v options: 3399 set -xv 3400 Unset all positional parameters: 3401 set - - 3402 Set $1 to the value of -x, even if x begins with '-' or '+': 3403 set - - "$x" 3404 Set the positional parameters to the expansion of x, even if x expands with a leading '-' or '+': 3405 set - - $x 3406 RATIONALE 3407 The set - - form is listed specifically in the SYNOPSIS even though this usage is implied by the 3408 Utility Syntax Guidelines. The explanation of this feature removes any ambiguity about whether 3409 the set - - form might be misinterpreted as being equivalent to set without any options or 3410 arguments. The functionality of this form has been adopted from the KornShell. In System V, set 3411 - - only unsets parameters if there is at least one argument; the only way to unset all parameters 3412 is to use shift. Using the KornShell version should not affect System V scripts because there 3413 should be no reason to issue it without arguments deliberately; if it were issued as, for example: 3414 set - - "$@" 2290 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language set 3415 and there were in fact no arguments resulting from "$@", unsetting the parameters would have 3416 no result. 3417 The set + form in early proposals was omitted as being an unnecessary duplication of set alone 3418 and not widespread historical practice. 3419 The noclobber option was changed to allow set -C as well as the set -o noclobber option. The 3420 single-letter version was added so that the historical "$-" paradigm would not be broken; see 3421 Section 2.5.2 (on page 2235). 3422 The -h flag is related to command name hashing and is only required on XSI-conformant 3423 systems. 3424 The following set flags were omitted intentionally with the following rationale: 3425 -k The -k flag was originally added by the author of the Bourne shell to make it easier for 3426 users of pre-release versions of the shell. In early versions of the Bourne shell the construct 3427 set name=value, had to be used to assign values to shell variables. The problem with -k is 3428 that the behavior affects parsing, virtually precluding writing any compilers. To explain the 3429 behavior of -k, it is necessary to describe the parsing algorithm, which is implementation- 3430 defined. For example: 3431 set -k; echo name=value 3432 and: 3433 set x- -k 3434 echo name=value 3435 behave differently. The interaction with functions is even more complex. What is more, the 3436 -k flag is never needed, since the command line could have been reordered. 3437 -t The -t flag is hard to specify and almost never used. The only known use could be done 3438 with here-documents. Moreover, the behavior with ksh and sh differs. The reference page 3439 says that it exits after reading and executing one command. What is one command? If the 3440 input is date;date, sh executes both date commands while ksh does only the first. 3441 Consideration was given to rewriting set to simplify its confusing syntax. A specific suggestion 3442 was that the unset utility should be used to unset options instead of using the non-getopt( )-able 3443 +option syntax. However, the conclusion was reached that the historical practice of using +option 3444 was satisfactory and that there was no compelling reason to modify such widespread historical 3445 practice. 3446 The -o option was adopted from the KornShell to address user needs. In addition to its generally 3447 friendly interface, -o is needed to provide the vi command line editing mode, for which 3448 historical practice yields no single-letter option name. (Although it might have been possible to 3449 invent such a letter, it was recognized that other editing modes would be developed and -o 3450 provides ample name space for describing such extensions.) 3451 Historical implementations are inconsistent in the format used for -o option status reporting. 3452 The +o format without an option-argument was added to allow portable access to the options 3453 that can be saved and then later restored using, for instance, a dot script. 3454 Historically, sh did trace the command set +x, but ksh did not. 3455 The ignoreeof setting prevents accidental logouts when the end-of-file character (typically 3456 -D) is entered. A user shall explicitly exit to leave the interactive shell. 3457 The set -m option was added to apply only to the UPE because it applies primarily to interactive 3458 use, not shell script applications. Shell and Utilities, Issue 6 2291 set Shell Command Language 3459 The ability to do asynchronous notification became available in the 1988 version of the 3460 KornShell. To have it occur, the user had to issue the command: 3461 trap "jobs -n" CLD 3462 The C shell provides two different levels of an asynchronous notification capability. The 3463 environment variable notify is analogous to what is done in set -b or set -o notify. When set, it 3464 notifies the user immediately of background job completions. When unset, this capability is 3465 turned off. 3466 The other notification ability comes through the built-in utility notify. The syntax is: 3467 notify [%job ... ] 3468 By issuing notify with no operands, it causes the C shell to notify the user asynchronously when 3469 the state of the current job changes. If given operands, notify asynchronously informs the user of 3470 changes in the states of the specified jobs. 3471 To add asynchronous notification to the POSIX shell, neither the KornShell extensions to trap, 3472 nor the C shell notify environment variable seemed appropriate (notify is not a proper POSIX 3473 environment variable name). 3474 The set -b option was selected as a compromise. 3475 The notify built-in was considered to have more functionality than was required for simple 3476 asynchronous notification. 3477 FUTURE DIRECTIONS 3478 None. 3479 SEE ALSO 3480 Section 2.14 (on page 2266) 3481 CHANGE HISTORY 3482 Issue 6 3483 The obsolescent set command name followed by '-' has been removed. 3484 The following new requirements on POSIX implementations derive from alignment with the 3485 Single UNIX Specification: 3486 * The nolog option is added to set -o. 2292 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language shift 3487 NAME 3488 shift - shift positional parameters 3489 SYNOPSIS 3490 shift [n] 3491 DESCRIPTION 3492 The positional parameters shall be shifted. Positional parameter 1 shall be assigned the value of 3493 parameter (1+n), parameter 2 shall be assigned the value of parameter (2+n), and so on. The 3494 parameters represented by the numbers "$#" down to "$#-n+1" shall be unset, and the 3495 parameter '#' is updated to reflect the new number of positional parameters. 3496 The value n shall be an unsigned decimal integer less than or equal to the value of the special 3497 parameter '#'. If n is not given, it shall be assumed to be 1. If n is 0, the positional and special 3498 parameters are not changed. 3499 OPTIONS 3500 None. 3501 OPERANDS 3502 None. 3503 STDIN 3504 None. 3505 INPUT FILES 3506 None. 3507 ENVIRONMENT VARIABLES 3508 None. 3509 ASYNCHRONOUS EVENTS 3510 None. 3511 STDOUT 3512 None. 3513 STDERR 3514 None. 3515 OUTPUT FILES 3516 None. 3517 EXTENDED DESCRIPTION 3518 None. 3519 EXIT STATUS 3520 The exit status is >0 if n>$#; otherwise, it is zero. 3521 CONSEQUENCES OF ERRORS 3522 None. Shell and Utilities, Issue 6 2293 shift Shell Command Language 3523 APPLICATION USAGE 3524 None. 3525 EXAMPLES 3526 $ set a b c d e 3527 $ shift 2 3528 $ echo $* 3529 c d e 3530 RATIONALE 3531 None. 3532 FUTURE DIRECTIONS 3533 None. 3534 SEE ALSO 3535 Section 2.14 (on page 2266) 3536 CHANGE HISTORY 3537 None. 2294 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language times 3538 NAME 3539 times - write process times 3540 SYNOPSIS 3541 times 3542 DESCRIPTION 3543 Write the accumulated user and system times for the shell and for all of its child processes, in the 3544 following POSIX locale format: 3545 "%dm%fs %dm%fs\n%dm%fs %dm%fs\n", , 3546 , , 3547 , , 3548 , , 3549 3550 The four pairs of times shall correspond to the members of the tms structure | 3551 (defined in the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers) as 3552 returned by times( ): tms_utime, tms_stime, tms_cutime, and tms_cstime, respectively. 3553 OPTIONS 3554 None. 3555 OPERANDS 3556 None. 3557 STDIN 3558 None. 3559 INPUT FILES 3560 None. 3561 ENVIRONMENT VARIABLES 3562 None. 3563 ASYNCHRONOUS EVENTS 3564 None. 3565 STDOUT 3566 None. 3567 STDERR 3568 None. 3569 OUTPUT FILES 3570 None. 3571 EXTENDED DESCRIPTION 3572 None. 3573 EXIT STATUS 3574 Zero. 3575 CONSEQUENCES OF ERRORS 3576 None. Shell and Utilities, Issue 6 2295 times Shell Command Language 3577 APPLICATION USAGE 3578 None. 3579 EXAMPLES 3580 $ times 3581 0m0.43s 0m1.11s 3582 8m44.18s 1m43.23s 3583 RATIONALE 3584 The times special built-in from the Single UNIX Specification is now required for all conforming 3585 shells. 3586 FUTURE DIRECTIONS 3587 None. 3588 SEE ALSO 3589 Section 2.14 (on page 2266) 3590 CHANGE HISTORY 3591 None. 2296 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language trap 3592 NAME 3593 trap - trap signals 3594 SYNOPSIS 3595 trap [action condition ...] 3596 DESCRIPTION 3597 If action is '-', the shell shall reset each condition to the default value. If action is null (" "), the 3598 shell shall ignore each specified condition if it arises. Otherwise, the argument action shall be read 3599 and executed by the shell when one of the corresponding conditions arises. The action of trap 3600 shall override a previous action (either default action or one explicitly set). The value of "$?" 3601 after the trap action completes shall be the value it had before trap was invoked. 3602 The condition can be EXIT, 0 (equivalent to EXIT), or a signal specified using a symbolic name, 3603 without the SIG prefix, as listed in the tables of signal names in the header defined in 3604 the Base Definitions volume of IEEE Std 1003.1-200x, Chapter 13, Headers; for example, HUP, 3605 INT, QUIT, TERM. Implementations may permit lowercase signal names or names with the SIG 3606 prefix as an extension. Setting a trap for SIGKILL or SIGSTOP produces undefined results. 3607 The environment in which the shell executes a trap on EXIT shall be identical to the environment 3608 immediately after the last command executed before the trap on EXIT was taken. 3609 Each time trap is invoked, the action argument shall be processed in a manner equivalent to: 3610 eval "$action" 3611 Signals that were ignored on entry to a non-interactive shell cannot be trapped or reset, although 3612 no error need be reported when attempting to do so. An interactive shell may reset or catch 3613 signals ignored on entry. Traps shall remain in place for a given shell until explicitly changed 3614 with another trap command. 3615 When a subshell is entered, traps that are not being ignored are set to the default actions. This 3616 does not imply that the trap command cannot be used within the subshell to set new traps. 3617 The trap command with no arguments shall write to standard output a list of commands 3618 associated with each condition. The format shall be: 3619 "trap - - %s %s ...\n", , ... 3620 The shell shall format the output, including the proper use of quoting, so that it is suitable for 3621 reinput to the shell as commands that achieve the same trapping results. For example: 3622 save_traps=$(trap) 3623 ... 3624 eval "$save_traps" 3625 XSI XSI-conformant systems also allow numeric signal numbers for the conditions corresponding to 3626 the following signal names: Shell and Utilities, Issue 6 2297 trap Shell Command Language 3627 _______________________________ 3628 _ Signal Number Signal Name ______________________________ 3629 XSI 1 SIGHUP 3630 XSI 2 SIGINT 3631 XSI 3 SIGQUIT 3632 XSI 6 SIGABRT 3633 XSI 9 SIGKILL 3634 XSI 14 SIGALRM 3635 XSI _ 15 SIGTERM ______________________________ 3636 The trap special built-in shall conform to the Base Definitions volume of IEEE Std 1003.1-200x, 3637 Section 12.2, Utility Syntax Guidelines. 3638 OPTIONS 3639 None. 3640 OPERANDS 3641 None. 3642 STDIN 3643 None. 3644 INPUT FILES 3645 None. 3646 ENVIRONMENT VARIABLES 3647 None. 3648 ASYNCHRONOUS EVENTS 3649 None. 3650 STDOUT 3651 None. 3652 STDERR 3653 None. 3654 OUTPUT FILES 3655 None. 3656 EXTENDED DESCRIPTION 3657 None. 3658 EXIT STATUS 3659 XSI If the trap name or number is invalid, a non-zero exit status shall be returned; otherwise, zero 3660 XSI shall be returned. For both interactive and non-interactive shells, invalid signal names or 3661 numbersshall not be considered a syntax error and do not cause the shell to abort. | 3662 CONSEQUENCES OF ERRORS 3663 None. | 2298 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language trap 3664 APPLICATION USAGE | 3665 None. 3666 EXAMPLES 3667 Write out a list of all traps and actions: 3668 trap 3669 Set a trap so the logout utility in the directory referred to by the HOME environment variable 3670 executes when the shell terminates: 3671 trap '$HOME/logout' EXIT 3672 or: 3673 trap '$HOME/logout' 0 3674 Unset traps on INT, QUIT, TERM, and EXIT: 3675 trap - INT QUIT TERM EXIT 3676 RATIONALE 3677 Implementations may permit lowercase signal names as an extension. Implementations may 3678 also accept the names with the SIG prefix; no known historical shell does so. The trap and kill 3679 utilities in this volume of IEEE Std 1003.1-200x are now consistent in their omission of the SIG 3680 prefix for signal names. Some kill implementations do not allow the prefix, and kill -l lists the 3681 signals without prefixes. 3682 Trapping SIGKILL or SIGSTOP is syntactically accepted by some historical implementations, but 3683 it has no effect. Portable POSIX applications cannot attempt to trap these signals. 3684 The output format is not historical practice. Since the output of historical trap commands is not 3685 portable (because numeric signal values are not portable) and had to change to become so, an 3686 opportunity was taken to format the output in a way that a shell script could use to save and 3687 then later reuse a trap if it wanted. 3688 The KornShell uses an ERR trap that is triggered whenever set -e would cause an exit. This is 3689 allowable as an extension, but was not mandated, as other shells have not used it. 3690 The text about the environment for the EXIT trap invalidates the behavior of some historical 3691 versions of interactive shells which, for example, close the standard input before executing a 3692 trap on 0. For example, in some historical interactive shell sessions the following trap on 0 would 3693 always print "- -": 3694 trap 'read foo; echo "-$foo-"' 0 3695 FUTURE DIRECTIONS 3696 None. 3697 SEE ALSO 3698 Section 2.14 (on page 2266) 3699 CHANGE HISTORY 3700 Issue 6 3701 XSI-conforming implementations provide the mapping of signal names to numbers given above 3702 (previously this had been marked obsolescent). Other implementations need not provide this 3703 optional mapping. Shell and Utilities, Issue 6 2299 unset Shell Command Language 3704 NAME 3705 unset - unset values and attributes of variables and functions 3706 SYNOPSIS 3707 unset [-fv] name ... 3708 DESCRIPTION 3709 Each variable or function specified by name shall be unset. 3710 If -v is specified, name refers to a variable name and the shell shall unset it and remove it from 3711 the environment. Read-only variables cannot be unset. 3712 If -f is specified, name refers to a function and the shell shall unset the function definition. 3713 If neither -f nor -v is specified, name refers to a variable; if a variable by that name does not 3714 exist, it is unspecified whether a function by that name, if any, shall be unset. 3715 Unsetting a variable or function that was not previously set shall not be considered an error and 3716 does not cause the shell to abort. 3717 The unset special built-in shall support the Base Definitions volume of IEEE Std 1003.1-200x, 3718 Section 12.2, Utility Syntax Guidelines. 3719 Note that: 3720 VARIABLE= 3721 is not equivalent to an unset of VARIABLE; in the example, VARIABLE is set to " ". Also, the 3722 variables that can be unset should not be misinterpreted to include the special parameters (see 3723 Section 2.5.2 (on page 2235)). 3724 OPTIONS 3725 None. 3726 OPERANDS 3727 None. 3728 STDIN 3729 None. 3730 INPUT FILES 3731 None. 3732 ENVIRONMENT VARIABLES 3733 None. 3734 ASYNCHRONOUS EVENTS 3735 None. 3736 STDOUT 3737 None. 3738 STDERR 3739 None. 3740 OUTPUT FILES 3741 None. 3742 EXTENDED DESCRIPTION 3743 None. 2300 Technical Standard (2001) (Draft April 16, 2001) Shell Command Language unset 3744 EXIT STATUS 3745 0 All name operands were successfully unset. 3746 >0 At least one name could not be unset. 3747 CONSEQUENCES OF ERRORS 3748 None. 3749 APPLICATION USAGE 3750 None. 3751 EXAMPLES 3752 Unset VISUAL variable: 3753 unset -v VISUAL 3754 Unset the functions foo and bar: 3755 unset -f foo bar 3756 RATIONALE 3757 Consideration was given to omitting the -f option in favor of an unfunction utility, but the 3758 standard developers decided to retain historical practice. 3759 The -v option was introduced because System V historically used one name space for both 3760 variables and functions. When unset is used without options, System V historically unset either a 3761 function or a variable, and there was no confusion about which one was intended. A portable 3762 POSIX application can use unset without an option to unset a variable, but not a function; the -f 3763 option must be used. 3764 FUTURE DIRECTIONS 3765 None. 3766 SEE ALSO 3767 Section 2.14 (on page 2266) 3768 CHANGE HISTORY 3769 None. Shell and Utilities, Issue 6 2301 Shell Command Language 3770 | 2302 Technical Standard (2001) (Draft April 16, 2001) Chapter 3 Batch Environment Services 3771 3772 BE This chapter describes the services and utilities that shall be implemented on all systems that 3773 claim conformance to the Batch Environment option. This functionality is dependent on support 3774 of this option (and the rest of this section is not further shaded for this option). 3775 3.1 General Concepts 3776 3.1.1 Batch Client-Server Interaction 3777 Batch jobs are created and managed by batch servers. A batch client interacts with a batch server 3778 to access batch services on behalf of the user. In order to use batch services, a user must have 3779 access to a batch client. 3780 A batch server is a computational entity, such as a daemon process, that provides batch services. 3781 Batch servers route, queue, modify, and execute batch jobs on behalf of batch clients. 3782 The batch utilities described in this volume of IEEE Std 1003.1-200x (and listed in Table 3-1) are 3783 clients of batch services; they allow users to perform actions on the job such as creating, 3784 modifying, and deleting batch jobs from a shell command line. Although these batch utilities 3785 may be said to accomplish certain services, they actually obtain services on behalf of a user by 3786 means of requests to batch servers. 3787 Table 3-1 Batch Utilities | 3788 qalter qmove qrls qstat ||||||||| 3789 qdel qmsg qselect qsub |||||||| 3790 qhold qrerun qsig |||||| 3791 Client-server interaction takes place by means of the batch requests defined in this chapter. 3792 Because direct access to batch jobs and queues is limited to batch servers, clients and servers of 3793 different implementations can interoperate, since dependencies on private structures for batch 3794 jobs and queues are limited to batch servers. Also, batch servers may be clients of other batch 3795 servers. 3796 3.1.2 Batch Queues 3797 Two types of batch queue are described: routing queues and execution queues. When a batch job is 3798 placed in a routing queue, it is a candidate for routing. A batch job is removed from routing 3799 queues under the following conditions: 3800 * The batch job has been routed to another queue. 3801 * The batch job has been deleted from the batch queue. 3802 * The batch job has been aborted. 3803 When a batch job is placed in an execution queue, it is a candidate for execution. 3804 A batch job is removed from an execution queue under the following conditions: 3805 * The batch job has been executed and exited. Shell and Utilities, Issue 6 2303 General Concepts Batch Environment Services 3806 * The batch job has been aborted. 3807 * The batch job has been deleted from the batch queue. 3808 * The batch job has been moved to another queue. 3809 Access to a batch queue is limited to the batch server that manages the batch queue. Clients 3810 never access a batch queue or a batch job directly, either to read or write information; all client 3811 access to batch queues or jobs takes place through batch servers. 3812 3.1.3 Batch Job Creation 3813 When a batch server creates a batch job on behalf of a client, it shall assign a batch job identifier | 3814 to the job. A batch job identifier consists of both a sequence number that is unique among the | 3815 sequence numbers issued by that server and the name of the server. Since the batch server name 3816 is unique within a name space, the job identifier is likewise unique within the name space. 3817 The batch server that creates a batch job shall return the batch server-assigned job identifier to | 3818 the client that requested the job creation. If the batch server routes or moves the job to another 3819 server, it sends the job identifier with the job. Once assigned, the job identifier of a batch job shall | 3820 never change. | 3821 3.1.4 Batch Job Tracking 3822 Since a batch job may be moved after creation, the batch server name component of the job | 3823 identifier need not indicate the location of the job. An implementation may provide a batch job | 3824 tracking mechanism, in which case the user generally does not need to know the location of the | 3825 job. However, an implementation need not provide a batch job tracking mechanism, in which | 3826 case the user must find routed jobs by probing the possible destinations. | 3827 3.1.5 Batch Job Routing 3828 To route a batch job, a batch server either moves the job to some other queue that is managed by 3829 the batch server, or requests that some other batch server accept the job. 3830 Each routing queue has one or more queues to which it can route batch jobs. The batch server 3831 administrator creates routing queues. 3832 A batch server may route a batch job from a routing queue to another routing queue. Batch 3833 servers shall prevent or otherwise handle cases of circular routing paths. As a deferred service, a 3834 batch server routes jobs from the routing queues that it manages. The algorithm by which a 3835 batch server selects a batch queue to which to route a batch job is implementation-defined. 3836 A batch job need not be eligible for routing to all the batch queues fed by the routing queue from 3837 which it is routed. A batch server that has been asked to accept the job may reject the request if 3838 the job requires resources that are unavailable to that batch server, or if the client is not 3839 authorized to access the batch server. 3840 Batch servers may route high-priority jobs before low-priority jobs, but, on other than 3841 overloaded systems, the effect may be imperceptible to the user. If all the batch servers fed by a 3842 routing queue reject requests to accept the job for reasons that are permanent, the batch server | 3843 that manages the job shall abort the job. If all or some rejections are temporary, the batch server | 3844 should try to route the job again at some later point. | 3845 The reasons for rejecting a batch job are implementation-defined. The reasons for which the | 3846 routing should be retried later and the reasons for which the job should be aborted are also | 3847 implementation-defined. | 2304 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services General Concepts 3848 3.1.6 Batch Job Execution 3849 To execute a batch job is to create a session leader (a process) that runs the shell program 3850 indicated by the Shell_Path attribute of the job. The script shall be passed to the program as its | 3851 standard input. An implementation may pass the script to the program by other | 3852 implementation-defined means. At the time a batch job begins execution, it is defined to enter | 3853 the RUNNING state. The primary program that is executed by a batch job is typically, though | 3854 not necessarily, a shell program. | 3855 A batch server shall execute eligible jobs as a deferred service-no client request is necessary | 3856 once the batch job is created and eligible. However, the attributes of a batch job, such as the job | 3857 hold type, may render the job ineligible. A batch server shall scan the execution queues that it | 3858 manages for jobs that are eligible for execution. The algorithm by which the batch server selects 3859 eligible jobs for execution is implementation-defined. 3860 As part of creating the process for the batch job, the batch server shall open the standard output | 3861 and standard error streams of the session. | 3862 The attributes of a batch job may indicate that the batch server executing the job shall send mail | 3863 to a list of users at the time it begins execution of the job. | 3864 3.1.7 Batch Job Exit 3865 When the session leader of an executing job terminates, the job exits. As part of exiting a batch 3866 job, the batch server that manages the job shall remove the job from the batch queue in which it 3867 resides. The server shall transfer output files of the job to a location described by the attributes of 3868 the job. 3869 The attributes of a batch job may indicate that the batch server managing the job shall send mail | 3870 to a list of users at the time the job exits. | 3871 3.1.8 Batch Job Abort 3872 A batch server shall abort jobs for which a required deferred service cannot be performed. The | 3873 attributes of a batch job may indicate that the batch server that aborts the job shall send mail to a | 3874 list of users at the time it aborts the job. | 3875 3.1.9 Batch Authorization 3876 Clients, such as the batch environment utilities (marked BE), access batch services by means of | 3877 requests to one or more batch servers. To acquire the services of any given batch server, the user 3878 identifier under which the client runs must be authorized to use that batch server. 3879 The user with an associated user name that creates a batch job shall own the job and can perform | 3880 actions such as read, modify, delete, and move. | 3881 A user identifier of the same value at a different host need not be the same user. For example, 3882 user name smith at host alpha may or may not represent the same person as user name smith at 3883 host beta. Likewise, the same person may have access to different user names on different hosts. 3884 An implementation may optionally provide an authorization mechanism that permits one user 3885 name to access jobs under another user name. 3886 A process on a client host may be authorized to run processes under multiple user names at a 3887 batch server host. Where appropriate, the utilities defined in this volume of IEEE Std 1003.1-200x 3888 provide a means for a user to choose from among such user names when creating or modifying a 3889 batch job. Shell and Utilities, Issue 6 2305 General Concepts Batch Environment Services 3890 3.1.10 Batch Administration 3891 The processing of a batch job by a batch server is affected by the attributes of the job. The 3892 processing of a batch job may also be affected by the attributes of the batch queue in which the 3893 job resides and by the status of the batch server that manages the job. See also the Base | 3894 Definitions volume of IEEE Std 1003.1-200x, Section 3.43, Batch Administrator and the Base | 3895 Definitions volume of IEEE Std 1003.1-200x, Section 3.58, Batch Operator. | 3896 3.1.11 Batch Notification 3897 Whereas batch servers are persistent entities, clients are often transient. For example, the qsub 3898 utility creates a batch job and exits. For this reason, batch servers notify users of batch job events 3899 by sending mail to the user that owns the job, or to other designated users. 3900 3.2 Batch Services 3901 The presence of Batch Environment option services is indicated by the configuration variable 3902 POSIX2_PBS. A conforming batch server provides services as defined in this section. 3903 A batch server shall provide batch services in two ways: | 3904 1. The batch server provides a service at the request of a client. 3905 2. The batch server provides a deferred service as a result of a change in conditions 3906 monitored by the batch server. 3907 If a batch server cannot complete a request, it shall reject the request. If a batch server cannot | 3908 complete a deferred service for a batch job, the batch server shall abort the batch job. Table 3-2 | 3909 (on page 2307) is a summary of environment variables that shall be supported by an 3910 implementation of the batch server and utilities. 2306 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 3911 Table 3-2 Environment Variable Summary | __________________________________________________________________________________ | 3912 _ Variable Description _________________________________________________________________________________ || 3913 PBS_DPREFIX Defines the directive prefix (see qsub) ||| 3914 PBS_ENVIRONMENT Batch Job is batch or interactive (see Section 3.2.2.1 (on page ||| 3915 2308)) || 3916 PBS_JOBID The job_identifier attribute of job (see Section 3.2.3.8 (on page ||| 3917 2320)) || 3918 PBS_JOBNAME The job_name attribute of job (see Section 3.2.3.8 (on page 2320)) ||| 3919 PBS_O_HOME Defines the HOME of the batch client (see qsub) ||| 3920 PBS_O_HOST Defines the host name of the batch client (see qsub) ||| 3921 PBS_O_LANG Defines the LANG of the batch client (see qsub) ||| 3922 PBS_O_LOGNAME Defines the LOGNAME of the batch client (see qsub) ||| 3923 PBS_O_MAIL Defines the MAIL of the batch client (see qsub) ||| 3924 PBS_O_PATH Defines the PATH of the batch client (see qsub) ||| 3925 PBS_O_QUEUE Defines the submit queue of the batch client (see qsub) ||| 3926 PBS_O_SHELL Defines the SHELL of the batch client (see qsub) ||| 3927 PBS_O_TZ Defines the TZ of the batch client (see qsub) ||| 3928 PBS_O_WORKDIR Defines the working directory of the batch client (see qsub) ||| 3929 PBS_QUEUE Defines the initial execution queue (see Section 3.2.2.1 (on page ||| 3930 2308)) || _ _________________________________________________________________________________ |||| 3931 3.2.1 Batch Job States 3932 A batch job shall always be in one of the following states: QUEUED, RUNNING, HELD, | 3933 WAITING, EXITING, or TRANSITING. The state of a batch job determines the types of requests | 3934 that the batch server that manages the batch job can accept for the batch job. A batch server shall | 3935 change the state of a batch job either in response to service requests from clients or as a result of | 3936 deferred services, such as job execution or job routing. | 3937 A batch job that is in the QUEUED state resides in a queue but is still pending either execution or 3938 routing, depending on the queue type. 3939 A batch server that queues a batch job in a routing queue shall put the batch job in the QUEUED 3940 state. A batch server that puts a batch job in an execution queue, but has not yet executed the 3941 batch job, shall put the batch job in the QUEUED state. A batch job that resides in an execution 3942 queue and is executing is defined to be in the RUNNING state. While a batch job is in the 3943 RUNNING state, a session leader is associated with the batch job. 3944 A batch job that resides in an execution queue, but is ineligible to run because of a hold attribute, 3945 is defined to be in the HELD state. 3946 A batch job that is not held, but must wait until a future date and time before executing, is 3947 defined to be in the WAITING state. 3948 When the session leader associated with a running job exits, the batch job shall be placed in the 3949 EXITING state. 3950 A batch job for which the session leader has terminated is defined to be in the EXITING state, 3951 and the batch server that manages such a batch job cannot accept job modification requests that 3952 affect the batch job. While a batch job is in the EXITING state, the batch server that manages the 3953 batch job is staging output files and notifying clients of job completion. Once a batch job has 3954 exited, it no longer exists as an object managed by a batch server. Shell and Utilities, Issue 6 2307 Batch Services Batch Environment Services 3955 A batch job that is being moved from a routing queue to another queue is defined to be in the 3956 TRANSITING state. 3957 When a batch job in a routing queue has been selected to be moved to a new destination, then | 3958 the batch job shal be in either the QUEUED state or the TRANSITING state, depending on the | 3959 batch server implementation. | 3960 Batch jobs with either a Execution_Time attribute value set in the future or a Hold_Types attribute 3961 of value not equal to NO_HOLD, or both, may be routed or held in the routing queue. The | 3962 treatment of jobs with the Execution_Time or Hold_Types attributes in a routing queue is | 3963 implementation-defined. | 3964 When a batch job in a routing queue has not been selected to be moved to a new destination and 3965 the batch job has a Hold_Types attribute value of other than NO_HOLD, then the job should be in 3966 the HELD state. 3967 Note: The effect of a hold upon a batch job in a routing queue is implementation-defined. The 3968 implementation should use the state that matches whether the batch job can route with a hold 3969 or not. 3970 When a batch job in a routing queue has not been selected to be moved to a new destination and 3971 the batch job has: 3972 * A Hold_Types attribute value of NO_HOLD 3973 * An Execution_Time attribute in the past 3974 then the batch job shall be in the QUEUED state. 3975 When a batch job in a routing queue has not been selected to be moved to a new destination and 3976 the batch job has: 3977 * A Hold_Types attribute value of NO_HOLD 3978 * An Execution_Time attribute in the future | 3979 then the batch job may be in the WAITING state. 3980 Note: The effect of a future execution time upon a batch job in a routing queue is implementation- 3981 defined. The implementation should use the state that matches whether the batch job can route 3982 with a hold or not. 3983 Table 3-3 (on page 2309) describes the next state of a batch job, given the current state of the 3984 batch job and the type of request. Table 3-4 (on page 2310) describes the response of a batch 3985 server to a request, given the current state of the batch job and the type of request. 3986 3.2.2 Deferred Batch Services 3987 This section describes the deferred services performed by batch servers: job execution, job 3988 routing, job exit, job abort, and the rerunning of jobs after a restart. 3989 3.2.2.1 Batch Job Execution 3990 To execute a batch job is to create a session leader (a process) that runs the shell program 3991 indicated by the Shell_Path_List attribute of the batch job. The script is passed to the program as 3992 its standard input. An implementation may pass the script to the program by other | 3993 implementation-defined means. At the time a batch job begins execution, it is defined to enter | 3994 the RUNNING state. | 2308 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 3995 Table 3-3 Next State Table ________________________________________________________________ | 3996 _ Current State _____________________________________ || 3997 _ Request Type X Q R H W E T _______________________________________________________________ | | 3998 Queue Batch Job Request Q e e e e e e | 3999 Modify Batch Job Request e Q R H W e T | 4000 Delete Batch Job Request e X E X X E X | 4001 Batch Job Message Request e Q R H W E T | 4002 Rerun Batch Job Request e e Q e e e e | 4003 Signal Batch Job Request e e R H W e e | 4004 Batch Job Status Request e Q R H W E T | 4005 Batch Queue Status Request X Q R H W E T | 4006 Server Status Request X Q R H W E T | 4007 Select Batch Jobs Request X Q R H W E T | 4008 Move Batch Job Request e Q R H W e T | 4009 Hold Batch Job Request e H R/H H H e T | 4010 Release Batch Job Request Q R Q/W/H W e T | 4011 Server Shutdown Request X Q Q H W E T | 4012 _ Locate Batch Job Request e Q R H W E T _______________________________________________________________ ||||||||||| 4013 Legend 4014 X Nonexistent 4015 Q QUEUED 4016 R RUNNING 4017 H HELD 4018 W WAITING 4019 E EXITING 4020 T TRANSITING 4021 e Error 4022 A batch server that has an execution queue containing jobs is said to own the queue and manage 4023 the batch jobs in that queue. A batch server that has been started shall execute the batch jobs in 4024 the execution queues owned by the batch server. The batch server shall schedule for execution 4025 those jobs in the execution queues that are in the QUEUED state. The algorithm for scheduling 4026 jobs is implementation-defined. 4027 A batch server that executes a batch job shall create, in the environment of the session leader of 4028 the batch job, an environment variable named PBS_ENVIRONMENT, the value of which is the 4029 string PBS_BATCH encoded in the portable character set. 4030 A batch server that executes a batch job shall create, in the environment of the session leader of 4031 the batch job, an environment variable named PBS_QUEUE, the value of which is the name of 4032 the execution queue of the batch job encoded in the portable character set. 4033 To rerun a batch job is to requeue a batch job that is currently executing and then kill the session 4034 leader of the executing job by sending a SIGKILL prior to completion; see Section 3.2.3.11 (on 4035 page 2322). A batch server that reruns a batch job shall append the standard output and 4036 standard error files of the batch job to the corresponding files of the previous execution, if they 4037 exist, with appropriate annotation. If either file does not exist, that file shall be created as in 4038 normal execution. Shell and Utilities, Issue 6 2309 Batch Services Batch Environment Services 4039 Table 3-4 Results/Output Table __________________________________________________________ | 4040 _ Current State ________________________________ || 4041 _ Request Type X Q R H W E T _________________________________________________________ | | 4042 Queue Batch Job Request O e e e e e e | 4043 Modify Batch Job Request e O e O O e e | 4044 Delete Batch Job Request e O O O O e O | 4045 Batch Job Message Request e e O e e e e | 4046 Rerun Batch Job Request e e O e e e e | 4047 Signal Batch Job Request e e O e e e e | 4048 Batch Job Status Request e O O O O O O | 4049 Batch Queue Status Request O O O O O O O | 4050 Server Status Request O O O O O O O | 4051 Select Batch Job Request e O O O O O O | 4052 Move Batch Job Request e O O O O e e | 4053 Hold Batch Job Request e O O O O e e | 4054 Release Batch Job Request e O e O O e e | 4055 Server Shutdown Request O O e O O e e | 4056 _ Locate Batch Job Request e O O O O O O _________________________________________________________ ||||||||||| 4057 Legend 4058 O OK 4059 e Error message 4060 The execution of a batch job by a batch server shall be controlled by job, queue, and server | 4061 attributes, as defined in this section. | 4062 Account_Name Attribute 4063 Batch accounting is an optional feature of batch servers. If a batch server implements 4064 accounting, the statements in this section apply and the configuration variable 4065 POSIX2_PBS_ACCOUNTING shall be set to 1. 4066 A batch server that executes a batch job shall charge the account named in the Account_Name 4067 attribute of the batch job for resources consumed by the batch job. 4068 If the Account_Name attribute of the batch job is absent from the batch job attribute list or is 4069 altered while the batch job is in execution, the batch server action is implementation-defined. 4070 Checkpoint Attribute 4071 Batch checkpointing is an optional feature of batch servers. If a batch server implements 4072 checkpointing, the statements in this section apply and the configuration variable 4073 POSIX2_PBS_CHECKPOINT shall be set to 1. 4074 There are two attributes associated with the checkpointing feature: Checkpoint and 4075 Minimum_Cpu_Interval. Checkpoint is a batch job attribute, while Minimum_Cpu_Interval is a 4076 queue attribute. An implementation that does not support checkpointing shall support the 4077 Checkpoint job attribute to the extent that the batch server shall maintain and pass this attribute 4078 to other servers. 4079 The behavior of a batch server that executes a batch job for which the value of the Checkpoint | 4080 attribute is CHECKPOINT_UNSPECIFIED is implementation-defined. A batch server that | 4081 executes a batch job for which the value of the Checkpoint attribute is NO_CHECKPOINT shall | 2310 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4082 not checkpoint the batch job. 4083 A batch server that executes a batch job for which the value of the Checkpoint attribute is 4084 CHECKPOINT_AT_SHUTDOWN shall checkpoint the batch job only when the batch server 4085 accepts a request to shut down during the time when the batch job is in the RUNNING state. 4086 A batch server that executes a batch job for which the value of the Checkpoint attribute is 4087 CHECKPOINT_AT_MIN_CPU_INTERVAL shall checkpoint the batch job at the interval 4088 specified by the Minimum_Cpu_Interval attribute of the queue for which the batch job has been 4089 selected. The Minimum_Cpu_Interval attribute shall be specified in units of CPU minutes. 4090 A batch server that executes a batch job for which the value of the Checkpoint attribute is an 4091 unsigned integer shall checkpoint the batch job at an interval that is the value of either the 4092 Checkpoint attribute, or the Minimum_Cpu_Interval attribute of the queue for which the batch job 4093 has been selected, whichever is greater. Both intervals shall be in units of CPU minutes. When 4094 the Minimum_Cpu_Interval attribute is greater than the Checkpoint attribute, the batch job shall 4095 write a warning message to the standard error stream of the batch job. 4096 Error_Path Attribute 4097 The Error_Path attribute of a running job cannot be changed by a Modify Batch Job Request. When 4098 the Join_Path attribute of the batch job is set to the value FALSE and the Keep_Files attribute of 4099 the batch job does not contain the value KEEP_STD_ERROR, a batch server that executes a batch 4100 job shall perform one of the following actions: 4101 * Set the standard error stream of the session leader of the batch job to the path described by 4102 the value of the Error_Path attribute of the batch job. 4103 * Buffer the standard error of the session leader of the batch job until completion of the batch 4104 job, and when the batch job exits return the contents to the destination described by the value 4105 of the Error_Path attribute of the batch job. 4106 Applications shall not rely on having access to the standard error of a batch job prior to the 4107 completion of the batch job. 4108 When the Error_Path attribute does not specify a host name, then the batch server shall retain the 4109 standard error of the batch job on the host of execution. 4110 When the Error_Path attribute does specify a host name and the Keep_Files attribute does not 4111 contain the value KEEP_STD_ERROR, then the final destination of the standard error of the 4112 batch job shall be on the host whose host name is specified. 4113 If the path indicated by the value of the Error_Path attribute of the batch job is a relative path, the 4114 batch server shall expand the path relative to the home directory of the user on the host to which 4115 the file is being returned. 4116 When the batch server buffers the standard error of the batch job and the file cannot be opened 4117 for write upon completion of the batch job, then the server shall place the standard error in an 4118 implementation-defined location and notify the user of the location via mail. It shall be possible 4119 for the user to process this mail using the mailx utility. 4120 If a batch server that does not buffer the standard error cannot open the standard error path of 4121 the batch job for write access, then the batch server shall abort the batch job. Shell and Utilities, Issue 6 2311 Batch Services Batch Environment Services 4122 Execution_Time Attribute 4123 A batch server shall not execute a batch job before the time represented by the value of the 4124 Execution_Time attribute of the batch job. The Execution_Time attribute is defined in seconds since 4125 the Epoch. 4126 Hold_Types Attribute 4127 A batch server shall support the following hold types: 4128 s Can be set or released by a user with at least a privilege level of batch administrator 4129 (SYSTEM). 4130 o Can be set or released by a user with at least a privilege level of batch operator 4131 (OPERATOR). 4132 u Can be set or released by the user with at least a privilege level of user, where the user is 4133 defined in the Job_Owner attribute (USER). 4134 n Indicates that none of the Hold_Types attributes are set (NO_HOLD). 4135 An implementation may define other hold types. Any additional hold types, how they are | 4136 specified, their internal representation, their behavior, and how they affect the behavior of other | 4137 utilities are implementation-defined. | 4138 The value of the Hold_Types attribute shall be the union of the valid hold types ('s', 'o', 'u', 4139 and any implementation-defined hold types), or 'n'. 4140 A batch server shall not execute a batch job if the Hold_Types attribute of the batch job has a 4141 value other than NO_HOLD. If the Hold_Types attribute of the batch job has a value other than 4142 NO_HOLD, the batch job shall be in the HELD state. 4143 Job_Owner Attribute 4144 The Job_Owner attribute consists of a pair of user name and host name values of the form: 4145 username@hostname | 4146 A batch server that accepts a Queue Batch Job Request shall set the Job_Owner attribute to a string 4147 that is the username@hostname of the user who submitted the job. 4148 Join_Path Attribute 4149 A batch server that executes a batch job for which the value of the Join_Path attribute is TRUE 4150 shall ignore the value of the Error_Path attribute and merge the standard error of the batch job 4151 with the standard output of the batch job. 4152 Keep_Files Attribute 4153 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 4154 the value KEEP_STD_OUTPUT shall retain the standard output of the batch job on the host 4155 where execution occurs. The standard output shall be retained in the home directory of the user 4156 under whose user ID the batch job is executed and the filename shall be the default filename for 4157 the standard output as defined under the -o option of the qsub utility. The Output_Path attribute 4158 is not modified. 4159 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 4160 the value KEEP_STD_ERROR shall retain the standard error of the batch job on the host where 4161 execution occurs. The standard error shall be retained in the home directory of the user under 4162 whose user ID the batch job is executed and the filename shall be the default filename for 2312 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4163 standard error as defined under the -e option of the qsub utility. The Error_Path attribute is not 4164 modified. 4165 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 4166 values other than KEEP_STD_OUTPUT and KEEP_STD_ERROR shall retain these other files on 4167 the host where execution occurs. These files (with implementation-defined names) shall be | 4168 retained in the home directory of the user under whose user identifier the batch job is executed. | 4169 Mail_Points and Mail_Users Attributes 4170 A batch server that executes a batch job for which one of the values of the Mail_Points attribute is 4171 the value MAIL_AT_BEGINNING shall send a mail message to each user account listed in the 4172 Mail_Users attribute of the batch job. 4173 The mail message shall contain at least the batch job identifier, queue, and server at which the 4174 batch job currently resides, and the Job_Owner attribute. 4175 Output_Path Attribute 4176 The Output_Path attribute of a running job cannot be changed by a Modify Batch Job Request. 4177 When the Keep_Files attribute of the batch job does not contain the value KEEP_STD_OUTPUT, a 4178 batch server that executes a batch job shall either: 4179 * Set the standard output stream of the session leader of the batch job to the destination 4180 described by the value of the Output_Path attribute of the batch job. 4181 or: 4182 * Buffer the standard output of the session leader of the batch job until completion of the batch 4183 job, and when the batch job exits return the contents to the destination described by the value 4184 of the Output_Path attribute of the batch job. 4185 When the Output_Path attribute does not specify a host name, then the batch server shall retain 4186 the standard output of the batch job on the host of execution. 4187 When the Keep_Files attribute does not contain the value KEEP_STD_OUTPUT and the 4188 Output_Path attribute does specify a host name, then the final destination of the standard output 4189 of the batch job shall be on the host specified. 4190 If the path specified in the Output_Path attribute of the batch job is a relative path, the batch 4191 server shall expand the path relative to the home directory of the user on the host to which the 4192 file is being returned. 4193 Whether or not the batch server buffers the standard output of the batch job until completion of 4194 the batch job is implementation-defined. Applications shall not rely on having access to the 4195 standard output of a batch job prior to the completion of the batch job. 4196 When the batch server does buffer the standard output of the batch job and the file cannot be 4197 opened for write upon completion of the batch job, then the batch server shall place the standard 4198 output in an implementation-defined location and notify the user of the location via mail. It shall 4199 be possible for the user to process this mail using the mailx utility. 4200 If a batch server that does not buffer the standard output cannot open the standard output path 4201 of the batch job for write access, then the batch server shall abort the batch job. Shell and Utilities, Issue 6 2313 Batch Services Batch Environment Services 4202 Priority Attribute 4203 A batch server implementation may choose to preferentially execute a batch job based on the 4204 Priority attribute. The interpretation of the batch job Priority attribute by a batch server is 4205 implementation-defined. If an implementation uses the Priority attribute, it shall interpret larger 4206 values of the Priority attribute to mean the batch job shall be preferentially selected for execution. 4207 Rerunable Attribute 4208 A batch job that began execution but did not complete, because the batch server either shut 4209 down or terminated abnormally, shall be requeued if the Rerunable attribute of the batch job has 4210 the value TRUE. 4211 If a batch job, which was requeued after beginning execution but prior to completion, has a valid 4212 checkpoint file and the batch server supports checkpointing, then the batch job shall be restarted 4213 from the last valid checkpoint. 4214 If the batch job cannot be restarted from a checkpoint, then when a batch job has a Rerunable 4215 attribute value of TRUE and was requeued after beginning execution but prior to completion, 4216 the batch server shall place the batch job into execution at the beginning of the job. 4217 When a batch job has a Rerunable attribute value other than TRUE and was requeued after 4218 beginning execution but prior to completion, and the batch job cannot be restarted from a 4219 checkpoint, then the batch server shall abort the batch job. 4220 Resource_List Attribute 4221 A batch server that executes a batch job shall establish the resource limits of the session leader of 4222 the batch job according to the values of the Resource_List attribute of the batch job. Resource 4223 limits shall be enforced by an implementation-defined method. 4224 Shell_Path_List Attribute 4225 The Shell_Path_List job attribute consists of a list of pairs of pathname and host name values. The 4226 host name component can be omitted, in which case the pathname serves as the default 4227 pathname when a batch server cannot find the name of the host on which it is running in the list. 4228 A batch server that executes a batch job shall select, from the value of the Shell_Path_List 4229 attribute of the batch job, a pathname where the shell to execute the batch job shall be found. The 4230 batch server shall select the pathname, in order of preference, according to the following 4231 methods: 4232 * Select the pathname that contains the name of the host on which the batch server is running. 4233 * Select the pathname for which the host name has been omitted. 4234 * Select the pathname for the login shell of the user under which the batch job is to execute. 4235 If the shell path value selected is an invalid pathname, the batch server shall abort the batch job. 4236 If the value of the selected pathname from the Shell_Path_List attribute of the batch job 4237 represents a partial path, the batch server shall expand the path relative to a path that is 4238 implementation-defined. 4239 The batch server that executes the batch job shall execute the program that was selected from the 4240 Shell_Path_List attribute of the batch job. The batch server shall pass the path to the script of the 4241 batch job as the first argument to the shell program. 2314 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4242 User_List Attribute 4243 The User_List job attribute consists of a list of pairs of user name and host name values. The host 4244 name component can be omitted, in which case the user name serves as a default when a batch 4245 server cannot find the name of the host on which it is running in the list. 4246 A batch server that executes a batch job shall select, from the value of the User_List attribute of 4247 the batch job, a user name under which to create the session leader. The server shall select the 4248 user name, in order of preference, according to the following methods: 4249 * Select the user name of a value that contains the name of the host on which the batch server 4250 executes. 4251 * Select the user name of a value for which the host name has been omitted. 4252 * Select the user name from the Job_Owner attribute of the batch job. 4253 Variable_List Attribute 4254 A batch server that executes a batch job shall create, in the environment of the session leader of 4255 the batch job, each environment variable listed in the Variable_List attribute of the batch job, and 4256 set the value of each such environment variable to that of the corresponding variable in the 4257 variable list. 4258 3.2.2.2 Batch Job Routing 4259 To route a batch job is to select a queue from a list and move the batch job to that queue. 4260 A batch server that has routing queues, which have been started, shall route the jobs in the 4261 routing queues owned by the batch server. A batch server may delay the routing of a batch job. | 4262 The algorithm for selecting a batch job and the queue to which it will be routed is | 4263 implementation-defined. 4264 When a routing queue has multiple possible destinations specified, then the precedence of the | 4265 destinations is implementation-defined. | 4266 A batch server that routes a batch job to a queue at another server shall move the batch job into 4267 the target queue with a Queue Batch Job Request. 4268 If the target server rejects the Queue Batch Job Request, the routing server shall retry routing the 4269 batch job or abort the batch job. A batch server that retries failed routings shall provide a means 4270 for the batch administrator to specify the number of retries and the minimum period of time 4271 between retries. The means by which an administrator specifies the number of retries and the 4272 delay between retries is implementation-defined. When the number of retries specified by the 4273 batch administrator has been exhausted, the batch server shall abort the batch job and perform 4274 the functions of Batch Job Exit; see Section 3.2.2.3. 4275 3.2.2.3 Batch Job Exit 4276 For each job in the EXITING state, the batch server that exited the batch job shall perform the 4277 following deferred services in the order specified: 4278 1. If buffering standard error, move that file into the location specified by the Error_Path 4279 attribute of the batch job. 4280 2. If buffering standard output, move that file into the location specified by the Output_Path 4281 attribute of the batch job. 4282 3. If the Mail_Points attribute of the batch job includes MAIL_AT_EXIT, send mail to the users 4283 listed in the Mail_Users attribute of the batch job. The mail message shall contain at least Shell and Utilities, Issue 6 2315 Batch Services Batch Environment Services 4284 the batch job identifier, queue, and server at which the batch job currently resides, and the 4285 Job_Owner attribute. 4286 4. Remove the batch job from the queue. 4287 If a batch server that buffers the standard error output cannot return the standard error file to 4288 the standard error path at the time the batch job exits, the batch server shall do one of the 4289 following: 4290 * Mail the standard error file to the batch job owner. 4291 * Save the standard error file and mail the location and name of the file where the standard 4292 error is stored to the batch job owner. 4293 * Save the standard error file and notify the user by other implementation-defined means. | 4294 If a batch server that buffers the standard output cannot return the standard output file to the 4295 standard output path at the time the batch job exits, the batch server shall do one of the 4296 following: 4297 * Mail the standard output file to the batch job owner. 4298 * Save the standard output file and mail the location and name of the file where the standard 4299 output is stored to the batch job owner. 4300 * Save the standard output file and notify the user by other implementation-defined means. | 4301 At the conclusion of job exit processing, the batch job is no longer managed by a batch server. 4302 3.2.2.4 Batch Server Restart 4303 A batch server that has been either shutdown or terminated abnormally, and has returned to 4304 operation, is said to have restarted. 4305 Upon restarting, a batch server shall requeue those jobs managed by the batch server that were 4306 in the RUNNING state at the time the batch server shut down and for which the Rerunable 4307 attribute of the batch job has the value TRUE. 4308 Queues are defined to be non-volatile. A batch server shall store the content of queues that it 4309 controls in such a way that server and system shutdowns do not erase the content of the queues. 4310 3.2.2.5 Batch Job Abort 4311 A batch server that cannot perform a deferred service for a batch job shall abort the batch job. 4312 A batch server that aborts a batch job shall perform the following services: 4313 * Delete the batch job from the queue in which it resides. 4314 * If the Mail_Points attribute of the batch job includes the value MAIL_AT_ABORT, send mail 4315 to the users listed in the value of the Mail_Users attribute of the job. The mail message shall 4316 contain at least the batch job identifier, queue, and server at which the batch job currently 4317 resides, the Job_Owner attribute, and the reason for the abort. 4318 * If the batch job was in the RUNNING state, terminate the session leader of the executing job 4319 by sending the session leader a SIGKILL, place the batch job in the EXITING state, and | 4320 perform the actions of Batch Job Exit. | 2316 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4321 3.2.3 Requested Batch Services 4322 This section describes the services provided by batch servers in response to requests from 4323 clients. Table 3-5 summarizes the current set of batch service requests and for each gives its type 4324 (deferred or not) and whether it is an optional function. 4325 Table 3-5 Batch Services Summary _______________________________________________ | 4326 Batch Service Deferred Optional _______________________________________________ || 4327 Batch Job Execution Yes No | 4328 Batch Job Routing Yes No | 4329 Batch Job Exit Yes No | 4330 Batch Server Restart Yes No | 4331 Batch Job Abort Yes No | 4332 Delete Batch Job Request No No | 4333 Hold Batch Job Request No No | 4334 Batch Job Message Request No Yes | 4335 Batch Job Status Request No No | 4336 Locate Batch Job Request No Yes | 4337 Modify Batch Job Request No No | 4338 Move Batch Job Request No No | 4339 Queue Batch Job Request No No | 4340 Batch Queue Status Request No No | 4341 Release Batch Job Request No No | 4342 Rerun Batch Job Request No No | 4343 Select Batch Jobs Request No No | 4344 Server Shutdown Request No No | 4345 Server Status Request No No | 4346 Signal Batch Job Request No No | 4347 Track Batch Job Request No Yes _______________________________________________ |||||| 4348 If a request is rejected because the batch client is not authorized to perform the action, the batch 4349 server shall return the same status as when the batch job does not exist. 4350 3.2.3.1 Delete Batch Job Request 4351 A batch job is defined to have been deleted when it has been removed from the queue in which it 4352 resides and not instantiated in another queue. A client requests that the server that manages a 4353 batch job delete the batch job. Such a request is called a Delete Batch Job Request. 4354 A batch server shall reject a Delete Batch Job Request if any of the following statements are true: 4355 * The user of the batch client is not authorized to delete the designated job. 4356 * The designated job is not managed by the batch server. 4357 * The designated job is in a state inconsistent with the delete request. 4358 A batch server may reject a Delete Batch Job Request for other implementation-defined reasons. | 4359 The method used to determine whether the user of a client is authorized to perform the | 4360 requested action is implementation-defined. | 4361 A batch server requested to delete a batch job shall delete the batch job if the batch job exists and 4362 is not in the EXITING state. 4363 A batch server that deletes a batch job in the RUNNING state shall send a SIGKILL signal to the | 4364 session leader of the batch job. It is implementation-defined whether additional signals are sent | Shell and Utilities, Issue 6 2317 Batch Services Batch Environment Services 4365 to the session leader of the job prior to sending the SIGKILL signal. | 4366 A batch server that deletes a batch job in the RUNNING state shall place the batch job in the 4367 EXITING state after it has killed the session leader of the batch job and shall perform the actions | 4368 of Batch Job Exit. | 4369 3.2.3.2 Hold Batch Job Request 4370 A batch client can request that the batch server add one or more holds to a batch job. Such a 4371 request is called a Hold Batch Job Request. 4372 A batch server shall reject a Hold Batch Job Request if any of the following statements are true: 4373 * The batch server does not support one or more of the requested holds to be added to the 4374 batch job. 4375 * The user of the batch client is not authorized to add one or more of the requested holds to the 4376 batch job. 4377 * The batch server does not manage the specified job. 4378 * The designated job is in the EXITING state. 4379 A batch server may reject a Hold Batch Job Request for other implementation-defined reasons. The | 4380 method used to determine whether the user of a client is authorized to perform the requested | 4381 action is implementation-defined. | 4382 A batch server that accepts a Hold Batch Job Request for a batch job in the RUNNING state shall 4383 place a hold on the batch job. The effects, if any, the hold will have on a batch job in the | 4384 RUNNING state are implementation-defined. | 4385 A batch server that accepts a Hold Batch Job Request shall add each type of hold listed in the Hold 4386 Batch Job Request, that is not already present, to the value of the Hold_Types attribute of the batch 4387 job. 4388 3.2.3.3 Batch Job Message Request 4389 Batch Job Message Request is an optional feature of batch servers. If an implementation supports 4390 Batch Job Message Request, the statements in this section apply and the configuration variable 4391 POSIX2_PBS_MESSAGE shall be set to 1. 4392 A batch client can request that a batch server write a message into certain output files of a batch 4393 job. Such a request is called a Batch Job Message Request. 4394 A batch server shall reject a Batch Job Message Request if any of the following statements are true: 4395 * The batch server does not support sending messages to jobs. 4396 * The user of the batch client is not authorized to post a message to the designated job. 4397 * The designated job does not exist on the batch server. 4398 * The designated job is not in the RUNNING state. 4399 A batch server may reject a Batch Job Message Request for other implementation-defined reasons. | 4400 The method used to determine whether the user of a client is authorized to perform the | 4401 requested action is implementation-defined. | 4402 A batch server that accepts a Batch Job Message Request shall write the message sent by the batch 4403 client into the files indicated by the batch client. 2318 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4404 3.2.3.4 Batch Job Status Request 4405 A batch client can request that a batch server respond with the status and attributes of a batch 4406 job. Such a request is called a Batch Job Status Request. 4407 A batch server shall reject a Batch Job Status Request if any of the following statements are true: 4408 * The user of the batch client is not authorized to query the status of the designated job. 4409 * The designated job is not managed by the batch server. 4410 A batch server may reject a Batch Job Status Request for other implementation-defined reasons. | 4411 The method used to determine whether the user of a client is authorized to perform the | 4412 requested action is implementation-defined. | 4413 A batch server that accepts a Batch Job Status Request shall return a Batch Job Status Message to the 4414 batch client. 4415 A batch server may return other information in response to a Batch Job Status Request. 4416 3.2.3.5 Locate Batch Job Request 4417 Locate Batch Job Request is an optional feature of batch servers. If an implementation supports 4418 Locate Batch Job Request, the statements in this section apply and the configuration variable 4419 POSIX2_PBS_LOCATE shall be set to 1. 4420 A batch client can ask a batch server to respond with the location of a batch job that was created 4421 by the batch server. Such a request is called a Locate Batch Job Request. 4422 A batch server that accepts a Locate Batch Job Request shall return a Batch Job Location Message to 4423 the batch client. 4424 A batch server may reject a Locate Batch Job Request for a batch job that was not created by that 4425 server. 4426 A batch server may reject a Locate Batch Job Request for a batch job that is no longer managed by 4427 that server; that is, for a batch job that is not in a queue owned by that server. 4428 A batch server may reject a Locate Batch Job Request for other implementation-defined reasons. | 4429 3.2.3.6 Modify Batch Job Request 4430 Batch clients modify (alter) the attributes of a batch job by making a request to the server that 4431 manages the batch job. Such a request is called a Modify Batch Job Request. 4432 A batch server shall reject a Modify Batch Job Request if any of the following statements are true: 4433 * The user of the batch client is not authorized to make the requested modification to the batch 4434 job. 4435 * The designated job is not managed by the batch server. 4436 * The requested modification is inconsistent with the state of the batch job. 4437 * An unrecognized resource is requested for a batch job in an execution queue. 4438 A batch server may reject a Modify Batch Job Request for other implementation-defined reasons. | 4439 The method used to determine whether the user of a client is authorized to perform the | 4440 requested action is implementation-defined. | 4441 A batch server that accepts a Modify Batch Job Request shall modify all the specified attributes of 4442 the batch job. A batch server that rejects a Modify Batch Job Request shall modify none of the 4443 attributes of the batch job. Shell and Utilities, Issue 6 2319 Batch Services Batch Environment Services 4444 If the servicing by a batch server of an otherwise valid request would result in no change, then 4445 the batch server shall indicate successful completion of the request. 4446 3.2.3.7 Move Batch Job Request 4447 A batch client can request that a batch server move a batch job to another destination. Such a 4448 request is called a Move Batch Job Request. 4449 A batch server shall reject a Move Batch Job Request if any of the following statements are true: 4450 * The user of the batch client is not authorized to remove the designated job from the queue in 4451 which the batch job resides. 4452 * The user of the batch client is not authorized to move the designated job to the destination. 4453 * The designated job is not managed by the batch server. 4454 * The designated job is in the EXITING state. 4455 * The destination is inaccessible. 4456 A batch server can reject a Move Batch Job Request for other implementation-defined reasons. The | 4457 method used to determine whether the user of a client is authorized to perform the requested | 4458 action is implementation-defined. | 4459 A batch server that accepts a Move Batch Job Request shall perform the following services: 4460 * Queue the designated job at the destination. 4461 * Remove the designated job from the queue in which the batch job resides. 4462 If the destination resides on another batch server, the batch server shall queue the batch job at 4463 the destination by sending a Queue Batch Job Request to the other server. If the Queue Batch Job 4464 Request fails, the batch server shall reject the Move Batch Job Request. If the Queue Batch Job Request 4465 succeeds, the batch server shall remove the batch job from its queue. 4466 The batch server shall not modify any attributes of the batch job. 4467 3.2.3.8 Queue Batch Job Request 4468 A batch queue is controlled by one and only one batch server. A batch server is said to own the 4469 queues that it controls. Batch clients make requests of batch servers to have jobs queued. Such a 4470 request is called a Queue Batch Job Request. 4471 A batch server requested to queue a batch job for which the queue is not specified shall select an | 4472 implementation-defined queue for the batch job. Such a queue is called the default queue of the | 4473 batch server. The implementation shall provide the means for a batch administrator to specify | 4474 the default queue. The queue, whether specified or defaulted, is called the target queue. | 4475 A batch server shall reject a Queue Batch Job Request if any of the following statements are true: 4476 * The client is not authorized to create a batch job in the target queue. 4477 * The request specifies a queue that does not exist on the batch server. 4478 * The target queue is an execution queue and the batch server cannot satisfy a resource 4479 requirement of the batch job. 4480 * The target queue is an execution queue and an unrecognized resource is requested. 4481 * The target queue is an execution queue, the batch server does not support checkpointing, and 4482 the value of the Checkpoint attribute of the batch job is not NO_CHECKPOINT. 2320 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4483 * The job requires access to a user identifier that the batch client is not authorized to access. 4484 A batch server may reject a Queue Batch Job Request for other implementation-defined reasons. | 4485 A batch server that accepts a Queue Batch Job Request for a batch job for which the 4486 PBS_O_QUEUE value is missing from the value of the Variable_List attribute of the batch job 4487 shall add that variable to the list and set the value to the name of the target queue. Once set, no 4488 server shall change the value of PBS_O_QUEUE, even if the batch job is moved to another 4489 queue. 4490 A batch server that accepts a Queue Batch Job Request for a batch job for which the PBS_JOBID 4491 value is missing from the value of the Variable_List attribute shall add that variable to the list and 4492 set the value to the batch job identifier assigned by the server in the format: 4493 sequence_number.server | 4494 A batch server that accepts a Queue Batch Job Request for a batch job for which the 4495 PBS_JOBNAME value is missing from the value of the Variable_List attribute of the batch job 4496 shall add that variable to the list and set the value to the Job_Name attribute of the batch job. 4497 3.2.3.9 Batch Queue Status Request 4498 A batch client can request that a batch server respond with the status and attributes of a queue. 4499 Such a request is called a Batch Queue Status Request. 4500 A batch server shall reject a Batch Queue Status Request if any of the following statements are true: 4501 * The user of the batch client is not authorized to query the status of the designated queue. 4502 * The designated queue does not exist on the batch server. 4503 A batch server may reject a Batch Queue Status Request for other implementation-defined reasons. | 4504 The method used to determine whether the user of a client is authorized to perform the | 4505 requested action is implementation-defined. | 4506 A batch server that accepts a Batch Queue Status Request shall return a Batch Queue Status Reply to 4507 the batch client. 4508 3.2.3.10 Release Batch Job Request 4509 A batch client can request that server remove one or more holds from a batch job. Such a request 4510 is called a Release Batch Job Request. 4511 A batch server shall reject a Release Batch Job Request if any of the following statements are true: 4512 * The user of the batch client is not authorized to remove one or more of the requested holds 4513 from the batch job. 4514 * The batch server does not manage the specified job. 4515 A batch server may reject a Release Batch Job Request for other implementation-defined reasons. | 4516 The method used to determine whether the user of a client is authorized to perform the | 4517 requested action is implementation-defined. | 4518 A batch server that accepts a Release Batch Job Request shall remove each type of hold listed in the 4519 Release Batch Job Request, that is present, from the value of the Hold_Types attribute of the batch 4520 job. Shell and Utilities, Issue 6 2321 Batch Services Batch Environment Services 4521 3.2.3.11 Rerun Batch Job Request 4522 To rerun a batch job is to kill the session leader of the batch job and leave the batch job eligible 4523 for re-execution. A batch client can request that a batch server rerun a batch job. Such a request is 4524 called Rerun Batch Job Request. 4525 A batch server shall reject a Rerun Batch Job Request if any of the following statements are true: 4526 * The user of the batch client is not authorized to rerun the designated job. 4527 * The Rerunable attribute of the designated job has the value FALSE. 4528 * The designated job is not in the RUNNING state. 4529 * The batch server does not manage the designated job. 4530 A batch server may reject a Rerun Batch Job Request for other implementation-defined reasons. | 4531 The method used to determine whether the user of a client is authorized to perform the | 4532 requested action is implementation-defined. | 4533 A batch server that rejects a Rerun Batch Job Request shall in no way modify the execution of the 4534 batch job. 4535 A batch server that accepts a request to rerun a batch job shall perform the following services: 4536 * Requeue the batch job in the execution queue in which it was executing. 4537 * Send a SIGKILL signal to the process group of the session leader of the batch job. 4538 An implementation may indicate to the batch job owner that the batch job has been rerun. | 4539 Whether and how the batch job owner is notified that a batch job is rerun is implementation- | 4540 defined. | 4541 A batch server that reruns a batch job may send other implementation-defined signals to the | 4542 session leader of the batch job prior to sending the SIGKILL signal. | 4543 A batch server may preferentially select a rerun job for execution. Whether rerun jobs shall be | 4544 selected for execution before other jobs is implementation-defined. | 4545 3.2.3.12 Select Batch Jobs Request 4546 A batch client can request from a batch server a list of jobs managed by that server that match a 4547 list of selection criteria. Such a request is called a Select Batch Jobs Request. All the batch jobs 4548 managed by the batch server that receives the request are candidates for selection. 4549 A batch server that accepts a Select Batch Jobs Request shall return a list of zero or more job 4550 identifiers that correspond to jobs that meet the selection criteria. 4551 If the batch client is not authorized to query the status of a batch job, the batch server shall not 4552 select the batch job. 4553 3.2.3.13 Server Shutdown Request 4554 A batch server is defined to have shut down when it does not respond to requests from clients 4555 and does not perform deferred services for jobs. A batch client can request that a batch server 4556 shut down. Such a request is called a Server Shutdown Request. 4557 A batch server shall reject a Server Shutdown Request from a client that is not authorized to shut | 4558 down the batch server. The method used to determine whether the user of a client is authorized | 4559 to perform the requested action is implementation-defined. | 2322 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Batch Services 4560 A batch server may reject a Server Shutdown Request for other implementation-defined reasons. | 4561 The reasons for which a Server Shutdown Request may be rejected are implementation-defined. | 4562 At server shutdown, a batch server shall do, in order of preference, one of the following: 4563 * If checkpointing is implemented and the batch job is checkpointable, then checkpoint the 4564 batch job and requeue it. 4565 * If the batch job is rerunable, then requeue the batch job to be rerun (restarted from the 4566 beginning). 4567 * Abort the batch job. 4568 3.2.3.14 Server Status Request 4569 A batch client can request that a batch server respond with the status and attributes of the batch 4570 server. Such a request is called a Server Status Request. 4571 A batch server shall reject a Server Status Request if the following statement is true: 4572 * The user of the batch client is not authorized to query the status of the designated server. 4573 A batch server may reject a Server Status Request for other implementation-defined reasons. The | 4574 method used to determine whether the user of a client is authorized to perform the requested | 4575 action is implementation-defined. | 4576 A batch server that accepts a Server Status Request shall return a Server Status Reply to the batch 4577 client. 4578 3.2.3.15 Signal Batch Job Request 4579 A batch client can request that a batch server signal the session leader of a batch job. Such a 4580 request is called a Signal Batch Job Request. 4581 A batch server shall reject a Signal Batch Job Request if any of the following statements are true: 4582 * The user of the batch client is not authorized to signal the batch job. 4583 * The job is not in the RUNNING state. 4584 * The batch server does not manage the designated job. 4585 * The requested signal is not supported by the implementation. 4586 A batch server may reject a Signal Batch Job Request for other implementation-defined reasons. | 4587 The method used to determine whether the user of a client is authorized to perform the | 4588 requested action is implementation-defined. | 4589 A batch server that accepts a request to signal a batch job shall send the signal requested by the 4590 batch client to the process group of the session leader of the batch job. 4591 3.2.3.16 Track Batch Job Request 4592 Track Batch Job Request is an optional feature of batch servers. If an implementation supports 4593 Track Batch Job Request, the statements in this section apply and the configuration variable 4594 POSIX2_PBS_TRACK shall be set to 1. 4595 Track Batch Job Request provides a method for tracking the current location of a batch job. Clients 4596 may use the tracking information to determine the batch server that should receive a batch 4597 server request. Shell and Utilities, Issue 6 2323 Batch Services Batch Environment Services 4598 If Track Batch Job Request is supported by a batch server, then when the batch server queues a 4599 batch job as a result of a Queue Batch Job Request, and the batch server is not the batch server that 4600 created the batch job, the batch server shall send a Track Batch Job Request to the batch server that 4601 created the job. 4602 If Track Batch Job Request is supported by a batch server, then the Track Batch Job Request may also 4603 be sent to other servers as a backup to the primary server. The method by which backup servers 4604 are specified is implementation-defined. 4605 If Track Batch Job Request is supported by a batch server that receives a Track Batch Job Request, 4606 then the batch server shall record the current location of the batch job as contained in the 4607 request. 4608 3.3 Common Behavior for Batch Environment Utilities 4609 3.3.1 Batch Job Identifier 4610 A utility shall recognize job_identifiers of the format: 4611 [sequence_number][.server_name][@server] | 4612 where: 4613 sequence_number An integer that, when combined with server_name, provides a batch job 4614 identifier that is unique within the batch system. 4615 server_name The name of the batch server to which the batch job was originally submitted. 4616 server The name of the batch server that is currently managing the batch job. 4617 If the application omits the batch server_name portion of a batch job identifier, a utility shall use 4618 the name of a default batch server. 4619 If the application omits the batch server portion of a batch job identifier, a utility shall use: 4620 * The batch server indicated by server_name, if present. 4621 * The name of the default batch server. 4622 * The name of the batch server that is currently managing the batch job. 4623 If only @server is specified, then the status of all jobs owned by the user on the requested server 4624 is listed. 4625 The means by which a utility determines the default batch server is implementation-defined. 4626 If the application presents the batch server portion of a batch job identifier to a utility, the utility 4627 shall send the request to the specified server. 4628 A strictly conforming application shall use the syntax described for the job identifier. Whenever 4629 a batch job identifier is specified whose syntax is not recognized by an implementation, then a 4630 message for each error that occurs shall be written to standard error and the utility shall exit 4631 with an exit status greater than zero. 4632 When a batch job identifier is supplied as an argument to a batch utility and the server_name 4633 portion of the batch job identifier is omitted, then the utility shall use the name of the default 4634 batch server. 4635 When a batch job identifier is supplied as an argument to a batch utility and the batch server 4636 portion of the batch job identifier is omitted, then the utility shall use either: 2324 Technical Standard (2001) (Draft April 16, 2001) Batch Environment Services Common Behavior for Batch Environment Utilities 4637 * The name of the default batch server 4638 or: 4639 * The name of the batch server that is currently managing the batch job 4640 When a batch job identifier is supplied as an argument to a batch utility and the batch server 4641 portion of the batch job identifier is specified, then the utility shall send the required Batch Server 4642 Request to the specified server. 4643 3.3.2 Destination 4644 The utility shall recognize a destination of the format: 4645 [queue][@server] | 4646 where: 4647 queue The name of a valid execution or routing queue at the batch server denoted by 4648 @server, defined as a string of up to 15 alphanumeric characters in the portable 4649 character set (see the Base Definitions volume of IEEE Std 1003.1-200x, Section 4650 6.1, Portable Character Set) where the first character is alphabetic. 4651 server The name of a batch server, defined as a string of alphanumeric characters in 4652 the portable character set. 4653 If the application omits the batch server portion of a destination, then the utility shall use either: 4654 * The name of the default batch server 4655 or: 4656 * The name of the batch server that is currently managing the batch job 4657 The means by which a utility determines the default batch server is implementation-defined. 4658 If the application omits the queue portion of a destination, then the utility shall use the name of 4659 the default queue at the batch server chosen. The means by which a batch server determines its | 4660 default queue is implementation-defined. If a destination is specified in the queue@server form, | 4661 then the utility shall use the specified queue at the specified server. 4662 A strictly conforming application shall use the syntax described for a destination. Whenever a 4663 destination is specified whose syntax is not recognized by an implementation, then a message 4664 shall be written to standard error and the utility shall exit with an exit status greater than zero. 4665 3.3.3 Multiple Keyword-Value Pairs 4666 For each option that can have multiple keyword-value pair arguments, the following rules shall 4667 apply. Examples of options that can have list-oriented option-arguments are -u value@keyword 4668 and -l keyword=value. 4669 1. If a batch utility is presented with a list-oriented option-argument for which a keyword has 4670 a corresponding value that begins with a single or double quote, then the utility shall stop 4671 interpreting the input stream for delimiters until a second single or double quote, 4672 respectively, is encountered. This feature allows some flexibility for a comma (',') or 4673 equals sign ('=') to be part of the value string for a particular keyword; for example: 4674 keywd1='val1,val2',keywd2="val3,val4" | 4675 Note: This may require the user to escape the quotes as in the following command: Shell and Utilities, Issue 6 2325 Common Behavior for Batch Environment Utilities Batch Environment Services 4676 foo -xkeywd1=\'val1,val2\',keywd2=\"val3,val4\" 4677 2. If a batch server is presented with a list-oriented attribute that has a keyword that was 4678 encountered earlier in the list, then the later entry for that keyword shall replace the earlier 4679 entry. 4680 3. If a batch server is presented with a list-oriented attribute that has a keyword without any 4681 corresponding value of the form keyword= or @keyword and the same keyword was 4682 encountered earlier in the list, then the prior entry for that keyword shall be ignored by the 4683 batch server. 4684 4. If a batch utility is expecting a list-oriented option-argument entry of the form 4685 keyword=value, but is presented with an entry of the form keyword without any 4686 corresponding value, then the entry shall be treated as though a default value of NULL was 4687 assigned (that is, keyword=NULL) for entry parsing purposes. The utility shall include only 4688 the keyword, not the NULL value, in the associated job attribute. 4689 5. If a batch utility is expecting a list-oriented option-argument entry of the form 4690 value@keyword, but is presented with an entry of the form value without any corresponding 4691 keyword, then the entry shall be treated as though a keyword of NULL was assigned (that 4692 is, value@NULL) for entry parsing purposes. The utility shall include only the value, not 4693 the NULL keyword, in the associated job attribute. 4694 6. A batch server shall accept a list-oriented attribute that has multiple occurrences of the 4695 same keyword, interpreting the keywords, in order, with the last value encountered taking 4696 precedence over prior instances of the same keyword. This rule allows, but does not 4697 require, a batch utility to preprocess the attribute to remove duplicate keywords. 4698 7. If a batch utility is presented with multiple list-oriented option-arguments on the 4699 command line or in script directives, or both, for a single option, then the utility shall 4700 concatenate, in order, any command line keyword and value pairs to the end of any 4701 directive keyword and value pairs separated by a single comma to produce a single string 4702 that is an equivalent, valid option-argument. The resulting string shall be assigned to the 4703 associated attribute of the batch job (after optionally removing duplicate entries as 4704 described in item 6. | 2326 Technical Standard (2001) (Draft April 16, 2001) Chapter 4 Utilities 4705 4706 This chapter contains the definitions of the utilities, as follows: 4707 * Mandatory utilities that are present on every conformant system 4708 * Optional utilities that are present only on systems supporting the associated option; see 4709 Section 1.8.1 (on page 2210) for information on the options in this volume of 4710 IEEE Std 1003.1-200x Shell and Utilities, Issue 6 2327 admin Utilities 4711 NAME 4712 admin - create and administer SCCS files (DEVELOPMENT) 4713 SYNOPSIS 4714 XSI admin -i[name][-n][-a login][-d flag][-e login][-f flag][-m mrlist] | 4715 [-r rel][-t[name][-y[comment]] newfile | 4716 admin -n[-a login][-d flag][-e login][-f flag][-m mrlist][-t[name]] | 4717 [-y[comment]] newfile ... | 4718 admin [-a login][-d flag][-m mrlist][-r rel][-t[name]] file ... | 4719 admin -h file ... 4720 admin -z file ... 4721 4722 DESCRIPTION 4723 The admin utility shall create new SCCS files or change parameters of existing ones. If a named 4724 file does not exist, it shall be created, and its parameters shall be initialized according to the 4725 specified options. Parameters not initialized by an option shall be assigned a default value. If a 4726 named file does exist, parameters corresponding to specified options shall be changed, and other 4727 parameters shall be left as is. 4728 All SCCS filenames supplied by the application shall be of the form s.filename. New SCCS files 4729 shall be given read-only permission mode. Write permission in the parent directory is required 4730 to create a file. All writing done by admin shall be to a temporary x-file, named x.filename (see get) 4731 created with read-only mode if admin is creating a new SCCS file, or created with the same mode 4732 as that of the SCCS file if the file already exists. After successful execution of admin, the SCCS file 4733 shall be removed (if it exists), and the x-file shall be renamed with the name of the SCCS file. This 4734 ensures that changes are made to the SCCS file only if no errors occur. 4735 The admin utility shall also use a transient lock file (named z.filename), which is used to prevent 4736 simultaneous updates to the SCCS file; see get (on page 2675). 4737 OPTIONS 4738 The admin utility shall conform to the Base Definitions volume of IEEE Std 1003.1-200x, Section 4739 12.2, Utility Syntax Guidelines, except that the -i, -t, and -y options have optional option- 4740 arguments. These optional option-arguments shall not be presented as separate arguments. The 4741 following options are supported: 4742 -n Create a new SCCS file. When -n is used without -i, the SCCS file shall be created 4743 with control information but without any file data. 4744 -i[name] Specify the name of a file from which the text for a new SCCS file shall be taken. 4745 The text constitutes the first delta of the file (see the -r option for delta numbering 4746 scheme). If the -i option is used, but the name option-argument is omitted, the text 4747 shall be obtained by reading the standard input. If this option is omitted, the SCCS 4748 file shall be created with control information but without any file data. The -i 4749 option implies the -n option. | 4750 -r SID Specify the SID of the initial delta to be inserted. This SID shall be a trunk SID; that | 4751 is, the branch and sequence numbers shall be zero or missing. The level number is | 4752 optional, and defaults to 1. | 4753 -t[name] Specify the name of a file from which descriptive text for the SCCS file shall be 4754 taken. In the case of existing SCCS files (neither -i nor -n is specified): 2328 Technical Standard (2001) (Draft April 16, 2001) Utilities admin 4755 * A -t option without a name option-argument shall cause the removal of 4756 descriptive text (if any) currently in the SCCS file. 4757 * A -t option with a name option-argument shall cause the text (if any) in the 4758 named file to replace the descriptive text (if any) currently in the SCCS file. 4759 -f flag Specify a flag, and, possibly, a value for the flag, to be placed in the SCCS file. 4760 Several -f options may be supplied on a single admin command line. | 4761 Implementations shall recognize the following flags and associated values: | 4762 b Allow use of the -b option on a get command to create branch deltas. 4763 cceil Specify the highest release (that is, ceiling), a number less than or equal to 4764 9 999, which may be retrieved by a get command for editing. The default 4765 value for an unspecified c flag shall be 9 999. 4766 ffloor Specify the lowest release (that is, floor), a number greater than 0 but less 4767 than 9 999, which may be retrieved by a get command for editing. The 4768 default value for an unspecified f flag shall be 1. 4769 dSID Specify the default delta number (SID) to be used by a get command. 4770 istr Treat the ``No ID keywords'' message issued by get or delta as a fatal 4771 error. In the absence of this flag, the message is only a warning. The 4772 message is issued if no SCCS identification keywords (see get (on page 4773 2675)) are found in the text retrieved or stored in the SCCS file. If a value 4774 is supplied, the application shall ensure that the keywords exactly match 4775 the given string; however, the string shall contain a keyword, and no 4776 embedded s. 4777 j Allow concurrent get commands for editing on the same SID of an SCCS 4778 file. This allows multiple concurrent updates to the same version of the 4779 SCCS file. 4780 llist Specify a list of releases to which deltas can no longer be made (that is, get 4781 -e against one of these locked releases fails). Conforming applications 4782 shall use the following syntax to specify a list. Implementations may 4783 accept additional forms as an extension: 4784 ::= a | 4785 ::= | , 4786 ::= 4787 The character a in the list shall be equivalent to specifying all releases for 4788 the named SCCS file. The non-terminal in range shall be the delta 4789 number of an existing delta associated with the SCCS file. 4790 n Cause delta to create a null delta in each of those releases (if any) being 4791 skipped when a delta is made in a new release (for example, in making 4792 delta 5.1 after delta 2.7, releases 3 and 4 are skipped). These null deltas | 4793 shall serve as anchor points so that branch deltas may later be created | 4794 from them. The absence of this flag shall cause skipped releases to be | 4795 nonexistent in the SCCS file, preventing branch deltas from being created | 4796 from them in the future. During the initial creation of an SCCS file, the n | 4797 flag may be ignored; that is, if the -r option is used to set the release | 4798 number of the initial SID to a value greater than 1, null deltas need not be | 4799 created for the ``skipped'' releases. | Shell and Utilities, Issue 6 2329 admin Utilities 4800 qtext Substitute user-definable text for all occurrences of the %Q% keyword in 4801 the SCCS file text retrieved by get. 4802 mmod Specify the module name of the SCCS file substituted for all occurrences 4803 of the %M% keyword in the SCCS file text retrieved by get. If the m flag 4804 is not specified, the value assigned shall be the name of the SCCS file with 4805 the leading '.' removed. 4806 ttype Specify the type of module in the SCCS file substituted for all occurrences 4807 of the %Y% keyword in the SCCS file text retrieved by get. 4808 vpgm Cause delta to prompt for modification request (MR) numbers as the 4809 reason for creating a delta. The optional value specifies the name of an 4810 MR number validation program. (If this flag is set when creating an SCCS 4811 file, the application shall ensure that the m option is also used even if its 4812 value is null.) 4813 -d flag Remove (delete) the specified flag from an SCCS file. Several -d options may be 4814 supplied on a single admin command. See the -f option for allowable flag names. 4815 (The llist flag gives a list of releases to be unlocked. See the -f option for further 4816 description of the l flag and the syntax of a list.) 4817 -a login Specify a login name, or numerical group ID, to be added to the list of users who 4818 may make deltas (changes) to the SCCS file. A group ID shall be equivalent to | 4819 specifying all login names common to that group ID. Several -a options may be | 4820 used on a single admin command line. As many logins, or numerical group IDs, as 4821 desired may be on the list simultaneously. If the list of users is empty, then anyone 4822 may add deltas. If login or group ID is preceded by a '!', the users so specified | 4823 shall be denied permission to make deltas. | 4824 -e login Specify a login name, or numerical group ID, to be erased from the list of users 4825 allowed to make deltas (changes) to the SCCS file. Specifying a group ID is 4826 equivalent to specifying all login names common to that group ID. Several -e 4827 options may be used on a single admin command line. 4828 -y[comment] Insert the comment text into the SCCS file as a comment for the initial delta in a 4829 manner identical to that of delta. In the POSIX locale, omission of the -y option 4830 shall result in a default comment line being inserted in the form: 4831 "date and time created %s %s by %s", ,

P LATIN CAPITAL LETTER P 3608 Q LATIN CAPITAL LETTER Q 3609 R LATIN CAPITAL LETTER R 3610 S LATIN CAPITAL LETTER S 3611 T LATIN CAPITAL LETTER T 3612 U LATIN CAPITAL LETTER U 3613 V LATIN CAPITAL LETTER V 3614 W LATIN CAPITAL LETTER W 3615 X LATIN CAPITAL LETTER X 3616 Y LATIN CAPITAL LETTER Y 3617 Z LATIN CAPITAL LETTER Z 3618 [ LEFT SQUARE BRACKET 3619 \ REVERSE SOLIDUS 3620 \ REVERSE SOLIDUS 3621 ] RIGHT SQUARE BRACKET 3622 ^ CIRCUMFLEX ACCENT 3623 ^ CIRCUMFLEX ACCENT 3624 _ LOW LINE 3625 _ _ LOW LINE ____________________________________________________________________________ 112 Technical Standard (2001) (Draft April 13, 2001) Character Set Portable Character Set 3626 _____________________________________________________________________________ 3627 _ Symbolic Name Glyph UCS Description ____________________________________________________________________________ 3628 ` GRAVE ACCENT 3629 a LATIN SMALL LETTER A 3630 b LATIN SMALL LETTER B 3631 c LATIN SMALL LETTER C 3632 d LATIN SMALL LETTER D 3633 e LATIN SMALL LETTER E 3634 f LATIN SMALL LETTER F 3635 g LATIN SMALL LETTER G 3636 h LATIN SMALL LETTER H 3637 i LATIN SMALL LETTER I 3638 j LATIN SMALL LETTER J 3639 k LATIN SMALL LETTER K 3640 l LATIN SMALL LETTER L 3641 m LATIN SMALL LETTER M 3642 n LATIN SMALL LETTER N 3643 o LATIN SMALL LETTER O 3644