sphinx: remove texinfo files
gcc/d/ChangeLog: * gdc.texi: Removed. gcc/ChangeLog: * doc/analyzer.texi: Removed. * doc/avr-mmcu.texi: Removed. * doc/bugreport.texi: Removed. * doc/cfg.texi: Removed. * doc/collect2.texi: Removed. * doc/compat.texi: Removed. * doc/configfiles.texi: Removed. * doc/configterms.texi: Removed. * doc/contrib.texi: Removed. * doc/contribute.texi: Removed. * doc/cpp.texi: Removed. * doc/cppdiropts.texi: Removed. * doc/cppenv.texi: Removed. * doc/cppinternals.texi: Removed. * doc/cppopts.texi: Removed. * doc/cppwarnopts.texi: Removed. * doc/extend.texi: Removed. * doc/fragments.texi: Removed. * doc/frontends.texi: Removed. * doc/gcc.texi: Removed. * doc/gccint.texi: Removed. * doc/gcov-dump.texi: Removed. * doc/gcov-tool.texi: Removed. * doc/gcov.texi: Removed. * doc/generic.texi: Removed. * doc/gimple.texi: Removed. * doc/gnu.texi: Removed. * doc/gty.texi: Removed. * doc/headerdirs.texi: Removed. * doc/hostconfig.texi: Removed. * doc/implement-c.texi: Removed. * doc/implement-cxx.texi: Removed. * doc/include/fdl.texi: Removed. * doc/include/funding.texi: Removed. * doc/include/gcc-common.texi: Removed. * doc/include/gpl_v3.texi: Removed. * doc/install.texi: Removed. * doc/interface.texi: Removed. * doc/invoke.texi: Removed. * doc/languages.texi: Removed. * doc/libgcc.texi: Removed. * doc/loop.texi: Removed. * doc/lto-dump.texi: Removed. * doc/lto.texi: Removed. * doc/makefile.texi: Removed. * doc/match-and-simplify.texi: Removed. * doc/md.texi: Removed. * doc/objc.texi: Removed. * doc/optinfo.texi: Removed. * doc/options.texi: Removed. * doc/passes.texi: Removed. * doc/plugins.texi: Removed. * doc/poly-int.texi: Removed. * doc/portability.texi: Removed. * doc/rtl.texi: Removed. * doc/service.texi: Removed. * doc/sourcebuild.texi: Removed. * doc/standards.texi: Removed. * doc/tm.texi: Removed. * doc/tree-ssa.texi: Removed. * doc/trouble.texi: Removed. * doc/ux.texi: Removed. * doc/tm.texi.in: Removed. gcc/fortran/ChangeLog: * gfc-internals.texi: Removed. * gfortran.texi: Removed. * intrinsic.texi: Removed. * invoke.texi: Removed. gcc/go/ChangeLog: * gccgo.texi: Removed. libgomp/ChangeLog: * libgomp.texi: Removed. libiberty/ChangeLog: * at-file.texi: Removed. * copying-lib.texi: Removed. * functions.texi: Removed. * libiberty.texi: Removed. * obstacks.texi: Removed. libitm/ChangeLog: * libitm.texi: Removed. libquadmath/ChangeLog: * libquadmath.texi: Removed.
This commit is contained in:
Martin Liska
@@ -1,15 +0,0 @@
|
||||
@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.
|
||||
@@ -1,560 +0,0 @@
|
||||
@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!
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,313 +0,0 @@
|
||||
\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
|
||||
|
||||
@@ -1,774 +0,0 @@
|
||||
@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
|
||||
|
||||
Reference in New Issue
Block a user