\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/libc.info
@settitle libc.a reference
@c %**end of header

@setchapternewpage odd
@paragraphindent 0

@ifinfo
This is the reference manual for libc.a

Copyright (c) 1996 DJ Delorie
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{libc.a reference}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1996 DJ Delorie
@end titlepage

@node    Top,       Introduction,  (dir),    (dir)
@comment node-name, next,          previous, up

@menu
* Introduction::

* Functional Categories::  All public symbols listed by
                           category

* Alphabetical List::      All public symbols in alphabetical
                           order

* Unimplemented::          Compatibility functions that either
                           always fail or do nothing

* Master Index::
@end menu

@node    Introduction, Functional Categories, Top,      Top
@comment node-name,    next,                  previous, up
@chapter Introduction

The standard C library, @file{libc.a}, is automatically linked into your
programs by the @file{gcc} control program.  It provides many of the
functions that are normally associated with C programs.  This document
gives the proper usage information about each of the functions and
variables found in @file{libc.a}. 

For each function or variable that the library provides, the definition
of that symbol will include information on which header files to include
in your source to obtain prototypes and type definitions relevant to the
use of that symbol. 

Note that many of the functions in @file{libm.a} (the math library) are
defined in @file{math.h} but are not present in libc.a.  Some are, which
may get confusing, but the rule of thumb is this---the C library
contains those functions that ANSI dictates must exist, so that you
don't need the @code{-lm} if you only use ANSI functions.  In contrast,
@file{libm.a} contains more functions and supports additional
functionality such as the @code{matherr} call-back and compliance to
several alternative standards of behavior in case of FP errors.
@xref{libm}, for more details.

Debugging support functions are in the library @file{libdbg.a}; link
your program with @samp{-ldbg} to use them.

@include libc2.tex

@node Unimplemented, Master Index, Alphabetical List, Top
@chapter Unimplemented Functions

The DJGPP standard C library is @sc{ansi}- and @sc{posix}-compliant, and
provides many additional functions for compatibility with Unix/Linux
systems.  However, some of the functions needed for this compatibility
are very hard or impossible to implement using DOS facilities.

Therefore, a small number of library functions are really just stubs:
they are provided because @sc{posix} requires them to be present in a
compliant library, or because they are widely available on Unix systems,
but they either always fail, or handle only the trivial cases and fail
for all the others.  An example of the former behavior is the function
@code{fork}: it always returns a failure indication; an example of the
latter behavior is the function @code{mknode}: it handles the cases of
regular files and existing character devices, but fails for all other
file types.

This chapter lists all such functions.  This list is here for the
benefit of programmers who write portable programs or port Unix packages
to DJGPP.

Each function below is labeled as either ``always fails'' or
``trivial'', depending on which of the two classes described above it
belongs to.  An additional class, labeled ``no-op'', includes functions
which pretend to succeed, but have no real effect, since the underlying
functionality is either always available or always ignored.

@menu
* addmntent::                Always fails.
* cfgetispeed::              No-op.
* cfgetospeed::              No-op.
* cfsetispeed::              No-op.
* cfsetospeed::              No-op.
* chown::                    Trivial.
* fcntl::                    Always fails for all operations except
                             @code{F_DUPFD} and @code{F_GETFD}.
* fork::                     Always fails.
* getgrgid::                 Trivial.
* getgrnam::                 Trivial.
* getgroups::                Trivial.
* getpwnam::                 Trivial.
* getpwuid::                 Trivial.
* lchown::                   Trivial.
* mkfifo::                   Always fails.
* mknod::                    Trivial.
* nice::                     No-op.
* pipe::                     Always fails.
* setgid::                   Trivial.
* setpgid::                  Trivial.
* setsid::                   Trivial.
* setuid::                   Trivial.
* tcdrain::                  No-op.
* tcsendbreak::              No-op.
* tcsetpgrp::                Trivial.
* umask::                    Trivial.
* vfork::                    Always fails.
* wait::                     Always fails.
* waitpid::                  Always fails.
@end menu

@node Master Index, , Unimplemented, Top
@printindex cp

@xref{Alphabetical List}.

@contents
@bye