diff options
author | Martin Liska <mliska@suse.cz> | 2022-11-13 21:59:29 +0100 |
---|---|---|
committer | Martin Liska <mliska@suse.cz> | 2022-11-14 09:35:06 +0100 |
commit | d77de738290156fafe079182888e5e03a2f835f1 (patch) | |
tree | 0fa1501804778de28e5323a1ecc0d39073b4045c /libiberty | |
parent | 40a39381063fdd83c4cbf5eacebfc50a2201308b (diff) | |
download | gcc-d77de738290156fafe079182888e5e03a2f835f1.zip gcc-d77de738290156fafe079182888e5e03a2f835f1.tar.gz gcc-d77de738290156fafe079182888e5e03a2f835f1.tar.bz2 |
Revert "sphinx: remove texinfo files"
This reverts commit 54ca4eef58661a7d7a511e2bbbe309bde1732abf.
Diffstat (limited to 'libiberty')
-rw-r--r-- | libiberty/at-file.texi | 15 | ||||
-rw-r--r-- | libiberty/copying-lib.texi | 560 | ||||
-rw-r--r-- | libiberty/functions.texi | 2063 | ||||
-rw-r--r-- | libiberty/libiberty.texi | 313 | ||||
-rw-r--r-- | libiberty/obstacks.texi | 774 |
5 files changed, 3725 insertions, 0 deletions
diff --git a/libiberty/at-file.texi b/libiberty/at-file.texi new file mode 100644 index 0000000..080d195 --- /dev/null +++ b/libiberty/at-file.texi @@ -0,0 +1,15 @@ +@c This file is designed to be included in manuals that use +@c expandargv. + +@item @@@var{file} +Read command-line options from @var{file}. The options read are +inserted in place of the original @@@var{file} option. If @var{file} +does not exist, or cannot be read, then the option will be treated +literally, and not removed. + +Options in @var{file} are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The @var{file} may itself contain additional +@@@var{file} options; any such options will be processed recursively. diff --git a/libiberty/copying-lib.texi b/libiberty/copying-lib.texi new file mode 100644 index 0000000..7f32e1f --- /dev/null +++ b/libiberty/copying-lib.texi @@ -0,0 +1,560 @@ +@node Library Copying +@appendixsec GNU LESSER GENERAL PUBLIC LICENSE + +@cindex LGPL, Lesser General Public License +@center Version 2.1, February 1999 + +@display +Copyright @copyright{} 1991-2022 Free Software Foundation, Inc. +51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, 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 Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] +@end display + +@appendixsubsec 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 Lesser General Public License, applies to some +specially designated software---typically libraries---of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +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 and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +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 other code 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. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the @dfn{Lesser} General Public License because it +does @emph{Less} to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + 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, whereas the latter must +be combined with the library in order to run. + +@iftex +@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center GNU LESSER GENERAL PUBLIC LICENSE +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser 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 combine 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 +Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user's computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + +@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 materials to be 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 with +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 Lesser 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. + +@center NO WARRANTY + +@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 +@appendixsubsec 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 an 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 Lesser General Public License as published by +the Free Software Foundation; either version 2.1 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 +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +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: + +@smallexample +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 smallexample + +That's all there is to it! diff --git a/libiberty/functions.texi b/libiberty/functions.texi new file mode 100644 index 0000000..b56b02e --- /dev/null +++ b/libiberty/functions.texi @@ -0,0 +1,2063 @@ +@c Automatically generated from *.c and others (the comments before +@c each entry tell you which file and where in that file). DO NOT EDIT! +@c Edit the *.c files, configure with --enable-maintainer-mode, +@c run 'make stamp-functions' and gather-docs will build a new copy. + +@c alloca.c:26 +@deftypefn Replacement void* alloca (size_t @var{size}) + +This function allocates memory which will be automatically reclaimed +after the procedure exits. The @libib{} implementation does not free +the memory immediately but will do so eventually during subsequent +calls to this function. Memory is allocated using @code{xmalloc} under +normal circumstances. + +The header file @file{alloca-conf.h} can be used in conjunction with the +GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make +available this function. The @code{AC_FUNC_ALLOCA} test requires that +client code use a block of preprocessor code to be safe (see the Autoconf +manual for more); this header incorporates that logic and more, including +the possibility of a GCC built-in function. + +@end deftypefn + +@c asprintf.c:32 +@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) + +Like @code{sprintf}, but instead of passing a pointer to a buffer, you +pass a pointer to a pointer. This function will compute the size of +the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{sprintf} would return. If memory could +not be allocated, minus one is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + +@c atexit.c:6 +@deftypefn Supplemental int atexit (void (*@var{f})()) + +Causes function @var{f} to be called at exit. Returns 0. + +@end deftypefn + +@c basename.c:6 +@deftypefn Supplemental char* basename (const char *@var{name}) + +Returns a pointer to the last component of pathname @var{name}. +Behavior is undefined if the pathname ends in a directory separator. + +@end deftypefn + +@c bcmp.c:6 +@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) + +Compares the first @var{count} bytes of two areas of memory. Returns +zero if they are the same, nonzero otherwise. Returns zero if +@var{count} is zero. A nonzero result only indicates a difference, +it does not indicate any sorting order (say, by having a positive +result mean @var{x} sorts before @var{y}). + +@end deftypefn + +@c bcopy.c:3 +@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. The use of @code{bcopy} is deprecated in new programs. + +@end deftypefn + +@c bsearch.c:33 +@deftypefn Supplemental void* bsearch (const void *@var{key}, @ + const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ + int (*@var{compar})(const void *, const void *)) + +Performs a search over an array of @var{nmemb} elements pointed to by +@var{base} for a member that matches the object pointed to by @var{key}. +The size of each member is specified by @var{size}. The array contents +should be sorted in ascending order according to the @var{compar} +comparison function. This routine should take two arguments pointing to +the @var{key} and to an array member, in that order, and should return an +integer less than, equal to, or greater than zero if the @var{key} object +is respectively less than, matching, or greater than the array member. + +@end deftypefn + +@c bsearch_r.c:33 +@deftypefn Supplemental void* bsearch_r (const void *@var{key}, @ + const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ + int (*@var{compar})(const void *, const void *, void *), void *@var{arg}) + +Performs a search over an array of @var{nmemb} elements pointed to by +@var{base} for a member that matches the object pointed to by @var{key}. +The size of each member is specified by @var{size}. The array contents +should be sorted in ascending order according to the @var{compar} +comparison function. This routine should take three arguments: the first +two point to the @var{key} and to an array member, and the last is passed +down unchanged from @code{bsearch_r}'s last argument. It should return an +integer less than, equal to, or greater than zero if the @var{key} object +is respectively less than, matching, or greater than the array member. + +@end deftypefn + +@c argv.c:138 +@deftypefn Extension char** buildargv (char *@var{sp}) + +Given a pointer to a string, parse the string extracting fields +separated by whitespace and optionally enclosed within either single +or double quotes (which are stripped off), and build a vector of +pointers to copies of the string for each field. The input string +remains unchanged. The last element of the vector is followed by a +@code{NULL} element. + +All of the memory for the pointer array and copies of the string +is obtained from @code{xmalloc}. All of the memory can be returned to the +system with the single function call @code{freeargv}, which takes the +returned result of @code{buildargv}, as it's argument. + +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient +memory to complete building the argument vector. + +If the input is a null string (as opposed to a @code{NULL} pointer), +then buildarg returns an argument vector that has one arg, a null +string. + +@end deftypefn + +@c bzero.c:6 +@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) + +Zeros @var{count} bytes starting at @var{mem}. Use of this function +is deprecated in favor of @code{memset}. + +@end deftypefn + +@c calloc.c:6 +@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) + +Uses @code{malloc} to allocate storage for @var{nelem} objects of +@var{elsize} bytes each, then zeros the memory. + +@end deftypefn + +@c filename_cmp.c:201 +@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b}) + +Return non-zero if file names @var{a} and @var{b} are equivalent. +This function compares the canonical versions of the filenames as returned by +@code{lrealpath()}, so that so that different file names pointing to the same +underlying file are treated as being identical. + +@end deftypefn + +@c choose-temp.c:45 +@deftypefn Extension char* choose_temp_base (void) + +Return a prefix for temporary file names or @code{NULL} if unable to +find one. The current directory is chosen if all else fails so the +program is exited if a temporary directory can't be found (@code{mktemp} +fails). The buffer for the result is obtained with @code{xmalloc}. + +This function is provided for backwards compatibility only. Its use is +not recommended. + +@end deftypefn + +@c make-temp-file.c:95 +@deftypefn Replacement const char* choose_tmpdir () + +Returns a pointer to a directory path suitable for creating temporary +files in. + +@end deftypefn + +@c clock.c:27 +@deftypefn Supplemental long clock (void) + +Returns an approximation of the CPU time used by the process as a +@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the +number of seconds used. + +@end deftypefn + +@c concat.c:24 +@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ + @dots{}, @code{NULL}) + +Concatenate zero or more of strings and return the result in freshly +@code{xmalloc}ed memory. The argument list is terminated by the first +@code{NULL} pointer encountered. Pointers to empty strings are ignored. + +@end deftypefn + +@c argv.c:495 +@deftypefn Extension int countargv (char * const *@var{argv}) + +Return the number of elements in @var{argv}. +Returns zero if @var{argv} is NULL. + +@end deftypefn + +@c crc32.c:140 +@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ + int @var{len}, unsigned int @var{init}) + +Compute the 32-bit CRC of @var{buf} which has length @var{len}. The +starting value is @var{init}; this may be used to compute the CRC of +data split across multiple buffers by passing the return value of each +call as the @var{init} parameter of the next. + +This is used by the @command{gdb} remote protocol for the @samp{qCRC} +command. In order to get the same results as gdb for a block of data, +you must pass the first CRC parameter as @code{0xffffffff}. + +This CRC can be specified as: + + Width : 32 + Poly : 0x04c11db7 + Init : parameter, typically 0xffffffff + RefIn : false + RefOut : false + XorOut : 0 + +This differs from the "standard" CRC-32 algorithm in that the values +are not reflected, and there is no final XOR value. These differences +make it easy to compose the values of multiple blocks. + +@end deftypefn + +@c argv.c:59 +@deftypefn Extension char** dupargv (char * const *@var{vector}) + +Duplicate an argument vector. Simply scans through @var{vector}, +duplicating each argument until the terminating @code{NULL} is found. +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if there is insufficient memory to complete building the +argument vector. + +@end deftypefn + +@c strerror.c:572 +@deftypefn Extension int errno_max (void) + +Returns the maximum @code{errno} value for which a corresponding +symbolic name or message is available. Note that in the case where we +use the @code{sys_errlist} supplied by the system, it is possible for +there to be more symbolic names than messages, or vice versa. In +fact, the manual page for @code{perror(3C)} explicitly warns that one +should check the size of the table (@code{sys_nerr}) before indexing +it, since new error codes may be added to the system before they are +added to the table. Thus @code{sys_nerr} might be smaller than value +implied by the largest @code{errno} value defined in @code{<errno.h>}. + +We return the maximum value that can be used to obtain a meaningful +symbolic name or message. + +@end deftypefn + +@c argv.c:352 +@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) + +The @var{argcp} and @code{argvp} arguments are pointers to the usual +@code{argc} and @code{argv} arguments to @code{main}. This function +looks for arguments that begin with the character @samp{@@}. Any such +arguments are interpreted as ``response files''. The contents of the +response file are interpreted as additional command line options. In +particular, the file is separated into whitespace-separated strings; +each such string is taken as a command-line option. The new options +are inserted in place of the option naming the response file, and +@code{*argcp} and @code{*argvp} will be updated. If the value of +@code{*argvp} is modified by this function, then the new value has +been dynamically allocated and can be deallocated by the caller with +@code{freeargv}. However, most callers will simply call +@code{expandargv} near the beginning of @code{main} and allow the +operating system to free the memory when the program exits. + +@end deftypefn + +@c fdmatch.c:23 +@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) + +Check to see if two open file descriptors refer to the same file. +This is useful, for example, when we have an open file descriptor for +an unnamed file, and the name of a file that we believe to correspond +to that fd. This can happen when we are exec'd with an already open +file (@code{stdout} for example) or from the SVR4 @file{/proc} calls +that return open file descriptors for mapped address spaces. All we +have to do is open the file by name and check the two file descriptors +for a match, which is done by comparing major and minor device numbers +and inode numbers. + +@end deftypefn + +@c fopen_unlocked.c:49 +@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ + const char * @var{mode}) + +Opens and returns a @code{FILE} pointer via @code{fdopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c ffs.c:3 +@deftypefn Supplemental int ffs (int @var{valu}) + +Find the first (least significant) bit set in @var{valu}. Bits are +numbered from right to left, starting with bit 1 (corresponding to the +value 1). If @var{valu} is zero, zero is returned. + +@end deftypefn + +@c filename_cmp.c:37 +@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent. +If not equivalent, the returned value is similar to what @code{strcmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + +@c filename_cmp.c:183 +@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) + +Return non-zero if file names @var{s1} and @var{s2} are equivalent. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:152 +@deftypefn Extension hashval_t filename_hash (const void *@var{s}) + +Return the hash value for file name @var{s} that will be compared +using filename_cmp. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:94 +@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent +in range @var{n}. +If not equivalent, the returned value is similar to what @code{strncmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + +@c fnmatch.txh:1 +@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ + const char *@var{string}, int @var{flags}) + +Matches @var{string} against @var{pattern}, returning zero if it +matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the +wildcards @code{?} to match any one character, @code{*} to match any +zero or more characters, or a set of alternate characters in square +brackets, like @samp{[a-gt8]}, which match one character (@code{a} +through @code{g}, or @code{t}, or @code{8}, in this example) if that one +character is in the set. A set may be inverted (i.e., match anything +except what's in the set) by giving @code{^} or @code{!} as the first +character in the set. To include those characters in the set, list them +as anything other than the first character of the set. To include a +dash in the set, list it last in the set. A backslash character makes +the following character not special, so for example you could match +against a literal asterisk with @samp{\*}. To match a literal +backslash, use @samp{\\}. + +@code{flags} controls various aspects of the matching process, and is a +boolean OR of zero or more of the following values (defined in +@code{<fnmatch.h>}): + +@table @code + +@item FNM_PATHNAME +@itemx FNM_FILE_NAME +@var{string} is assumed to be a path name. No wildcard will ever match +@code{/}. + +@item FNM_NOESCAPE +Do not interpret backslashes as quoting the following special character. + +@item FNM_PERIOD +A leading period (at the beginning of @var{string}, or if +@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or +@code{?} but must be matched explicitly. + +@item FNM_LEADING_DIR +Means that @var{string} also matches @var{pattern} if some initial part +of @var{string} matches, and is followed by @code{/} and zero or more +characters. For example, @samp{foo*} would match either @samp{foobar} +or @samp{foobar/grill}. + +@item FNM_CASEFOLD +Ignores case when performing the comparison. + +@end table + +@end deftypefn + +@c fopen_unlocked.c:39 +@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ + const char * @var{mode}) + +Opens and returns a @code{FILE} pointer via @code{fopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c argv.c:93 +@deftypefn Extension void freeargv (char **@var{vector}) + +Free an argument vector that was built using @code{buildargv}. Simply +scans through @var{vector}, freeing the memory for each argument until +the terminating @code{NULL} is found, and then frees @var{vector} +itself. + +@end deftypefn + +@c fopen_unlocked.c:59 +@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ + const char * @var{mode}, FILE * @var{stream}) + +Opens and returns a @code{FILE} pointer via @code{freopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c getruntime.c:86 +@deftypefn Replacement long get_run_time (void) + +Returns the time used so far, in microseconds. If possible, this is +the time used by this process, else it is the elapsed time since the +process started. + +@end deftypefn + +@c getcwd.c:6 +@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) + +Copy the absolute pathname for the current working directory into +@var{pathname}, which is assumed to point to a buffer of at least +@var{len} bytes, and return a pointer to the buffer. If the current +directory's path doesn't fit in @var{len} characters, the result is +@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, +@code{getcwd} will obtain @var{len} bytes of space using +@code{malloc}. + +@end deftypefn + +@c getpagesize.c:5 +@deftypefn Supplemental int getpagesize (void) + +Returns the number of bytes in a page of memory. This is the +granularity of many of the system memory management routines. No +guarantee is made as to whether or not it is the same as the basic +memory management hardware page size. + +@end deftypefn + +@c getpwd.c:5 +@deftypefn Supplemental char* getpwd (void) + +Returns the current working directory. This implementation caches the +result on the assumption that the process will not call @code{chdir} +between calls to @code{getpwd}. + +@end deftypefn + +@c gettimeofday.c:12 +@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) + +Writes the current time to @var{tp}. This implementation requires +that @var{tz} be NULL. Returns 0 on success, -1 on failure. + +@end deftypefn + +@c hex.c:33 +@deftypefn Extension void hex_init (void) + +Initializes the array mapping the current character set to +corresponding hex values. This function must be called before any +call to @code{hex_p} or @code{hex_value}. If you fail to call it, a +default ASCII-based table will normally be used on ASCII systems. + +@end deftypefn + +@c hex.c:42 +@deftypefn Extension int hex_p (int @var{c}) + +Evaluates to non-zero if the given character is a valid hex character, +or zero if it is not. Note that the value you pass will be cast to +@code{unsigned char} within the macro. + +@end deftypefn + +@c hex.c:50 +@deftypefn Extension {unsigned int} hex_value (int @var{c}) + +Returns the numeric equivalent of the given character when interpreted +as a hexadecimal digit. The result is undefined if you pass an +invalid hex digit. Note that the value you pass will be cast to +@code{unsigned char} within the macro. + +The @code{hex_value} macro returns @code{unsigned int}, rather than +signed @code{int}, to make it easier to use in parsing addresses from +hex dump files: a signed @code{int} would be sign-extended when +converted to a wider unsigned type --- like @code{bfd_vma}, on some +systems. + +@end deftypefn + +@c safe-ctype.c:24 +@defvr Extension HOST_CHARSET +This macro indicates the basic character set and encoding used by the +host: more precisely, the encoding used for character constants in +preprocessor @samp{#if} statements (the C "execution character set"). +It is defined by @file{safe-ctype.h}, and will be an integer constant +with one of the following values: + +@ftable @code +@item HOST_CHARSET_UNKNOWN +The host character set is unknown - that is, not one of the next two +possibilities. + +@item HOST_CHARSET_ASCII +The host character set is ASCII. + +@item HOST_CHARSET_EBCDIC +The host character set is some variant of EBCDIC. (Only one of the +nineteen EBCDIC varying characters is tested; exercise caution.) +@end ftable +@end defvr + +@c hashtab.c:327 +@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ +htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ +htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ +htab_free @var{free_f}) + +This function creates a hash table that uses two different allocators +@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself +and its entries respectively. This is useful when variables of different +types need to be allocated with different allocators. + +The created hash table is slightly larger than @var{size} and it is +initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). +The function returns the created hash table, or @code{NULL} if memory +allocation fails. + +@end deftypefn + +@c index.c:5 +@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) + +Returns a pointer to the first occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. The use of @code{index} is +deprecated in new programs in favor of @code{strchr}. + +@end deftypefn + +@c insque.c:6 +@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ + struct qelem *@var{pred}) +@deftypefnx Supplemental void remque (struct qelem *@var{elem}) + +Routines to manipulate queues built from doubly linked lists. The +@code{insque} routine inserts @var{elem} in the queue immediately +after @var{pred}. The @code{remque} routine removes @var{elem} from +its containing queue. These routines expect to be passed pointers to +structures which have as their first members a forward pointer and a +back pointer, like this prototype (although no prototype is provided): + +@example +struct qelem @{ + struct qelem *q_forw; + struct qelem *q_back; + char q_data[]; +@}; +@end example + +@end deftypefn + +@c safe-ctype.c:45 +@deffn Extension ISALPHA (@var{c}) +@deffnx Extension ISALNUM (@var{c}) +@deffnx Extension ISBLANK (@var{c}) +@deffnx Extension ISCNTRL (@var{c}) +@deffnx Extension ISDIGIT (@var{c}) +@deffnx Extension ISGRAPH (@var{c}) +@deffnx Extension ISLOWER (@var{c}) +@deffnx Extension ISPRINT (@var{c}) +@deffnx Extension ISPUNCT (@var{c}) +@deffnx Extension ISSPACE (@var{c}) +@deffnx Extension ISUPPER (@var{c}) +@deffnx Extension ISXDIGIT (@var{c}) + +These twelve macros are defined by @file{safe-ctype.h}. Each has the +same meaning as the corresponding macro (with name in lowercase) +defined by the standard header @file{ctype.h}. For example, +@code{ISALPHA} returns true for alphabetic characters and false for +others. However, there are two differences between these macros and +those provided by @file{ctype.h}: + +@itemize @bullet +@item These macros are guaranteed to have well-defined behavior for all +values representable by @code{signed char} and @code{unsigned char}, and +for @code{EOF}. + +@item These macros ignore the current locale; they are true for these +fixed sets of characters: +@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} +@item @code{ALPHA} @tab @kbd{A-Za-z} +@item @code{ALNUM} @tab @kbd{A-Za-z0-9} +@item @code{BLANK} @tab @kbd{space tab} +@item @code{CNTRL} @tab @code{!PRINT} +@item @code{DIGIT} @tab @kbd{0-9} +@item @code{GRAPH} @tab @code{ALNUM || PUNCT} +@item @code{LOWER} @tab @kbd{a-z} +@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} +@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} +@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} +@item @code{UPPER} @tab @kbd{A-Z} +@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} +@end multitable + +Note that, if the host character set is ASCII or a superset thereof, +all these macros will return false for all values of @code{char} outside +the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return +false for characters with numeric values from 128 to 255. +@end itemize +@end deffn + +@c safe-ctype.c:94 +@deffn Extension ISIDNUM (@var{c}) +@deffnx Extension ISIDST (@var{c}) +@deffnx Extension IS_VSPACE (@var{c}) +@deffnx Extension IS_NVSPACE (@var{c}) +@deffnx Extension IS_SPACE_OR_NUL (@var{c}) +@deffnx Extension IS_ISOBASIC (@var{c}) +These six macros are defined by @file{safe-ctype.h} and provide +additional character classes which are useful when doing lexical +analysis of C or similar languages. They are true for the following +sets of characters: + +@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} +@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} +@item @code{IDST} @tab @kbd{A-Za-z_} +@item @code{VSPACE} @tab @kbd{\r \n} +@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} +@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} +@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} +@end multitable +@end deffn + +@c lbasename.c:23 +@deftypefn Replacement {const char*} lbasename (const char *@var{name}) + +Given a pointer to a string containing a typical pathname +(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the +last component of the pathname (@samp{ls.c} in this case). The +returned pointer is guaranteed to lie within the original +string. This latter fact is not true of many vendor C +libraries, which return special strings or modify the passed +strings for particular input. + +In particular, the empty string returns the same empty string, +and a path ending in @code{/} returns the empty string after it. + +@end deftypefn + +@c lrealpath.c:25 +@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) + +Given a pointer to a string containing a pathname, returns a canonical +version of the filename. Symlinks will be resolved, and ``.'' and ``..'' +components will be simplified. The returned value will be allocated using +@code{malloc}, or @code{NULL} will be returned on a memory allocation error. + +@end deftypefn + +@c make-relative-prefix.c:23 +@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ + const char *@var{bin_prefix}, const char *@var{prefix}) + +Given three paths @var{progname}, @var{bin_prefix}, @var{prefix}, +return the path that is in the same position relative to +@var{progname}'s directory as @var{prefix} is relative to +@var{bin_prefix}. That is, a string starting with the directory +portion of @var{progname}, followed by a relative pathname of the +difference between @var{bin_prefix} and @var{prefix}. + +If @var{progname} does not contain any directory separators, +@code{make_relative_prefix} will search @env{PATH} to find a program +named @var{progname}. Also, if @var{progname} is a symbolic link, +the symbolic link will be resolved. + +For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, +@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is +@code{/red/green/blue/gcc}, then this function will return +@code{/red/green/blue/../../omega/}. + +The return value is normally allocated via @code{malloc}. If no +relative prefix can be found, return @code{NULL}. + +@end deftypefn + +@c make-temp-file.c:173 +@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) + +Return a temporary file name (as a string) or @code{NULL} if unable to +create one. @var{suffix} is a suffix to append to the file name. The +string is @code{malloc}ed, and the temporary file has been created. + +@end deftypefn + +@c memchr.c:3 +@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ + size_t @var{n}) + +This function searches memory starting at @code{*@var{s}} for the +character @var{c}. The search only ends with the first occurrence of +@var{c}, or after @var{length} characters; in particular, a null +character does not terminate the search. If the character @var{c} is +found within @var{length} characters of @code{*@var{s}}, a pointer +to the character is returned. If @var{c} is not found, then @code{NULL} is +returned. + +@end deftypefn + +@c memcmp.c:6 +@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ + size_t @var{count}) + +Compares the first @var{count} bytes of two areas of memory. Returns +zero if they are the same, a value less than zero if @var{x} is +lexically less than @var{y}, or a value greater than zero if @var{x} +is lexically greater than @var{y}. Note that lexical order is determined +as if comparing unsigned char arrays. + +@end deftypefn + +@c memcpy.c:6 +@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. Returns a pointer to @var{out}. + +@end deftypefn + +@c memmem.c:20 +@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ + size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) + +Returns a pointer to the first occurrence of @var{needle} (length +@var{needle_len}) in @var{haystack} (length @var{haystack_len}). +Returns @code{NULL} if not found. + +@end deftypefn + +@c memmove.c:6 +@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ + size_t @var{count}) + +Copies @var{count} bytes from memory area @var{from} to memory area +@var{to}, returning a pointer to @var{to}. + +@end deftypefn + +@c mempcpy.c:23 +@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. Returns a pointer to @var{out} + @var{length}. + +@end deftypefn + +@c memset.c:6 +@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ + size_t @var{count}) + +Sets the first @var{count} bytes of @var{s} to the constant byte +@var{c}, returning a pointer to @var{s}. + +@end deftypefn + +@c mkstemps.c:60 +@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) + +Generate a unique temporary file name from @var{pattern}. +@var{pattern} has the form: + +@example + @var{path}/ccXXXXXX@var{suffix} +@end example + +@var{suffix_len} tells us how long @var{suffix} is (it can be zero +length). The last six characters of @var{pattern} before @var{suffix} +must be @samp{XXXXXX}; they are replaced with a string that makes the +filename unique. Returns a file descriptor open on the file for +reading and writing. + +@end deftypefn + +@c pexecute.txh:278 +@deftypefn Extension void pex_free (struct pex_obj @var{obj}) + +Clean up and free all data associated with @var{obj}. If you have not +yet called @code{pex_get_times} or @code{pex_get_status}, this will +try to kill the subprocesses. + +@end deftypefn + +@c pexecute.txh:251 +@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ + int @var{count}, int *@var{vector}) + +Returns the exit status of all programs run using @var{obj}. +@var{count} is the number of results expected. The results will be +placed into @var{vector}. The results are in the order of the calls +to @code{pex_run}. Returns 0 on error, 1 on success. + +@end deftypefn + +@c pexecute.txh:261 +@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ + int @var{count}, struct pex_time *@var{vector}) + +Returns the process execution times of all programs run using +@var{obj}. @var{count} is the number of results expected. The +results will be placed into @var{vector}. The results are in the +order of the calls to @code{pex_run}. Returns 0 on error, 1 on +success. + +@code{struct pex_time} has the following fields of the type +@code{unsigned long}: @code{user_seconds}, +@code{user_microseconds}, @code{system_seconds}, +@code{system_microseconds}. On systems which do not support reporting +process times, all the fields will be set to @code{0}. + +@end deftypefn + +@c pexecute.txh:2 +@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ + const char *@var{pname}, const char *@var{tempbase}) + +Prepare to execute one or more programs, with standard output of each +program fed to standard input of the next. This is a system +independent interface to execute a pipeline. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_RECORD_TIMES +@item PEX_RECORD_TIMES +Record subprocess times if possible. + +@vindex PEX_USE_PIPES +@item PEX_USE_PIPES +Use pipes for communication between processes, if possible. + +@vindex PEX_SAVE_TEMPS +@item PEX_SAVE_TEMPS +Don't delete temporary files used for communication between +processes. + +@end table + +@var{pname} is the name of program to be executed, used in error +messages. @var{tempbase} is a base name to use for any required +temporary files; it may be @code{NULL} to use a randomly chosen name. + +@end deftypefn + +@c pexecute.txh:161 +@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{in_name}) + +Return a stream for a temporary file to pass to the first program in +the pipeline as input. + +The name of the input file is chosen according to the same rules +@code{pex_run} uses to choose output file names, based on +@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. + +Don't call @code{fclose} on the returned stream; the first call to +@code{pex_run} closes it automatically. + +If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in +binary mode; otherwise, open it in the default mode. Including +@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. +@end deftypefn + +@c pexecute.txh:179 +@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Return a stream @var{fp} for a pipe connected to the standard input of +the first program in the pipeline; @var{fp} is opened for writing. +You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call +that returned @var{obj}. + +You must close @var{fp} using @code{fclose} yourself when you have +finished writing data to the pipeline. + +The file descriptor underlying @var{fp} is marked not to be inherited +by child processes. + +On systems that do not support pipes, this function returns +@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would +like to write code that is portable to all systems the @code{pex} +functions support, consider using @code{pex_input_file} instead. + +There are two opportunities for deadlock using +@code{pex_input_pipe}: + +@itemize @bullet +@item +Most systems' pipes can buffer only a fixed amount of data; a process +that writes to a full pipe blocks. Thus, if you write to @file{fp} +before starting the first process, you run the risk of blocking when +there is no child process yet to read the data and allow you to +continue. @code{pex_input_pipe} makes no promises about the +size of the pipe's buffer, so if you need to write any data at all +before starting the first process in the pipeline, consider using +@code{pex_input_file} instead. + +@item +Using @code{pex_input_pipe} and @code{pex_read_output} together +may also cause deadlock. If the output pipe fills up, so that each +program in the pipeline is waiting for the next to read more data, and +you fill the input pipe by writing more data to @var{fp}, then there +is no way to make progress: the only process that could read data from +the output pipe is you, but you are blocked on the input pipe. + +@end itemize + +@end deftypefn + +@c pexecute.txh:286 +@deftypefn Extension {const char *} pex_one (int @var{flags}, @ + const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ + int *@var{status}, int *@var{err}) + +An interface to permit the easy execution of a +single program. The return value and most of the parameters are as +for a call to @code{pex_run}. @var{flags} is restricted to a +combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and +@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if +@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will +be set to the exit status of the program. + +@end deftypefn + +@c pexecute.txh:237 +@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Returns a @code{FILE} pointer which may be used to read the standard +error of the last program in the pipeline. When this is used, +@code{PEX_LAST} should not be used in a call to @code{pex_run}. After +this is called, @code{pex_run} may no longer be called with the same +@var{obj}. @var{binary} should be non-zero if the file should be +opened in binary mode. Don't call @code{fclose} on the returned file; +it will be closed by @code{pex_free}. + +@end deftypefn + +@c pexecute.txh:224 +@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Returns a @code{FILE} pointer which may be used to read the standard +output of the last program in the pipeline. When this is used, +@code{PEX_LAST} should not be used in a call to @code{pex_run}. After +this is called, @code{pex_run} may no longer be called with the same +@var{obj}. @var{binary} should be non-zero if the file should be +opened in binary mode. Don't call @code{fclose} on the returned file; +it will be closed by @code{pex_free}. + +@end deftypefn + +@c pexecute.txh:34 +@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{outname}, const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline. On success this returns +@code{NULL}. On failure it returns an error message, a statically +allocated string. + +@var{obj} is returned by a previous call to @code{pex_init}. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_LAST +@item PEX_LAST +This must be set on the last program in the pipeline. In particular, +it should be set when executing a single program. The standard output +of the program will be sent to @var{outname}, or, if @var{outname} is +@code{NULL}, to the standard output of the calling program. Do @emph{not} +set this bit if you want to call @code{pex_read_output} +(described below). After a call to @code{pex_run} with this bit set, +@var{pex_run} may no longer be called with the same @var{obj}. + +@vindex PEX_SEARCH +@item PEX_SEARCH +Search for the program using the user's executable search path. + +@vindex PEX_SUFFIX +@item PEX_SUFFIX +@var{outname} is a suffix. See the description of @var{outname}, +below. + +@vindex PEX_STDERR_TO_STDOUT +@item PEX_STDERR_TO_STDOUT +Send the program's standard error to standard output, if possible. + +@vindex PEX_BINARY_INPUT +@vindex PEX_BINARY_OUTPUT +@vindex PEX_BINARY_ERROR +@item PEX_BINARY_INPUT +@itemx PEX_BINARY_OUTPUT +@itemx PEX_BINARY_ERROR +The standard input (output or error) of the program should be read (written) in +binary mode rather than text mode. These flags are ignored on systems +which do not distinguish binary mode and text mode, such as Unix. For +proper behavior these flags should match appropriately---a call to +@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a +call using @code{PEX_BINARY_INPUT}. + +@vindex PEX_STDERR_TO_PIPE +@item PEX_STDERR_TO_PIPE +Send the program's standard error to a pipe, if possible. This flag +cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This +flag can be specified only on the last program in pipeline. + +@end table + +@var{executable} is the program to execute. @var{argv} is the set of +arguments to pass to the program; normally @code{@var{argv}[0]} will +be a copy of @var{executable}. + +@var{outname} is used to set the name of the file to use for standard +output. There are two cases in which no output file will be used: + +@enumerate +@item +if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} +was set in the call to @code{pex_init}, and the system supports pipes + +@item +if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is +@code{NULL} +@end enumerate + +@noindent +Otherwise the code will use a file to hold standard +output. If @code{PEX_LAST} is not set, this file is considered to be +a temporary file, and it will be removed when no longer needed, unless +@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. + +There are two cases to consider when setting the name of the file to +hold standard output. + +@enumerate +@item +@code{PEX_SUFFIX} is set in @var{flags}. In this case +@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter +to @code{pex_init} was not @code{NULL}, then the output file name is +the concatenation of @var{tempbase} and @var{outname}. If +@var{tempbase} was @code{NULL}, then the output file name is a random +file name ending in @var{outname}. + +@item +@code{PEX_SUFFIX} was not set in @var{flags}. In this +case, if @var{outname} is not @code{NULL}, it is used as the output +file name. If @var{outname} is @code{NULL}, and @var{tempbase} was +not NULL, the output file name is randomly chosen using +@var{tempbase}. Otherwise the output file name is chosen completely +at random. +@end enumerate + +@var{errname} is the file name to use for standard error output. If +it is @code{NULL}, standard error is the same as the caller's. +Otherwise, standard error is written to the named file. + +On an error return, the code sets @code{*@var{err}} to an @code{errno} +value, or to 0 if there is no relevant @code{errno}. + +@end deftypefn + +@c pexecute.txh:145 +@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ + const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline, permitting the environment for the +program to be specified. Behaviour and parameters not listed below are +as for @code{pex_run}. + +@var{env} is the environment for the child process, specified as an array of +character pointers. Each element of the array should point to a string of the +form @code{VAR=VALUE}, with the exception of the last element that must be +@code{NULL}. + +@end deftypefn + +@c pexecute.txh:301 +@deftypefn Extension int pexecute (const char *@var{program}, @ + char * const *@var{argv}, const char *@var{this_pname}, @ + const char *@var{temp_base}, char **@var{errmsg_fmt}, @ + char **@var{errmsg_arg}, int @var{flags}) + +This is the old interface to execute one or more programs. It is +still supported for compatibility purposes, but is no longer +documented. + +@end deftypefn + +@c strsignal.c:541 +@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) + +Print @var{message} to the standard error, followed by a colon, +followed by the description of the signal specified by @var{signo}, +followed by a newline. + +@end deftypefn + +@c putenv.c:21 +@deftypefn Supplemental int putenv (const char *@var{string}) + +Uses @code{setenv} or @code{unsetenv} to put @var{string} into +the environment or remove it. If @var{string} is of the form +@samp{name=value} the string is added; if no @samp{=} is present the +name is unset/removed. + +@end deftypefn + +@c pexecute.txh:312 +@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) + +Another part of the old execution interface. + +@end deftypefn + +@c random.c:39 +@deftypefn Supplement {long int} random (void) +@deftypefnx Supplement void srandom (unsigned int @var{seed}) +@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ + void *@var{arg_state}, unsigned long @var{n}) +@deftypefnx Supplement void* setstate (void *@var{arg_state}) + +Random number functions. @code{random} returns a random number in the +range 0 to @code{LONG_MAX}. @code{srandom} initializes the random +number generator to some starting point determined by @var{seed} +(else, the values returned by @code{random} are always the same for each +run of the program). @code{initstate} and @code{setstate} allow fine-grained +control over the state of the random number generator. + +@end deftypefn + +@c concat.c:160 +@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ + @dots{}, @code{NULL}) + +Same as @code{concat}, except that if @var{optr} is not @code{NULL} it +is freed after the string is created. This is intended to be useful +when you're extending an existing string or building up a string in a +loop: + +@example + str = reconcat (str, "pre-", str, NULL); +@end example + +@end deftypefn + +@c rename.c:6 +@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) + +Renames a file from @var{old} to @var{new}. If @var{new} already +exists, it is removed. + +@end deftypefn + +@c rindex.c:5 +@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) + +Returns a pointer to the last occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is +deprecated in new programs in favor of @code{strrchr}. + +@end deftypefn + +@c setenv.c:22 +@deftypefn Supplemental int setenv (const char *@var{name}, @ + const char *@var{value}, int @var{overwrite}) +@deftypefnx Supplemental void unsetenv (const char *@var{name}) + +@code{setenv} adds @var{name} to the environment with value +@var{value}. If the name was already present in the environment, +the new value will be stored only if @var{overwrite} is nonzero. +The companion @code{unsetenv} function removes @var{name} from the +environment. This implementation is not safe for multithreaded code. + +@end deftypefn + +@c setproctitle.c:31 +@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) + +Set the title of a process to @var{fmt}. va args not supported for now, +but defined for compatibility with BSD. + +@end deftypefn + +@c strsignal.c:348 +@deftypefn Extension int signo_max (void) + +Returns the maximum signal value for which a corresponding symbolic +name or message is available. Note that in the case where we use the +@code{sys_siglist} supplied by the system, it is possible for there to +be more symbolic names than messages, or vice versa. In fact, the +manual page for @code{psignal(3b)} explicitly warns that one should +check the size of the table (@code{NSIG}) before indexing it, since +new signal codes may be added to the system before they are added to +the table. Thus @code{NSIG} might be smaller than value implied by +the largest signo value defined in @code{<signal.h>}. + +We return the maximum value that can be used to obtain a meaningful +symbolic name or message. + +@end deftypefn + +@c sigsetmask.c:8 +@deftypefn Supplemental int sigsetmask (int @var{set}) + +Sets the signal mask to the one provided in @var{set} and returns +the old mask (which, for libiberty's implementation, will always +be the value @code{1}). + +@end deftypefn + +@c simple-object.txh:96 +@deftypefn Extension {const char *} simple_object_attributes_compare @ + (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ + int *@var{err}) + +Compare @var{attrs1} and @var{attrs2}. If they could be linked +together without error, return @code{NULL}. Otherwise, return an +error message and set @code{*@var{err}} to an errno value or @code{0} +if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:81 +@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ + (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) + +Fetch the attributes of @var{simple_object}. The attributes are +internal information such as the format of the object file, or the +architecture it was compiled for. This information will persist until +@code{simple_object_attributes_release} is called, even if +@var{simple_object} itself is released. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:49 +@deftypefn Extension {int} simple_object_find_section @ + (simple_object_read *@var{simple_object} off_t *@var{offset}, @ + off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) + +Look for the section @var{name} in @var{simple_object}. This returns +information for the first section with that name. + +If found, return 1 and set @code{*@var{offset}} to the offset in the +file of the section contents and set @code{*@var{length}} to the +length of the section contents. The value in @code{*@var{offset}} +will be relative to the offset passed to +@code{simple_object_open_read}. + +If the section is not found, and no error occurs, +@code{simple_object_find_section} returns @code{0} and set +@code{*@var{errmsg}} to @code{NULL}. + +If an error occurs, @code{simple_object_find_section} returns +@code{0}, sets @code{*@var{errmsg}} to an error message, and sets +@code{*@var{err}} to an errno value or @code{0} if there is no +relevant errno. + +@end deftypefn + +@c simple-object.txh:27 +@deftypefn Extension {const char *} simple_object_find_sections @ + (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ + const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ + void *@var{data}, int *@var{err}) + +This function calls @var{pfn} for each section in @var{simple_object}. +It calls @var{pfn} with the section name, the offset within the file +of the section contents, and the length of the section contents. The +offset within the file is relative to the offset passed to +@code{simple_object_open_read}. The @var{data} argument to this +function is passed along to @var{pfn}. + +If @var{pfn} returns @code{0}, the loop over the sections stops and +@code{simple_object_find_sections} returns. If @var{pfn} returns some +other value, the loop continues. + +On success @code{simple_object_find_sections} returns. On error it +returns an error string, and sets @code{*@var{err}} to an errno value +or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:2 +@deftypefn Extension {simple_object_read *} simple_object_open_read @ + (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Opens an object file for reading. Creates and returns an +@code{simple_object_read} pointer which may be passed to other +functions to extract data from the object file. + +@var{descriptor} holds a file descriptor which permits reading. + +@var{offset} is the offset into the file; this will be @code{0} in the +normal case, but may be a different value when reading an object file +in an archive file. + +@var{segment_name} is only used with the Mach-O file format used on +Darwin aka Mac OS X. It is required on that platform, and means to +only look at sections within the segment with that name. The +parameter is ignored on other systems. + +If an error occurs, this functions returns @code{NULL} and sets +@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to +an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:107 +@deftypefn Extension {void} simple_object_release_attributes @ + (simple_object_attributes *@var{attrs}) + +Release all resources associated with @var{attrs}. + +@end deftypefn + +@c simple-object.txh:73 +@deftypefn Extension {void} simple_object_release_read @ + (simple_object_read *@var{simple_object}) + +Release all resources associated with @var{simple_object}. This does +not close the file descriptor. + +@end deftypefn + +@c simple-object.txh:184 +@deftypefn Extension {void} simple_object_release_write @ + (simple_object_write *@var{simple_object}) + +Release all resources associated with @var{simple_object}. + +@end deftypefn + +@c simple-object.txh:114 +@deftypefn Extension {simple_object_write *} simple_object_start_write @ + (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Start creating a new object file using the object file format +described in @var{attrs}. You must fetch attribute information from +an existing object file before you can create a new one. There is +currently no support for creating an object file de novo. + +@var{segment_name} is only used with Mach-O as found on Darwin aka Mac +OS X. The parameter is required on that target. It means that all +sections are created within the named segment. It is ignored for +other object file formats. + +On error @code{simple_object_start_write} returns @code{NULL}, sets +@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} +to an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:153 +@deftypefn Extension {const char *} simple_object_write_add_data @ + (simple_object_write *@var{simple_object}, @ + simple_object_write_section *@var{section}, const void *@var{buffer}, @ + size_t @var{size}, int @var{copy}, int *@var{err}) + +Add data @var{buffer}/@var{size} to @var{section} in +@var{simple_object}. If @var{copy} is non-zero, the data will be +copied into memory if necessary. If @var{copy} is zero, @var{buffer} +must persist until @code{simple_object_write_to_file} is called. is +released. + +On success this returns @code{NULL}. On error this returns an error +message, and sets @code{*@var{err}} to an errno value or 0 if there is +no relevant erro. + +@end deftypefn + +@c simple-object.txh:134 +@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ + (simple_object_write *@var{simple_object}, const char *@var{name}, @ + unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) + +Add a section to @var{simple_object}. @var{name} is the name of the +new section. @var{align} is the required alignment expressed as the +number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit +boundary). + +The section is created as containing data, readable, not writable, not +executable, not loaded at runtime. The section is not written to the +file until @code{simple_object_write_to_file} is called. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:170 +@deftypefn Extension {const char *} simple_object_write_to_file @ + (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) + +Write the complete object file to @var{descriptor}, an open file +descriptor. This writes out all the data accumulated by calls to +@code{simple_object_write_create_section} and +@var{simple_object_write_add_data}. + +This returns @code{NULL} on success. On error this returns an error +message and sets @code{*@var{err}} to an errno value or @code{0} if +there is no relevant errno. + +@end deftypefn + +@c snprintf.c:28 +@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, ...) + +This function is similar to @code{sprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. +On error the return value is -1, otherwise it returns the number of +bytes, not including the terminating null byte, that would have been +written had @var{n} been sufficiently large, regardless of the actual +value of @var{n}. Note some pre-C99 system libraries do not implement +this correctly so users cannot generally rely on the return value if +the system version of this function is used. + +@end deftypefn + +@c spaces.c:22 +@deftypefn Extension char* spaces (int @var{count}) + +Returns a pointer to a memory region filled with the specified +number of spaces and null terminated. The returned pointer is +valid until at least the next call. + +@end deftypefn + +@c splay-tree.c:305 +@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ +(splay_tree_compare_fn @var{compare_fn}, @ +splay_tree_delete_key_fn @var{delete_key_fn}, @ +splay_tree_delete_value_fn @var{delete_value_fn}, @ +splay_tree_allocate_fn @var{tree_allocate_fn}, @ +splay_tree_allocate_fn @var{node_allocate_fn}, @ +splay_tree_deallocate_fn @var{deallocate_fn}, @ +void * @var{allocate_data}) + +This function creates a splay tree that uses two different allocators +@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the +tree itself and its nodes respectively. This is useful when variables of +different types need to be allocated with different allocators. + +The splay tree will use @var{compare_fn} to compare nodes, +@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to +deallocate values. Keys and values will be deallocated when the +tree is deleted using splay_tree_delete or when a node is removed +using splay_tree_remove. splay_tree_insert will release the previously +inserted key and value using @var{delete_key_fn} and @var{delete_value_fn} +if the inserted key is already found in the tree. + +@end deftypefn + +@c stack-limit.c:28 +@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) + +Attempt to increase stack size limit to @var{pref} bytes if possible. + +@end deftypefn + +@c stpcpy.c:23 +@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) + +Copies the string @var{src} into @var{dst}. Returns a pointer to +@var{dst} + strlen(@var{src}). + +@end deftypefn + +@c stpncpy.c:23 +@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ + size_t @var{len}) + +Copies the string @var{src} into @var{dst}, copying exactly @var{len} +and padding with zeros if necessary. If @var{len} < strlen(@var{src}) +then return @var{dst} + @var{len}, otherwise returns @var{dst} + +strlen(@var{src}). + +@end deftypefn + +@c strcasecmp.c:15 +@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) + +A case-insensitive @code{strcmp}. + +@end deftypefn + +@c strchr.c:6 +@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) + +Returns a pointer to the first occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the +null character, the results are undefined. + +@end deftypefn + +@c strdup.c:3 +@deftypefn Supplemental char* strdup (const char *@var{s}) + +Returns a pointer to a copy of @var{s} in memory obtained from +@code{malloc}, or @code{NULL} if insufficient memory was available. + +@end deftypefn + +@c strerror.c:675 +@deftypefn Replacement {const char*} strerrno (int @var{errnum}) + +Given an error number returned from a system call (typically returned +in @code{errno}), returns a pointer to a string containing the +symbolic name of that error number, as found in @code{<errno.h>}. + +If the supplied error number is within the valid range of indices for +symbolic names, but no name is available for the particular error +number, then returns the string @samp{Error @var{num}}, where @var{num} +is the error number. + +If the supplied error number is not within the range of valid +indices, then returns @code{NULL}. + +The contents of the location pointed to are only guaranteed to be +valid until the next call to @code{strerrno}. + +@end deftypefn + +@c strerror.c:608 +@deftypefn Supplemental char* strerror (int @var{errnoval}) + +Maps an @code{errno} number to an error message string, the contents +of which are implementation defined. On systems which have the +external variables @code{sys_nerr} and @code{sys_errlist}, these +strings will be the same as the ones used by @code{perror}. + +If the supplied error number is within the valid range of indices for +the @code{sys_errlist}, but no message is available for the particular +error number, then returns the string @samp{Error @var{num}}, where +@var{num} is the error number. + +If the supplied error number is not a valid index into +@code{sys_errlist}, returns @code{NULL}. + +The returned string is only guaranteed to be valid only until the +next call to @code{strerror}. + +@end deftypefn + +@c strncasecmp.c:15 +@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) + +A case-insensitive @code{strncmp}. + +@end deftypefn + +@c strncmp.c:6 +@deftypefn Supplemental int strncmp (const char *@var{s1}, @ + const char *@var{s2}, size_t @var{n}) + +Compares the first @var{n} bytes of two strings, returning a value as +@code{strcmp}. + +@end deftypefn + +@c strndup.c:23 +@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) + +Returns a pointer to a copy of @var{s} with at most @var{n} characters +in memory obtained from @code{malloc}, or @code{NULL} if insufficient +memory was available. The result is always NUL terminated. + +@end deftypefn + +@c strnlen.c:6 +@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) + +Returns the length of @var{s}, as with @code{strlen}, but never looks +past the first @var{maxlen} characters in the string. If there is no +'\0' character in the first @var{maxlen} characters, returns +@var{maxlen}. + +@end deftypefn + +@c strrchr.c:6 +@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) + +Returns a pointer to the last occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the +null character, the results are undefined. + +@end deftypefn + +@c strsignal.c:383 +@deftypefn Supplemental {const char *} strsignal (int @var{signo}) + +Maps an signal number to an signal message string, the contents of +which are implementation defined. On systems which have the external +variable @code{sys_siglist}, these strings will be the same as the +ones used by @code{psignal()}. + +If the supplied signal number is within the valid range of indices for +the @code{sys_siglist}, but no message is available for the particular +signal number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not a valid index into +@code{sys_siglist}, returns @code{NULL}. + +The returned string is only guaranteed to be valid only until the next +call to @code{strsignal}. + +@end deftypefn + +@c strsignal.c:448 +@deftypefn Extension {const char*} strsigno (int @var{signo}) + +Given an signal number, returns a pointer to a string containing the +symbolic name of that signal number, as found in @code{<signal.h>}. + +If the supplied signal number is within the valid range of indices for +symbolic names, but no name is available for the particular signal +number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not within the range of valid +indices, then returns @code{NULL}. + +The contents of the location pointed to are only guaranteed to be +valid until the next call to @code{strsigno}. + +@end deftypefn + +@c strstr.c:6 +@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) + +This function searches for the substring @var{sub} in the string +@var{string}, not including the terminating null characters. A pointer +to the first occurrence of @var{sub} is returned, or @code{NULL} if the +substring is absent. If @var{sub} points to a string with zero +length, the function returns @var{string}. + +@end deftypefn + +@c strtod.c:27 +@deftypefn Supplemental double strtod (const char *@var{string}, @ + char **@var{endptr}) + +This ISO C function converts the initial portion of @var{string} to a +@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the +character after the last character used in the conversion is stored in +the location referenced by @var{endptr}. If no conversion is +performed, zero is returned and the value of @var{string} is stored in +the location referenced by @var{endptr}. + +@end deftypefn + +@c strerror.c:734 +@deftypefn Extension int strtoerrno (const char *@var{name}) + +Given the symbolic name of a error number (e.g., @code{EACCES}), map it +to an errno value. If no translation is found, returns 0. + +@end deftypefn + +@c strtol.c:33 +@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) + +The @code{strtol} function converts the string in @var{string} to a +long integer value according to the given @var{base}, which must be +between 2 and 36 inclusive, or be the special value 0. If @var{base} +is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} +to indicate bases 8 and 16, respectively, else default to base 10. +When the base is 16 (either explicitly or implicitly), a prefix of +@code{0x} is allowed. The handling of @var{endptr} is as that of +@code{strtod} above. The @code{strtoul} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strtoll.c:33 +@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long long int} strtoull (@ + const char *@var{string}, char **@var{endptr}, int @var{base}) + +The @code{strtoll} function converts the string in @var{string} to a +long long integer value according to the given @var{base}, which must be +between 2 and 36 inclusive, or be the special value 0. If @var{base} +is 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x} +to indicate bases 8 and 16, respectively, else default to base 10. +When the base is 16 (either explicitly or implicitly), a prefix of +@code{0x} is allowed. The handling of @var{endptr} is as that of +@code{strtod} above. The @code{strtoull} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strsignal.c:502 +@deftypefn Extension int strtosigno (const char *@var{name}) + +Given the symbolic name of a signal, map it to a signal number. If no +translation is found, returns 0. + +@end deftypefn + +@c strverscmp.c:25 +@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +The @code{strverscmp} function compares the string @var{s1} against +@var{s2}, considering them as holding indices/version numbers. Return +value follows the same conventions as found in the @code{strverscmp} +function. In fact, if @var{s1} and @var{s2} contain no digits, +@code{strverscmp} behaves like @code{strcmp}. + +Basically, we compare strings normally (character by character), until +we find a digit in each string - then we enter a special comparison +mode, where each sequence of digits is taken as a whole. If we reach the +end of these two parts without noticing a difference, we return to the +standard comparison mode. There are two types of numeric parts: +"integral" and "fractional" (those begin with a '0'). The types +of the numeric parts affect the way we sort them: + +@itemize @bullet +@item +integral/integral: we compare values as you would expect. + +@item +fractional/integral: the fractional part is less than the integral one. +Again, no surprise. + +@item +fractional/fractional: the things become a bit more complex. +If the common prefix contains only leading zeroes, the longest part is less +than the other one; else the comparison behaves normally. +@end itemize + +@smallexample +strverscmp ("no digit", "no digit") + @result{} 0 // @r{same behavior as strcmp.} +strverscmp ("item#99", "item#100") + @result{} <0 // @r{same prefix, but 99 < 100.} +strverscmp ("alpha1", "alpha001") + @result{} >0 // @r{fractional part inferior to integral one.} +strverscmp ("part1_f012", "part1_f01") + @result{} >0 // @r{two fractional parts.} +strverscmp ("foo.009", "foo.0") + @result{} <0 // @r{idem, but with leading zeroes only.} +@end smallexample + +This function is especially useful when dealing with filename sorting, +because filenames frequently hold indices/version numbers. +@end deftypefun + +@c timeval-utils.c:43 +@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Adds @var{a} to @var{b} and stores the result in @var{result}. + +@end deftypefn + +@c timeval-utils.c:67 +@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Subtracts @var{b} from @var{a} and stores the result in @var{result}. + +@end deftypefn + +@c tmpnam.c:3 +@deftypefn Supplemental char* tmpnam (char *@var{s}) + +This function attempts to create a name for a temporary file, which +will be a valid file name yet not exist when @code{tmpnam} checks for +it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, +or be @code{NULL}. Use of this function creates a security risk, and it must +not be used in new projects. Use @code{mkstemp} instead. + +@end deftypefn + +@c unlink-if-ordinary.c:27 +@deftypefn Supplemental int unlink_if_ordinary (const char*) + +Unlinks the named file, unless it is special (e.g. a device file). +Returns 0 when the file was unlinked, a negative value (and errno set) when +there was an error deleting the file, and a positive value if no attempt +was made to unlink the file because it is special. + +@end deftypefn + +@c fopen_unlocked.c:31 +@deftypefn Extension void unlock_std_streams (void) + +If the OS supports it, ensure that the standard I/O streams, +@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any +multi-threaded locking. Otherwise do nothing. + +@end deftypefn + +@c fopen_unlocked.c:23 +@deftypefn Extension void unlock_stream (FILE * @var{stream}) + +If the OS supports it, ensure that the supplied stream is setup to +avoid any multi-threaded locking. Otherwise leave the @code{FILE} +pointer unchanged. If the @var{stream} is @code{NULL} do nothing. + +@end deftypefn + +@c vasprintf.c:47 +@deftypefn Extension int vasprintf (char **@var{resptr}, @ + const char *@var{format}, va_list @var{args}) + +Like @code{vsprintf}, but instead of passing a pointer to a buffer, +you pass a pointer to a pointer. This function will compute the size +of the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{vsprintf} would return. If memory could +not be allocated, minus one is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + +@c vfork.c:6 +@deftypefn Supplemental int vfork (void) + +Emulates @code{vfork} by calling @code{fork} and returning its value. + +@end deftypefn + +@c vprintf.c:3 +@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ + const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vsprintf (char *@var{str}, @ + const char *@var{format}, va_list @var{ap}) + +These functions are the same as @code{printf}, @code{fprintf}, and +@code{sprintf}, respectively, except that they are called with a +@code{va_list} instead of a variable number of arguments. Note that +they do not call @code{va_end}; this is the application's +responsibility. In @libib{} they are implemented in terms of the +nonstandard but common function @code{_doprnt}. + +@end deftypefn + +@c vsnprintf.c:28 +@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, va_list @var{ap}) + +This function is similar to @code{vsprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. On error the +return value is -1, otherwise it returns the number of characters that +would have been printed had @var{n} been sufficiently large, +regardless of the actual value of @var{n}. Note some pre-C99 system +libraries do not implement this correctly so users cannot generally +rely on the return value if the system version of this function is +used. + +@end deftypefn + +@c waitpid.c:3 +@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) + +This is a wrapper around the @code{wait} function. Any ``special'' +values of @var{pid} depend on your implementation of @code{wait}, as +does the return value. The third argument is unused in @libib{}. + +@end deftypefn + +@c argv.c:289 +@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file}) + +Write each member of ARGV, handling all necessary quoting, to the file +named by FILE, separated by whitespace. Return 0 on success, non-zero +if an error occurred while writing to FILE. + +@end deftypefn + +@c xasprintf.c:31 +@deftypefn Replacement char* xasprintf (const char *@var{format}, ...) + +Print to allocated string without fail. If @code{xasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn + +@c xatexit.c:11 +@deftypefun int xatexit (void (*@var{fn}) (void)) + +Behaves as the standard @code{atexit} function, but with no limit on +the number of registered functions. Returns 0 on success, or @minus{}1 on +failure. If you use @code{xatexit} to register functions, you must use +@code{xexit} to terminate your program. + +@end deftypefun + +@c xmalloc.c:38 +@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) + +Allocate memory without fail, and set it to zero. This routine functions +like @code{calloc}, but will behave the same as @code{xmalloc} if memory +cannot be found. + +@end deftypefn + +@c xexit.c:22 +@deftypefn Replacement void xexit (int @var{code}) + +Terminates the program. If any functions have been registered with +the @code{xatexit} replacement function, they will be called first. +Termination is handled via the system's normal @code{exit} call. + +@end deftypefn + +@c xmalloc.c:22 +@deftypefn Replacement void* xmalloc (size_t) + +Allocate memory without fail. If @code{malloc} fails, this will print +a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, +if any) and then call @code{xexit}. Note that it is therefore safe for +a program to contain @code{#define malloc xmalloc} in its source. + +@end deftypefn + +@c xmalloc.c:53 +@deftypefn Replacement void xmalloc_failed (size_t) + +This function is not meant to be called by client code, and is listed +here for completeness only. If any of the allocation routines fail, this +function will be called to print an error message and terminate execution. + +@end deftypefn + +@c xmalloc.c:46 +@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) + +You can use this to set the name of the program used by +@code{xmalloc_failed} when printing a failure message. + +@end deftypefn + +@c xmemdup.c:7 +@deftypefn Replacement void* xmemdup (void *@var{input}, @ + size_t @var{copy_size}, size_t @var{alloc_size}) + +Duplicates a region of memory without fail. First, @var{alloc_size} bytes +are allocated, then @var{copy_size} bytes from @var{input} are copied into +it, and the new memory is returned. If fewer bytes are copied than were +allocated, the remaining memory is zeroed. + +@end deftypefn + +@c xmalloc.c:32 +@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) +Reallocate memory without fail. This routine functions like @code{realloc}, +but will behave the same as @code{xmalloc} if memory cannot be found. + +@end deftypefn + +@c xstrdup.c:7 +@deftypefn Replacement char* xstrdup (const char *@var{s}) + +Duplicates a character string without fail, using @code{xmalloc} to +obtain memory. + +@end deftypefn + +@c xstrerror.c:7 +@deftypefn Replacement char* xstrerror (int @var{errnum}) + +Behaves exactly like the standard @code{strerror} function, but +will never return a @code{NULL} pointer. + +@end deftypefn + +@c xstrndup.c:23 +@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) + +Returns a pointer to a copy of @var{s} with at most @var{n} characters +without fail, using @code{xmalloc} to obtain memory. The result is +always NUL terminated. + +@end deftypefn + +@c xvasprintf.c:38 +@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args}) + +Print to allocated string without fail. If @code{xvasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn + + diff --git a/libiberty/libiberty.texi b/libiberty/libiberty.texi new file mode 100644 index 0000000..ad1f8e3 --- /dev/null +++ b/libiberty/libiberty.texi @@ -0,0 +1,313 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename libiberty.info +@settitle @sc{gnu} libiberty +@c %**end of header + +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex pg cp + +@finalout +@c %**end of header + +@dircategory GNU libraries +@direntry +* Libiberty: (libiberty). Library of utility functions which + are missing or broken on some systems. +@end direntry + +@macro libib +@code{libiberty} +@end macro + +@ifinfo +This manual describes the GNU @libib library of utility subroutines. + +Copyright @copyright{} 2001-2022 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled ``GNU Free Documentation License''. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +@end ifinfo + + +@titlepage +@title @sc{gnu} libiberty +@author Phil Edwards et al. +@page + + +@vskip 0pt plus 1filll +Copyright @copyright{} 2001-2022 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled ``GNU Free Documentation License''. + +@end titlepage +@contents +@page + +@ifnottex +@node Top,Using,, +@top Introduction + +The @libib{} library is a collection of subroutines used by various +GNU programs. It is available under the Library General Public +License; for more information, see @ref{Library Copying}. + +@end ifnottex + +@menu +* Using:: How to use libiberty in your code. + +* Overview:: Overview of available function groups. + +* Functions:: Available functions, macros, and global variables. + +* Licenses:: The various licenses under which libiberty sources are + distributed. + +* Index:: Index of functions and categories. +@end menu + +@node Using +@chapter Using +@cindex using libiberty +@cindex libiberty usage +@cindex how to use + +@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY. + +To date, @libib{} is generally not installed on its own. It has evolved +over years but does not have its own version number nor release schedule. + +Possibly the easiest way to use @libib{} in your projects is to drop the +@libib{} code into your project's sources, and to build the library along +with your own sources; the library would then be linked in at the end. This +prevents any possible version mismatches with other copies of libiberty +elsewhere on the system. + +Passing @option{--enable-install-libiberty} to the @command{configure} +script when building @libib{} causes the header files and archive library +to be installed when @kbd{make install} is run. This option also takes +an (optional) argument to specify the installation location, in the same +manner as @option{--prefix}. + +For your own projects, an approach which offers stability and flexibility +is to include @libib{} with your code, but allow the end user to optionally +choose to use a previously-installed version instead. In this way the +user may choose (for example) to install @libib{} as part of GCC, and use +that version for all software built with that compiler. (This approach +has proven useful with software using the GNU @code{readline} library.) + +Making use of @libib{} code usually requires that you include one or more +header files from the @libib{} distribution. (They will be named as +necessary in the function descriptions.) At link time, you will need to +add @option{-liberty} to your link command invocation. + + +@node Overview +@chapter Overview + +Functions contained in @libib{} can be divided into three general categories. + + +@menu +* Supplemental Functions:: Providing functions which don't exist + on older operating systems. + +* Replacement Functions:: These functions are sometimes buggy or + unpredictable on some operating systems. + +* Extensions:: Functions which provide useful extensions + or safety wrappers around existing code. +@end menu + +@node Supplemental Functions +@section Supplemental Functions +@cindex supplemental functions +@cindex functions, supplemental +@cindex functions, missing + +Certain operating systems do not provide functions which have since +become standardized, or at least common. For example, the Single +Unix Specification Version 2 requires that the @code{basename} +function be provided, but an OS which predates that specification +might not have this function. This should not prevent well-written +code from running on such a system. + +Similarly, some functions exist only among a particular ``flavor'' +or ``family'' of operating systems. As an example, the @code{bzero} +function is often not present on systems outside the BSD-derived +family of systems. + +Many such functions are provided in @libib{}. They are quickly +listed here with little description, as systems which lack them +become less and less common. Each function @var{foo} is implemented +in @file{@var{foo}.c} but not declared in any @libib{} header file; more +comments and caveats for each function's implementation are often +available in the source file. Generally, the function can simply +be declared as @code{extern}. + + + +@node Replacement Functions +@section Replacement Functions +@cindex replacement functions +@cindex functions, replacement + +Some functions have extremely limited implementations on different +platforms. Other functions are tedious to use correctly; for example, +proper use of @code{malloc} calls for the return value to be checked and +appropriate action taken if memory has been exhausted. A group of +``replacement functions'' is available in @libib{} to address these issues +for some of the most commonly used subroutines. + +All of these functions are declared in the @file{libiberty.h} header +file. Many of the implementations will use preprocessor macros set by +GNU Autoconf, if you decide to make use of that program. Some of these +functions may call one another. + + +@menu +* Memory Allocation:: Testing and handling failed memory + requests automatically. +* Exit Handlers:: Calling routines on program exit. +* Error Reporting:: Mapping errno and signal numbers to + more useful string formats. +@end menu + +@node Memory Allocation +@subsection Memory Allocation +@cindex memory allocation + +The functions beginning with the letter @samp{x} are wrappers around +standard functions; the functions provided by the system environment +are called and their results checked before the results are passed back +to client code. If the standard functions fail, these wrappers will +terminate the program. Thus, these versions can be used with impunity. + + +@node Exit Handlers +@subsection Exit Handlers +@cindex exit handlers + +The existence and implementation of the @code{atexit} routine varies +amongst the flavors of Unix. @libib{} provides an unvarying dependable +implementation via @code{xatexit} and @code{xexit}. + + +@node Error Reporting +@subsection Error Reporting +@cindex error reporting + +These are a set of routines to facilitate programming with the system +@code{errno} interface. The @libib{} source file @file{strerror.c} +contains a good deal of documentation for these functions. + +@c signal stuff + + +@node Extensions +@section Extensions +@cindex extensions +@cindex functions, extension + +@libib{} includes additional functionality above and beyond standard +functions, which has proven generically useful in GNU programs, such as +obstacks and regex. These functions are often copied from other +projects as they gain popularity, and are included here to provide a +central location from which to use, maintain, and distribute them. + +@menu +* Obstacks:: Stacks of arbitrary objects. +@end menu + +@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl +@include obstacks.texi + +@node Functions +@chapter Function, Variable, and Macro Listing. +@include functions.texi + +@node Licenses +@appendix Licenses + +@menu + +* Library Copying:: The GNU Library General Public License +* BSD:: Regents of the University of California + +@end menu + +@c This takes care of Library Copying. It is the copying-lib.texi from the +@c GNU web site, with its @node line altered to make makeinfo shut up. +@include copying-lib.texi + +@page +@node BSD +@appendixsec BSD + +Copyright @copyright{} 1990 Regents of the University of California. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +@enumerate + +@item +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + +@item +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +@item +[rescinded 22 July 1999] + +@item +Neither the name of the University nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. + +@end enumerate + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@node Index +@unnumbered Index + +@printindex cp + +@bye + diff --git a/libiberty/obstacks.texi b/libiberty/obstacks.texi new file mode 100644 index 0000000..b2d2403 --- /dev/null +++ b/libiberty/obstacks.texi @@ -0,0 +1,774 @@ +@node Obstacks +@subsection Obstacks +@cindex obstacks + +An @dfn{obstack} is a pool of memory containing a stack of objects. You +can create any number of separate obstacks, and then allocate objects in +specified obstacks. Within each obstack, the last object allocated must +always be the first one freed, but distinct obstacks are independent of +each other. + +Aside from this one constraint of order of freeing, obstacks are totally +general: an obstack can contain any number of objects of any size. They +are implemented with macros, so allocation is usually very fast as long as +the objects are usually small. And the only space overhead per object is +the padding needed to start each object on a suitable boundary. + +@menu +* Creating Obstacks:: How to declare an obstack in your program. +* Preparing for Obstacks:: Preparations needed before you can + use obstacks. +* Allocation in an Obstack:: Allocating objects in an obstack. +* Freeing Obstack Objects:: Freeing objects in an obstack. +* Obstack Functions:: The obstack functions are really macros. +* Growing Objects:: Making an object bigger by stages. +* Extra Fast Growing:: Extra-high-efficiency (though more + complicated) growing objects. +* Status of an Obstack:: Inquiries about the status of an obstack. +* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. +* Obstack Chunks:: How obstacks obtain and release chunks; + efficiency considerations. +* Summary of Obstacks:: +@end menu + +@node Creating Obstacks +@subsubsection Creating Obstacks + +The utilities for manipulating obstacks are declared in the header +file @file{obstack.h}. +@pindex obstack.h + +@comment obstack.h +@comment GNU +@deftp {Data Type} {struct obstack} +An obstack is represented by a data structure of type @code{struct +obstack}. This structure has a small fixed size; it records the status +of the obstack and how to find the space in which objects are allocated. +It does not contain any of the objects themselves. You should not try +to access the contents of the structure directly; use only the macros +described in this chapter. +@end deftp + +You can declare variables of type @code{struct obstack} and use them as +obstacks, or you can allocate obstacks dynamically like any other kind +of object. Dynamic allocation of obstacks allows your program to have a +variable number of different stacks. (You can even allocate an +obstack structure in another obstack, but this is rarely useful.) + +All the macros that work with obstacks require you to specify which +obstack to use. You do this with a pointer of type @code{struct obstack +*}. In the following, we often say ``an obstack'' when strictly +speaking the object at hand is such a pointer. + +The objects in the obstack are packed into large blocks called +@dfn{chunks}. The @code{struct obstack} structure points to a chain of +the chunks currently in use. + +The obstack library obtains a new chunk whenever you allocate an object +that won't fit in the previous chunk. Since the obstack library manages +chunks automatically, you don't need to pay much attention to them, but +you do need to supply a function which the obstack library should use to +get a chunk. Usually you supply a function which uses @code{malloc} +directly or indirectly. You must also supply a function to free a chunk. +These matters are described in the following section. + +@node Preparing for Obstacks +@subsubsection Preparing for Using Obstacks + +Each source file in which you plan to use obstacks +must include the header file @file{obstack.h}, like this: + +@smallexample +#include <obstack.h> +@end smallexample + +@findex obstack_chunk_alloc +@findex obstack_chunk_free +Also, if the source file uses the macro @code{obstack_init}, it must +declare or define two macros that will be called by the +obstack library. One, @code{obstack_chunk_alloc}, is used to allocate +the chunks of memory into which objects are packed. The other, +@code{obstack_chunk_free}, is used to return chunks when the objects in +them are freed. These macros should appear before any use of obstacks +in the source file. + +Usually these are defined to use @code{malloc} via the intermediary +@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with +the following pair of macro definitions: + +@smallexample +#define obstack_chunk_alloc xmalloc +#define obstack_chunk_free free +@end smallexample + +@noindent +Though the memory you get using obstacks really comes from @code{malloc}, +using obstacks is faster because @code{malloc} is called less often, for +larger blocks of memory. @xref{Obstack Chunks}, for full details. + +At run time, before the program can use a @code{struct obstack} object +as an obstack, it must initialize the obstack by calling +@code{obstack_init} or one of its variants, @code{obstack_begin}, +@code{obstack_specify_allocation}, or +@code{obstack_specify_allocation_with_arg}. + +@comment obstack.h +@comment GNU +@deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) +Initialize obstack @var{obstack-ptr} for allocation of objects. This +macro calls the obstack's @code{obstack_chunk_alloc} function. If +allocation of memory fails, the function pointed to by +@code{obstack_alloc_failed_handler} is called. The @code{obstack_init} +macro always returns 1 (Compatibility notice: Former versions of +obstack returned 0 if allocation failed). +@end deftypefun + +Here are two examples of how to allocate the space for an obstack and +initialize it. First, an obstack that is a static variable: + +@smallexample +static struct obstack myobstack; +@dots{} +obstack_init (&myobstack); +@end smallexample + +@noindent +Second, an obstack that is itself dynamically allocated: + +@smallexample +struct obstack *myobstack_ptr + = (struct obstack *) xmalloc (sizeof (struct obstack)); + +obstack_init (myobstack_ptr); +@end smallexample + +@comment obstack.h +@comment GNU +@deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) +Like @code{obstack_init}, but specify chunks to be at least +@var{chunk_size} bytes in size. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) +Like @code{obstack_init}, specifying chunk size, chunk +alignment, and memory allocation functions. A @var{chunk_size} or +@var{alignment} of zero results in the default size or alignment +respectively being used. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) +Like @code{obstack_specify_allocation}, but specifying memory +allocation functions that take an extra first argument, @var{arg}. +@end deftypefun + +@comment obstack.h +@comment GNU +@defvar obstack_alloc_failed_handler +The value of this variable is a pointer to a function that +@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate +memory. The default action is to print a message and abort. +You should supply a function that either calls @code{exit} +(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local +Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return. + +@smallexample +void my_obstack_alloc_failed (void) +@dots{} +obstack_alloc_failed_handler = &my_obstack_alloc_failed; +@end smallexample + +@end defvar + +@node Allocation in an Obstack +@subsubsection Allocation in an Obstack +@cindex allocation (obstacks) + +The most direct way to allocate an object in an obstack is with +@code{obstack_alloc}, which is invoked almost like @code{malloc}. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) +This allocates an uninitialized block of @var{size} bytes in an obstack +and returns its address. Here @var{obstack-ptr} specifies which obstack +to allocate the block in; it is the address of the @code{struct obstack} +object which represents the obstack. Each obstack macro +requires you to specify an @var{obstack-ptr} as the first argument. + +This macro calls the obstack's @code{obstack_chunk_alloc} function if +it needs to allocate a new chunk of memory; it calls +@code{obstack_alloc_failed_handler} if allocation of memory by +@code{obstack_chunk_alloc} failed. +@end deftypefun + +For example, here is a function that allocates a copy of a string @var{str} +in a specific obstack, which is in the variable @code{string_obstack}: + +@smallexample +struct obstack string_obstack; + +char * +copystring (char *string) +@{ + size_t len = strlen (string) + 1; + char *s = (char *) obstack_alloc (&string_obstack, len); + memcpy (s, string, len); + return s; +@} +@end smallexample + +To allocate a block with specified contents, use the macro @code{obstack_copy}. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +This allocates a block and initializes it by copying @var{size} +bytes of data starting at @var{address}. It calls +@code{obstack_alloc_failed_handler} if allocation of memory by +@code{obstack_chunk_alloc} failed. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Like @code{obstack_copy}, but appends an extra byte containing a null +character. This extra byte is not counted in the argument @var{size}. +@end deftypefun + +The @code{obstack_copy0} macro is convenient for copying a sequence +of characters into an obstack as a null-terminated string. Here is an +example of its use: + +@smallexample +char * +obstack_savestring (char *addr, size_t size) +@{ + return obstack_copy0 (&myobstack, addr, size); +@} +@end smallexample + +@noindent +Contrast this with the previous example of @code{savestring} using +@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). + +@node Freeing Obstack Objects +@subsubsection Freeing Objects in an Obstack +@cindex freeing (obstacks) + +To free an object allocated in an obstack, use the macro +@code{obstack_free}. Since the obstack is a stack of objects, freeing +one object automatically frees all other objects allocated more recently +in the same obstack. + +@comment obstack.h +@comment GNU +@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +If @var{object} is a null pointer, everything allocated in the obstack +is freed. Otherwise, @var{object} must be the address of an object +allocated in the obstack. Then @var{object} is freed, along with +everything allocated in @var{obstack} since @var{object}. +@end deftypefun + +Note that if @var{object} is a null pointer, the result is an +uninitialized obstack. To free all memory in an obstack but leave it +valid for further allocation, call @code{obstack_free} with the address +of the first object allocated on the obstack: + +@smallexample +obstack_free (obstack_ptr, first_object_allocated_ptr); +@end smallexample + +Recall that the objects in an obstack are grouped into chunks. When all +the objects in a chunk become free, the obstack library automatically +frees the chunk (@pxref{Preparing for Obstacks}). Then other +obstacks, or non-obstack allocation, can reuse the space of the chunk. + +@node Obstack Functions +@subsubsection Obstack Functions and Macros +@cindex macros + +The interfaces for using obstacks are shown here as functions to +specify the return type and argument types, but they are really +defined as macros. This means that the arguments don't actually have +types, but they generally behave as if they have the types shown. +You can call these macros like functions, but you cannot use them in +any other way (for example, you cannot take their address). + +Calling the macros requires a special precaution: namely, the first +operand (the obstack pointer) may not contain any side effects, because +it may be computed more than once. For example, if you write this: + +@smallexample +obstack_alloc (get_obstack (), 4); +@end smallexample + +@noindent +you will find that @code{get_obstack} may be called several times. +If you use @code{*obstack_list_ptr++} as the obstack pointer argument, +you will get very strange results since the incrementation may occur +several times. + +If you use the GNU C compiler, this precaution is not necessary, because +various language extensions in GNU C permit defining the macros so as to +compute each argument only once. + +Note that arguments other than the first will only be evaluated once, +even when not using GNU C. + +@code{obstack.h} does declare a number of functions, +@code{_obstack_begin}, @code{_obstack_begin_1}, +@code{_obstack_newchunk}, @code{_obstack_free}, and +@code{_obstack_memory_used}. You should not call these directly. + +@node Growing Objects +@subsubsection Growing Objects +@cindex growing objects (in obstacks) +@cindex changing the size of a block (obstacks) + +Because memory in obstack chunks is used sequentially, it is possible to +build up an object step by step, adding one or more bytes at a time to the +end of the object. With this technique, you do not need to know how much +data you will put in the object until you come to the end of it. We call +this the technique of @dfn{growing objects}. The special macros +for adding data to the growing object are described in this section. + +You don't need to do anything special when you start to grow an object. +Using one of the macros to add data to the object automatically +starts it. However, it is necessary to say explicitly when the object is +finished. This is done with @code{obstack_finish}. + +The actual address of the object thus built up is not known until the +object is finished. Until then, it always remains possible that you will +add so much data that the object must be copied into a new chunk. + +While the obstack is in use for a growing object, you cannot use it for +ordinary allocation of another object. If you try to do so, the space +already added to the growing object will become part of the other object. + +@comment obstack.h +@comment GNU +@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) +The most basic macro for adding to a growing object is +@code{obstack_blank}, which adds space without initializing it. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) +To add a block of initialized space, use @code{obstack_grow}, which is +the growing-object analogue of @code{obstack_copy}. It adds @var{size} +bytes of data to the growing object, copying the contents from +@var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) +This is the growing-object analogue of @code{obstack_copy0}. It adds +@var{size} bytes copied from @var{data}, followed by an additional null +character. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) +To add one character at a time, use @code{obstack_1grow}. +It adds a single byte containing @var{c} to the growing object. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) +Adding the value of a pointer one can use +@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes +containing the value of @var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) +A single value of type @code{int} can be added by using +@code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to +the growing object and initializes them with the value of @var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) +When you are finished growing the object, use +@code{obstack_finish} to close it off and return its final address. + +Once you have finished the object, the obstack is available for ordinary +allocation or for growing another object. +@end deftypefun + +When you build an object by growing it, you will probably need to know +afterward how long it became. You need not keep track of this as you grow +the object, because you can find out the length from the obstack +with @code{obstack_object_size}, before finishing the object. + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +This macro returns the current size of the growing object, in bytes. +Remember to call @code{obstack_object_size} @emph{before} finishing the object. +After it is finished, @code{obstack_object_size} will return zero. +@end deftypefun + +If you have started growing an object and wish to cancel it, you should +finish it and then free it, like this: + +@smallexample +obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); +@end smallexample + +@noindent +This has no effect if no object was growing. + +@node Extra Fast Growing +@subsubsection Extra Fast Growing Objects +@cindex efficiency and obstacks + +The usual macros for growing objects incur overhead for checking +whether there is room for the new growth in the current chunk. If you +are frequently constructing objects in small steps of growth, this +overhead can be significant. + +You can reduce the overhead by using special ``fast growth'' +macros that grow the object without checking. In order to have a +robust program, you must do the checking yourself. If you do this checking +in the simplest way each time you are about to add data to the object, you +have not saved anything, because that is what the ordinary growth +macros do. But if you can arrange to check less often, or check +more efficiently, then you make the program faster. + +@code{obstack_room} returns the amount of room available +in the current chunk. + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr}) +This returns the number of bytes that can be added safely to the current +growing object (or to an object about to be started) in obstack +@var{obstack} using the fast growth macros. +@end deftypefun + +While you know there is room, you can use these fast growth macros +for adding data to a growing object: + +@comment obstack.h +@comment GNU +@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) +@code{obstack_1grow_fast} adds one byte containing the +character @var{c} to the growing object in obstack @var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) +@code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} +bytes containing the value of @var{data} to the growing object in +obstack @var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) +@code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes +containing the value of @var{data} to the growing object in obstack +@var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) +@code{obstack_blank_fast} adds @var{size} bytes to the +growing object in obstack @var{obstack-ptr} without initializing them. +@end deftypefun + +When you check for space using @code{obstack_room} and there is not +enough room for what you want to add, the fast growth macros +are not safe. In this case, simply use the corresponding ordinary +growth macro instead. Very soon this will copy the object to a +new chunk; then there will be lots of room available again. + +So, each time you use an ordinary growth macro, check afterward for +sufficient space using @code{obstack_room}. Once the object is copied +to a new chunk, there will be plenty of space again, so the program will +start using the fast growth macros again. + +Here is an example: + +@smallexample +@group +void +add_string (struct obstack *obstack, const char *ptr, size_t len) +@{ + while (len > 0) + @{ + size_t room = obstack_room (obstack); + if (room == 0) + @{ + /* @r{Not enough room. Add one character slowly,} + @r{which may copy to a new chunk and make room.} */ + obstack_1grow (obstack, *ptr++); + len--; + @} + else + @{ + if (room > len) + room = len; + /* @r{Add fast as much as we have room for.} */ + len -= room; + while (room-- > 0) + obstack_1grow_fast (obstack, *ptr++); + @} + @} +@} +@end group +@end smallexample + +@cindex shrinking objects +You can use @code{obstack_blank_fast} with a ``negative'' size +argument to make the current object smaller. Just don't try to shrink +it beyond zero length---there's no telling what will happen if you do +that. Earlier versions of obstacks allowed you to use +@code{obstack_blank} to shrink objects. This will no longer work. + +@node Status of an Obstack +@subsubsection Status of an Obstack +@cindex obstack status +@cindex status of obstack + +Here are macros that provide information on the current status of +allocation in an obstack. You can use them to learn about an object while +still growing it. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) +This macro returns the tentative address of the beginning of the +currently growing object in @var{obstack-ptr}. If you finish the object +immediately, it will have that address. If you make it larger first, it +may outgrow the current chunk---then its address will change! + +If no object is growing, this value says where the next object you +allocate will start (once again assuming it fits in the current +chunk). +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) +This macro returns the address of the first free byte in the current +chunk of obstack @var{obstack-ptr}. This is the end of the currently +growing object. If no object is growing, @code{obstack_next_free} +returns the same value as @code{obstack_base}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +This macro returns the size in bytes of the currently growing object. +This is equivalent to + +@smallexample +((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}))) +@end smallexample +@end deftypefun + +@node Obstacks Data Alignment +@subsubsection Alignment of Data in Obstacks +@cindex alignment (in obstacks) + +Each obstack has an @dfn{alignment boundary}; each object allocated in +the obstack automatically starts on an address that is a multiple of the +specified boundary. By default, this boundary is aligned so that +the object can hold any type of data. + +To access an obstack's alignment boundary, use the macro +@code{obstack_alignment_mask}. + +@comment obstack.h +@comment GNU +@deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +The value is a bit mask; a bit that is 1 indicates that the corresponding +bit in the address of an object should be 0. The mask value should be one +less than a power of 2; the effect is that all object addresses are +multiples of that power of 2. The default value of the mask is a value +that allows aligned objects to hold any type of data: for example, if +its value is 3, any type of data can be stored at locations whose +addresses are multiples of 4. A mask value of 0 means an object can start +on any multiple of 1 (that is, no alignment is required). + +The expansion of the macro @code{obstack_alignment_mask} is an lvalue, +so you can alter the mask by assignment. For example, this statement: + +@smallexample +obstack_alignment_mask (obstack_ptr) = 0; +@end smallexample + +@noindent +has the effect of turning off alignment processing in the specified obstack. +@end deftypefn + +Note that a change in alignment mask does not take effect until +@emph{after} the next time an object is allocated or finished in the +obstack. If you are not growing an object, you can make the new +alignment mask take effect immediately by calling @code{obstack_finish}. +This will finish a zero-length object and then do proper alignment for +the next object. + +@node Obstack Chunks +@subsubsection Obstack Chunks +@cindex efficiency of chunks +@cindex chunks + +Obstacks work by allocating space for themselves in large chunks, and +then parceling out space in the chunks to satisfy your requests. Chunks +are normally 4096 bytes long unless you specify a different chunk size. +The chunk size includes 8 bytes of overhead that are not actually used +for storing objects. Regardless of the specified size, longer chunks +will be allocated when necessary for long objects. + +The obstack library allocates chunks by calling the function +@code{obstack_chunk_alloc}, which you must define. When a chunk is no +longer needed because you have freed all the objects in it, the obstack +library frees the chunk by calling @code{obstack_chunk_free}, which you +must also define. + +These two must be defined (as macros) or declared (as functions) in each +source file that uses @code{obstack_init} (@pxref{Creating Obstacks}). +Most often they are defined as macros like this: + +@smallexample +#define obstack_chunk_alloc malloc +#define obstack_chunk_free free +@end smallexample + +Note that these are simple macros (no arguments). Macro definitions with +arguments will not work! It is necessary that @code{obstack_chunk_alloc} +or @code{obstack_chunk_free}, alone, expand into a function name if it is +not itself a function name. + +If you allocate chunks with @code{malloc}, the chunk size should be a +power of 2. The default chunk size, 4096, was chosen because it is long +enough to satisfy many typical requests on the obstack yet short enough +not to waste too much memory in the portion of the last chunk not yet used. + +@comment obstack.h +@comment GNU +@deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) +This returns the chunk size of the given obstack. +@end deftypefn + +Since this macro expands to an lvalue, you can specify a new chunk size by +assigning it a new value. Doing so does not affect the chunks already +allocated, but will change the size of chunks allocated for that particular +obstack in the future. It is unlikely to be useful to make the chunk size +smaller, but making it larger might improve efficiency if you are +allocating many objects whose size is comparable to the chunk size. Here +is how to do so cleanly: + +@smallexample +if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) + obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; +@end smallexample + +@node Summary of Obstacks +@subsubsection Summary of Obstack Macros + +Here is a summary of all the macros associated with obstacks. Each +takes the address of an obstack (@code{struct obstack *}) as its first +argument. + +@table @code +@item int obstack_init (struct obstack *@var{obstack-ptr}) +Initialize use of an obstack. @xref{Creating Obstacks}. + +@item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) +Initialize use of an obstack, with an initial chunk of +@var{chunk_size} bytes. + +@item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) +Initialize use of an obstack, specifying intial chunk size, chunk +alignment, and memory allocation functions. + +@item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) +Like @code{obstack_specify_allocation}, but specifying memory +allocation functions that take an extra first argument, @var{arg}. + +@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Allocate an object of @var{size} uninitialized bytes. +@xref{Allocation in an Obstack}. + +@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Allocate an object of @var{size} bytes, with contents copied from +@var{address}. @xref{Allocation in an Obstack}. + +@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Allocate an object of @var{size}+1 bytes, with @var{size} of them copied +from @var{address}, followed by a null character at the end. +@xref{Allocation in an Obstack}. + +@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +Free @var{object} (and everything allocated in the specified obstack +more recently than @var{object}). @xref{Freeing Obstack Objects}. + +@item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Add @var{size} uninitialized bytes to a growing object. +@xref{Growing Objects}. + +@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Add @var{size} bytes, copied from @var{address}, to a growing object. +@xref{Growing Objects}. + +@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Add @var{size} bytes, copied from @var{address}, to a growing object, +and then add another byte containing a null character. @xref{Growing +Objects}. + +@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) +Add one byte containing @var{data-char} to a growing object. +@xref{Growing Objects}. + +@item void *obstack_finish (struct obstack *@var{obstack-ptr}) +Finalize the object that is growing and return its permanent address. +@xref{Growing Objects}. + +@item size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +Get the current size of the currently growing object. @xref{Growing +Objects}. + +@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Add @var{size} uninitialized bytes to a growing object without checking +that there is enough room. @xref{Extra Fast Growing}. + +@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) +Add one byte containing @var{data-char} to a growing object without +checking that there is enough room. @xref{Extra Fast Growing}. + +@item size_t obstack_room (struct obstack *@var{obstack-ptr}) +Get the amount of room now available for growing the current object. +@xref{Extra Fast Growing}. + +@item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +The mask used for aligning the beginning of an object. This is an +lvalue. @xref{Obstacks Data Alignment}. + +@item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) +The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. + +@item void *obstack_base (struct obstack *@var{obstack-ptr}) +Tentative starting address of the currently growing object. +@xref{Status of an Obstack}. + +@item void *obstack_next_free (struct obstack *@var{obstack-ptr}) +Address just after the end of the currently growing object. +@xref{Status of an Obstack}. +@end table + |