initial import

1 files changed, 1007 insertions, 0 deletions

diff --git a/manual/libc.texinfo b/manual/libc.texinfo
new file mode 100644
index 0000000000..0b455b32d2
--- /dev/null
+++ b/manual/libc.texinfo
@@ -0,0 +1,1007 @@
+\input texinfo                  @c -*- Texinfo -*-
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename libc.info
+@settitle The GNU C Library
+@setchapternewpage odd
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@c This tells texinfo.tex to use the real section titles in xrefs in
+@c place of the node name, when no section title is explicitly given.
+@set xref-automatic-section-title
+@smallbook
+
+@c  I've already told people the printed edition will be 0.06
+@set EDITION 0.06
+@set VERSION 1.09 Beta
+@set UPDATED 23 December 1994
+@set ISBN 1-882114-53-1
+
+@ifinfo
+This file documents the GNU C library.
+
+This is Edition @value{EDITION}, last updated @value{UPDATED},
+of @cite{The GNU C Library Reference Manual}, for Version @value{VERSION}.
+
+Copyright (C) 1993, 1994 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries 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
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU Library General Public License'' is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+Library General Public License'' must be approved for accuracy by the
+Foundation.
+@end ifinfo
+
+@iftex
+@shorttitlepage The GNU C Library Reference Manual
+@end iftex
+@titlepage
+@center @titlefont{The GNU C Library}
+@sp 1
+@center @titlefont{Reference Manual}
+@sp 2
+@center Sandra Loosemore
+@center with
+@center Richard M. Stallman, Roland McGrath, and Andrew Oram
+@sp 3
+@center Edition @value{EDITION}
+@sp 1
+@center last updated @value{UPDATED}
+@sp 1
+@center for version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
+@sp 2
+Published by the Free Software Foundation @*
+675 Massachusetts Avenue, @*
+Cambridge, MA 02139 USA @*
+Printed copies are available for $50 each. @*
+ISBN @value{ISBN} @*
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU Library General Public License'' is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the text of the translation of the section entitled ``GNU
+Library General Public License'' must be approved for accuracy by the
+Foundation.
+@end titlepage
+@page
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top Main Menu
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The GNU C Library Reference Manual}, for Version @value{VERSION}
+of the GNU C Library.
+@end ifinfo
+
+
+@menu
+* Introduction::                Purpose of the GNU C Library.
+* Error Reporting::             How the GNU Library functions report
+                                 error conditions.
+* Memory Allocation::           Your program can allocate memory dynamically
+                                 and manipulate it via pointers.
+* Character Handling::          Character testing and conversion functions.
+* String and Array Utilities::  Utilities for copying and comparing
+                                 strings and arrays.
+* Extended Characters::         Support for extended character sets.
+* Locales::                     The country and language can affect
+                                 the behavior of library functions.
+* Searching and Sorting::       General searching and sorting functions.
+* Pattern Matching::            Matching wildcards and regular expressions,
+                                 and shell-style ``word expansion''.
+* I/O Overview::                Introduction to the I/O facilities.
+* Streams: I/O on Streams.      High-level, portable I/O facilities.
+* Low-Level I/O::               Low-level, less portable I/O.
+* File System Interface::       Functions for manipulating files.
+* Pipes and FIFOs::             A simple interprocess communication mechanism.
+* Sockets::                     A more complicated interprocess communication
+                                 mechanism, with support for networking.
+* Low-Level Terminal Interface::How to change the characteristics
+                                 of a terminal device.
+* Mathematics::                 Math functions (transcendental functions,
+                                 random numbers, absolute value, etc.).
+* Arithmetic::                  Low-level arithmetic functions.
+* Date and Time::               Functions for getting the date and time,
+                                 and for conversion between formats.
+* Non-Local Exits::             The @code{setjmp} and @code{longjmp} facilities.
+* Signal Handling::             All about signals; how to send them,
+                                 block them, and handle them.
+* Process Startup::             Writing the beginning and end of your program.
+* Processes::                   How to create processes and run other programs.
+* Job Control::                 All about process groups and sessions.
+* Users and Groups::            How users are identified and classified.
+* System Information::          Getting information about the
+                                 hardware and software configuration
+                                 of the machine a program runs on.
+* System Configuration::        Parameters describing operating system limits.
+
+Appendices
+
+* Language Features::           C language features provided by the library. 
+
+* Library Summary::             A summary showing the syntax, header file,
+                                 and derivation of each library feature.
+* Maintenance::                 How to install and maintain the GNU C Library.
+* Copying::                     The GNU Library General Public License says
+                                 how you can copy and share the GNU C Library.
+
+Indices
+
+* Concept Index::               Index of concepts and names.
+* Type Index::                  Index of types and type qualifiers.
+* Function Index::              Index of functions and function-like macros.
+* Variable Index::              Index of variables and variable-like macros.
+* File Index::                  Index of programs and files.
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Getting Started::             Getting Started
+* Standards and Portability::   Standards and Portability
+* Using the Library::           Using the Library
+* Roadmap to the Manual::       Roadmap to the Manual
+
+Standards and Portability
+
+* ANSI C::                      The American National Standard for the
+                                 C programming language.  
+* POSIX::                       The IEEE 1003 standards for operating systems.
+* Berkeley Unix::               BSD and SunOS.
+* SVID::                        The System V Interface Description.  
+
+Using the Library
+
+* Header Files::                How to use the header files in your programs.
+* Macro Definitions::           Some functions in the library may really
+                                 be implemented as macros.
+* Reserved Names::              The C standard reserves some names for
+                                 the library, and some for users.
+* Feature Test Macros::         How to control what names are defined.
+
+Error Reporting
+
+* Checking for Errors::         How errors are reported by library functions.
+* Error Codes::                 What all the error codes are.
+* Error Messages::              Mapping error codes onto error messages.
+
+Memory Allocation
+
+* Memory Concepts::             An introduction to concepts and terminology.
+* Dynamic Allocation and C::    How to get different kinds of allocation in C.
+* Unconstrained Allocation::    The @code{malloc} facility allows fully general
+                                 dynamic allocation.
+* Obstacks::                    Obstacks are less general than malloc
+                                 but more efficient and convenient.
+* Variable Size Automatic::     Allocation of variable-sized blocks
+                                 of automatic storage that are freed when the
+                                 calling function returns.
+* Relocating Allocator::        Waste less memory, if you can tolerate
+                                 automatic relocation of the blocks you get.
+* Memory Warnings::             Getting warnings when memory is nearly full.
+
+Unconstrained Allocation
+
+* Basic Allocation::            Simple use of @code{malloc}.
+* Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
+* Freeing after Malloc::        Use @code{free} to free a block you
+                                 got with @code{malloc}.
+* Changing Block Size::         Use @code{realloc} to make a block
+                                 bigger or smaller.
+* Allocating Cleared Space::    Use @code{calloc} to allocate a
+                                 block and clear it.
+* Efficiency and Malloc::       Efficiency considerations in use of
+                                 these functions.
+* Aligned Memory Blocks::       Allocating specially aligned memory:
+                                 @code{memalign} and @code{valloc}.
+* Heap Consistency Checking::   Automatic checking for errors.
+* Hooks for Malloc::            You can use these hooks for debugging
+				 programs that use @code{malloc}.
+* Statistics of Malloc::        Getting information about how much
+				 memory your program is using.
+* Summary of Malloc::           Summary of @code{malloc} and related functions.
+
+Obstacks
+
+* 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 both
+				 functions and 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::         
+
+Automatic Storage with Variable Size
+
+* Alloca Example::              Example of using @code{alloca}.
+* Advantages of Alloca::        Reasons to use @code{alloca}.
+* Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
+* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
+				 method of allocating dynamically and
+				 freeing automatically.
+Relocating Allocator
+
+* Relocator Concepts::		How to understand relocating allocation.
+* Using Relocator::		Functions for relocating allocation.
+
+Character Handling
+
+* Classification of Characters::Testing whether characters are
+                                 letters, digits, punctuation, etc.
+* Case Conversion::             Case mapping, and the like.
+
+String and Array Utilities
+
+* Representation of Strings::   Introduction to basic concepts.
+* String/Array Conventions::    Whether to use a string function or an
+				 arbitrary array function.
+* String Length::               Determining the length of a string.
+* Copying and Concatenation::   Functions to copy the contents of strings
+				 and arrays.
+* String/Array Comparison::     Functions for byte-wise and character-wise
+				 comparison.
+* Collation Functions::         Functions for collating strings.
+* Search Functions::            Searching for a specific element or substring.
+* Finding Tokens in a String::  Splitting a string into tokens by looking
+				 for delimiters.
+
+Extended Characters
+
+* Extended Char Intro::         Multibyte codes versus wide characters.
+* Locales and Extended Chars::  The locale selects the character codes.
+* Multibyte Char Intro::        How multibyte codes are represented.
+* Wide Char Intro::             How wide characters are represented.
+* Wide String Conversion::      Converting wide strings to multibyte code
+                                   and vice versa.
+* Length of Char::              how many bytes make up one multibyte char.
+* Converting One Char::         Converting a string character by character.
+* Example of Conversion::       Example showing why converting 
+				   one character at a time may be useful.
+* Shift State::                 Multibyte codes with "shift characters".
+
+Locales and Internationalization
+
+* Effects of Locale::           Actions affected by the choice of locale.
+* Choosing Locale::             How the user specifies a locale.
+* Locale Categories::           Different purposes for which
+                                 you can select a locale.
+* Setting the Locale::          How a program specifies the locale.
+* Standard Locales::            Locale names available on all systems.
+* Numeric Formatting::          How to format numbers for the chosen locale.
+
+Searching and Sorting 
+
+* Comparison Functions::        Defining how to compare two objects.
+				Since the sort and search facilities are
+				general, you have to specify the ordering.
+* Array Search Function::       The @code{bsearch} function.
+* Array Sort Function::         The @code{qsort} function.
+* Search/Sort Example::         An example program.
+
+Pattern Matching
+
+* Wildcard Matching::    Matching a wildcard pattern against a single string.
+* Globbing::             Finding the files that match a wildcard pattern.
+* Regular Expressions::  Matching regular expressions against strings.
+* Word Expansion::       Expanding shell variables, nested commands,
+                          arithmetic, and wildcards.
+			  This is what the shell does with shell commands.
+
+I/O Overview
+
+* I/O Concepts::                Some basic information and terminology.
+* File Names::                  How to refer to a file.
+
+I/O Concepts
+
+* Streams and File Descriptors:: The GNU Library provides two ways
+                                  to access the contents of files.
+* File Position::               The number of bytes from the
+                                 beginning of the file.
+
+File Names
+
+* Directories::                 Directories contain entries for files.
+* File Name Resolution::        A file name specifies how to look up a file.
+* File Name Errors::            Error conditions relating to file names.
+* File Name Portability::       File name portability and syntax issues.
+
+I/O on Streams
+
+* Streams::                     About the data type representing a stream.
+* Standard Streams::            Streams to the standard input and output 
+                                 devices are created for you.
+* Opening Streams::             How to create a stream to talk to a file.
+* Closing Streams::             Close a stream when you are finished with it.
+* Simple Output::               Unformatted output by characters and lines.
+* Character Input::             Unformatted input by characters and words.
+* Line Input::                  Reading a line or a record from a stream.
+* Unreading::                   Peeking ahead/pushing back input just read.
+* Formatted Output::            @code{printf} and related functions.
+* Customizing Printf::          You can define new conversion specifiers for
+                                 @code{printf} and friends.
+* Formatted Input::             @code{scanf} and related functions.
+* Block Input/Output::          Input and output operations on blocks of data.
+* EOF and Errors::              How you can tell if an I/O error happens.
+* Binary Streams::              Some systems distinguish between text files
+                                 and binary files.
+* File Positioning::            About random-access streams.
+* Portable Positioning::        Random access on peculiar ANSI C systems.
+* Stream Buffering::            How to control buffering of streams.
+* Temporary Files::             How to open a temporary file.
+* Other Kinds of Streams::      Other Kinds of Streams
+
+Unreading
+
+* Unreading Idea::              An explanation of unreading with pictures.
+* How Unread::                  How to call @code{ungetc} to do unreading.
+
+Formatted Output
+
+* Formatted Output Basics::     Some examples to get you started.
+* Output Conversion Syntax::    General syntax of conversion specifications.
+* Table of Output Conversions:: Summary of output conversions, what they do.
+* Integer Conversions::         Details of formatting integers.
+* Floating-Point Conversions::  Details of formatting floating-point numbers.
+* Other Output Conversions::    Details about formatting of strings,
+                                 characters, pointers, and the like.
+* Formatted Output Functions::  Descriptions of the actual functions.
+* Variable Arguments Output::   @code{vprintf} and friends.
+* Parsing a Template String::   What kinds of arguments does
+                                 a given template call for?
+
+Customizing Printf
+
+* Registering New Conversions::  
+* Conversion Specifier Options::  
+* Defining the Output Handler::  
+* Printf Extension Example::    
+
+Formatted Input
+
+* Formatted Input Basics::      Some basics to get you started.
+* Input Conversion Syntax::     Syntax of conversion specifications.
+* Table of Input Conversions::  Summary of input conversions and what they do.
+* Numeric Input Conversions::   Details of conversions for reading numbers.
+* String Input Conversions::    Details of conversions for reading strings.
+* Other Input Conversions::     Details of miscellaneous other conversions.
+* Formatted Input Functions::   Descriptions of the actual functions.
+* Variable Arguments Input::    @code{vscanf} and friends.
+
+Stream Buffering
+
+* Buffering Concepts::          Terminology is defined here.
+* Flushing Buffers::            How to ensure that output buffers are flushed.
+* Controlling Buffering::       How to specify what kind of buffering to use.
+
+Other Kinds of Streams
+
+* String Streams::              
+* Custom Streams::              
+
+Programming Your Own Custom Streams
+
+* Streams and Cookies::         
+* Hook Functions::              
+
+Low-Level I/O
+
+* Opening and Closing Files::   How to open and close file descriptors.
+* I/O Primitives::              Reading and writing data.
+* File Position Primitive::     Setting a descriptor's file position.
+* Descriptors and Streams::     Converting descriptor to stream or vice-versa.
+* Stream/Descriptor Precautions::  Precautions needed if you use both
+                                    descriptors and streams.
+* Waiting for I/O::             How to check for input or output
+                                 on multiple file descriptors.
+* Control Operations::          Various other operations on file descriptors.
+* Duplicating Descriptors::     Fcntl commands for duplicating descriptors.
+* Descriptor Flags::            Fcntl commands for manipulating flags
+                                 associated with file descriptors.
+* File Status Flags::           Fcntl commands for manipulating flags
+                                 associated with open files.
+* File Locks::                  Fcntl commands for implementing file locking.
+* Interrupt Input::             Getting a signal when input arrives.
+
+File System Interface
+
+* Working Directory::           This is used to resolve relative file names.
+* Accessing Directories::       Finding out what files a directory contains.
+* Hard Links::                  Adding alternate names to a file.
+* Symbolic Links::              A file that ``points to'' a file name.
+* Deleting Files::              How to delete a file, and what that means.
+* Renaming Files::              Changing a file's name.
+* Creating Directories::        A system call just for creating a directory.
+* File Attributes::             Attributes of individual files.
+* Making Special Files::        How to create special files.
+
+Accessing Directories
+
+* Directory Entries::           Format of one directory entry.
+* Opening a Directory::         How to open a directory stream.
+* Reading/Closing Directory::   How to read directory entries from the stream.
+* Simple Directory Lister::     A very simple directory listing program.
+* Random Access Directory::     Rereading part of the directory
+                                  already read with the same stream.
+
+File Attributes
+
+* Attribute Meanings::          The names of the file attributes,
+                                 and what their values mean.
+* Reading Attributes::          How to read the attributes of a file.
+* Testing File Type::           Distinguishing ordinary files,
+                                 directories, links...
+* File Owner::                  How ownership for new files is determined,
+                                 and how to change it.
+* Permission Bits::             How information about a file's access mode
+                                 is stored.
+* Access Permission::           How the system decides who can access a file.
+* Setting Permissions::         How permissions for new files are assigned,
+                                 and how to change them.
+* Testing File Access::         How to find out if your process can
+                                 access a file.
+* File Times::                  About the time attributes of a file.
+
+Pipes and FIFOs
+
+* Creating a Pipe::             Making a pipe with the @code{pipe} function.
+* Pipe to a Subprocess::        Using a pipe to communicate with a child.
+* FIFO Special Files::          Making a FIFO special file.
+
+Sockets
+
+* Socket Concepts::             Basic concepts you need to know about.
+* Communication Styles::        Stream communication, datagrams, and others.
+* Socket Addresses::            How socket names (``addresses'') work.
+* File Namespace::              Details about the file namespace.
+* Internet Namespace::          Details about the Internet namespace.
+* Open/Close Sockets::          Creating sockets and destroying them.
+* Connections::                 Operations on sockets with connection state.
+* Datagrams::                   Operations on datagram sockets.
+* Socket Options::              Miscellaneous low-level socket options.
+* Networks Database::           Accessing the database of network names.
+
+Socket Addresses
+
+* Address Formats::             About @code{struct sockaddr}.
+* Setting Address::             Binding an address to a socket.
+* Reading Address::             Reading the address of a socket.
+
+Internet Domain
+
+* Internet Address Format::     How socket addresses are specified in the
+                                 Internet namespace.
+* Host Addresses::              All about host addresses of Internet hosts.
+* Protocols Database::          Referring to protocols by name.
+* Services Database::           Ports may have symbolic names.
+* Byte Order::                  Different hosts may use different byte
+                                 ordering conventions; you need to
+                                 canonicalize host address and port number. 
+* Inet Example::                Putting it all together.
+
+Host Addresses
+
+* Abstract Host Addresses::             What a host number consists of.
+* Data type: Host Address Data Type.    Data type for a host number.
+* Functions: Host Address Functions.    Functions to operate on them.
+* Names: Host Names.                    Translating host names to host numbers.
+
+Open/Close Sockets
+
+* Creating a Socket::           How to open a socket.
+* Closing a Socket::            How to close a socket.
+* Socket Pairs::                These are created like pipes.
+
+Connections
+
+* Connecting::                  What the client program must do.
+* Listening::                   How a server program waits for requests.
+* Accepting Connections::       What the server does when it gets a request.
+* Who is Connected::            Getting the address of the
+                                 other side of a connection.
+* Transferring Data::           How to send and receive data.
+* Byte Stream Example::         An example client for communicating over a
+                                 byte stream socket in the Internet namespace.
+* Server Example::              A corresponding server program.
+* Out-of-Band Data::            This is an advanced feature.
+
+Transferring Data
+
+* Sending Data::                Sending data with @code{write}.
+* Receiving Data::              Reading data with @code{read}.
+* Socket Data Options::         Using @code{send} and @code{recv}.
+
+Datagrams
+
+* Sending Datagrams::           Sending packets on a datagram socket.
+* Receiving Datagrams::         Receiving packets on a datagram socket.
+* Datagram Example::            An example program: packets sent over a
+                                 datagram stream in the file namespace.
+* Example Receiver::            Another program, that receives those packets.
+
+Socket Options
+
+* Socket Option Functions::     The basic functions for setting and getting
+                                 socket options.
+* Socket-Level Options::        Details of the options at the socket level.
+