diff options
Diffstat (limited to 'gcc-4.7/libiberty/libiberty.texi')
| -rw-r--r-- | gcc-4.7/libiberty/libiberty.texi | 318 |
1 files changed, 0 insertions, 318 deletions
diff --git a/gcc-4.7/libiberty/libiberty.texi b/gcc-4.7/libiberty/libiberty.texi deleted file mode 100644 index 74f70d2bd..000000000 --- a/gcc-4.7/libiberty/libiberty.texi +++ /dev/null @@ -1,318 +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, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -2009, 2010 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, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -2009, 2010 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. - -* Obstacks:: Object Stacks. - -* 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 a make-obstacks-texi.sh -@c script of Phil's. Hope it's accurate. -@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 - |