diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/=copying.texinfo | 540 | ||||
| -rw-r--r-- | manual/=float.texinfo | 414 | ||||
| -rw-r--r-- | manual/=limits.texinfo | 593 | ||||
| -rw-r--r-- | manual/=process.texinfo | 1452 | ||||
| -rw-r--r-- | manual/=stdarg.texi | 290 | ||||
| -rw-r--r-- | manual/=stddef.texi | 81 | ||||
| -rw-r--r-- | manual/Makefile | 8 | ||||
| -rw-r--r-- | manual/arith.texi | 111 | ||||
| -rw-r--r-- | manual/lang.texi | 38 | ||||
| -rw-r--r-- | manual/socket.texi | 4 | ||||
| -rw-r--r-- | manual/stdio.texi | 12 |
11 files changed, 139 insertions, 3404 deletions
diff --git a/manual/=copying.texinfo b/manual/=copying.texinfo deleted file mode 100644 index 6a61d64bfb..0000000000 --- a/manual/=copying.texinfo +++ /dev/null @@ -1,540 +0,0 @@ -@comment This material was copied from /gd/gnu/doc/lgpl.texinfo. - -@node Copying, Concept Index, Maintenance, Top -@appendix GNU GENERAL PUBLIC LICENSE -@center Version 2, June 1991 - -@display -Copyright @copyright{} 1991 Free Software Foundation, Inc. -675 Mass Ave, Cambridge, MA 02139, USA -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. - -[This is the first released version of the library GPL. It is - numbered 2 because it goes with version 2 of the ordinary GPL.] -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software---to make sure the software is free for all its users. - - This license, the Library General Public License, applies to some -specially designated Free Software Foundation software, and to any -other libraries whose authors decide to use it. You can use it for -your libraries, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if -you distribute copies of the library, or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link a program with the library, you must provide -complete object files to the recipients so that they can relink them -with the library, after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - Our method of protecting your rights has two steps: (1) copyright -the library, and (2) offer you this license which gives you legal -permission to copy, distribute and/or modify the library. - - Also, for each distributor's protection, we want to make certain -that everyone understands that there is no warranty for this free -library. If the library is modified by someone else and passed on, we -want its recipients to know that what they have is not the original -version, so that any problems introduced by others will not reflect on -the original authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that companies distributing free -software will individually obtain patent licenses, thus in effect -transforming the program into proprietary software. To prevent this, -we have made it clear that any patent must be licensed for everyone's -free use or not licensed at all. - - Most GNU software, including some libraries, is covered by the ordinary -GNU General Public License, which was designed for utility programs. This -license, the GNU Library General Public License, applies to certain -designated libraries. This license is quite different from the ordinary -one; be sure to read it in full, and don't assume that anything in it is -the same as in the ordinary license. - - The reason we have a separate public license for some libraries is that -they blur the distinction we usually make between modifying or adding to a -program and simply using it. Linking a program with a library, without -changing the library, is in some sense simply using the library, and is -analogous to running a utility program or application program. However, in -a textual and legal sense, the linked executable is a combined work, a -derivative of the original library, and the ordinary General Public License -treats it as such. - - Because of this blurred distinction, using the ordinary General -Public License for libraries did not effectively promote software -sharing, because most developers did not use the libraries. We -concluded that weaker conditions might promote sharing better. - - However, unrestricted linking of non-free programs would deprive the -users of those programs of all benefit from the free status of the -libraries themselves. This Library General Public License is intended to -permit developers of non-free programs to use free libraries, while -preserving your freedom as a user of such programs to change the free -libraries that are incorporated in them. (We have not seen how to achieve -this as regards changes in header files, but we have achieved it as regards -changes in the actual functions of the Library.) The hope is that this -will lead to faster development of free libraries. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -``work based on the library'' and a ``work that uses the library''. The -former contains code derived from the library, while the latter only -works together with the library. - - Note that it is possible for a library to be covered by the ordinary -General Public License rather than by this special one. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end iftex -@ifinfo -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifinfo - -@enumerate -@item -This License Agreement applies to any software library which -contains a notice placed by the copyright holder or other authorized -party saying it may be distributed under the terms of this Library -General Public License (also called ``this License''). Each licensee is -addressed as ``you''. - - A ``library'' means a collection of software functions and/or data -prepared so as to be conveniently linked with application programs -(which use some of those functions and data) to form executables. - - The ``Library'', below, refers to any such software library or work -which has been distributed under these terms. A ``work based on the -Library'' means either the Library or any derivative work under -copyright law: that is to say, a work containing the Library or a -portion of it, either verbatim or with modifications and/or translated -straightforwardly into another language. (Hereinafter, translation is -included without limitation in the term ``modification''.) - - ``Source code'' for a work means the preferred form of the work for -making modifications to it. For a library, complete source code means -all the source code for all modules it contains, plus any associated -interface definition files, plus the scripts used to control compilation -and installation of the library. - - Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running a program using the Library is not restricted, and output from -such a program is covered only if its contents constitute a work based -on the Library (independent of the use of the Library in a tool for -writing it). Whether that is true depends on what the Library does -and what the program that uses the Library does. - -@item -You may copy and distribute verbatim copies of the Library's -complete source code as you receive it, in any medium, provided that -you conspicuously and appropriately publish on each copy an -appropriate copyright notice and disclaimer of warranty; keep intact -all the notices that refer to this License and to the absence of any -warranty; and distribute a copy of this License along with the -Library. - - You may charge a fee for the physical act of transferring a copy, -and you may at your option offer warranty protection in exchange for a -fee. - -@item -You may modify your copy or copies of the Library or any portion -of it, thus forming a work based on the Library, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@enumerate a -@item -The modified work must itself be a software library. - -@item -You must cause the files modified to carry prominent notices -stating that you changed the files and the date of any change. - -@item -You must cause the whole of the work to be licensed at no -charge to all third parties under the terms of this License. - -@item -If a facility in the modified Library refers to a function or a -table of data to be supplied by an application program that uses -the facility, other than as an argument passed when the facility -is invoked, then you must make a good faith effort to ensure that, -in the event an application does not supply such function or -table, the facility still operates, and performs whatever part of -its purpose remains meaningful. - -(For example, a function in a library to compute square roots has -a purpose that is entirely well-defined independent of the -application. Therefore, Subsection 2d requires that any -application-supplied function or table used by this function must -be optional: if the application does not supply it, the square -root function must still compute square roots.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Library, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Library, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library -with the Library (or with a work based on the Library) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -You may opt to apply the terms of the ordinary GNU General Public -License instead of this License to a given copy of the Library. To do -this, you must alter all the notices that refer to this License, so -that they refer to the ordinary GNU General Public License, version 2, -instead of to this License. (If a newer version than version 2 of the -ordinary GNU General Public License has appeared, then you can specify -that version instead if you wish.) Do not make any other change in -these notices. - - Once this change is made in a given copy, it is irreversible for -that copy, so the ordinary GNU General Public License applies to all -subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - -@item -You may copy and distribute the Library (or a portion or -derivative of it, under Section 2) in object code or executable form -under the terms of Sections 1 and 2 above provided that you accompany -it with the complete corresponding machine-readable source code, which -must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the -source code from the same place satisfies the requirement to -distribute the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -A program that contains no derivative of any portion of the -Library, but is designed to work with the Library by being compiled or -linked with it, is called a ``work that uses the Library''. Such a -work, in isolation, is not a derivative work of the Library, and -therefore falls outside the scope of this License. - - However, linking a ``work that uses the Library'' with the Library -creates an executable that is a derivative of the Library (because it -contains portions of the Library), rather than a ``work that uses the -library''. The executable is therefore covered by this License. -Section 6 states terms for distribution of such executables. - - When a ``work that uses the Library'' uses material from a header file -that is part of the Library, the object code for the work may be a -derivative work of the Library even though the source code is not. -Whether this is true is especially significant if the work can be -linked without the Library, or if the work is itself a library. The -threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data -structure layouts and accessors, and small macros and small inline -functions (ten lines or less in length), then the use of the object -file is unrestricted, regardless of whether it is legally a derivative -work. (Executables containing this object code plus portions of the -Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may -distribute the object code for the work under the terms of Section 6. -Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. - -@item -As an exception to the Sections above, you may also compile or -link a ``work that uses the Library'' with the Library to produce a -work containing portions of the Library, and distribute that work -under terms of your choice, provided that the terms permit -modification of the work for the customer's own use and reverse -engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the -Library is used in it and that the Library and its use are covered by -this License. You must supply a copy of this License. If the work -during execution displays copyright notices, you must include the -copyright notice for the Library among them, as well as a reference -directing the user to the copy of this License. Also, you must do one -of these things: - -@enumerate a -@item -Accompany the work with the complete corresponding -machine-readable source code for the Library including whatever -changes were used in the work (which must be distributed under -Sections 1 and 2 above); and, if the work is an executable linked -with the Library, with the complete machine-readable ``work that -uses the Library'', as object code and/or source code, so that the -user can modify the Library and then relink to produce a modified -executable containing the modified Library. (It is understood -that the user who changes the contents of definitions files in the -Library will not necessarily be able to recompile the application -to use the modified definitions.) - -@item -Accompany the work with a written offer, valid for at -least three years, to give the same user the materials -specified in Subsection 6a, above, for a charge no more -than the cost of performing this distribution. - -@item -If distribution of the work is made by offering access to copy -from a designated place, offer equivalent access to copy the above -specified materials from the same place. - -@item -Verify that the user has already received a copy of these -materials or that you have already sent this user a copy. -@end enumerate - - For an executable, the required form of the ``work that uses the -Library'' must include any data and utility programs needed for -reproducing the executable from it. However, as a special exception, -the source code distributed need not include anything that is normally -distributed (in either source or binary form) with the major -components (compiler, kernel, and so on) of the operating system on -which the executable runs, unless that component itself accompanies -the executable. - - It may happen that this requirement contradicts the license -restrictions of other proprietary libraries that do not normally -accompany the operating system. Such a contradiction means you cannot -use both them and the Library together in an executable that you -distribute. - -@item -You may place library facilities that are a work based on the -Library side-by-side in a single library together with other library -facilities not covered by this License, and distribute such a combined -library, provided that the separate distribution of the work based on -the Library and of the other library facilities is otherwise -permitted, and provided that you do these two things: - -@enumerate a -@item -Accompany the combined library with a copy of the same work -based on the Library, uncombined with any other library -facilities. This must be distributed under the terms of the -Sections above. - -@item -Give prominent notice with the combined library of the fact -that part of it is a work based on the Library, and explaining -where to find the accompanying uncombined form of the same work. -@end enumerate - -@item -You may not copy, modify, sublicense, link with, or distribute -the Library except as expressly provided under this License. Any -attempt otherwise to copy, modify, sublicense, link with, or -distribute the Library is void, and will automatically terminate your -rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Library or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Library (or any work based on the -Library), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Library or works based on it. - -@item -Each time you redistribute the Library (or any work based on the -Library), the recipient automatically receives a license from the -original licensor to copy, distribute, link with or modify the Library -subject to these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Library at all. For example, if a patent -license would not permit royalty-free redistribution of the Library by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply, -and the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Library is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Library under this License may add -an explicit geographical distribution limitation excluding those countries, -so that distribution is permitted only in or among countries not thus -excluded. In such case, this License incorporates the limitation as if -written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new -versions of the Library General Public License from time to time. -Such new versions will be similar in spirit to the present version, -but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -specifies a version number of this License which applies to it and -``any later version'', you have the option of following the terms and -conditions either of that version or of any later version published by -the Free Software Foundation. If the Library does not specify a -license version number, you may choose any version ever published by -the Free Software Foundation. - -@item -If you wish to incorporate parts of the Library into other free -programs whose distribution conditions are incompatible with these, -write to the author to ask for permission. For software which is -copyrighted by the Free Software Foundation, write to the Free -Software Foundation; we sometimes make exceptions for this. Our -decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing -and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@item -BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. -EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR -OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY -KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN -WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY -AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU -FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE -LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A -FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF -SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH -DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifinfo -@center END OF TERMS AND CONDITIONS -@end ifinfo - -@page -@unnumberedsec How to Apply These Terms to Your New Libraries - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms of the -ordinary General Public License). - - To apply these terms, attach the following notices to the library. It is -safest to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least the -``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the library's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Library General Public -License as published by the Free Software Foundation; either -version 2 of the License, or (at your option) any later version. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Library General Public License for more details. - -You should have received a copy of the GNU Library General Public -License along with this library; if not, write to the Free -Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the library, if -necessary. Here is a sample; alter the names: - -@example -Yoyodyne, Inc., hereby disclaims all copyright interest in the -library `Frob' (a library for tweaking knobs) written by James Random Hacker. - -@var{signature of Ty Coon}, 1 April 1990 -Ty Coon, President of Vice -@end example - -That's all there is to it! diff --git a/manual/=float.texinfo b/manual/=float.texinfo deleted file mode 100644 index d4e3920f8c..0000000000 --- a/manual/=float.texinfo +++ /dev/null @@ -1,414 +0,0 @@ -@node Floating-Point Limits -@chapter Floating-Point Limits -@pindex <float.h> -@cindex floating-point number representation -@cindex representation of floating-point numbers - -Because floating-point numbers are represented internally as approximate -quantities, algorithms for manipulating floating-point data often need -to be parameterized in terms of the accuracy of the representation. -Some of the functions in the C library itself need this information; for -example, the algorithms for printing and reading floating-point numbers -(@pxref{I/O on Streams}) and for calculating trigonometric and -irrational functions (@pxref{Mathematics}) use information about the -underlying floating-point representation to avoid round-off error and -loss of accuracy. User programs that implement numerical analysis -techniques also often need to be parameterized in this way in order to -minimize or compute error bounds. - -The specific representation of floating-point numbers varies from -machine to machine. The GNU C Library defines a set of parameters which -characterize each of the supported floating-point representations on a -particular system. - -@menu -* Floating-Point Representation:: Definitions of terminology. -* Floating-Point Parameters:: Descriptions of the library facilities. -* IEEE Floating-Point:: An example of a common representation. -@end menu - -@node Floating-Point Representation -@section Floating-Point Representation - -This section introduces the terminology used to characterize the -representation of floating-point numbers. - -You are probably already familiar with most of these concepts in terms -of scientific or exponential notation for floating-point numbers. For -example, the number @code{123456.0} could be expressed in exponential -notation as @code{1.23456e+05}, a shorthand notation indicating that the -mantissa @code{1.23456} is multiplied by the base @code{10} raised to -power @code{5}. - -More formally, the internal representation of a floating-point number -can be characterized in terms of the following parameters: - -@itemize @bullet -@item -The @dfn{sign} is either @code{-1} or @code{1}. -@cindex sign (of floating-point number) - -@item -The @dfn{base} or @dfn{radix} for exponentiation; an integer greater -than @code{1}. This is a constant for the particular representation. -@cindex base (of floating-point number) -@cindex radix (of floating-point number) - -@item -The @dfn{exponent} to which the base is raised. The upper and lower -bounds of the exponent value are constants for the particular -representation. -@cindex exponent (of floating-point number) - -Sometimes, in the actual bits representing the floating-point number, -the exponent is @dfn{biased} by adding a constant to it, to make it -always be represented as an unsigned quantity. This is only important -if you have some reason to pick apart the bit fields making up the -floating-point number by hand, which is something for which the GNU -library provides no support. So this is ignored in the discussion that -follows. -@cindex bias, in exponent (of floating-point number) - -@item -The value of the @dfn{mantissa} or @dfn{significand}, which is an -unsigned quantity. -@cindex mantissa (of floating-point number) -@cindex significand (of floating-point number) - -@item -The @dfn{precision} of the mantissa. If the base of the representation -is @var{b}, then the precision is the number of base-@var{b} digits in -the mantissa. This is a constant for the particular representation. - -Many floating-point representations have an implicit @dfn{hidden bit} in -the mantissa. Any such hidden bits are counted in the precision. -Again, the GNU library provides no facilities for dealing with such low-level -aspects of the representation. -@cindex precision (of floating-point number) -@cindex hidden bit, in mantissa (of floating-point number) -@end itemize - -The mantissa of a floating-point number actually represents an implicit -fraction whose denominator is the base raised to the power of the -precision. Since the largest representable mantissa is one less than -this denominator, the value of the fraction is always strictly less than -@code{1}. The mathematical value of a floating-point number is then the -product of this fraction; the sign; and the base raised to the exponent. - -If the floating-point number is @dfn{normalized}, the mantissa is also -greater than or equal to the base raised to the power of one less -than the precision (unless the number represents a floating-point zero, -in which case the mantissa is zero). The fractional quantity is -therefore greater than or equal to @code{1/@var{b}}, where @var{b} is -the base. -@cindex normalized floating-point number - -@node Floating-Point Parameters -@section Floating-Point Parameters - -@strong{Incomplete:} This section needs some more concrete examples -of what these parameters mean and how to use them in a program. - -These macro definitions can be accessed by including the header file -@file{<float.h>} in your program. - -Macro names starting with @samp{FLT_} refer to the @code{float} type, -while names beginning with @samp{DBL_} refer to the @code{double} type -and names beginning with @samp{LDBL_} refer to the @code{long double} -type. (In implementations that do not support @code{long double} as -a distinct data type, the values for those constants are the same -as the corresponding constants for the @code{double} type.)@refill - -Note that only @code{FLT_RADIX} is guaranteed to be a constant -expression, so the other macros listed here cannot be reliably used in -places that require constant expressions, such as @samp{#if} -preprocessing directives and array size specifications. - -Although the @w{ISO C} standard specifies minimum and maximum values for -most of these parameters, the GNU C implementation uses whatever -floating-point representations are supported by the underlying hardware. -So whether GNU C actually satisfies the @w{ISO C} requirements depends on -what machine it is running on. - -@comment float.h -@comment ISO -@defvr Macro FLT_ROUNDS -This value characterizes the rounding mode for floating-point addition. -The following values indicate standard rounding modes: - -@table @code -@item -1 -The mode is indeterminable. -@item 0 -Rounding is towards zero. -@item 1 -Rounding is to the nearest number. -@item 2 -Rounding is towards positive infinity. -@item 3 -Rounding is towards negative infinity. -@end table - -@noindent -Any other value represents a machine-dependent nonstandard rounding -mode. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_RADIX -This is the value of the base, or radix, of exponent representation. -This is guaranteed to be a constant expression, unlike the other macros -described in this section. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{float} data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{double} data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{long double} data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_DIG -This is the number of decimal digits of precision for the @code{float} -data type. Technically, if @var{p} and @var{b} are the precision and -base (respectively) for the representation, then the decimal precision -@var{q} is the maximum number of decimal digits such that any floating -point number with @var{q} base 10 digits can be rounded to a floating -point number with @var{p} base @var{b} digits and back again, without -change to the @var{q} decimal digits. - -The value of this macro is guaranteed to be at least @code{6}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_DIG -This is similar to @code{FLT_DIG}, but is for the @code{double} data -type. The value of this macro is guaranteed to be at least @code{10}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_DIG -This is similar to @code{FLT_DIG}, but is for the @code{long double} -data type. The value of this macro is guaranteed to be at least -@code{10}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_MIN_EXP -This is the minimum negative integer such that the mathematical value -@code{FLT_RADIX} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. In terms of the -actual implementation, this is just the smallest value that can be -represented in the exponent field of the number. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MIN_EXP -This is similar to @code{FLT_MIN_EXP}, but is for the @code{double} data -type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MIN_EXP -This is similar to @code{FLT_MIN_EXP}, but is for the @code{long double} -data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_MIN_10_EXP -This is the minimum negative integer such that the mathematical value -@code{10} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. This is -guaranteed to be no greater than @code{-37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MIN_10_EXP -This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{double} -data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MIN_10_EXP -This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{long -double} data type. -@end defvr - - - -@comment float.h -@comment ISO -@defvr Macro FLT_MAX_EXP -This is the maximum negative integer such that the mathematical value -@code{FLT_RADIX} raised to this power minus 1 can be represented as a -floating-point number of type @code{float}. In terms of the actual -implementation, this is just the largest value that can be represented -in the exponent field of the number. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MAX_EXP -This is similar to @code{FLT_MAX_EXP}, but is for the @code{double} data -type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MAX_EXP -This is similar to @code{FLT_MAX_EXP}, but is for the @code{long double} -data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro FLT_MAX_10_EXP -This is the maximum negative integer such that the mathematical value -@code{10} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. This is -guaranteed to be at least @code{37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MAX_10_EXP -This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{double} -data type. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MAX_10_EXP -This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{long -double} data type. -@end defvr - - -@comment float.h -@comment ISO -@defvr Macro FLT_MAX -The value of this macro is the maximum representable floating-point -number of type @code{float}, and is guaranteed to be at least -@code{1E+37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MAX -The value of this macro is the maximum representable floating-point -number of type @code{double}, and is guaranteed to be at least -@code{1E+37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MAX -The value of this macro is the maximum representable floating-point -number of type @code{long double}, and is guaranteed to be at least -@code{1E+37}. -@end defvr - - -@comment float.h -@comment ISO -@defvr Macro FLT_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{float}, and is -guaranteed to be no more than @code{1E-37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{double}, and -is guaranteed to be no more than @code{1E-37}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{long double}, -and is guaranteed to be no more than @code{1E-37}. -@end defvr - - -@comment float.h -@comment ISO -@defvr Macro FLT_EPSILON -This is the minimum positive floating-point number of type @code{float} -such that @code{1.0 + FLT_EPSILON != 1.0} is true. It's guaranteed to -be no greater than @code{1E-5}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro DBL_EPSILON -This is similar to @code{FLT_EPSILON}, but is for the @code{double} -type. The maximum value is @code{1E-9}. -@end defvr - -@comment float.h -@comment ISO -@defvr Macro LDBL_EPSILON -This is similar to @code{FLT_EPSILON}, but is for the @code{long double} -type. The maximum value is @code{1E-9}. -@end defvr - - - -@node IEEE Floating Point -@section IEEE Floating Point - -Here is an example showing how these parameters work for a common -floating point representation, specified by the @cite{IEEE Standard for -Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 or ANSI/IEEE -Std 854-1987)}. - -The IEEE single-precision float representation uses a base of 2. There -is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total -precision is 24 base-2 digits), and an 8-bit exponent that can represent -values in the range -125 to 128, inclusive. - -So, for an implementation that uses this representation for the -@code{float} data type, appropriate values for the corresponding -parameters are: - -@example -FLT_RADIX 2 -FLT_MANT_DIG 24 -FLT_DIG 6 -FLT_MIN_EXP -125 -FLT_MIN_10_EXP -37 -FLT_MAX_EXP 128 -FLT_MAX_10_EXP +38 -FLT_MIN 1.17549435E-38F -FLT_MAX 3.40282347E+38F -FLT_EPSILON 1.19209290E-07F -@end example diff --git a/manual/=limits.texinfo b/manual/=limits.texinfo deleted file mode 100644 index 7b55d70465..0000000000 --- a/manual/=limits.texinfo +++ /dev/null @@ -1,593 +0,0 @@ -@node Representation Limits, System Configuration Limits, System Information, Top -@chapter Representation Limits - -This chapter contains information about constants and parameters that -characterize the representation of the various integer and -floating-point types supported by the GNU C library. - -@menu -* Integer Representation Limits:: Determining maximum and minimum - representation values of - various integer subtypes. -* Floating-Point Limits :: Parameters which characterize - supported floating-point - representations on a particular - system. -@end menu - -@node Integer Representation Limits, Floating-Point Limits , , Representation Limits -@section Integer Representation Limits -@cindex integer representation limits -@cindex representation limits, integer -@cindex limits, integer representation - -Sometimes it is necessary for programs to know about the internal -representation of various integer subtypes. For example, if you want -your program to be careful not to overflow an @code{int} counter -variable, you need to know what the largest representable value that -fits in an @code{int} is. These kinds of parameters can vary from -compiler to compiler and machine to machine. Another typical use of -this kind of parameter is in conditionalizing data structure definitions -with @samp{#ifdef} to select the most appropriate integer subtype that -can represent the required range of values. - -Macros representing the minimum and maximum limits of the integer types -are defined in the header file @file{limits.h}. The values of these -macros are all integer constant expressions. -@pindex limits.h - -@comment limits.h -@comment ISO -@deftypevr Macro int CHAR_BIT -This is the number of bits in a @code{char}, usually eight. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int SCHAR_MIN -This is the minimum value that can be represented by a @code{signed char}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int SCHAR_MAX -This is the maximum value that can be represented by a @code{signed char}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int UCHAR_MAX -This is the maximum value that can be represented by a @code{unsigned char}. -(The minimum value of an @code{unsigned char} is zero.) -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int CHAR_MIN -This is the minimum value that can be represented by a @code{char}. -It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero -otherwise. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int CHAR_MAX -This is the maximum value that can be represented by a @code{char}. -It's equal to @code{SCHAR_MAX} if @code{char} is signed, or -@code{UCHAR_MAX} otherwise. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int SHRT_MIN -This is the minimum value that can be represented by a @code{signed -short int}. On most machines that the GNU C library runs on, -@code{short} integers are 16-bit quantities. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int SHRT_MAX -This is the maximum value that can be represented by a @code{signed -short int}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int USHRT_MAX -This is the maximum value that can be represented by an @code{unsigned -short int}. (The minimum value of an @code{unsigned short int} is zero.) -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int INT_MIN -This is the minimum value that can be represented by a @code{signed -int}. On most machines that the GNU C system runs on, an @code{int} is -a 32-bit quantity. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro int INT_MAX -This is the maximum value that can be represented by a @code{signed -int}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro {unsigned int} UINT_MAX -This is the maximum value that can be represented by an @code{unsigned -int}. (The minimum value of an @code{unsigned int} is zero.) -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro {long int} LONG_MIN -This is the minimum value that can be represented by a @code{signed long -int}. On most machines that the GNU C system runs on, @code{long} -integers are 32-bit quantities, the same size as @code{int}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro {long int} LONG_MAX -This is the maximum value that can be represented by a @code{signed long -int}. -@end deftypevr - -@comment limits.h -@comment ISO -@deftypevr Macro {unsigned long int} ULONG_MAX -This is the maximum value that can be represented by an @code{unsigned -long int}. (The minimum value of an @code{unsigned long int} is zero.) -@end deftypevr - -@strong{Incomplete:} There should be corresponding limits for the GNU -C Compiler's @code{long long} type, too. (But they are not now present -in the header file.) - -The header file @file{limits.h} also defines some additional constants -that parameterize various operating system and file system limits. These -constants are described in @ref{System Parameters} and @ref{File System -Parameters}. -@pindex limits.h - - -@node Floating-Point Limits , , Integer Representation Limits, Representation Limits -@section Floating-Point Limits -@cindex floating-point number representation -@cindex representation, floating-point number -@cindex limits, floating-point representation - -Because floating-point numbers are represented internally as approximate -quantities, algorithms for manipulating floating-point data often need -to be parameterized in terms of the accuracy of the representation. -Some of the functions in the C library itself need this information; for -example, the algorithms for printing and reading floating-point numbers -(@pxref{I/O on Streams}) and for calculating trigonometric and -irrational functions (@pxref{Mathematics}) use information about the -underlying floating-point representation to avoid round-off error and -loss of accuracy. User programs that implement numerical analysis -techniques also often need to be parameterized in this way in order to -minimize or compute error bounds. - -The specific representation of floating-point numbers varies from -machine to machine. The GNU C library defines a set of parameters which -characterize each of the supported floating-point representations on a -particular system. - -@menu -* Floating-Point Representation:: Definitions of terminology. -* Floating-Point Parameters:: Descriptions of the library - facilities. -* IEEE Floating Point:: An example of a common - representation. -@end menu - -@node Floating-Point Representation, Floating-Point Parameters, , Floating-Point Limits -@subsection Floating-Point Representation - -This section introduces the terminology used to characterize the -representation of floating-point numbers. - -You are probably already familiar with most of these concepts in terms -of scientific or exponential notation for floating-point numbers. For -example, the number @code{123456.0} could be expressed in exponential -notation as @code{1.23456e+05}, a shorthand notation indicating that the -mantissa @code{1.23456} is multiplied by the base @code{10} raised to -power @code{5}. - -More formally, the internal representation of a floating-point number -can be characterized in terms of the following parameters: - -@itemize @bullet -@item -The @dfn{sign} is either @code{-1} or @code{1}. -@cindex sign (of floating-point number) - -@item -The @dfn{base} or @dfn{radix} for exponentiation; an integer greater -than @code{1}. This is a constant for the particular representation. -@cindex base (of floating-point number) -@cindex radix (of floating-point number) - -@item -The @dfn{exponent} to which the base is raised. The upper and lower -bounds of the exponent value are constants for the particular -representation. -@cindex exponent (of floating-point number) - -Sometimes, in the actual bits representing the floating-point number, -the exponent is @dfn{biased} by adding a constant to it, to make it -always be represented as an unsigned quantity. This is only important -if you have some reason to pick apart the bit fields making up the -floating-point number by hand, which is something for which the GNU -library provides no support. So this is ignored in the discussion that -follows. -@cindex bias (of floating-point number exponent) - -@item -The value of the @dfn{mantissa} or @dfn{significand}, which is an -unsigned integer. -@cindex mantissa (of floating-point number) -@cindex significand (of floating-point number) - -@item -The @dfn{precision} of the mantissa. If the base of the representation -is @var{b}, then the precision is the number of base-@var{b} digits in -the mantissa. This is a constant for the particular representation. - -Many floating-point representations have an implicit @dfn{hidden bit} in -the mantissa. Any such hidden bits are counted in the precision. -Again, the GNU library provides no facilities for dealing with such low-level -aspects of the representation. -@cindex precision (of floating-point number) -@cindex hidden bit (of floating-point number mantissa) -@end itemize - -The mantissa of a floating-point number actually represents an implicit -fraction whose denominator is the base raised to the power of the -precision. Since the largest representable mantissa is one less than -this denominator, the value of the fraction is always strictly less than -@code{1}. The mathematical value of a floating-point number is then the -product of this fraction; the sign; and the base raised to the exponent. - -If the floating-point number is @dfn{normalized}, the mantissa is also -greater than or equal to the base raised to the power of one less -than the precision (unless the number represents a floating-point zero, -in which case the mantissa is zero). The fractional quantity is -therefore greater than or equal to @code{1/@var{b}}, where @var{b} is -the base. -@cindex normalized floating-point number - -@node Floating-Point Parameters, IEEE Floating Point, Floating-Point Representation, Floating-Point Limits -@subsection Floating-Point Parameters - -@strong{Incomplete:} This section needs some more concrete examples -of what these parameters mean and how to use them in a program. - -These macro definitions can be accessed by including the header file -@file{float.h} in your program. -@pindex float.h - -Macro names starting with @samp{FLT_} refer to the @code{float} type, -while names beginning with @samp{DBL_} refer to the @code{double} type -and names beginning with @samp{LDBL_} refer to the @code{long double} -type. (In implementations that do not support @code{long double} as -a distinct data type, the values for those constants are the same -as the corresponding constants for the @code{double} type.)@refill -@cindex @code{float} representation limits -@cindex @code{double} representation limits -@cindex @code{long double} representation limits - -Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant -expression. The other macros listed here cannot be reliably used in -places that require constant expressions, such as @samp{#if} -preprocessing directives or array size specifications. - -Although the @w{ISO C} standard specifies minimum and maximum values for -most of these parameters, the GNU C implementation uses whatever -floating-point representations are supported by the underlying hardware. -So whether GNU C actually satisfies the @w{ISO C} requirements depends on -what machine it is running on. - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_ROUNDS -This value characterizes the rounding mode for floating-point addition. -The following values indicate standard rounding modes: - -@table @code -@item -1 -The mode is indeterminable. -@item 0 -Rounding is towards zero. -@item 1 -Rounding is to the nearest number. -@item 2 -Rounding is towards positive infinity. -@item 3 -Rounding is towards negative infinity. -@end table - -@noindent -Any other value represents a machine-dependent nonstandard rounding -mode. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_RADIX -This is the value of the base, or radix, of exponent representation. -This is guaranteed to be a constant expression, unlike the other macros -described in this section. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{float} data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{double} data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_MANT_DIG -This is the number of base-@code{FLT_RADIX} digits in the floating-point -mantissa for the @code{long double} data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_DIG -This is the number of decimal digits of precision for the @code{float} -data type. Technically, if @var{p} and @var{b} are the precision and -base (respectively) for the representation, then the decimal precision -@var{q} is the maximum number of decimal digits such that any floating -point number with @var{q} base 10 digits can be rounded to a floating -point number with @var{p} base @var{b} digits and back again, without -change to the @var{q} decimal digits. - -The value of this macro is guaranteed to be at least @code{6}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_DIG -This is similar to @code{FLT_DIG}, but is for the @code{double} data -type. The value of this macro is guaranteed to be at least @code{10}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_DIG -This is similar to @code{FLT_DIG}, but is for the @code{long double} -data type. The value of this macro is guaranteed to be at least -@code{10}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_MIN_EXP -This is the minimum negative integer such that the mathematical value -@code{FLT_RADIX} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. In terms of the -actual implementation, this is just the smallest value that can be -represented in the exponent field of the number. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_MIN_EXP -This is similar to @code{FLT_MIN_EXP}, but is for the @code{double} data -type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_MIN_EXP -This is similar to @code{FLT_MIN_EXP}, but is for the @code{long double} -data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_MIN_10_EXP -This is the minimum negative integer such that the mathematical value -@code{10} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. This is -guaranteed to be no greater than @code{-37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_MIN_10_EXP -This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{double} -data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_MIN_10_EXP -This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{long -double} data type. -@end deftypevr - - - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_MAX_EXP -This is the maximum negative integer such that the mathematical value -@code{FLT_RADIX} raised to this power minus 1 can be represented as a -floating-point number of type @code{float}. In terms of the actual -implementation, this is just the largest value that can be represented -in the exponent field of the number. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_MAX_EXP -This is similar to @code{FLT_MAX_EXP}, but is for the @code{double} data -type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_MAX_EXP -This is similar to @code{FLT_MAX_EXP}, but is for the @code{long double} -data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int FLT_MAX_10_EXP -This is the maximum negative integer such that the mathematical value -@code{10} raised to this power minus 1 can be represented as a -normalized floating-point number of type @code{float}. This is -guaranteed to be at least @code{37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int DBL_MAX_10_EXP -This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{double} -data type. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro int LDBL_MAX_10_EXP -This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{long -double} data type. -@end deftypevr - - -@comment float.h -@comment ISO -@deftypevr Macro double FLT_MAX -The value of this macro is the maximum representable floating-point -number of type @code{float}, and is guaranteed to be at least -@code{1E+37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro double DBL_MAX -The value of this macro is the maximum representable floating-point -number of type @code{double}, and is guaranteed to be at least -@code{1E+37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro {long double} LDBL_MAX -The value of this macro is the maximum representable floating-point -number of type @code{long double}, and is guaranteed to be at least -@code{1E+37}. -@end deftypevr - - -@comment float.h -@comment ISO -@deftypevr Macro double FLT_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{float}, and is -guaranteed to be no more than @code{1E-37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro double DBL_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{double}, and -is guaranteed to be no more than @code{1E-37}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro {long double} LDBL_MIN -The value of this macro is the minimum normalized positive -floating-point number that is representable by type @code{long double}, -and is guaranteed to be no more than @code{1E-37}. -@end deftypevr - - -@comment float.h -@comment ISO -@deftypevr Macro double FLT_EPSILON -This is the minimum positive floating-point number of type @code{float} -such that @code{1.0 + FLT_EPSILON != 1.0} is true. It's guaranteed to -be no greater than @code{1E-5}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro double DBL_EPSILON -This is similar to @code{FLT_EPSILON}, but is for the @code{double} -type. The maximum value is @code{1E-9}. -@end deftypevr - -@comment float.h -@comment ISO -@deftypevr Macro {long double} LDBL_EPSILON -This is similar to @code{FLT_EPSILON}, but is for the @code{long double} -type. The maximum value is @code{1E-9}. -@end deftypevr - - -@node IEEE Floating Point, , Floating-Point Parameters, Floating-Point Limits -@subsection IEEE Floating Point -@cindex IEEE floating-point representation -@cindex floating-point, IEEE -@cindex IEEE Std 754 - - -Here is an example showing how these parameters work for a common -floating point representation, specified by the @cite{IEEE Standard for -Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 or ANSI/IEEE -Std 854-1987)}. Nearly all computers today use this format. - -The IEEE single-precision float representation uses a base of 2. There -is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total -precision is 24 base-2 digits), and an 8-bit exponent that can represent -values in the range -125 to 128, inclusive. - -So, for an implementation that uses this representation for the -@code{float} data type, appropriate values for the corresponding -parameters are: - -@example -FLT_RADIX 2 -FLT_MANT_DIG 24 -FLT_DIG 6 -FLT_MIN_EXP -125 -FLT_MIN_10_EXP -37 -FLT_MAX_EXP 128 -FLT_MAX_10_EXP +38 -FLT_MIN 1.17549435E-38F -FLT_MAX 3.40282347E+38F -FLT_EPSILON 1.19209290E-07F -@end example - -Here are the values for the @code{double} data type: - -@example -DBL_MANT_DIG 53 -DBL_DIG 15 -DBL_MIN_EXP -1021 -DBL_MIN_10_EXP -307 -DBL_MAX_EXP 1024 -DBL_MAX_10_EXP 308 -DBL_MAX 1.7976931348623157E+308 -DBL_MIN 2.2250738585072014E-308 -DBL_EPSILON 2.2204460492503131E-016 -@end example diff --git a/manual/=process.texinfo b/manual/=process.texinfo deleted file mode 100644 index 4618cff5fa..0000000000 --- a/manual/=process.texinfo +++ /dev/null @@ -1,1452 +0,0 @@ -@node Processes, Job Control, Signal Handling, Top -@chapter Processes - -@cindex process -@dfn{Processes} are the primitive units for allocation of system -resources. Each process has its own address space and (usually) one -thread of control. A process executes a program; you can have multiple -processes executing the same program, but each process has its own copy -of the program within its own address space and executes it -independently of the other copies. - -Processes are organized hierarchically. Child processes are created by -a parent process, and inherit many of their attributes from the parent -process. - -This chapter describes how a program can create, terminate, and control -child processes. - -@menu -* Program Arguments:: Parsing the command-line arguments to - a program. -* Environment Variables:: How to access parameters inherited from - a parent process. -* Program Termination:: How to cause a process to terminate and - return status information to its parent. -* Creating New Processes:: Running other programs. -@end menu - - -@node Program Arguments, Environment Variables, , Processes -@section Program Arguments -@cindex program arguments -@cindex command line arguments - -@cindex @code{main} function -When your C program starts, it begins by executing the function called -@code{main}. You can define @code{main} either to take no arguments, -or to take two arguments that represent the command line arguments -to the program, like this: - -@example -int main (int @var{argc}, char *@var{argv}[]) -@end example - -@cindex argc (program argument count) -@cindex argv (program argument vector) -The command line arguments are the whitespace-separated tokens typed by -the user to the shell in invoking the program. The value of the -@var{argc} argument is the number of command line arguments. The -@var{argv} argument is a vector of pointers to @code{char}; sometimes it -is also declared as @samp{char **@var{argv}}. The elements of -@var{argv} are the individual command line argument strings. By -convention, @code{@var{argv}[0]} is the file name of the program being -run, and @code{@var{argv}[@var{argc}]} is a null pointer. - -If the syntax for the command line arguments to your program is simple -enough, you can simply pick the arguments off from @var{argv} by hand. -But unless your program takes a fixed number of arguments, or all of the -arguments are interpreted in the same way (as file names, for example), -you are usually better off using @code{getopt} to do the parsing. - -@menu -* Argument Syntax Conventions:: By convention, program - options are specified by a - leading hyphen. -* Parsing Program Arguments:: The @code{getopt} function. -* Example Using getopt:: An example of @code{getopt}. -@end menu - -@node Argument Syntax Conventions, Parsing Program Arguments, , Program Arguments -@subsection Program Argument Syntax Conventions -@cindex program argument syntax -@cindex syntax, for program arguments -@cindex command argument syntax - -The @code{getopt} function decodes options following the usual -conventions for POSIX utilities: - -@itemize @bullet -@item -Arguments are options if they begin with a hyphen delimiter (@samp{-}). - -@item -Multiple options may follow a hyphen delimiter in a single token if -the options do not take arguments. Thus, @samp{-abc} is equivalent to -@samp{-a -b -c}. - -@item -Option names are single alphanumeric (as for @code{isalnum}; -see @ref{Classification of Characters}). - -@item -Certain options require an argument. For example, the @samp{-o} -command of the ld command requires an argument---an output file name. - -@item -An option and its argument may or may appear as separate tokens. (In -other words, the whitespace separating them is optional.) Thus, -@samp{-o foo} and @samp{-ofoo} are equivalent. - -@item -Options typically precede other non-option arguments. - -The implementation of @code{getopt} in the GNU C library normally makes -it appear as if all the option arguments were specified before all the -non-option arguments for the purposes of parsing, even if the user of -your program intermixed option and non-option arguments. It does this -by reordering the elements of the @var{argv} array. This behavior is -nonstandard; if you want to suppress it, define the -@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard -Environment Variables}. - -@item -The argument @samp{--} terminates all options; any following arguments -are treated as non-option arguments, even if they begin with a hyphen. - -@item -A token consisting of a single hyphen character is interpreted as an -ordinary non-option argument. By convention, it is used to specify -input from or output to the standard input and output streams. - -@item -Options may be supplied in any order, or appear multiple times. The -interpretation is left up to the particular application program. -@end itemize - -@node Parsing Program Arguments, Example Using getopt, Argument Syntax Conventions, Program Arguments -@subsection Parsing Program Arguments -@cindex program arguments, parsing -@cindex command arguments, parsing -@cindex parsing program arguments - -Here are the details about how to call the @code{getopt} function. To -use this facility, your program must include the header file -@file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.2 -@deftypevar int opterr -If the value of this variable is nonzero, then @code{getopt} prints an -error message to the standard error stream if it encounters an unknown -option character or an option with a missing required argument. This is -the default behavior. If you set this variable to zero, @code{getopt} -does not print any messages, but it still returns @code{?} to indicate -an error. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar int optopt -When @code{getopt} encounters an unknown option character or an option -with a missing required argument, it stores that option character in -this variable. You can use this for providing your own diagnostic -messages. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar int optind -This variable is set by @code{getopt} to the index of the next element -of the @var{argv} array to be processed. Once @code{getopt} has found -all of the option arguments, you can use this variable to determine -where the remaining non-option arguments begin. The initial value of -this variable is @code{1}. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypevar {char *} optarg -This variable is set by @code{getopt} to point at the value of the -option argument, for those options that accept arguments. -@end deftypevar - -@comment unistd.h -@comment POSIX.2 -@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options}) -The @code{getopt} function gets the next option argument from the -argument list specified by the @var{argv} and @var{argc} arguments. -Normally these arguments' values come directly from the arguments of -@code{main}. - -The @var{options} argument is a string that specifies the option -characters that are valid for this program. An option character in this -string can be followed by a colon (@samp{:}) to indicate that it takes a -required argument. - -If the @var{options} argument string begins with a hyphen (@samp{-}), this -is treated specially. It permits arguments without an option to be -returned as if they were associated with option character @samp{\0}. - -The @code{getopt} function returns the option character for the next -command line option. When no more option arguments are available, it -returns @code{-1}. There may still be more non-option arguments; you -must compare the external variable @code{optind} against the @var{argv} -parameter to check this. - -If the options has an argument, @code{getopt} returns the argument by -storing it in the varables @var{optarg}. You don't ordinarily need to -copy the @code{optarg} string, since it is a pointer into the original -@var{argv} array, not into a static area that might be overwritten. - -If @code{getopt} finds an option character in @var{argv} that was not -included in @var{options}, or a missing option argument, it returns -@samp{?} and sets the external variable @code{optopt} to the actual -option character. In addition, if the external variable @code{opterr} -is nonzero, @code{getopt} prints an error message. -@end deftypefun - -@node Example Using getopt, , Parsing Program Arguments, Program Arguments -@subsection Example of Parsing Program Arguments - -Here is an example showing how @code{getopt} is typically used. The -key points to notice are: - -@itemize @bullet -@item -Normally, @code{getopt} is called in a loop. When @code{getopt} returns -@code{-1}, indicating no more options are present, the loop terminates. - -@item -A @code{switch} statement is used to dispatch on the return value from -@code{getopt}. In typical use, each case just sets a variable that -is used later in the program. - -@item -A second loop is used to process the remaining non-option arguments. -@end itemize - -@example -@include testopt.c.texi -@end example - -Here are some examples showing what this program prints with different -combinations of arguments: - -@example -% testopt -aflag = 0, bflag = 0, cvalue = (null) - -% testopt -a -b -aflag = 1, bflag = 1, cvalue = (null) - -% testopt -ab -aflag = 1, bflag = 1, cvalue = (null) - -% testopt -c foo -aflag = 0, bflag = 0, cvalue = foo - -% testopt -cfoo -aflag = 0, bflag = 0, cvalue = foo - -% testopt arg1 -aflag = 0, bflag = 0, cvalue = (null) -Non-option argument arg1 - -% testopt -a arg1 -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument arg1 - -% testopt -c foo arg1 -aflag = 0, bflag = 0, cvalue = foo -Non-option argument arg1 - -% testopt -a -- -b -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument -b - -% testopt -a - -aflag = 1, bflag = 0, cvalue = (null) -Non-option argument - -@end example - -@node Environment Variables, Program Termination, Program Arguments, Processes -@section Environment Variables - -@cindex environment variable -When a program is executed, it receives information about the context in -which it was invoked in two ways. The first mechanism uses the -@var{argv} and @var{argc} arguments to its @code{main} function, and is -discussed in @ref{Program Arguments}. The second mechanism is -uses @dfn{environment variables} and is discussed in this section. - -The @var{argv} mechanism is typically used to pass command-line -arguments specific to the particular program being invoked. The -environment, on the other hand, keeps track of information that is -shared by many programs, changes infrequently, and that is less -frequently accessed. - -The environment variables discussed in this section are the same -environment variables that you set using the assignments and the -@code{export} command in the shell. Programs executed from the shell -inherit all of the environment variables from the shell. - -@cindex environment -Standard environment variables are used for information about the user's -home directory, terminal type, current locale, and so on; you can define -additional variables for other purposes. The set of all environment -variables that have values is collectively known as the -@dfn{environment}. - -Names of environment variables are case-sensitive and must not contain -the character @samp{=}. System-defined environment variables are -invariably uppercase. - -The values of environment variables can be anything that can be -represented as a string. A value must not contain an embedded null -character, since this is assumed to terminate the string. - - -@menu -* Environment Access:: How to get and set the values of - environment variables. -* Standard Environment Variables:: These environment variables have - standard interpretations. -@end menu - -@node Environment Access, Standard Environment Variables, , Environment Variables -@subsection Environment Access -@cindex environment access -@cindex environment representation - -The value of an environment variable can be accessed with the -@code{getenv} function. This is declared in the header file -@file{stdlib.h}. -@pindex stdlib.h - -@comment stdlib.h -@comment ISO -@deftypefun {char *} getenv (const char *@var{name}) -This function returns a string that is the value of the environment -variable @var{name}. You must not modify this string. In some systems -not using the GNU library, it might be overwritten by subsequent calls -to @code{getenv} (but not by any other library function). If the -environment variable @var{name} is not defined, the value is a null -pointer. -@end deftypefun - - -@comment stdlib.h -@comment SVID -@deftypefun int putenv (const char *@var{string}) -The @code{putenv} function adds or removes definitions from the environment. -If the @var{string} is of the form @samp{@var{name}=@var{value}}, the -definition is added to the environment. Otherwise, the @var{string} is -interpreted as the name of an environment variable, and any definition -for this variable in the environment is removed. - -The GNU library provides this function for compatibility with SVID; it -may not be available in other systems. -@end deftypefun - -You can deal directly with the underlying representation of environment -objects to add more variables to the environment (for example, to -communicate with another program you are about to execute; see -@ref{Executing a File}). - -@comment unistd.h -@comment POSIX.1 -@deftypevar {char **} environ -The environment is represented as an array of strings. Each string is -of the format @samp{@var{name}=@var{value}}. The order in which -strings appear in the environment is not significant, but the same -@var{name} must not appear more than once. The last element of the -array is a null pointer. - -This variable is not declared in any header file, but if you declare it -in your own program as @code{extern}, the right thing will happen. - -If you just want to get the value of an environment variable, use -@code{getenv}. -@end deftypevar - -@node Standard Environment Variables, , Environment Access, Environment Variables -@subsection Standard Environment Variables -@cindex standard environment variables - -These environment variables have standard meanings. -This doesn't mean that they are always present in the -environment, though; it just means that if these variables @emph{are} -present, they have these meanings, and that you shouldn't try to use -these environment variable names for some other purpose. - -@table @code -@item HOME -@cindex HOME environment variable -@cindex home directory -This is a string representing the user's @dfn{home directory}, or -initial default working directory. @xref{User Database}, for a -more secure way of determining this information. - -@comment RMS says to explay why HOME is better, but I don't know why. - -@item LOGNAME -@cindex LOGNAME environment variable -This is the name that the user used to log in. Since the value in the -environment can be tweaked arbitrarily, this is not a reliable way to -identify the user who is running a process; a function like -@code{getlogin} (@pxref{User Identification Functions}) is better for -that purpose. - -@comment RMS says to explay why LOGNAME is better, but I don't know why. - -@item PATH -@cindex PATH environment variable -A @dfn{path} is a sequence of directory names which is used for -searching for a file. The variable @var{PATH} holds a path The -@code{execlp} and @code{execvp} functions (@pxref{Executing a File}) -uses this environment variable, as do many shells and other utilities -which are implemented in terms of those functions. - -The syntax of a path is a sequence of directory names separated by -colons. An empty string instead of a directory name stands for the -current directory. (@xref{Working Directory}.) - -A typical value for this environment variable might be a string like: - -@example -.:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin -@end example - -This means that if the user tries to execute a program named @code{foo}, -the system will look for files named @file{./foo}, @file{/bin/foo}, -@file{/etc/foo}, and so on. The first of these files that exists is -the one that is executed. - -@item TERM -@cindex TERM environment variable -This specifies the kind of terminal that is receiving program output. -Some programs can make use of this information to take advantage of -special escape sequences or terminal modes supported by particular kinds -of terminals. Many programs which use the termcap library -(@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library -Manual}) use the @code{TERM} environment variable, for example. - -@item TZ -@cindex TZ environment variable -This specifies the time zone. @xref{Time Zone}, for information about -the format of this string and how it is used. - -@item LANG -@cindex LANG environment variable -This specifies the default locale to use for attribute categories where -neither @code{LC_ALL} nor the specific environment variable for that -category is set. @xref{Locales}, for more information about -locales. - -@item LC_ALL -@cindex LC_ALL environment variable -This is similar to the @code{LANG} environment variable. However, its -value takes precedence over any values provided for the individual -attribute category environment variables, or for the @code{LANG} -environment variable. - -@item LC_COLLATE -@cindex LC_COLLATE environment variable -This specifies what locale to use for string sorting. - -@item LC_CTYPE -@cindex LC_CTYPE environment variable -This specifies what locale to use for character sets and character -classification. - -@item LC_MONETARY -@cindex LC_MONETARY environment variable -This specifies what locale to use for formatting monetary values. - -@item LC_NUMERIC -@cindex LC_NUMERIC environment variable -This specifies what locale to use for formatting numbers. - -@item LC_TIME -@cindex LC_TIME environment variable -This specifies what locale to use for formatting date/time values. - -@item _POSIX_OPTION_ORDER -@cindex _POSIX_OPTION_ORDER environment variable. -If this environment variable is defined, it suppresses the usual -reordering of command line arguments by @code{getopt}. @xref{Program -Argument Syntax Conventions}. -@end table - -@node Program Termination, Creating New Processes, Environment Variables, Processes -@section Program Termination -@cindex program termination -@cindex process termination - -@cindex exit status value -The usual way for a program to terminate is simply for its @code{main} -function to return. The @dfn{exit status value} returned from the -@code{main} function is used to report information back to the process's -parent process or shell. - -A program can also terminate normally calling the @code{exit} -function - -In addition, programs can be terminated by signals; this is discussed in -more detail in @ref{Signal Handling}. The @code{abort} function causes -a terminal that kills the program. - -@menu -* Normal Program Termination:: -* Exit Status:: Exit Status -* Cleanups on Exit:: Cleanups on Exit -* Aborting a Program:: -* Termination Internals:: Termination Internals -@end menu - -@node Normal Program Termination, Exit Status, , Program Termination -@subsection Normal Program Termination - -@comment stdlib.h -@comment ISO -@deftypefun void exit (int @var{status}) -The @code{exit} function causes normal program termination with status -@var{status}. This function does not return. -@end deftypefun - -When a program terminates normally by returning from its @code{main} -function or by calling @code{exit}, the following actions occur in -sequence: - -@enumerate -@item -Functions that were registered with the @code{atexit} or @code{on_exit} -functions are called in the reverse order of their registration. This -mechanism allows your application to specify its own ``cleanup'' actions -to be performed at program termination. Typically, this is used to do -things like saving program state information in a file, or unlock locks -in shared data bases. - -@item -All open streams are closed; writing out any buffered output data. See -@ref{Opening and Closing Streams}. In addition, temporary files opened -with the @code{tmpfile} function are removed; see @ref{Temporary Files}. - -@item -@code{_exit} is called. @xref{Termination Internals} -@end enumerate - -@node Exit Status, Cleanups on Exit, Normal Program Termination, Program Termination -@subsection Exit Status -@cindex exit status - -When a program exits, it can return to the parent process a small -amount of information about the cause of termination, using the -@dfn{exit status}. This is a value between 0 and 255 that the exiting -process passes as an argument to @code{exit}. - -Normally you should use the exit status to report very broad information -about success or failure. You can't provide a lot of detail about the -reasons for the failure, and most parent processes would not want much -detail anyway. - -There are conventions for what sorts of status values certain programs -should return. The most common convention is simply 0 for success and 1 -for failure. Programs that perform comparison use a different -convention: they use status 1 to indicate a mismatch, and status 2 to -indicate an inability to compare. Your program should follow an -existing convention if an existing convention makes sense for it. - -A general convention reserves status values 128 and up for special -purposes. In particular, the value 128 is used to indicate failure to -execute another program in a subprocess. This convention is not -universally obeyed, but it is a good idea to follow it in your programs. - -@strong{Warning:} Don't try to use the number of errors as the exit -status. This is actually not very useful; a parent process would -generally not care how many errors occurred. Worse than that, it does -not work, because the status value is truncated to eight bits. -Thus, if the program tried to report 256 errors, the parent would -receive a report of 0 errors---that is, success. - -For the same reason, it does not work to use the value of @code{errno} -as the exit status---these can exceed 255. - -@strong{Portability note:} Some non-POSIX systems use different -conventions for exit status values. For greater portability, you can -use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the -conventional status value for success and failure, respectively. They -are declared in the file @file{stdlib.h}. -@pindex stdlib.h - -@comment stdlib.h -@comment ISO -@deftypevr Macro int EXIT_SUCCESS -This macro can be used with the @code{exit} function to indicate -successful program completion. - -On POSIX systems, the value of this macro is @code{0}. On other -systems, the value might be some other (possibly non-constant) integer -expression. -@end deftypevr - -@comment stdlib.h -@comment ISO -@deftypevr Macro int EXIT_FAILURE -This macro can be used with the @code{exit} function to indicate -unsuccessful program completion in a general sense. - -On POSIX systems, the value of this macro is @code{1}. On other -systems, the value might be some other (possibly non-constant) integer -expression. Other nonzero status values also indicate future. Certain -programs use different nonzero status values to indicate particular -kinds of "non-success". For example, @code{diff} uses status value -@code{1} to mean that the files are different, and @code{2} or more to -mean that there was difficulty in opening the files. -@end deftypevr - -@node Cleanups on Exit, Aborting a Program, Exit Status, Program Termination -@subsection Cleanups on Exit - -@comment stdlib.h -@comment ISO -@deftypefun int atexit (void (*@var{function})) -The @code{atexit} function registers the function @var{function} to be -called at normal program termination. The @var{function} is called with -no arguments. - -The return value from @code{atexit} is zero on success and nonzero if -the function cannot be registered. -@end deftypefun - -@comment stdlib.h -@comment GNU -@deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg}) -This function is a somewhat more powerful variant of @code{atexit}. It -accepts two arguments, a function @var{function} and an arbitrary -pointer @var{arg}. At normal program termination, the @var{function} is -called with two arguments: the @var{status} value passed to @code{exit}, -and the @var{arg}. - -This function is a GNU extension, and may not be supported by other -implementations. -@end deftypefun - -Here's a trivial program that illustrates the use of @code{exit} and -@code{atexit}: - -@example -#include <stdio.h> -#include <stdlib.h> - -void bye (void) -@{ - printf ("Goodbye, cruel world....\n"); -@} - -void main (void) -@{ - atexit (bye); - exit (EXIT_SUCCESS); -@} -@end example - -@noindent -When this program is executed, it just prints the message and exits. - - -@node Aborting a Program, Termination Internals, Cleanups on Exit, Program Termination -@subsection Aborting a Program -@cindex aborting a program - -You can abort your program using the @code{abort} function. The prototype -for this function is in @file{stdlib.h}. -@pindex stdlib.h - -@comment stdlib.h -@comment ISO -@deftypefun void abort () -The @code{abort} function causes abnormal program termination, without -executing functions registered with @code{atexit} or @code{on_exit}. - -This function actually terminates the process by raising a -@code{SIGABRT} signal, and your program can include a handler to -intercept this signal; see @ref{Signal Handling}. - -@strong{Incomplete:} Why would you want to define such a handler? -@end deftypefun - -@node Termination Internals, , Aborting a Program, Program Termination -@subsection Termination Internals - -The @code{_exit} function is the primitive used for process termination -by @code{exit}. It is declared in the header file @file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypefun void _exit (int @var{status}) -The @code{_exit} function is the primitive for causing a process to -terminate with status @var{status}. Calling this function does not -execute cleanup functions registered with @code{atexit} or -@code{on_exit}. -@end deftypefun - -When a process terminates for any reason---either by an explicit -termination call, or termination as a result of a signal---the -following things happen: - -@itemize @bullet -@item -All open file descriptors in the process are closed. @xref{Low-Level -Input/Output}. - -@item -The low-order 8 bits of the return status code are saved to be reported -back to the parent process via @code{wait} or @code{waitpid}; see -@ref{Process Completion}. - -@item -Any child processes of the process being terminated are assigned a new -parent process. (This is the @code{init} process, with process ID 1.) - -@item -A @code{SIGCHLD} signal is sent to the parent process. - -@item -If the process is a session leader that has a controlling terminal, then -a @code{SIGHUP} signal is sent to each process in the foreground job, -and the controlling terminal is disassociated from that session. -@xref{Job Control}. - -@item -If termination of a process causes a process group to become orphaned, -and any member of that process group is stopped, then a @code{SIGHUP} -signal and a @code{SIGCONT} signal are sent to each process in the -group. @xref{Job Control}. -@end itemize - -@node Creating New Processes, , Program Termination, Processes -@section Creating New Processes - -This section describes how your program can cause other programs to be -executed. Actually, there are three distinct operations involved: -creating a new child process, causing the new process to execute a -program, and coordinating the completion of the child process with the -original program. - -The @code{system} function provides a simple, portable mechanism for -running another program; it does all three steps automatically. If you -need more control over the details of how this is done, you can use the -primitive functions to do each step individually instead. - -@menu -* Running a Command:: The easy way to run another program. -* Process Creation Concepts:: An overview of the hard way to do it. -* Process Identification:: How to get the process ID of a process. -* Creating a Process:: How to fork a child process. -* Executing a File:: How to get a process to execute another - program. -* Process Completion:: How to tell when a child process has - completed. -* Process Completion Status:: How to interpret the status value - returned from a child process. -* BSD wait Functions:: More functions, for backward - compatibility. -* Process Creation Example:: A complete example program. -@end menu - - -@node Running a Command, Process Creation Concepts, , Creating New Processes -@subsection Running a Command -@cindex running a command - -The easy way to run another program is to use the @code{system} -function. This function does all the work of running a subprogram, but -it doesn't give you much control over the details: you have to wait -until the subprogram terminates before you can do anything else. - -@pindex stdlib.h - -@comment stdlib.h -@comment ISO -@deftypefun int system (const char *@var{command}) -This function executes @var{command} as a shell command. In the GNU C -library, it always uses the default shell @code{sh} to run the command. -In particular, it searching the directories in @code{PATH} to find -programs to execute. The return value is @code{-1} if it wasn't -possible to create the shell process, and otherwise is the status of the -shell process. @xref{Process Completion}, for details on how this -status code can be interpreted. -@pindex sh -@end deftypefun - -The @code{system} function is declared in the header file -@file{stdlib.h}. - -@strong{Portability Note:} Some C implementations may not have any -notion of a command processor that can execute other programs. You can -determine whether a command processor exists by executing @code{system -(o)}; in this case the return value is nonzero if and only if such a -processor is available. - -The @code{popen} and @code{pclose} functions (@pxref{Pipe to a -Subprocess}) are closely related to the @code{system} function. They -allow the parent process to communicate with the standard input and -output channels of the command being executed. - -@node Process Creation Concepts, Process Identification, Running a Command, Creating New Processes -@subsection Process Creation Concepts - -This section gives an overview of processes and of the steps involved in -creating a process and making it run another program. - -@cindex process ID -@cindex process lifetime -Each process is named by a @dfn{process ID} number. A unique process ID -is allocated to each process when it is created. The @dfn{lifetime} of -a process ends when its termination is reported to its parent process; -at that time, all of the process resources, including its process ID, -are freed. - -@cindex creating a process -@cindex forking a process -@cindex child process -@cindex parent process -Processes are created with the @code{fork} system call (so the operation -of creating a new process is sometimes called @dfn{forking} a process). -The @dfn{child process} created by @code{fork} is an exact clone of the -original @dfn{parent process}, except that it has its own process ID. - -After forking a child process, both the parent and child processes -continue to execute normally. If you want your program to wait for a -child process to finish executing before continuing, you must do this -explicitly after the fork operation. This is done with the @code{wait} -or @code{waitpid} functions (@pxref{Process Completion}). These -functions give the parent information about why the child -terminated---for example, its exit status code. - -A newly forked child process continues to execute the same program as -its parent process, at the point where the @code{fork} call returns. -You can use the return value from @code{fork} to tell whether the program -is running in the parent process or the child. - -@cindex process image -Having all processes run the same program is usually not very useful. -But the child can execute another program using one of the @code{exec} -functions; see @ref{Executing a File}. The program that the process is -executing is called its @dfn{process image}. Starting execution of a -new program causes the process to forget all about its current process -image; when the new program exits, the process exits too, instead of -returning to the previous process image. - - -@node Process Identification, Creating a Process, Process Creation Concepts, Creating New Processes -@subsection Process Identification - -The @code{pid_t} data type represents process IDs. You can get the -process ID of a process by calling @code{getpid}. The function -@code{getppid} returns the process ID of the parent of the parent of the -current process (this is also known as the @dfn{parent process ID}). -Your program should include the header files @file{unistd.h} and -@file{sys/types.h} to use these functions. -@pindex sys/types.h -@pindex unistd.h - -@comment sys/types.h -@comment POSIX.1 -@deftp {Data Type} pid_t -The @code{pid_t} data type is a signed integer type which is capable -of representing a process ID. In the GNU library, this is an @code{int}. -@end deftp - -@comment unistd.h -@comment POSIX.1 -@deftypefun pid_t getpid () -The @code{getpid} function returns the process ID of the current process. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun pid_t getppid () -The @code{getppid} function returns the process ID of the parent of the -current process. -@end deftypefun - -@node Creating a Process, Executing a File, Process Identification, Creating New Processes -@subsection Creating a Process - -The @code{fork} function is the primitive for creating a process. -It is declared in the header file @file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypefun pid_t fork () -The @code{fork} function creates a new process. - -If the operation is successful, there are then both parent and child -processes and both see @code{fork} return, but with different values: it -returns a value of @code{0} in the child process and returns the child's -process ID in the parent process. If the child process could not be -created, a value of @code{-1} is returned in the parent process. The -following @code{errno} error conditions are defined for this function: - -@table @code -@item EAGAIN -There aren't enough system resources to create another process, or the -user already has too many processes running. - -@item ENOMEM -The process requires more space than the system can supply. -@end table -@end deftypefun - -The specific attributes of the child process that differ from the -parent process are: - -@itemize @bullet -@item -The child process has its own unique process ID. - -@item -The parent process ID of the child process is the process ID of its -parent process. - -@item -The child process gets its own copies of the parent process's open file -descriptors. Subsequently changing attributes of the file descriptors -in the parent process won't affect the file descriptors in the child, -and vice versa. @xref{Control Operations}. - -@item -The elapsed processor times for the child process are set to zero; -see @ref{Processor Time}. - -@item -The child doesn't inherit file locks set by the parent process. -@xref{Control Operations}. - -@item -The child doesn't inherit alarms set by the parent process. -@xref{Setting an Alarm}. - -@item -The set of pending signals (@pxref{Delivery of Signal}) for the child -process is cleared. (The child process inherits its mask of blocked -signals and signal actions from the parent process.) -@end itemize - - -@comment unistd.h -@comment BSD -@deftypefun pid_t vfork (void) -The @code{vfork} function is similar to @code{fork} but more efficient; -however, there are restrictions you must follow to use it safely. - -While @code{fork} makes a complete copy of the calling process's address -space and allows both the parent and child to execute independently, -@code{vfork} does not make this copy. Instead, the child process -created with @code{vfork} shares its parent's address space until it calls -one of the @code{exec} functions. In the meantime, the parent process -suspends execution. - -You must be very careful not to allow the child process created with -@code{vfork} to modify any global data or even local variables shared -with the parent. Furthermore, the child process cannot return from (or -do a long jump out of) the function that called @code{vfork}! This -would leave the parent process's control information very confused. If -in doubt, use @code{fork} instead. - -Some operating systems don't really implement @code{vfork}. The GNU C -library permits you to use @code{vfork} on all systems, but actually -executes @code{fork} if @code{vfork} isn't available. -@end deftypefun - -@node Executing a File, Process Completion, Creating a Process, Creating New Processes -@subsection Executing a File -@cindex executing a file -@cindex @code{exec} functions - -This section describes the @code{exec} family of functions, for executing -a file as a process image. You can use these functions to make a child -process execute a new program after it has been forked. - -The functions in this family differ in how you specify the arguments, -but otherwise they all do the same thing. They are declared in the -header file @file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]}) -The @code{execv} function executes the file named by @var{filename} as a -new process image. - -The @var{argv} argument is an array of null-terminated strings that is -used to provide a value for the @code{argv} argument to the @code{main} -function of the program to be executed. The last element of this array -must be a null pointer. @xref{Program Arguments}, for information on -how programs can access these arguments. - -The environment for the new process image is taken from the -@code{environ} variable of the current process image; see @ref{Environment -Variables}, for information about environments. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{}) -This is similar to @code{execv}, but the @var{argv} strings are -specified individually instead of as an array. A null pointer must be -passed as the last such argument. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]}) -This is similar to @code{execv}, but permits you to specify the environment -for the new program explicitly as the @var{env} argument. This should -be an array of strings in the same format as for the @code{environ} -variable; see @ref{Environment Access}. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{}) -This is similar to @code{execl}, but permits you to specify the -environment for the new program explicitly. The environment argument is -passed following the null pointer that marks the last @var{argv} -argument, and should be an array of strings in the same format as for -the @code{environ} variable. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]}) -The @code{execvp} function is similar to @code{execv}, except that it -searches the directories listed in the @code{PATH} environment variable -(@pxref{Standard Environment Variables}) to find the full file name of a -file from @var{filename} if @var{filename} does not contain a slash. - -This function is useful for executing installed system utility programs, -so that the user can control where to look for them. It is also useful -in shells, for executing commands typed by the user. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{}) -This function is like @code{execl}, except that it performs the same -file name searching as the @code{execvp} function. -@end deftypefun - - -The size of the argument list and environment list taken together must not -be greater than @code{ARG_MAX} bytes. @xref{System Parameters}. - -@strong{Incomplete:} The POSIX.1 standard requires some statement here -about how null terminators, null pointers, and alignment requirements -affect the total size of the argument and environment lists. - -These functions normally don't return, since execution of a new program -causes the currently executing program to go away completely. A value -of @code{-1} is returned in the event of a failure. In addition to the -usual file name syntax errors (@pxref{File Name Errors}), the following -@code{errno} error conditions are defined for these functions: - -@table @code -@item E2BIG -The combined size of the new program's argument list and environment list -is larger than @code{ARG_MAX} bytes. - -@item ENOEXEC -The specified file can't be executed because it isn't in the right format. - -@item ENOMEM -Executing the specified file requires more storage than is available. -@end table - -If execution of the new file is successful, the access time field of the -file is updated as if the file had been opened. @xref{File Times}, for -more details about access times of files. - -The point at which the file is closed again is not specified, but -is at some point before the process exits or before another process -image is executed. - -Executing a new process image completely changes the contents of memory, -except for the arguments and the environment, but many other attributes -of the process are unchanged: - -@itemize @bullet -@item -The process ID and the parent process ID. @xref{Process Creation Concepts}. - -@item -Session and process group membership. @xref{Job Control Concepts}. - -@item -Real user ID and group ID, and supplementary group IDs. @xref{User/Group -IDs of a Process}. - -@item -Pending alarms. @xref{Setting an Alarm}. - -@item -Current working directory and root directory. @xref{Working Directory}. - -@item -File mode creation mask. @xref{Setting Permissions}. - -@item -Process signal mask; see @ref{Process Signal Mask}. - -@item -Pending signals; see @ref{Blocking Signals}. - -@item -Elapsed processor time associated with the process; see @ref{Processor Time}. -@end itemize - -If the set-user-ID and set-group-ID mode bits of the process image file -are set, this affects the effective user ID and effective group ID -(respectively) of the process. These concepts are discussed in detail -in @ref{User/Group IDs of a Process}. - -Signals that are set to be ignored in the existing process image are -also set to be ignored in the new process image. All other signals are -set to the default action in the new process image. For more -information about signals, see @ref{Signal Handling}. - -File descriptors open in the existing process image remain open in the -new process image, unless they have the @code{FD_CLOEXEC} -(close-on-exec) flag set. The files that remain open inherit all -attributes of the open file description from the existing process image, -including file locks. File descriptors are discussed in @ref{Low-Level -Input/Output}. - -Streams, by contrast, cannot survive through @code{exec} functions, -because they are located in the memory of the process itself. The new -process image has no streams except those it creates afresh. Each of -the streams in the pre-@code{exec} process image has a descriptor inside -it, and these descriptors do survive through @code{exec} (provided that -they do not have @code{FD_CLOEXEC} set. The new process image can -reconnect these to new streams using @code{fdopen}. - -@node Process Completion, Process Completion Status, Executing a File, Creating New Processes -@subsection Process Completion -@cindex process completion -@cindex waiting for completion of child process -@cindex testing exit status of child process - -The functions described in this section are used to wait for a child -process to terminate or stop, and determine its status. These functions -are declared in the header file @file{sys/wait.h}. -@pindex sys/wait.h - -@comment sys/wait.h -@comment POSIX.1 -@deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status_ptr}, int @var{options}) -The @code{waitpid} function is used to request status information from a -child process whose process ID is @var{pid}. Normally, the calling -process is suspended until the child process makes status information -available by terminating. - -Other values for the @var{pid} argument have special interpretations. A -value of @code{-1} or @code{WAIT_ANY} requests status information for -any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests -information for any child process in the same process group as the -calling process; and any other negative value @minus{} @var{pgid} -requests information for any child process whose process group ID is -@var{pgid}. - -If status information for a child process is available immediately, this -function returns immediately without waiting. If more than one eligible -child process has status information available, one of them is chosen -randomly, and its status is returned immediately. To get the status -from the other programs, you need to call @code{waitpid} again. - -The @var{options} argument is a bit mask. Its value should be the -bitwise OR (that is, the @samp{|} operator) of zero or more of the -@code{WNOHANG} and @code{WUNTRACED} flags. You can use the -@code{WNOHANG} flag to indicate that the parent process shouldn't wait; -and the @code{WUNTRACED} flag to request status information from stopped -processes as well as processes that have terminated. - -The status information from the child process is stored in the object -that @var{status_ptr} points to, unless @var{status_ptr} is a null pointer. - -The return value is normally the process ID of the child process whose -status is reported. If the @code{WNOHANG} option was specified and no -child process is waiting to be noticed, a value of zero is returned. A -value of @code{-1} is returned in case of error. The following -@code{errno} error conditions are defined for this function: - -@table @code -@item EINTR -The function was interrupted by delivery of a signal to the calling -process. - -@item ECHILD -There are no child processes to wait for, or the specified @var{pid} -is not a child of the calling process. - -@item EINVAL -An invalid value was provided for the @var{options} argument. -@end table -@end deftypefun - -These symbolic constants are defined as values for the @var{pid} argument -to the @code{waitpid} function. - -@table @code -@item WAIT_ANY -This constant macro (whose value is @code{-1}) specifies that -@code{waitpid} should return status information about any child process. - -@item WAIT_MYPGRP -This constant (with value @code{0}) specifies that @code{waitpid} should -return status information about any child process in the same process -group as the calling process. - -These symbolic constants are defined as flags for the @var{options} -argument to the @code{waitpid} function. You can bitwise-OR the flags -together to obtain a value to use as the argument. - -@item WNOHANG -This flag specifies that @code{waitpid} should return immediately -instead of waiting if there is no child process ready to be noticed. - -@item WUNTRACED -This macro is used to specify that @code{waitpid} should also report the -status of any child processes that have been stopped as well as those -that have terminated. -@end table - -@deftypefun pid_t wait (int *@var{status_ptr}) -This is a simplified version of @code{waitpid}, and is used to wait -until any one child process terminates. - -@example -wait (&status) -@end example - -@noindent -is equivalent to: - -@example -waitpid (-1, &status, 0) -@end example - -Here's an example of how to use @code{waitpid} to get the status from -all child processes that have terminated, without ever waiting. This -function is designed to be used as a handler for @code{SIGCHLD}, the -signal that indicates that at least one child process has terminated. - -@example -void -sigchld_handler (int signum) -@{ - int pid; - int status; - while (1) @{ - pid = waitpid (WAIT_ANY, Estatus, WNOHANG); - if (pid < 0) @{ - perror ("waitpid"); - break; - @} - if (pid == 0) - break; - notice_termination (pid, status); - @} -@} -@end example -@end deftypefun - -@node Process Completion Status, BSD wait Functions, Process Completion, Creating New Processes -@subsection Process Completion Status - -If the exit status value (@pxref{Program Termination}) of the child -process is zero, then the status value reported by @code{waitpid} or -@code{wait} is also zero. You can test for other kinds of information -encoded in the returned status value using the following macros. -These macros are defined in the header file @file{sys/wait.h}. -@pindex sys/wait.h - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WIFEXITED (int @var{status}) -This macro returns a non-zero value if the child process terminated -normally with @code{exit} or @code{_exit}. -@end deftypefn - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WEXITSTATUS (int @var{status}) -If @code{WIFEXITED} is true of @var{status}, this macro returns the -low-order 8 bits of the exit status value from the child process. -@end deftypefn - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WIFSIGNALED (int @var{status}) -This macro returns a non-zero value if the child process terminated -by receiving a signal that was not handled. -@end deftypefn - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WTERMSIG (int @var{status}) -If @code{WIFSIGNALED} is true of @var{status}, this macro returns the -number of the signal that terminated the child process. -@end deftypefn - -@comment sys/wait.h -@comment BSD -@deftypefn Macro int WCOREDUMP (int @var{status}) -This macro returns a non-zero value if the child process terminated -and produced a core dump. -@end deftypefn - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WIFSTOPPED (int @var{status}) -This macro returns a non-zero value if the child process is stopped. -@end deftypefn - -@comment sys/wait.h -@comment POSIX.1 -@deftypefn Macro int WSTOPSIG (int @var{status}) -If @code{WIFSTOPPED} is true of @var{status}, this macro returns the -number of the signal that caused the child process to stop. -@end deftypefn - - -@node BSD wait Functions, Process Creation Example, Process Completion Status, Creating New Processes -@subsection BSD Process Completion Functions - -The GNU library also provides these related facilities for compatibility -with BSD Unix. BSD uses the @code{union wait} data type to represent -status values rather than an @code{int}. The two representations are -actually interchangeable; they describe the same bit patterns. The macros -such as @code{WEXITSTATUS} are defined so that they will work on either -kind of object, and the @code{wait} function is defined to accept either -type of pointer as its @var{status_ptr} argument. - -These functions are declared in @file{sys/wait.h}. -@pindex sys/wait.h - -@comment sys/wait.h -@comment BSD -@deftp {union Type} wait -This data type represents program termination status values. It has -the following members: - -@table @code -@item int w_termsig -This member is equivalent to the @code{WTERMSIG} macro. - -@item int w_coredump -This member is equivalent to the @code{WCOREDUMP} macro. - -@item int w_retcode -This member is equivalent to the @code{WEXISTATUS} macro. - -@item int w_stopsig -This member is equivalent to the @code{WSTOPSIG} macro. -@end table - -Instead of accessing these members directly, you should use the -equivalent macros. -@end deftp - -@comment sys/wait.h -@comment BSD -@deftypefun pid_t wait3 (union wait *@var{status_ptr}, int @var{options}, void * @var{usage}) -If @var{usage} is a null pointer, this function is equivalent to -@code{waitpid (-1, @var{status_ptr}, @var{options})}. - -The @var{usage} argument may also be a pointer to a -@code{struct rusage} object. Information about system resources used by -terminated processes (but not stopped processes) is returned in this -structure. - -@strong{Incomplete:} The description of the @code{struct rusage} structure -hasn't been written yet. Put in a cross-reference here. -@end deftypefun - -@comment sys/wait.h -@comment BSD -@deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status_ptr}, int @var{options}, void *@var{usage}) -If @var{usage} is a null pointer, this function is equivalent to -@code{waitpid (@var{pid}, @var{status_ptr}, @var{options})}. - -The @var{usage} argument may also be a pointer to a -@code{struct rusage} object. Information about system resources used by -terminated processes (but not stopped processes) is returned in this -structure. - -@strong{Incomplete:} The description of the @code{struct rusage} structure -hasn't been written yet. Put in a cross-reference here. -@end deftypefun - -@node Process Creation Example, , BSD wait Functions, Creating New Processes -@subsection Process Creation Example - -Here is an example program showing how you might write a function -similar to the built-in @code{system}. It executes its @var{command} -argument using the equivalent of @samp{sh -c @var{command}}. - -@example -#include <stddef.h> -#include <stdlib.h> -#include <unistd.h> -#include <sys/types.h> -#include <sys/wait.h> - -/* @r{Execute the command using this shell program.} */ -#define SHELL "/bin/sh" - -int -my_system (char *command) -@{ - int status; - pid_t pid; - - pid = fork (); - if (pid == 0) @{ - /* @r{This is the child process. Execute the shell command.} */ - execl (SHELL, SHELL, "-c", command, NULL); - exit (EXIT_FAILURE); - @} - else if (pid < 0) - /* @r{The fork failed. Report failure.} */ - status = -1; - else @{ - /* @r{This is the parent process. Wait for the child to complete.} */ - if (waitpid (pid, &status, 0) != pid) - status = -1; - @} - return status; -@} -@end example - -@comment Yes, this example has been tested. - -There are a couple of things you should pay attention to in this -example. - -Remember that the first @code{argv} argument supplied to the program -represents the name of the program being executed. That is why, in the -call to @code{execl}, @code{SHELL} is supplied once to name the program -to execute and a second time to supply a value for @code{argv[0]}. - -The @code{execl} call in the child process doesn't return if it is -successful. If it fails, you must do something to make the child -process terminate. Just returning a bad status code with @code{return} -would leave two processes running the original program. Instead, the -right behavior is for the child process to report failure to its parent -process. To do this, @code{exit} is called with a failure status. diff --git a/manual/=stdarg.texi b/manual/=stdarg.texi deleted file mode 100644 index a209efc785..0000000000 --- a/manual/=stdarg.texi +++ /dev/null @@ -1,290 +0,0 @@ -@node Variable Argument Facilities, Memory Allocation, Common Definitions, Top -@chapter Variable Argument Facilities -@cindex variadic argument functions -@cindex variadic functions -@cindex variable number of arguments -@cindex optional arguments - -@w{ISO C} defines a syntax as part of the kernel language for specifying -functions that take a variable number or type of arguments. (Such -functions are also referred to as @dfn{variadic functions}.) However, -the kernel language provides no mechanism for actually accessing -non-required arguments; instead, you use the variable arguments macros -defined in @file{stdarg.h}. -@pindex stdarg.h - -@menu -* Why Variable Arguments are Used:: Using variable arguments can - save you time and effort. -* How Variable Arguments are Used:: An overview of the facilities for - receiving variable arguments. -* Variable Arguments Interface:: Detailed specification of the - library facilities. -* Example of Variable Arguments:: A complete example. -@end menu - -@node Why Variable Arguments are Used, How Variable Arguments are Used, , Variable Argument Facilities -@section Why Variable Arguments are Used - -Most C functions take a fixed number of arguments. When you define a -function, you also supply a specific data type for each argument. -Every call to the function should supply the same number and type of -arguments as specified in the function definition. - -On the other hand, sometimes a function performs an operation that can -meaningfully accept an unlimited number of arguments. - -For example, consider a function that joins its arguments into a linked -list. It makes sense to connect any number of arguments together into a -list of arbitrary length. Without facilities for variable arguments, -you would have to define a separate function for each possible number of -arguments you might want to link together. This is an example of a -situation where some kind of mapping or iteration is performed over an -arbitrary number of arguments of the same type. - -Another kind of application where variable arguments can be useful is -for functions where values for some arguments can simply be omitted in -some calls, either because they are not used at all or because the -function can determine appropriate defaults for them if they're missing. - -The library function @code{printf} (@pxref{Formatted Output}) is an -example of still another class of function where variable arguments are -useful. This function prints its arguments (which can vary in type as -well as number) under the control of a format template string. - -@node How Variable Arguments are Used, Variable Arguments Interface, Why Variable Arguments are Used, Variable Argument Facilities -@section How Variable Arguments are Used - -This section describes how you can define and call functions that take -variable arguments, and how to access the values of the non-required -arguments. - -@menu -* Syntax for Variable Arguments:: How to make a prototype for a - function with variable arguments. -* Receiving the Argument Values:: Steps you must follow to access the - optional argument values. -* How Many Arguments:: How to decide whether there are more - arguments. -* Calling Variadic Functions:: Things you need to know about calling - variable arguments functions. -@end menu - -@node Syntax for Variable Arguments, Receiving the Argument Values, , How Variable Arguments are Used -@subsection Syntax for Variable Arguments - -A function that accepts a variable number of arguments must have at -least one required argument with a specified type. In the function -definition or prototype declaration, you indicate the fact that a -function can accept additional arguments of unspecified type by putting -@samp{@dots{}} at the end of the arguments. For example, - -@example -int -func (const char *a, int b, @dots{}) -@{ - @dots{} -@} -@end example - -@noindent -outlines a definition of a function @code{func} which returns an -@code{int} and takes at least two arguments, the first two being a -@code{const char *} and an @code{int}.@refill - -An obscure restriction placed by the @w{ISO C} standard is that the last -required argument must not be declared @code{register} in the function -definition. Furthermore, this argument must not be of a function or -array type, and may not be, for example, a @code{char} or @code{short -int} (whether signed or not) or a @code{float}. - -@strong{Compatibility Note:} Many older C dialects provide a similar, -but incompatible, mechanism for defining functions with variable numbers -of arguments. In particular, the @samp{@dots{}} syntax is a new feature -of @w{ISO C}. - - -@node Receiving the Argument Values, How Many Arguments, Syntax for Variable Arguments, How Variable Arguments are Used -@subsection Receiving the Argument Values - -Inside the definition of a variadic function, to access the optional -arguments with the following three step process: - -@enumerate -@item -You initialize an argument pointer variable of type @code{va_list} using -@code{va_start}. - -@item -You access the optional arguments by successive calls to @code{va_arg}. - -@item -You call @code{va_end} to indicate that you are finished accessing the -arguments. -@end enumerate - -Steps 1 and 3 must be performed in the function that is defined to -accept variable arguments. However, you can pass the @code{va_list} -variable as an argument to another function and perform all or part of -step 2 there. After doing this, the value of the @code{va_list} -variable in the calling function becomes undefined for further calls to -@code{va_arg}; you should just pass it to @code{va_end}. - -You can perform the entire sequence of the three steps multiple times -within a single function invocation. And, if the function doesn't want -to look at its optional arguments at all, it doesn't have to do any of -these steps. It is also perfectly all right for a function to access -fewer arguments than were supplied in the call, but you will get garbage -values if you try to access too many arguments. - - -@node How Many Arguments, Calling Variadic Functions, Receiving the Argument Values, How Variable Arguments are Used -@subsection How Many Arguments Were Supplied - -There is no general way for a function to determine the number and type -of the actual values that were passed as optional arguments. Typically, -the value of one of the required arguments is used to tell the function -this information. It is up to you to define an appropriate calling -convention for each function, and write all calls accordingly. - -One calling convention is to make one of the required arguments be an -explicit argument count. This convention is usable if all of the -optional arguments are of the same type. - -A required argument can be used as a pattern to specify both the number -and types of the optional arguments. The format template string -argument to @code{printf} is one example of this. - -A similar technique that is sometimes used is to have one of the -required arguments be a bit mask, with a bit for each possible optional -argument that might be supplied. The bits are tested in a predefined -sequence; if the bit is set, the value of the next argument is -retrieved, and otherwise a default value is used. - -Another technique that is sometimes used is to pass an ``end marker'' -value as the last optional argument. For example, for a function that -manipulates an arbitrary number of pointer arguments, a null pointer -might indicate the end of the argument list, provided that a null -pointer isn't otherwise meaningful to the function. - - -@node Calling Variadic Functions, , How Many Arguments, How Variable Arguments are Used -@subsection Calling Variadic Functions - -Functions that are @emph{defined} to be variadic must also be -@emph{declared} to be variadic using a function prototype in the scope -of all calls to it. This is because C compilers might use a different -internal function call protocol for variadic functions than for -functions that take a fixed number and type of arguments. If the -compiler can't determine in advance that the function being called is -variadic, it may end up trying to call it incorrectly and your program -won't work. -@cindex function prototypes -@cindex prototypes for variadic functions -@cindex variadic functions need prototypes - -Since the prototype doesn't specify types for optional arguments, in a -call to a variadic function the @dfn{default argument promotions} are -performed on the optional argument values. This means the objects of -type @code{char} or @code{short int} (whether signed or not) are -promoted to either @code{int} or @code{unsigned int}, as appropriate; -and that objects of type @code{float} are promoted to type -@code{double}. So, if the caller passes a @code{char} as an optional -argument, it is promoted to a @code{int}, and the function should get it -with @code{va_arg (@var{ap}, int)}. - -Promotions of the required arguments are determined by the function -prototype in the usual way (as if by assignment to the types of the -corresponding formal parameters). -@cindex default argument promotions -@cindex argument promotion - -@node Variable Arguments Interface, Example of Variable Arguments, How Variable Arguments are Used, Variable Argument Facilities -@section Variable Arguments Interface - -Here are descriptions of the macros used to retrieve variable arguments. -These macros are defined in the header file @file{stdarg.h}. -@pindex stdarg.h - -@comment stdarg.h -@comment ISO -@deftp {Data Type} va_list -The type @code{va_list} is used for argument pointer variables. -@end deftp - -@comment stdarg.h -@comment ISO -@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required}) -This macro initialized the argument pointer variable @var{ap} to point -to the first of the optional arguments of the current function; -@var{last_required} must be the last required argument to the function. -@end deftypefn - -@comment stdarg.h -@comment ISO -@deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type}) -The @code{va_arg} macro returns the value of the next optional argument, -and changes the internal state of @var{ap} to move past this argument. -Thus, successive uses of @code{va_arg} return successive optional -arguments. -The type of the value returned by @code{va_arg} is the @var{type} -specified in the call. - -The @var{type} must match the type of the actual argument, and must not -be @code{char} or @code{short int} or @code{float}. (Remember that the -default argument promotions apply to optional arguments.) -@end deftypefn - -@comment stdarg.h -@comment ISO -@deftypefn {Macro} void va_end (va_list @var{ap}) -This ends the use of @var{ap}. After a @code{va_end} call, further -@code{va_arg} calls with the same @var{ap} may not work. You should invoke -@code{va_end} before returning from the function in which @code{va_start} -was invoked with the same @var{ap} argument. - -In the GNU C library, @code{va_end} does nothing, and you need not ever -use it except for reasons of portability. -@refill -@end deftypefn - - -@node Example of Variable Arguments, , Variable Arguments Interface, Variable Argument Facilities -@section Example of Variable Arguments - -Here is a complete sample function that accepts variable numbers of -arguments. The first argument to the function is the count of remaining -arguments, which are added up and the result returned. (This is -obviously a rather pointless function, but it serves to illustrate the -way the variable arguments facility is commonly used.) - -@comment Yes, this example has been tested. - -@example -#include <stdarg.h> - -int -add_em_up (int count, @dots{}) -@{ - va_list ap; - int i, sum; - - va_start (ap, count); /* @r{Initialize the argument list.} */ - - sum = 0; - for (i = 0; i < count; i++) - sum = sum + va_arg (ap, int); /* @r{Get the next argument value.} */ - - va_end (ap); /* @r{Clean up.} */ - return sum; -@} - -void main (void) -@{ - /* @r{This call prints 16.} */ - printf ("%d\n", add_em_up (3, 5, 5, 6)); - - /* @r{This call prints 55.} */ - printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)); -@} -@end example diff --git a/manual/=stddef.texi b/manual/=stddef.texi deleted file mode 100644 index e15fd7375f..0000000000 --- a/manual/=stddef.texi +++ /dev/null @@ -1,81 +0,0 @@ -@node Common Definitions, Memory Allocation, Error Reporting, Top -@chapter Common Definitions - -There are some miscellaneous data types and macros that are not part of -the C language kernel but are nonetheless almost universally used, such -as the macro @code{NULL}. In order to use these type and macro -definitions, your program should include the header file -@file{stddef.h}. -@pindex stddef.h - -@comment stddef.h -@comment ISO -@deftp {Data Type} ptrdiff_t -This is the signed integer type of the result of subtracting two -pointers. For example, with the declaration @code{char *p1, *p2;}, the -expression @code{p2 - p1} is of type @code{ptrdiff_t}. This will -probably be one of the standard signed integer types (@code{short int}, -@code{int} or @code{long int}), but might be a nonstandard type that -exists only for this purpose. -@end deftp - -@comment stddef.h -@comment ISO -@deftp {Data Type} size_t -This is an unsigned integer type used to represent the sizes of objects. -The result of the @code{sizeof} operator is of this type, and functions -such as @code{malloc} (@pxref{Unconstrained Allocation}) and -@code{memcpy} (@pxref{Copying and Concatenation}) that manipulate -objects of arbitrary sizes accept arguments of this type to specify -object sizes. -@end deftp - -In the GNU system @code{size_t} is equivalent to one of the types -@code{unsigned int} and @code{unsigned long int}. These types have -identical properties on the GNU system, and for most purposes, you -can use them interchangeably. However, they are distinct types, -and in certain contexts, you may not treat them as identical. For -example, when you specify the type of a function argument in a -function prototype, it makes a difference which one you use. If -the system header files declare @code{malloc} with an argument -of type @code{size_t} and you declare @code{malloc} with an argument -of type @code{unsigned int}, you will get a compilation error if -@code{size_t} happens to be @code{unsigned long int} on your system. -To avoid any possibility of error, when a function argument is -supposed to have type @code{size_t}, always write the type as -@code{size_t}, and make no assumptions about what that type might -actually be. - -@strong{Compatibility Note:} Types such as @code{size_t} are new -features of @w{ISO C}. Older, pre-ANSI C implementations have -traditionally used @code{unsigned int} for representing object sizes -and @code{int} for pointer subtraction results. - -@comment stddef.h -@comment ISO -@deftypevr Macro {void *} NULL -@cindex null pointer -This is a null pointer constant. It can be assigned to any pointer -variable since it has type @code{void *}, and is guaranteed not to -point to any real object. This macro is the best way to get a null -pointer value. You can also use @code{0} or @code{(void *)0} as a null -pointer constant, but using @code{NULL} makes the purpose of the -constant more evident. - -When passing a null pointer as an argument to a function for which there -is no prototype declaration in scope, you should explicitly cast -@code{NULL} or @code{0} into a pointer of the appropriate type. Again, -this is because the default argument promotions may not do the right -thing. -@end deftypevr - -@comment stddef.h -@comment ISO -@deftypefn {Macro} size_t offsetof (@var{type}, @var{member}) -This expands to a integer constant expression that is the offset of the -structure member named @var{member} in a @code{struct} of type -@var{type}. For example, @code{offsetof (struct s, elem)} is the -offset, in bytes, of the member @code{elem} in a @code{struct s}. This -macro won't work if @var{member} is a bit field; you get an error from -the C compiler in that case. -@end deftypefn diff --git a/manual/Makefile b/manual/Makefile index 0e8ae85dc7..fafa7e77d9 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -66,10 +66,10 @@ stamp-summary: summary.awk $(chapters) $(chapters-incl) # Generate a file which can be added to the `dir' content to provide direct # access to the documentation of the function, variables, and other # definitions. -dir-add.texi: manual/xtract-typefun.awk $(chapters-incl) - if test -n "$(chapters-incl)"; then \ - (for i in $(chapters-incl); do \ - $(GAWK) -f $< < $i; \ +dir-add.texi: xtract-typefun.awk $(chapters) + if test -n "$(chapters)"; then \ + (for i in $(chapters); do \ + $(GAWK) -f $< < $$i; \ done) | sort > $@.new; \ ./move-if-change $@.new $@; \ fi diff --git a/manual/arith.texi b/manual/arith.texi index 59ddbd626f..d8703ea6c1 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -411,7 +411,36 @@ type @code{long int} rather than @code{int}.) @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator}) The @code{ldiv} function is similar to @code{div}, except that the arguments are of type @code{long int} and the result is returned as a -structure of type @code{ldiv}. +structure of type @code{ldiv_t}. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftp {Data Type} lldiv_t +This is a structure type used to hold the result returned by the @code{lldiv} +function. It has the following members: + +@table @code +@item long long int quot +The quotient from the division. + +@item long long int rem +The remainder from the division. +@end table + +(This is identical to @code{div_t} except that the components are of +type @code{long long int} rather than @code{int}.) +@end deftp + +@comment stdlib.h +@comment GNU +@deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator}) +The @code{lldiv} function is like the @code{div} function, but the +arguments are of type @code{long long int} and the result is returned as +a structure of type @code{lldiv_t}. + +The @code{lldiv} function is a GNU extension but it will eventually be +part of the next ISO C standard. @end deftypefun @@ -519,42 +548,48 @@ to @code{EINVAL} and returns @code{0ul}. @end deftypefun @comment stdlib.h -@comment BSD -@deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base}) -The @code{strtoq} (``string-to-quad-word'') function is like -@code{strtol} except that is deals with extra long numbers and it -returns its value with type @code{long long int}. +@comment GNU +@deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base}) +The @code{strtoll} function is like @code{strtol} except that is deals +with extra long numbers and it returns its value with type @code{long +long int}. If the string has valid syntax for an integer but the value is not -representable because of overflow, @code{strtoq} returns either +representable because of overflow, @code{strtoll} returns either @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as appropriate for the sign of the value. It also sets @code{errno} to @code{ERANGE} to indicate there was overflow. -@end deftypefun -@comment stdlib.h -@comment GNU -@deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base}) -@code{strtoll} is only an commonly used other name for the @code{strtoq} -function. Everything said for @code{strtoq} applies to @code{strtoll} -as well. +The @code{strtoll} function is a GNU extension but it will eventually be +part of the next ISO C standard. @end deftypefun @comment stdlib.h @comment BSD -@deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base}) -The @code{strtouq} (``string-to-unsigned-quad-word'') function is like -@code{strtoul} except that is deals with extra long numbers and it -returns its value with type @code{unsigned long long int}. The value -returned in case of overflow is @code{ULONG_LONG_MAX} (@pxref{Range of Type}). +@deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@code{strtoq} (``string-to-quad-word'') is only an commonly used other +name for the @code{strtoll} function. Everything said for +@code{strtoll} applies to @code{strtoq} as well. @end deftypefun @comment stdlib.h @comment GNU @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base}) -@code{strtoull} is only an commonly used other name for the @code{strtouq} -function. Everything said for @code{strtouq} applies to @code{strtoull} -as well. +The @code{strtoull} function is like @code{strtoul} except that is deals +with extra long numbers and it returns its value with type +@code{unsigned long long int}. The value returned in case of overflow +is @code{ULONG_LONG_MAX} (@pxref{Range of Type}). + +The @code{strtoull} function is a GNU extension but it will eventually be +part of the next ISO C standard. +@end deftypefun + +@comment stdlib.h +@comment BSD +@deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@code{strtouq} (``string-to-unsigned-quad-word'') is only an commonly +used other name for the @code{strtoull} function. Everything said for +@code{strtoull} applies to @code{strtouq} as well. @end deftypefun @comment stdlib.h @@ -574,6 +609,16 @@ value rather than @code{long int}. The @code{atoi} function is also considered obsolete; use @code{strtol} instead. @end deftypefun +@comment stdlib.h +@comment GNU +@deftypefun {long long int} atoll (const char *@var{string}) +This function is similar to @code{atol}, except it returns a @code{long +long int} value rather than @code{long int}. + +The @code{atoll} function is a GNU extension but it will eventually be +part of the next ISO C standard. +@end deftypefun + The POSIX locales contain some information about how to format numbers (@pxref{General Numeric}). This mainly deals with representing numbers for better readability for humans. The functions present so far in this @@ -688,6 +733,24 @@ the sign of the value. Similarly, if the value is not representable because of underflow, @code{strtod} returns zero. It also sets @code{errno} to @code{ERANGE} if there was overflow or underflow. +There are two more special inputs which are recognized by @code{strtod}. +The string @code{"inf"} or @code{"infinity"} (without consideration of +case and optionally preceded by a @code{"+"} or @code{"-"} sign) is +changed to the floating-point value for infinity if the floating-point +format supports this; and to the largest representable value otherwise. + +If the input string is @code{"nan"} or +@code{"nan(@var{n-char-sequence})"} the return value of @code{strtod} is +the representation of the NaN (not a number) value (if the +flaoting-point formats supports this. The form with the +@var{n-char-sequence} enables in an implementation specific way to +specify the form of the NaN value. When using the @w{IEEE 754} +floating-point format, the NaN value can have a lot of forms since only +at least one bit in the mantissa must be set. In the GNU C library +implementation of @code{strtod} the @var{n-char-sequence} is interpreted +as a number (as recognized by @code{strtol}, @pxref{Parsing of Integers}) +The mantissa of the return value corresponds to this given number. + Since the value zero which is returned in the error case is also a valid result the user should set the global variable @code{errno} to zero before calling this function. So one can test for failures after the @@ -707,7 +770,7 @@ precision can require additional computation. If the string has valid syntax for a floating-point number but the value is not representable because of overflow, @code{strtof} returns either -positive or negative @code{HUGE_VALf} (@pxref{Mathematics}), depending on +positive or negative @code{HUGE_VALF} (@pxref{Mathematics}), depending on the sign of the value. This function is a GNU extension. @@ -725,7 +788,7 @@ of precision are required. If the string has valid syntax for a floating-point number but the value is not representable because of overflow, @code{strtold} returns either -positive or negative @code{HUGE_VALl} (@pxref{Mathematics}), depending on +positive or negative @code{HUGE_VALL} (@pxref{Mathematics}), depending on the sign of the value. This function is a GNU extension. diff --git a/manual/lang.texi b/manual/lang.texi index 39bba83540..7520da2fbe 100644 --- a/manual/lang.texi +++ b/manual/lang.texi @@ -462,6 +462,44 @@ use it except for reasons of portability. @refill @end deftypefn +Sometimes it is necessary to parse the list of parameters more than once +or one wants to remember a certain position in the parameter list. To +do this one will have to make a copy of the current value of the +argument. But @code{va_list} is an opaque type and it is not guaranteed +that one can simply assign the value of a variable to another one of +type @code{va_list} + +@comment stdarg.h +@comment GNU +@deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src}) +The @code{__va_copy} macro allows copying of objects of type +@code{va_list} even if this is no integral type. The argument pointer +in @var{dest} is initialized to point to the same argument as the +pointer in @var{src}. + +This macro is a GNU extension but it will hopefully also be available in +the next update of the ISO C standard. +@end deftypefn + +If you want to use @code{__va_copy} you should always be prepared that +this macro is not available. On architectures where a simple assignment +is invalid it hopefully is and so one should always write something like +this: + +@smallexample +@{ + va_list ap, save; + @dots{} +#ifdef __va_copy + __va_copy (save, ap); +#else + save = ap; +#endif + @dots{} +@} +@end smallexample + + @node Variadic Example @subsection Example of a Variadic Function diff --git a/manual/socket.texi b/manual/socket.texi index cb7b5ddc94..c122106e2b 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -826,6 +826,10 @@ string in the standard numbers-and-dots notation. The return value is a pointer into a statically-allocated buffer. Subsequent calls will overwrite the same buffer, so you should copy the string if you need to save it. + +In multi-threaded programs each thread has an own statically-allocated +buffer. But still subsequent calls of @code{inet_ntoa} in the same +thread will overwrite the result of the last call. @end deftypefun @comment arpa/inet.h diff --git a/manual/stdio.texi b/manual/stdio.texi index 103be34abb..dd8555478a 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -1479,11 +1479,11 @@ the @var{size} argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least @var{size} characters for the string @var{s}. -The return value is the number of characters which are generated for the -given input. If this value is greater than @var{size}, not all -characters from the result have been stored in @var{s}. You should -try again with a bigger output string. Here is an example of doing -this: +The return value is the number of characters which would be generated +for the given input. If this value is greater or equal to @var{size}, +not all characters from the result have been stored in @var{s}. You +should try again with a bigger output string. Here is an example of +doing this: @smallexample @group @@ -1503,7 +1503,7 @@ make_message (char *name, char *value) name, value); @end group @group - if (nchars) >= size) + if (nchars >= size) @{ /* @r{Reallocate buffer now that we know how much space is needed.} */ buffer = (char *) xrealloc (buffer, nchars + 1); |