\input texinfo @c -*-texinfo-*-
@c $Id: ctalk.texi,v 1.4 2008/11/30 17:37:25 kiesling Exp $
@c %**start of header  
@setfilename ctalk.info
@settitle Ctalk
@setchapternewpage odd
@paragraphindent 0
@c %**end of header

@set VERSION 0.0.89a

@macro idxfncite{fnname}
@cite{\fnname\} C function
@end macro

@macro idxclscite{fnname}
(@code{\fnname\} class)
@end macro

@macro mnm{methodname}
@code{\methodname\}
@end macro

@macro flnm{filename}
@code{\filename\}
@end macro

@ifinfo

@dircategory Ctalk
@direntry
* ctalk: (ctalk).	The Ctalk language reference manual.
@end direntry

This file documents Ctalk version @value{VERSION}.

Copyright @copyright{} 2007, 2008,  Robert Kiesling

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 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 ifinfo

@iftex

@titlepage
@title Ctalk Language Reference
@subtitle Object Oriented Extensions for C
@author Robert Kiesling

@page
@vskip 0pt plus 1filll

Ctalk Language Reference.  This manual describes Ctalk, version
@value{VERSION}.

Copyright @copyright{} 2007,2008, Robert Kiesling

Permission is granted to distribute this document
under the terms of the GNU Free Documentation
License. @xref{GNU Free Documentation License}.

@end titlepage

@contents

@end iftex

@ifinfo
@node Top, , (dir), (dir)
@end ifinfo
@ifhtml
@node Top, , Top, 
@end ifhtml

@c title, next, previous, up
@iftex
@chapter Introduction to Ctalk
@end iftex
@ifnottex
@chapheading Ctalk Language Reference
@end ifnottex

@iftex
Ctalk is a dialect of the C programming language that allows
programmers to use object oriented language features, like class
objects, methods, operator overloading, and inheritance, in C programs.
This manual describes Ctalk, version @value{VERSION}.

If you are not familiar with object oriented programming concepts, you
might like to read an introductory text on the subject.  Using Ctalk
requires that you are familiar with the concepts of object oriented
programming, as well as the C language.  This manual uses object
oriented programming terms extensively.

The next chapter describes how to use Ctalk to create programs and its
command line interface.  The following chapters describe the class
hierarchy, method application programming interface, the interface
with C and its run-time libraries, and finally, some simple example
programs.

@section C Language Conformance
@cindex C language conformance

Ctalk conforms as closely as possible to the C language defined by
@cite{International Standard ISO/IEC 9899}, commonly known as C99.

@section Compiler Compatibility
@cindex Compiler compatibility

Ctalk is compatible with GNU GCC, version 2.95 and later.  Ctalk
recognizes GCC extensions like function and data attributes, and the
preprocessor can use directives like @code{#include_next}.  Ctalk
recognizes but does not process deprecated language extensions and
preprocessor directives like @code{#sccs} and @code{#unassert}.

To adapt Ctalk to another compiler, you may need to provide
compiler-specific definitions.  You will also need to add your
compiler's definition file and initialization code, if necessary, to
the file, @file{src/ccompat.c}, which contains the
@code{COMPAT_INCLUDE} definition and functions for specific compilers.

The @command{ctpp} preprocessor also contains system-specific 
definitions.  Consult its documentation for details.

@chapheading Some Document Conventions

When the term, ``Ctalk,'' appears in this manual, it refers to the
programming language, and when @command{ctalk} appears, it
refers to the Ctalk program and libraries.

@table @code
@item identifier  
Names of classes, variables, methods and messages, file names, 
and source code examples appear in monospaced type.
@end table
@table @var
@item variable
Metasyntactic variables and citations appear in italic or oblique
type.
@end table
@end iftex

@menu
* Invoking::                          Command line options.
* Classes::                           The Ctalk class library.
* Methods::                           How to use and implement methods.
* C::                                 C language implementation.
* Copying::                           Ctalk is free software.
* GNU Free Documentation License::    Copying and distributing this manual.
* Index::
@end menu

@node Invoking, Classes, Top, Top
@iftex
@chapter Using Ctalk
@end iftex
@ifnottex
@heading Invoking Ctalk
@end ifnottex
@cindex Invoking @command{ctalk}

Ctalk has two parts: a preprocessor and interpreter that translates
Ctalk code into C, which a compiler can use to create an executable
program, and a run-time library, which the compiler links with the
executable.

@cindex @command{ctpp} preprocessor
Ctalk has its own C99 compatible preprocessor, @command{ctpp,}
which is described in its Texinfo manual, @flnm{ctpp.info}.

To use @command{ctalk,} you must provide at least the name of the
input file.  Normally, you also provide the name of the output file
with the @samp{-o} option.  If you use the conventions followed by GNU
C, the output file is normally the base name of the input file with
the extension @samp{.i}, as in this example.

@example
$ ctalk myprog.c -o myprog.i
@end example

The @command{ctalk} program preprocesses @flnm{myprog.c} and
translates it into standard C.  After @command{ctalk} has finished,
you can compile and link the output of @command{ctalk} to produce an
executable program.

@example
$ gcc myprog.i -o myprog -lctalk
@end example

Often, you can combine these steps.

@example
$ ctalk myprog.c -o myprog.i && gcc myprog.i -o myprog -lctalk
@end example

@cindex @code{ctcc} command
The @code{ctcc} command combines these operations.
@example
$ ctcc myprog.c
@end example

@iftex
@section Command Line Options
@end iftex
@ifnottex
@heading Command Line Options
@end ifnottex
@cindex Command Line Options

@table @code
@item -E
Preprocess the input and exit.

@item -h, --help
Print a help message and exit.

@item -I @var{dir}
Add @var{dir} to the @command{ctalk} include search path.

@item --keeppragmas
Write pragmas untranslated to the output.

@item --nolibinc
Do not include Ctalk's system headers in the output.

@item -o @var{file}
Write the @command{ctalk} output to @var{file.}

@item -P
Do not output line number information.

@item -s @var{dir}
Add @var{dir} to the compiler system include search path.

@item -V
Print the @command{ctalk} version number and exit.

@item -v
Print verbose warnings.

@item --warnextension
Print warnings for some compiler extensions.
@end table

@node Classes, Methods, Invoking, Top
@iftex
@chapter Classes
@end iftex
@ifnottex
@heading Classes
@end ifnottex
@cindex Classes

Class library files contain class and method definitions and are
located in the @flnm{classes} subdirectory.  After installation, the
libraries are in a @flnm{ctalk} include subdirectory defined by the
macro @var{CLASSLIBDIR} when the program is built.

@iftex
@section Class Hierarchy
@example
Object
 Collection
  Array
  List
   AssociativeArray
  Stream
   FileStream
    DirectoryStream
    ReadFileStream
    WriteFileStream
   TerminalStream
    Win32TerminalStream
 Event
  Application
  Exception
   SystemErrnoException
  SignalEvent
   SignalHandler
 Expr
  CFunction
 Magnitude
  Character
   String
  Float
  Integer
   Boolean
   Time
  LongInteger
 Symbol
  Key
@end example
@end iftex
@ifnottex
@menu
* Object::
*  Collection::
*   Array::
*   List::
*    AssociativeArray::
*   Stream::
*    FileStream::
*     DirectoryStream::
*     ReadFileStream::
*     WriteFileStream::
*    TerminalStream::
*     Win32TerminalStream::
*  Event::
*   Application::
*   Exception::
*    SystemErrnoException::
*   SignalEvent::
*    SignalHandler::
*  Expr::
*   CFunction::
*  Magnitude::
*   Character::
*    String::
*   Float::
*   Integer::
*    Boolean::
*    Time::
*   LongInteger::
*  Symbol::
*   Key::
@end menu
@end ifnottex

@node Object, Collection, , Classes

@iftex
@section @code{Object} class
@end iftex
@ifnottex
@subheading @code{Object} Class
@end ifnottex

@cindex @code{Object} class

Ctalk defines the @code{Object} class by default at run time.  All
other classes are subclasses of @code{Object}.

@subsubheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Object}

@item value
The value of the object.  For classes that correspond to the C data
types: @code{Character}, @code{Float}, @code{Integer},
@code{LongInteger}, and @code{String}, ctalk formats the value as it
would appear as if output by the C @code{printf} function.

When you use one of these classes in a C expression, ctalk translates
the object's value to its C data type.

Other classes may define @code{value} to return class specific data.

@end table

@subsubheading Instance Methods

@table @code

@cindex @mnm{addInstanceVariable} method @idxclscite{Object}
@item @mnm{addInstanceVariable} (@code{char *}@var{name}, @code{OBJECT *}@var{value})
Add instance variable @var{name} with @var{value} to the receiver.

@cindex @mnm{class} method @idxclscite{Object}
@item @mnm{class} (@code{char *}@var{classname})
Declare a new class @code{classname}.

@cindex @mnm{className} method @idxclscite{Object}
@item @mnm{className} (@code{void})
Return a @code{String} object containing the class name of the receiver.

@cindex @mnm{copy} method @idxclscite{Object}
@item @mnm{copy} (@code{Object} @var{source_object}) 
Copy the object of @var{source_object} to the receiver.

@cindex @mnm{delete} method @idxclscite{Object}
@item @mnm{delete} (@code{void})
Delete an object and its instance variables.

@cindex @mnm{is} method @idxclscite{Object}
@item @mnm{is} (@code{char *}@var{className})
Return an @code{Integer} value of @code{TRUE} if the receiver is a
member of the class given in the argument, @code{FALSE} otherwise.

@cindex @mnm{instanceMethod} method @idxclscite{Object}
@item @mnm{instanceMethod} @code{[}@code{char *}@var{alias}@code{]}, @code{char *}@var{name}, (@var{args})
Declare a method of the receiver's class with the name @var{name}, 
with the arguments @var{args}, and, optionally, with the alias
@var{alias}.  @xref{Methods}.

@cindex @mnm{name} method @idxclscite{Object}
@item @mnm{name} (@code{void})
Return the name of the receiver as a @code{String} object.

@cindex @mnm{new} method @idxclscite{Object}
@item @mnm{new} (@code{char *}@var{label})
Create an object of the receiver's class with the name @var{label}.

@example
  String new myString;
@end example

@cindex @mnm{value} method @idxclscite{Object}
@item @mnm{value} (@code{void})
Returns the value of the receiver object.  When you use an object
without a method, ctalk uses the @mnm{value} message to return the
object's value.  For example,

@example
  printf ("%s", stringObject);
@end example

is the same as,

@example
  printf ("%s", stringObject value);
@end example

@end table

@node Collection, Event, Object, Classes

@iftex
@section @code{Collection} class
@end iftex
@ifnottex
@subheading @code{Collection} Class
@end ifnottex

@cindex @code{Collection} class

The @code{Collection} class is the superclass of all objects that
contain groups of objects.

@node Array, List, , Classes
@iftex
@section @code{Array} Class
@end iftex
@ifnottex
@subheading @code{Array} Class
@end ifnottex
@cindex @code{Array} class

The @code{Array} class contains objects ordered by index from
0... n.

@subsubheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Array}
@item value
The value is the name of the array.

@item 0... n
These instance variables refer to the elements of the array.

@end table

@subsubheading Methods

@table @code

@cindex @mnm{=} method @idxclscite{Array}
@item @mnm{=} (@code{Array} @var{a})
Set the receiver array's elements equal to the argument array's
elements.

@cindex @mnm{at} method @idxclscite{Array}
@item @mnm{at} (@code{int} @var{n})
Retrieve the @var{n}th element of the receiver array.

@cindex @mnm{atPut} method @idxclscite{Array}
@item @mnm{atPut} (@code{int} @var{index}, @code{OBJECT *}@var{item})
Add @var{item} to the receiver at @var{index}.

@cindex @mnm{map} method @idxclscite{Array}
@item @mnm{map} (@var{method})
Executes @var{method} with each element of the receiver.

The argument, @var{method}, is a method that should belong to the same
class as the receiver. When @var{method} is executed, its receiver is
each successive array element, and @var{method} can refer to it with
@code{self.}

@cindex @mnm{size} method @idxclscite{Array}
@item @mnm{size} (@code{void})
Return the number of elements in the receiver.

@end table

@node List, AssociativeArray, Array, Classes
@iftex
@section @code{List} Class
@end iftex
@ifnottex
@subheading @code{List} Class
@end ifnottex
@cindex @code{List} class

Objects of class @code{List} allow sets of objects to be sequentially
added, removed, and used as method receivers.

@subheading Instance Methods

@table @code
@cindex @mnm{isEmtpy} method @idxclscite{List}
@item @mnm{isEmtpy} (@code{void})
Return @code{TRUE} if the list is emtpy, @code{FALSE} otherwise.

@cindex @mnm{map} method @idxclscite{List}
@item @mnm{map} (@code{OBJECT *(*}@var{method}@code{)()})
Execute @var{method}, an instance method of class @code{List,} for
each member of the receiver list.  Within @var{method}, @code{self}
refers to the list element.

@cindex @mnm{new} method @idxclscite{List}
@item @mnm{new} (@code{char *}@var{name})
Create the @code{List} object @var{name}.

@cindex @mnm{pop} method @idxclscite{List}
@item @mnm{pop} (@code{void})
Remove the object from the end of the receiver's list and return the
object.

@cindex @mnm{push} method @idxclscite{List}
@item @mnm{push} (@code{OBJECT *(*}@var{object}@code{)(int)})
Add @var{object} to the end of the receiver's list contents.

@cindex @mnm{shift} method @idxclscite{List}
@item @mnm{shift} (@code{OBJECT *(*}@var{object}@code{)(int)})
Add @var{object} as the first element of the receiver's list contents.

@cindex @mnm{unshift} method @idxclscite{List}
@item @mnm{unshift} (@code{void})
Remove the first object from the receiver's list and return the
object.

@cindex @mnm{value} method @idxclscite{List}
@item @mnm{value} (@code{void})
Class @code{List} objects have no @code{value} instance variable.
Instead, return the @code{List} object's contents, or @code{NULL} if
the list is empty.
@end table

@node AssociativeArray, Stream, List, Classes
@iftex
@section @code{AssociativeArray} Class
@end iftex
@ifnottex
@subheading @code{AssociativeArray} Class
@end ifnottex
@cindex @code{AssociativeArray} class

Objects of class @code{AssociativeArray} contain members that are
stored and retrieved using @code{Key} objects. @xref{Key}.  


@subheading Instance Methods

@table @code
@cindex @mnm{at} method @idxclscite{AssociativeArray}
@item @mnm{at} (@code{char *}@var{key})
Retrieve the element of the receiver array stored at @var{key}.

@cindex @mnm{atPut} method @idxclscite{AssociativeArray}
@item @mnm{atPut} (@code{char *}@var{key}, @code{OBJECT *}@var{item})
Add @var{item} to the receiver at @var{key}.

@cindex @mnm{keyAt} method @idxclscite{AssociativeArray}
@item @mnm{keyAt} (@code{char *}@var{keyname})
Return the @code{Key} object with @var{keyname}.

@cindex @mnm{map} method @idxclscite{AssociativeArray}
@item @mnm{map} (@code{OBJECT *(*}@var{method}@code{)()})
Execute @var{method}, an instance method of class
@code{AssociativeArray,} for each member of the receiver array.  Within
@var{method}, @code{self} refers to the array element.

@cindex @mnm{new} method @idxclscite{AssociativeArray}
@item @mnm{new} (@code{char *}@var{arrayName})
Create a new @code{AssociativeArray} with the name @var{arrayName}.

@cindex @mnm{setValue} method @idxclscite{AssociativeArray}
@item @mnm{setValue} (@code{void})
A wrapper method for @mnm{getValue} in class @code{Key.} If received
by an instance of @code{Collection} or its subclasses instead of a
@code{Key} object, this method generates an exception.
@end table

@node Stream, , AssociativeArray, Classes

@iftex
@section @code{Stream} Class
@end iftex
@ifnottex
@subheading @code{Stream} Class
@end ifnottex
@cindex @code{Stream} class

@code{Stream} class is the superclass of classes that provide
sequential read and write access to objects and I/O devices.

@node FileStream, , , Classes

@iftex
@section @code{FileStream} Class
@end iftex
@ifnottex
@subheading @code{FileStream} Class
@end ifnottex
@cindex @code{FileStream} class

@code{FileStream} and its subclasses contain methods and variables
that read and write to files and other I/O devices.

@subheading Instance Variables

@table @code
@item streamMode (Class Integer)
File permissions mode.
@item streamDev   (Class Integer)
Device ID of a file.
@item streamRdev  (Class Integer)
Device ID if a special file.
@item streamSize  (Class LongInteger)
File size in bytes.
@item streamAtime (Class LongInteger)
Time of last file access.
@item streamMtime (Class LongInteger)
Time of last file modification.
@item streamCtime (Class LongInteger)
Time of last file status change.
@item streamPos   (Class LongInteger)
Offset of read or write operation in the file,
if a regular file.
@item streamErrno
System error number of the last file operation, 
EOF at the end of the file, or 0 on success.
@item streamPath
A @code{String} object, containing the path name of a 
regular file.
@end table

@subheading Class Variables

None.

@subheading Instance Methods

@table @code
@cindex @mnm{=} method @idxclscite{FileStream}
@item @mnm{=} @var{arg}
Assign the value of the file stream in the argument to the receiver.  
This method does not duplicate the file handle.

@cindex @mnm{streamEof} method @idxclscite{FileStream}
@item @mnm{streamEof}
Returns a non-zero @code{Integer} object if at the end of the receiver's
file stream, a zero-value @code{Integer} otherwise.

@cindex @mnm{isDir} method @idxclscite{FileStream}
@item @mnm{isDir} (@code{void})
Return an @code{Integer} object that evaluates to @code{TRUE} if the
receiver is a directory, @code{FALSE} otherwise.

@cindex @mnm{statStream} method @idxclscite{FileStream}
@item @mnm{statStream} (@code{void})
Wrapper method for the C @code{fstat(2)} function.  The method fills
in the @code{streamMode}, @code{streamDev}, @code{StreamRdev},
@code{streamSize}, @code{streamAtime}, @code{streamMtime}, and
@code{streamCtime} instance variables of the receiver.  Returns
@samp{0} (class @code{Integer}) on success or @samp{-1} (class
@code{Integer}) if there is an error.

@cindex @mnm{size} method @idxclscite{FileStream}
@item @mnm{size}
Returns the size of the receiver's file as a @code{LongInteger}.

@end table

@subheading Class Methods

None.

@node DirectoryStream, ReadFileStream, , Classes
@iftex
@section @code{DirectoryStream} Class
@end iftex
@ifnottex
@subheading @code{DirectoryStream} Class
@end ifnottex
@cindex @code{DirectoryStream} class

The @code{DirectoryStream} class contains methods 
for creating and deleting directories.

@cindex Directory mode
@cindex @code{CTALK_DIRECTORY_MODE} macro
The default mode for new directories is @code{0755}
(@samp{drwxr-xr-x}) modified by the user's @code{UMASK}.  Programs can
change the default directory permissions by redefining the macro
@code{CTALK_DIRECTORY_MODE}.

The methods @code{chDir}, @code{mkDir}, and @code{rmDir} raise a
@code{SystemErrnoException} on error and return an @code{Integer} with
the value @code{-1}.

@subheading Instance Methods
@table @code

@cindex @mnm{chDir} method @idxclscite{DirectoryStream}
@item chDir (@code{char *}@var{dir})
Change to the directory @var{dir}.

@cindex @mnm{directoryList} method @idxclscite{DirectoryStream}
@item directoryList (@code{char *}@var{dirname}, @code{List} @var{dirlist})
List directory @var{dirname}, and store it in the @code{List} @var{dirlist}.

@cindex @mnm{getCwd} method @idxclscite{DirectoryStream}
@item getCwd (@code{void})
Return the current directory as a @code{String} object.

@cindex @mnm{mkDir} method @idxclscite{DirectoryStream}
@item mkDir (@code{char *}@var{directoryname})
Create the directory @var{directoryname}.

@cindex @mnm{rmDir} method @idxclscite{DirectoryStream}
@item rmDir (@code{char *}@var{directoryname})
Delete the directory @var{directoryname}.
@end table

@node ReadFileStream, WriteFileStream, DirectoryStream, Classes

@iftex
@section @code{ReadFileStream} Class
@end iftex
@ifnottex
@subheading @code{ReadFileStream} Class
@end ifnottex
@cindex @code{ReadFileStream} class

The @code{ReadFileStream} class contains methods and objects
for reading files.

@subheading Instance Variables

None

@subheading Class Variables

@table @code
@cindex @code{stdinStream} @idxclscite{ReadFileStream}
@cindex @code{stdin}
@item stdinStream
The @code{stdinStream} object contains the value of the 
application's standard input channel.
@end table

@subheading Instance Methods

@table @code

@cindex closeStream method @idxclscite{ReadFileStream}
@item closeStream
Close the receiver's input file stream.  Note that @code{closeStream} does 
@emph{not} delete the receiver object.  You must call @code{delete} 
(Class Object) to delete the object explicitly.  Deleting global 
and local objects is still not complete - you must check the receiver
and argument stacks, and the local variables of the function or
method, to make sure that the object is removed from its dictionary.

@cindex @mnm{new} method @idxclscite{ReadFileStream}
@item @mnm{new} @var{name}
Creates a new @code{ReadFileStream} object called @var{name}.

@cindex @mnm{openOn} method @idxclscite{ReadFileStream}
@item @mnm{openOn} @var{path}
Open file @var{path} with mode @samp{r} and set the receiver's 
value to the file input stream.

@cindex @mnm{readAll} method @idxclscite{ReadFileStream}
@item @mnm{readAll}
Returns a String with the contents of the receiver's file stream.

@cindex @mnm{readChar} method @idxclscite{ReadFileStream}
@item @mnm{readChar}
Returns a Character from the stream defined by the receiver, or 
@samp{EOF} at the end of the input.

@cindex @mnm{readLine} method @idxclscite{ReadFileStream}
@item @mnm{readLine}
Returns a String of characters up to and including the next
newline of the stream defined by the receiver, or a String 
containing @samp{EOF} at the end of the input.

@cindex @mnm{value} method @idxclscite{ReadFileStream}
@item @mnm{value}
Returns the receiver's @code{value} instance variable.

@end table


@subheading Class Methods

@table @code 
@cindex @mnm{classInit} method @idxclscite{ReadFileStream}
@item classInit
Called automatically by @code{new} when the first
@code{ReadFileStream} object is created.  Initializes 
@code{stdinStream}.
@end table

@c @node ReadWriteFileStream, WriteFileStream, ReadFileStream, Classes

@c @iftex
@c @section @code{ReadFileStream} Class
@c @end iftex
@c @ifnottex
@c @subheading @code{ReadFileStream} Class
@c @end ifnottex
@c @cindex @code{ReadWriteFileStream} class

@node WriteFileStream, , ReadFileStream, Classes
@iftex
@section @code{WriteFileStream} Class
@end iftex
@ifnottex
@subheading @code{WriteFileStream} Class
@end ifnottex
@cindex @code{WriteFileStream} class

Class @code{WriteFileStream} provides objects and methods for writing
to files, including the application's @code{stdout} and @code{stderr}
output channels.


@subheading Instance Variables

None

@subheading Class Variables

@table @code
@cindex @code{stdoutStream} @idxclscite{WriteFileStream}
@cindex @code{stdout}
@item stdoutStream
The @code{stdoutStream} object contains the application's 
standard output channel.

@cindex @code{stderrStream} @idxclscite{WriteFileStream}
@cindex @code{stderr}
@item stderrStream
The @code{stderrStream} object contains the application's 
standard error channel.
@end table

@subheading Instance Methods

@table @code

@cindex @mnm{closeStream} method @idxclscite{WriteFileStream}
@item @mnm{closeStream}
Close the receiver's output file stream.  Note that @code{closeStream} does 
@emph{not} delete the receiver object.  You must call @code{delete} 
(Class @code{Object}) to delete the object explicitly.  Deleting global 
and local objects is still not complete - you must check the receiver
and argument stacks, and the local variables of the function or
method, to make sure that the object is removed from its dictionary.

@cindex @mnm{new} method @idxclscite{WriteFileStream}
@item @mnm{new} @var{name}
Creates a new @code{WriteFileStream} object called @var{name}.

@cindex @mnm{openOn} method @idxclscite{WriteFileStream}
@item @mnm{openOn} @var{path}
Open file @var{path} with mode @samp{w} and set the receiver's 
value to the file output stream.

@cindex @mnm{printOn} method @idxclscite{WriteFileStream}
@item @mnm{printOn} (@code{char *}@var{fmt}, ...)
Format and print the method's arguments to the receiver, which must be
a @code{WriteFileStream} object that has been opened with @mnm{openOn.}

@cindex @mnm{value} method @idxclscite{WriteFileStream}
@item @mnm{value}
Returns the receiver's @code{value} instance variable.

@cindex @mnm{writeChar} method @idxclscite{WriteFileStream}
@item @mnm{writeChar} @var{char}
Writes @var{char} to the receiver's output file stream.

@anchor{writeFormat--class WriteFileStream}
@cindex @mnm{writeFormat} method @idxclscite{WriteFileStream}
@item @mnm{writeFormat} (@code{char *}@var{fmt}, ...)
Writes its arguments to the receiver using format @var{fmt}.

@cindex @mnm{writeStream} method @idxclscite{WriteFileStream}
@item @mnm{writeStream} @var{string}
Write @var{string} to the receiver's output file stream.
@end table

@node TerminalStream, , , Classes
@iftex
@section @code{TerminalStream} Class
@end iftex
@ifnottex
@subheading @code{TerminalStream} Class
@end ifnottex
@cindex @code{TerminalStream} class

@code{TerminalStream} is the superclass of terminal classes that provide
terminal and console input and output capabilities.

@node Win32TerminalStream, , , Classes
@iftex
@section @code{Win32TerminalStream} Class
@end iftex
@ifnottex
@subheading @code{Win32TerminalStream} Class
@end ifnottex
@cindex @code{Win32TerminalStream} class

The @code{Win32TerminalStream} class provides basic text-mode
formatting for @code{cmd.exe} consoles, using DJGPP's @file{conio.h}
capabilities.  This class is not strictly a stream, and is likely to
remain limited to displays in the @code{cmd.exe} window until 
Ctalk can implement a genuine @cite{fork(3)} system call for non-POSIX
systems. 

@subsubheading Instance Methods

@table @code
@cindex @mnm{cGetStr} method @idxclscite{Win32TerminalStream}
@item cGetStr (void)
Returns a @code{String} object that contains input typed by
the user.  The input is echoed to the console.

@cindex @mnm{clear} method @idxclscite{Win32TerminalStream}
@item clear (void)
Clears the terminal window and moves the cursor to the upper 
left-hand cornet.

@cindex @mnm{cPutStr} method @idxclscite{Win32TerminalStream}
@item cPutStr (@code{char *}@var{str}
Prints @var{str} to the console at the current cursor position.

@cindex @mnm{gotoXY} method @idxclscite{Win32TerminalStream}
@item gotoXY (@code{int} @var{x}, @code{int}@var{y})
Positions the cursor at character position @var{x}, @var{y}.  
The upper left-hand corner of the screen is row 1, column 1.

@cindex @mnm{screenColor} @idxclscite{Win32TerminalStream}
@item screenColor (@code{char *}@var{fgcolor}, @code{char*}@var{bgcolor})
Sets the window's foreground and background colors for following 
writes using @mnm{cPutStr,} above.  The arguments are class
@code{String,} and may have the following values.
@example
black
blue
green
cyan
red
magenta
brown
lightgray
darkgray
lightblue
lightgreen
lightcyan
lightred
yellow
white
@end example

@end table


@node Event, Expr, Collection, Classes
@iftex
@section @code{Event} Class
@end iftex
@ifnottex
@subheading @code{Event} Class
@end ifnottex
@cindex @code{Event} class

@code{Event} and its subclasses represent system and language events
like applications, errors, input, and signals, and these classes
provide the methods that receive and handle the events.

@node Application, , , Classes
@iftex
@section @code{Application} Class
@end iftex
@ifnottex
@subheading @code{Application} Class
@end ifnottex
@cindex @code{Application} class

Objects of @code{Application} class represent running programs.  This
class provides basic methods for initializing and exiting programs.

@node Exception, , , Classes
@iftex
@section @code{Exception} Class
@end iftex
@ifnottex
@subheading @code{Exception} Class
@end ifnottex
@cindex @code{Exception} class

@code{Exception} is the superclass of classes that handle system and
language error events, and these classes provides the handlers to respond to the events.

@subsubheading Exception Codes

Exceptions have a corresponding integer code.  The following macros
correspond to the actual exceptions.

@cindex @code{SUCCESS_X} exception
@cindex @code{CPLUSPLUS_HEADER_X} exception
@cindex @code{MISMATCHED_PAREN_X} exception
@cindex @code{FALSE_ASSERTION_X} exception
@cindex @code{FILE_IS_DIRECTORY_X} exception
@cindex @code{FILE_ALREADY_OPEN_X} exception
@cindex @code{UNDEFINED_PARAM_CLASS_X} exception
@cindex @code{PARSE_ERROR_X} exception
@cindex @code{INVALID_OPERAND_X} exception
@cindex @code{PTR_CONVERSION_X} exception
@cindex @code{UNDEFINED_CLASS_X} exception
@cindex @code{UNDEFINED_METHOD_X} exception
@cindex @code{METHOD_USED_BEFORE_DEFINE_X} exception
@cindex @code{SELF_WITHOUT_RECEIVER_X} exception
@cindex @code{UNDEFINED_LABEL_X} exception
@cindex @code{UNDEFINED_TYPE_X} exception
@cindex @code{UNDEFINED_RECEIVER_X} exception
@cindex @code{UNKNOWN_FILE_MODE_X} exception
@cindex @code{INVALID_VARIABLE_DECLARATION_X} exception
@cindex @code{WRONG_NUMBER_OF_ARGUMENTS_X} exception
@cindex @code{SIGNAL_EVENT_X} exception
@cindex @code{INVALID_RECEIVER_X} exception
@example
SUCCESS_X
CPLUSPLUS_HEADER_X
MISMATCHED_PAREN_X
FALSE_ASSERTION_X
FILE_IS_DIRECTORY_X
FILE_ALREADY_OPEN_X
UNDEFINED_PARAM_CLASS_X
PARSE_ERROR_X
INVALID_OPERAND_X
PTR_CONVERSION_X
UNDEFINED_CLASS_X
UNDEFINED_METHOD_X
METHOD_USED_BEFORE_DEFINE_X
SELF_WITHOUT_RECEIVER_X
UNDEFINED_LABEL_X
UNDEFINED_TYPE_X
UNDEFINED_RECEIVER_X
UNKNOWN_FILE_MODE_X
INVALID_VARIABLE_DECLARATION_X
WRONG_NUMBER_OF_ARGUMENTS_X
SIGNAL_EVENT_X
INVALID_RECEIVER_X
@end example

@subsubheading Instance Methods

@table @code
@cindex @mnm{handle} method @idxclscite{Exception}
@item handle (@code{void})
Execute the exception handler for the next pending method.

@cindex @mnm{pending} method @idxclscite{Exception}
@item pending (@code{void})
Return @code{TRUE} if any exceptions are pending, @code{FALSE} otherwise.

@cindex @mnm{raiseCriticalException} @idxclscite{Exception}
@item raiseCriticalException (@code{EXCEPTION }@var{ex}, @code{char *}@var{text})
Raise a critical exception.  A critical exception is similar to a
normal exception, below, except that it is not caught internally.  The
application must catch the exception with @code{pending} and @code{handle.}

You should use one of the @code{EXCEPTION} macros defined above
as the argument @var{ex}.

@cindex @mnm{raiseException} @idxclscite{Exception}
@item raiseException (@code{EXCEPTION }@var{ex}, @code{char *}@var{text})
Raise an exception.  You should use one of the @code{EXCEPTION} macros
defined above as the argument @var{ex}.
@end table

@node SystemErrnoException, , , Classes
@iftex
@section @code{SystemErrnoException} class
@end iftex
@ifnottex
@subheading @code{SystemErrnoException} Class
@end ifnottex
@cindex @code{SystemErrnoException} Class

The @code{SystemErrnoException} class raises exceptions for errors
reported by the C library's @code{errno} variable or macro.

@subsubheading Class Variables

@table @code
@cindex @code{sysErrno} @idxclscite{SystemErrnoException}
@cindex @code{errno}
@item sysErrno
The @code{sysErrno} object contains the value of the C library's 
@code{errno} variable or macro.
@end table

@subsubheading Instance Methods

@table @code
@cindex @mnm{raiseCriticalException} method @idxclscite{SystemErrnoException}
@item raiseCriticalException (@code{char *}@var{data})
Raises an exception and executes the exception handler, then
exits the program with an error code of @code{errno.}

@cindex @mnm{raiseException} method @idxclscite{SystemErrnoException}
@item raiseException (@code{char *}@var{data})
Sets the value of the @code{sysErrno} class variable and raises an
exception if the C library's @code{errno} variable or macro returns a
nonzero value.
@end table

@node SignalEvent, , , Classes
@iftex
@section @code{SignalEvent} Class
@end iftex
@ifnottex
@subheading @code{SignalEvent} Class
@end ifnottex
@cindex @code{SignalEvent} class

The @code{SignalEvent} class provides methods and variable definitions
for Ctalk programs to handle signal events.

Signal handler (@ref{SignalHandler}) methods act like C functions
when a program installs them to handle signals.  The signal handler
methods cannot, in most cases, create objects.  Ctalk provides the
C function @code{__ctalkNewSignalEventInternal} to create and queue
@code{SignalEvent} objects from the handler.  

Here is an example of a signal handler method that creates
@code{SignalEvent} objects.
@example
#include <time.h>

SignalHandler instanceMethod handleSignal (__c_arg__ int signo) @{
  time_t t;
  char buf[MAXLABEL];
  noMethodInit;
  t = time (NULL);
  /* Format the system time and add it to the SignalEvent object's
     data instance variable. */
  __ctalkDecimalIntegerToASCII (t, buf);
  __ctalkNewSignalEventInternal (signo, getpid (), buf);
  methodReturnNULL
@}
@end example

Refer to @ref{Method functions}, and @ref{__ctalkNewSignalEventInternal}.

@subsubheading Class Variables

@table @code
@cindex @code{pendingEvents} @idxclscite{SignalEvent}
@item pendingEvents
A @code{List} of pending signal events.
@end table

@subsubheading Instance Variables

@table @code
@cindex @code{processID} @idxclscite{SignalHandler}
@item processID
An @code{Integer} that contains the process ID of the program that
received the signal.

@cindex @code{sigNo} @idxclscite{SignalHandler}
@item sigNo
An @code{Integer} that contains the signal number of the handler.

@cindex @code{data} @idxclscite{SignalHandler}
@item data
A @code{String} object that contains data from the signal handler.
@end table

@subsubheading Class Methods
@table @code
@cindex @mnm{classInit} method @idxclscite{SignalEvent}
@item @mnm{classInit} (@code{void})
Initialize the @code{SignalHandler} class.  
@end table

@subsubheading Instance Methods

@table @code
@cindex @mnm{=} method @idxclscite{SignalEvent}
@item @mnm{=} (@code{SignalEvent} @var{event})
Assign the instance variable values of the argument, @var{event}, to
the receiver.

@cindex @mnm{getPID} method @idxclscite{SignalEvent}
@item @mnm{getPID} (@code{void})
Set the @code{SignalEvent} object's @code{pid} instance variable to
the program's process ID.

@cindex @mnm{new} method @idxclscite{SignalEvent}
@item @mnm{new} (@code{char *}@var{name})
Create a new @code{SignalEvent} object with name @var{name}.

@cindex @mnm{nextEvent} method @idxclscite{SignalEvent}
@item @mnm{nextEvent} (@code{void})
Return the next @code{signalEvent} object from the class'
@code{pendingEvents} queue.

@cindex @mnm{pending} method @idxclscite{SignalEvent}
@item @mnm{pending} (@code{void})
Return @code{TRUE} if the class' @code{pendingEvents} queue contains
@code{SignalEvent} event objects, @code{FALSE} otherwise.

@cindex @mnm{queueEvent} method @idxclscite{SignalEvent}
@item @mnm{queueEvent} (@code{void})
Add the receiver to the class' @code{pendingEvents} queue.

@end table

@node SignalHandler, , , Classes
@iftex
@section @code{SignalHandler} Class
@end iftex
@ifnottex
@subheading @code{SignalHandler} Class
@end ifnottex
@cindex @code{SignalHandler} class

Class @code{SignalHandler} provides the methods that install handlers
for signals from the operating system.  

Applications can also define signal handlers with this class.  Signal
handler methods need to use the calling conventions of C functions.
@xref{Method functions}.

For POSIX signals, you can use a method to set the signal number.
@cindex @mnm{setSigHup} method @idxclscite{SignalHandler}
@cindex @mnm{setSigInt} method @idxclscite{SignalHandler}
@cindex @mnm{setSigQuit} method @idxclscite{SignalHandler}
@cindex @mnm{setSigIll} method @idxclscite{SignalHandler}
@cindex @mnm{setSigAbrt} method @idxclscite{SignalHandler}
@cindex @mnm{setSigFpe} method @idxclscite{SignalHandler}
@cindex @mnm{setSigSegv} method @idxclscite{SignalHandler}
@cindex @mnm{setSigPipe} method @idxclscite{SignalHandler}
@cindex @mnm{setSigAlrm} method @idxclscite{SignalHandler}
@cindex @mnm{setSigTerm} method @idxclscite{SignalHandler}
@cindex @mnm{setSigUsr1} method @idxclscite{SignalHandler}
@cindex @mnm{setSigUsr2} method @idxclscite{SignalHandler}
@cindex @mnm{setSigChld} method @idxclscite{SignalHandler}
@cindex @mnm{setSigCont} method @idxclscite{SignalHandler}
@cindex @mnm{setSigTstp} method @idxclscite{SignalHandler}
@cindex @mnm{setSigTtin} method @idxclscite{SignalHandler}
@cindex @mnm{setSigTtou} method @idxclscite{SignalHandler}
@example
Signal    Method       Signal
------    ------       ------
SIGHUP    setSigHup    Termination of terminal process.
SIGINT    setSigInt    Interrupt from keyboard.
SIGQUIT   setSigQuit   Quit from keyboard.
SIGILL    setSigIll    Illegal instruction.
SIGABRT   setSigAbrt   Abort from C library abort(3).
SIGFPE    setSigFpe    Floating point exception.
SIGKILL   -            Kill process - non-catchable.
SIGSEGV   setSigSegv   Invalid memory address.
SIGPIPE   setSigPipe   Broken pipe or write to pipe with no reader.
SIGALRM   setSigAlrm   Timer signal from C library alarm(2).
SIGTERM   setSigTerm   Process termination.
SIGUSR1   setSigUsr1   User defined.
SIGUSR2   setSigUsr2   User defined.
SIGCHLD   setSigChld   Child process stopped or terminated.
SIGCONT   setSigCont   Continue stopped process.
SIGSTOP   -            Stop process - non-catchable.
SIGTSTP   setSigTstp   Stop from tty.
SIGTTIN   setSigTtin   Terminal input for background process.
SIGTTOU   setSigTtou   Terminal output from background process.
@end example

@cindex @mnm{setSigNo} method @idxclscite{SignalHandler}
You can also set system-specific signals by number with
@mnm{setSigNo.}  

@code{SignalHandler} methods can also send @code{SignalEvent}
objects to Ctalk programs.  Refer to @ref{Method functions},
@ref{SignalEvent}, and @ref{__ctalkNewSignalEventInternal}. 


@subsubheading Instance Variables

@table @code
@cindex @code{attributes} instance variable @idxclscite{SignalHandler}
@item attributes
The value of @code{attributes} can be one of the following.
@table @code
@item SIG_DEFAULT
The application uses the operating system's default signal handler for
the signal.  The operating system's documentation describes how it
handles signals.
@item SIG_IGNORE
The application ignores the signal.
@item SIG_METHOD
The application provides a method to handle the signal.
@end table

@cindex @code{handler} instance variable @idxclscite{SignalHandler}
@item handler
The value is an instance method of class @code{SignalHandler} that is 
provided by the application.
@end table

@subsubheading Instance Methods

@table @code
@cindex @mnm{defaultHandler} @idxclscite{SignalHandler}
@item @mnm{defaultHandler} (@code{void})
Install the operating system's default handler for the receiver's 
signal number @code{sigNo.}  The operating system's documentation
describes how it handles signals.

@cindex @mnm{ignoreSignal} method @idxclscite{SignalHandler}
@item @mnm{ignoreSignal} (@code{void})
Set the receiver signal handler to ignore a signal.

@cindex @mnm{installHandler} method @idxclscite{SignalHandler}
@item @mnm{installHandler} (@code{OBJECT *(*}@var{method}@code{)(int)})
Install @var{method} as the receiver's signal handler.  The method
must be callable as a C function.  @xref{Method functions}.

@cindex @mnm{new} method @idxclscite{SignalHandler}
@item @mnm{new} (@code{char *}@var{name})
Create a new @code{SignalHandler} object with name @var{name}.

@cindex @mnm{raiseSignal} method @idxclscite{SignalHandler}
@item @mnm{raiseSignal} (@code{void})
Send the signal of the receiver's @code{sigNo} variable to the 
current program.

@cindex @mnm{setSigAbrt} method @idxclscite{SignalHandler}
@item @mnm{setSigAbrt} (@code{void})
Set the signal of the receiver's handler to @code{SIGABRT.}

@cindex @mnm{setSigAlrm} method @idxclscite{SignalHandler}
@item @mnm{setSigAlrm} (@code{void})
Set the signal of the receiver's handler to @code{SIGALRM.}

@cindex @mnm{setSigChld} method @idxclscite{SignalHandler}
@item @mnm{setSigChld} (@code{void})
Set the signal of the receiver's handler to @code{SIGCHLD.}

@cindex @mnm{setSigCont} method @idxclscite{SignalHandler}
@item @mnm{setSigCont} (@code{void})
Set the signal of the receiver's handler to @code{SIGCONT.}

@cindex @mnm{setSigFpe} method @idxclscite{SignalHandler}
@item @mnm{setSigFpe} (@code{void})
Set the signal of the receiver's handler to @code{SIGFPE.}

@cindex @mnm{setSigHup} method @idxclscite{SignalHandler}
@item @mnm{setSigHup} (@code{void})
Set the signal of the receiver's handler to @code{SIGHUP.}

@cindex @mnm{setSigIll} method @idxclscite{SignalHandler}
@item @mnm{setSigIll} (@code{void})
Set the signal of the receiver's handler to @code{SIGILL.}

@cindex @mnm{setSigInt} method @idxclscite{SignalHandler}
@item @mnm{setSigInt} (@code{void})
Set the signal of the receiver's handler to @code{SIGINT.}

@cindex @mnm{setSigNo} method @idxclscite{SignalHandler}
@item @mnm{setSigNo} (@code{int }@var{signum})
Set the signal number of the receiver to @var{signum}.

@cindex @mnm{setSigPipe} method @idxclscite{SignalHandler}
@item @mnm{setSigPipe} (@code{void})
Set the signal of the receiver's handler to @code{SIGPIPE.}

@cindex @mnm{setSigQuit} method @idxclscite{SignalHandler}
@item @mnm{setSigQuit} (@code{void})
Set the signal of the receiver's handler to @code{SIGQUIT.}

@cindex @mnm{setSigSegv} method @idxclscite{SignalHandler}
@item @mnm{setSigSegv} (@code{void})
Set the signal of the receiver's handler to @code{SIGSEGV.}

@cindex @mnm{setSigTerm} method @idxclscite{SignalHandler}
@item @mnm{setSigTerm} (@code{void})
Set the signal of the receiver's handler to @code{SIGTERM.}

@cindex @mnm{setSigTstp} method @idxclscite{SignalHandler}
@item @mnm{setSigTstp} (@code{void})
Set the signal of the receiver's handler to @code{SIGTSTP.}

@cindex @mnm{setSigTtin} method @idxclscite{SignalHandler}
@item @mnm{setSigTtin} (@code{void})
Set the signal of the receiver's handler to @code{SIGTTIN.}

@cindex @mnm{setSigTtou} method @idxclscite{SignalHandler}
@item @mnm{setSigTtou} (@code{void})
Set the signal of the receiver's handler to @code{SIGTTOU.}

@cindex @mnm{setSigUsr1} method @idxclscite{SignalHandler}
@item @mnm{setSigUsr1} (@code{void})
Set the signal of the receiver's handler to @code{SIGUSR1.}

@cindex @mnm{setSigUsr2} method @idxclscite{SignalHandler}
@item @mnm{setSigUsr2} (@code{void})
Set the signal of the receiver's handler to @code{SIGUSR2.}

@cindex @mnm{signalProcessID} method @idxclscite{SignalHandler}
@item @mnm{signalProcessID} (@code{int} @var{processid})
Send the signal @code{sigNo} of the receiver to process @var{processid}.
@end table

@node Expr, Magnitude, Event, Classes
@iftex
@section @code{Expr} Class
@end iftex
@ifnottex
@subheading @code{Expr} Class
@end ifnottex
@cindex @code{Expr} class

Ctalk uses objects of class @code{Expr} and its subclasses internally
to represent C expressions, functions, and variables.

@node CFunction, , , Classes
@iftex
@section @code{CFunction} Class
@end iftex
@ifnottex
@subheading @code{CFunction} Class
@end ifnottex
@cindex @code{CFunction} class

Ctalk uses the @code{CFunction} class internally to represent C
function calls.  Ctalk installs the @code{CFunction} methods library
templates in @code{CLASSLIBDIR/libc} and @code{CLASSLIBDIR/libctalk}.

Note that this class does not, at this time, provide methods for all
C99 library function calls.  If you want to add C library templates,
look at the templates in @flnm{classes/libc} and at the API
documentation.  @xref{Templates}.  Refer to the @flnm{README} file in
the Ctalk distribution for instructions on submitting source code
contributions.


@subsubheading Class Methods

@table @code
@cindex @mnm{cAbs} method @idxclscite{CFunction}
@cindex @idxfncite{abs(3)}
@item @mnm{cAbs} (@code{int} @var{i})
Return the result object of an @cite{abs(3)} library call.

@cindex @mnm{cAcos} method @idxclscite{CFunction}
@cindex @idxfncite{acos(3)}
@item @mnm{cAcos} (@code{double} @var{d})
Return the result object of an @cite{acos(3)} library call.

@cindex @mnm{cAcosh} method @idxclscite{CFunction}
@cindex @idxfncite{acosh(3)}
@item @mnm{cAcosh} (@code{double} @var{d})
Return the result object of an @cite{acosh(3)} library call.

@cindex @mnm{cAscTime} method @idxclscite{CFunction}
@cindex @idxfncite{asctime(3)}
@item @mnm{cAscTime} (@code{struct tm *}@var{tm})
Return the result object of an @cite{asctime(3)} library call. The
value of @var{tm} is the result of a @cite{gmtime(3)} or
@cite{localtime(3)} call.

@cindex @mnm{cAsin} method @idxclscite{CFunction}
@cindex @idxfncite{asin(3)}
@item @mnm{cAsin} (@code{double} @var{d})
Return the result object of an @cite{asin(3)} library call.

@cindex @mnm{cAsinh} method @idxclscite{CFunction}
@cindex @idxfncite{asinh(3)}
@item @mnm{cAsinh} (@code{double} @var{d})
Return the result object of an @cite{asinh(3)} library call.

@cindex @mnm{cAtof} method @idxclscite{CFunction}
@cindex @idxfncite{atof(3)}
@item @mnm{cAtof} (@code{char *}@var{s})
Return the result object of an @cite{atof(3)} library call.

@cindex @mnm{cAtoi} method @idxclscite{CFunction}
@cindex @idxfncite{atoi(3)}
@item @mnm{cAtoi} (@code{char *}@var{s})
Return the result object of an @cite{atoi(3)} library call.

@cindex @mnm{cAtol} method @idxclscite{CFunction}
@cindex @idxfncite{atol(3)}
@item @mnm{cAtol} (@code{char *}@var{s})
Return the result object of an @cite{atol(3)} library call.

@cindex @mnm{cAtoll} method @idxclscite{CFunction}
@cindex @idxfncite{atoll(3)}
@item @mnm{cAtoll} (@code{char *}@var{s})
Return the result object of an @cite{atoll(3)} library call.

@cindex @mnm{cCbrt} method @idxclscite{CFunction}
@cindex @idxfncite{cbrt(3)}
@item @mnm{cCbrt} (@code{double} @var{d})
Return the result object of a @cite{cbrt(3)} library call.

@cindex @mnm{cCeil} method @idxclscite{CFunction}
@cindex @idxfncite{ceil(3)}
@item @mnm{cCeil} (@code{double} @var{d})
Return the result object of a @cite{ceil(3)} library call.

@cindex @mnm{cChdir} method @idxclscite{CFunction}
@cindex @idxfncite{chdir(3)}
@item @mnm{cChdir} (@code{char *}@var{s})
Change the working directory to @var{s}.  Returns @code{0}
on success, @code{-1} on error, and sets the system error
number.

@cindex @mnm{cClearErr} method @idxclscite{CFunction}
@cindex @idxfncite{clearerr(3)}
@item @mnm{cClearErr} (@code{OBJECT *} @var{FILECLASSOBJECT})
Perform a @cite{clearerr(3)} library call on the file stream of the 
argument.

@cindex @mnm{cClock} method @idxclscite{CFunction}
@cindex @idxfncite{clock(3)}
@item @mnm{cClock} (@code{void})
Return the result object of a @cite{clock(3)} library call.

@cindex @mnm{cCopySign} method @idxclscite{CFunction}
@cindex @idxfncite{copysign(3)}
@item @mnm{cCopySign} (@code{double} @var{d}@code{, double} @var{s})
Return the result object of a @cite{copysign(3)} library call.

@cindex @mnm{cCos} method @idxclscite{CFunction}
@cindex @idxfncite{cos(3)}
@item @mnm{cCos} (@code{double} @var{d})
Return the result object of a @cite{cos(3)} library call.

@cindex @mnm{cCosh} method @idxclscite{CFunction}
@cindex @idxfncite{cosh(3)}
@item @mnm{cCosh} (@code{double} @var{d})
Return the result object of a @cite{cosh(3)} library call.

@cindex @mnm{cCTime} method @idxclscite{CFunction}
@cindex @idxfncite{ctime(3)}
@item @mnm{cCTime} (@code{int *}@var{t})
Return the result object of a @cite{ctime(3)} library call.

@emph{Note:} Because @cite{ctime(3)} uses a pointer to @code{int} as
its argument, arguments to @mnm{cCTime} should be of class
@code{Symbol.}  @xref{Objects in Function Arguments}.

@cindex @mnm{cDiffTime} method @idxclscite{CFunction}
@cindex @idxfncite{difftime(3)}
@item @mnm{cDiffTime} (@code{int} @var{time1}@code{, int} @var{time2})
Return the result object of a @cite{difftime(3)} library call.

@cindex @mnm{cErf} method @idxclscite{CFunction}
@cindex @idxfncite{erf(3)}
@item @mnm{cErf} (@code{double} @var{d})
Return the result object of an @cite{erf(3)} library call.

@cindex @mnm{cErfc} method @idxclscite{CFunction}
@cindex @idxfncite{erfc(3)}
@item @mnm{cErfc} (@code{double} @var{d})
Return the result object of an @cite{erfc(3)} library call.

@cindex @mnm{cExp} method @idxclscite{CFunction}
@cindex @idxfncite{exp(3)}
@item @mnm{cExp} (@code{double} @var{d})
Return the result object of an @cite{exp(3)} library call.

@cindex @mnm{cExpm1} method @idxclscite{CFunction}
@cindex @idxfncite{expm1(3)}
@item @mnm{cExpm1} (@code{double} @var{d})
Return the result object of an @cite{expm1(3)} library call.

@cindex @mnm{cFabs} method @idxclscite{CFunction}
@cindex @idxfncite{fabs(3)}
@item @mnm{cFabs} (@code{double} @var{d})
Return the result object of a @cite{fabs(3)} library call.

@cindex @mnm{cFabsf} method @idxclscite{CFunction}
@cindex @idxfncite{fabsf(3)}
@item @mnm{cFabsf} (@code{double} @var{d})
Return the result object of a @cite{fabsf(3)} library call.

@emph{Note:} Not supported on SunOS.  Use @mnm{cFabs} instead.

@cindex @mnm{cGetchar} method @idxclscite{CFunction}
@cindex @idxfncite{getchar(3)}
@item @mnm{cGetchar} (@code{void})
Return an object of class @code{Integer} from the standard input.

@cindex @mnm{cGetCwd} method @idxclscite{CFunction}
@cindex @idxfncite{getcwd(3)}
@item @mnm{cGetCwd} (@code{void})
Return the current directory as a @code{String} object.

@cindex @mnm{cGetEnv} method @idxclscite{CFunction}
@cindex @idxfncite{getenv(3)}
Return a @code{String} object with the result of a 
@cite{getenv(3)} C library function call.

@cindex @mnm{cGetPID} method @idxclscite{CFunction}
@cindex @idxfncite{getpid(3)}
@item @mnm{cGetPID} (@code{void})
Return an @code{Integer} object with the result of a 
@cite{getpid(3)} C library function call.

@cindex @mnm{cStrcat} method @idxclscite{CFunction}
@cindex @idxfncite{strcat(3)}
@item @mnm{cStrcat} (@code{char *}@var{s1}, @code{char *}@var{s2})
Return the result of a @cite{strcat(3)} library function call.

@cindex @mnm{cStrcasecmp} method @idxclscite{CFunction}
@cindex @idxfncite{strcasecmp(3)}
@item @mnm{cStrcasecmp} (@code{char *}@var{s1}, @code{char *}@var{s2})
Return the result of a @cite{strcasecmp(3)} library call.

@cindex @mnm{cStrcmp} method @idxclscite{CFunction}
@cindex @idxfncite{strcmp(3)}
@item @mnm{cStrcmp} (@code{char *}@var{s1}, @code{char *}@var{s2})
Return the result of a @cite{strcmp(3)} library call.

@cindex @mnm{cStrlen} method @idxclscite{CFunction}
@cindex @idxfncite{strlen(3)}
@item @mnm{cStrlen} (@code{char *}@var{s})
Return the result of a @cite{strlen(3)} library call.

@cindex @mnm{cStrncat} method @idxclscite{CFunction}
@cindex @idxfncite{strncat(3)}
@item @mnm{cStrncat} (@code{char *}@var{s1}, @code{char *}@var{s2}, @code{int} @var{n})
Return the result of a @cite{strncat(3)} library call.

@cindex @mnm{cStrncasecmp} method @idxclscite{CFunction}
@cindex @idxfncite{strncasecmp(3)}
@item @mnm{cStrncasecmp} (@code{char *}@var{s1}, @code{char *}@var{s2}, @code{int} @var{n})
Return the result of a @cite{strncasecmp(3)} library call.

@cindex @mnm{cStrncmp} method @idxclscite{CFunction}
@cindex @idxfncite{strncmp(3)}
@item @mnm{cStrncmp} (@code{char *}@var{s1}, @code{char *}@var{s2}, @code{int} @var{n})
Return the result of a @cite{strncmp(3)} library call.

@cindex @mnm{cStrncpy} method @idxclscite{CFunction}
@cindex @idxfncite{strncpy(3)}
@item @mnm{cStrncpy} (@code{char *}@var{s1}, @code{char *}@var{s2}, @code{int} @var{n})
Return the result of a @cite{strncpy(3)} library call.

@end table

@emph{Warning} - This class is not complete.  The use of C library
functions is described further in this manual. @xref{C library
functions}.

@node Magnitude, Symbol, Expr, Classes
@iftex
@section @code{Magnitude} Class
@end iftex
@ifnottex
@subheading @code{Magnitude} Class
@end ifnottex
@cindex @code{Magnitude} class

@code{Magnitude} is the superclass of all object classes that contain
quantities.

@subsubheading Instance Methods

@table @code
@cindex @mnm{asCharacter} method @idxclscite{Magnitude}
@item @mnm{asCharacter} (@code{void})
Return an object with the receiver's value as a @code{Character} object.

@cindex @mnm{asInteger} method @idxclscite{Magnitude}
@item @mnm{asInteger} (@code{void})
Return an object with the receiver's value as an @code{Integer} object.

@cindex @mnm{asLongInteger} method @idxclscite{Magnitude}
@item @mnm{asLongInteger} (@code{void})
Return an object with the receiver's value as a @code{LongInteger} object.

@end table

@node Character, Float, , Classes
@iftex
@section @code{Character} Class
@end iftex
@ifnottex
@subheading @code{Character} Class
@end ifnottex
@cindex @code{Character} class

The value of @code{Character} class objects is (on most hardware 
platforms) an 8-bit integer corresponding to the ISO-8859-1 character
set.  Methods that test @code{Character} objects return a non-zero
@code{Integer} object if the result is true, and an @code{Integer}
object if the result is false.

@subheading Instance Variables

@table @code

@cindex @mnm{value} instance variable @idxclscite{Character}
@item value
The value of an 8-bit character in the ISO-8859-1 character set.

@end table

@subheading Methods

@table @code

@cindex @mnm{!=} method @idxclscite{Character}
@item @mnm{!=} (@code{char} @var{character})
Returns true if the receiver is not equal to @var{character}.

@cindex @mnm{&} method @idxclscite{Character}
@item @mnm{&} (@code{char} @var{character})
Returns a bitwise AND of the receiver and the argument.

@cindex @mnm{&&} method @idxclscite{Character}
@item @mnm{&&} (@code{char} @var{character})
Returns @code{TRUE} if both operands are @code{TRUE,} @code{FALSE} otherwise.

@cindex @mnm{*} method @idxclscite{Character}
@item @mnm{*} (@code{char} @var{c})
Multiply the receiver and the operand.  The result is a @code{Character}
object. 

@cindex @mnm{+} method @idxclscite{Character}
@item @mnm{+} (@code{char} @var{c})
Add the receiver and the operand.  The result is a @code{Character}
object. 

@cindex @mnm{-} method @idxclscite{Character}
@item @mnm{-} (@code{char} @var{c})
Subtract the receiver and the operand.  The result is a @code{Character}
object. 

@cindex @mnm{/} method @idxclscite{Character}
@item @mnm{/} (@code{char} @var{c})
Divide the receiver and the operand.  The result is a @code{Character}
object. 

@cindex @mnm{<} method @idxclscite{Character}
@item @mnm{<} (@code{char} @var{character})
Returns @code{TRUE} if the receiver is less than the operand, @code{FALSE}
otherwise.

@cindex @mnm{<<} method @idxclscite{Character}
@item @mnm{<<} (@code{int} @var{i})
Shift the receiver left by the number of bits in the operand, which
must be an @code{Integer}.

@cindex @mnm{<=} method @idxclscite{Character}
@item @mnm{<=} (@code{char} @var{character})
Returns @code{TRUE} if the receiver is less than or equal to the operand,
FALSE otherwise.

@cindex @mnm{=} method @idxclscite{Character}
@item @mnm{=} (@code{char} @var{character})
Set the value of the receiver object to @var{character}.

@cindex @mnm{>} method @idxclscite{Character}
@item @mnm{>} (@code{char} @var{character})
Returns @code{TRUE} if the receiver is greater than the operand, @code{FALSE}
otherwise.

@cindex @mnm{>>} method @idxclscite{Character}
@item @mnm{>>} (@code{int} @var{i})
Shift the receiver right by the number of bits in the operand, which
must be an @code{Integer}.

@cindex @mnm{>=} method @idxclscite{Character}
@item @mnm{>=} (@code{char} @var{character})
Returns @code{TRUE} if the receiver is greater than or equal to the operand,
FALSE otherwise.

@cindex @mnm{==} method @idxclscite{Character}
@item @mnm{==} (@code{char} @var{character})
Returns true if the receiver is equal to @var{character}.

@cindex @mnm{^} method @idxclscite{Character}
@item @mnm{^} (@code{char} @var{character})
Returns a bitwise XOR of the receiver and the argument.

@cindex @mnm{bitComp} method @idxclscite{Character}
@item @mnm{bitComp} (@code{void})
Perform a bitwise complement of the receiver.

@cindex @mnm{invert} method @idxclscite{Character}
@item @mnm{invert} (@code{void})
Returns @code{TRUE} if the receiver evaluates to @code{FALSE,}
@code{FALSE} if the receiver evaluates to @code{TRUE.}

@cindex @mnm{isASCII} method @idxclscite{Character}
@item @mnm{isASCII} (@code{void})
Returns @code{TRUE} if the receiver is a 7-bit ASCII character @samp{0-127},
FALSE otherwise.

@cindex @mnm{isAlNum} method @idxclscite{Character}
@item @mnm{isAlNum} (@code{void})
Returns @code{TRUE} if the receiver is an alphanumeric character @samp{0-9},
@samp{A-Z}, @samp{a-z}, @code{FALSE} otherwise.

@cindex @mnm{isAlpha} method @idxclscite{Character}
@item @mnm{isAlpha} (@code{void})
Returns @code{TRUE} if the receiver is an alphabetic character
@samp{A-Z}, @samp{a-z}, @code{FALSE} otherwise.

@cindex @mnm{isBlank} method @idxclscite{Character}
@item @mnm{isBlank} (@code{void})
Returns @code{TRUE} if the receiver is a space @samp{ } or horizontal
tab @samp{\t} character, @code{FALSE} otherwise.

@cindex @mnm{isCntrl} method @idxclscite{Character}
@item @mnm{isCntrl} (@code{void})
Returns @code{TRUE} if the receiver is a control character, @code{FALSE} otherwise.

@cindex @mnm{isDigit} method @idxclscite{Character}
@item @mnm{isDigit} (@code{void})
Returns @code{TRUE} if the receiver is a character @samp{0-9}, @code{FALSE} otherwise.

@cindex @mnm{isGraph} method @idxclscite{Character}
@item @mnm{isGraph}(@code{void})
Returns @code{TRUE} if the receiver is any character except a space, @code{FALSE}
otherwise.

@cindex @mnm{isLower} method @idxclscite{Character}
@item @mnm{isLower} (@code{void})
Returns @code{TRUE} if the receiver is a lower case character, @code{FALSE}
otherwise.

@cindex @mnm{isPrint} method @idxclscite{Character}
@item @mnm{isPrint} (@code{void})
Returns @code{TRUE} if the receiver is a printable character, @code{FALSE}
otherwise.

@cindex @mnm{isPunct} method @idxclscite{Character}
@item @mnm{isPunct} (@code{void})
Returns @code{TRUE} if the receiver is a printable non-alphanumeric
character, @code{FALSE} otherwise. 

@cindex @mnm{isSpace} method @idxclscite{Character}
@item @mnm{isSpace} (@code{void})
Returns @code{TRUE} if the receiver is a space, horizontal tab (@code{\t}),
newline (@code{\n}), vertical tab (@code{\v}), form feed (@code{\f}),
or carriage return (@code{\r}) character, @code{FALSE} otherwise.

@cindex @mnm{isUpper} method @idxclscite{Character}
@item @mnm{isUpper} (@code{void})
Returns @code{TRUE} if the receiver is an upper case letter, @code{FALSE} otherwise.

@cindex @mnm{isXDigit} method @idxclscite{Character}
@item @mnm{isXDigit} (@code{void})
Returns @code{TRUE} if the receiver is a character @samp{0-9},
@samp{a-f}, or @samp{A-F}, @code{FALSE} otherwise.

@cindex @mnm{toLower} method @idxclscite{Character}
@item @mnm{toLower} (@code{void})
If the receiver is an upper case letter, returns the lower case
version. 

@cindex @mnm{toUpper} method @idxclscite{Character}
@item @mnm{toUpper} (@code{void})
If the receiver is a lower case letter, returns the upper case 
version.

@cindex @mnm{|} method @idxclscite{Character}
@item @mnm{|} (@code{char} @var{character})
Returns a bitwise OR of the receiver and the argument.

@cindex @mnm{||} method @idxclscite{Character}
@item @mnm{||} (@code{char} @var{character})
Returns @code{TRUE} if either operand is @code{TRUE,} @code{FALSE} otherwise.

@end table

@node String, , , Classes
@iftex
@section @code{String} Class
@end iftex
@ifnottex
@subheading @code{String} Class
@end ifnottex
@cindex @code{String} class

Objects of @code{String} class represent @code{char *} arrays of
characters. 

@subsubheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{String}
@item value
The value is a pointer to the character string.

@end table

@subsubheading Methods

@table @code

@cindex @mnm{=} method @idxclscite{String}
@item @mnm{=} (@code{char *}@var{s})
Set the value of the receiver object to @var{s.}

@cindex @mnm{==} method @idxclscite{String}
@item @mnm{==} (@code{char *}@var{s})
Return @code{TRUE} if @var{s} and the receiver are identical, 
@code{FALSE} otherwise.

@cindex @mnm{!=} method @idxclscite{String}
@item @mnm{!=} (@code{char *}@var{s})
Return @code{FALSE} if @var{s} and the receiver are not identical, 
@code{TRUE} otherwise.

@cindex @mnm{+} method @idxclscite{String}
@item @mnm{+} (@code{char *}@var{s})
Concatenate the receiver and @var{s}.

@cindex @mnm{asInteger} method @idxclscite{String}
@item @mnm{asInteger} (@code{void})
Return an @code{Integer} object with the value of the receiver.

@cindex @mnm{at} method @idxclscite{String}
@item @mnm{at} (@code{int} @var{index})
Return the character at @var{index}.  The first character of the 
string is at index 0.  If @var{index} is greater than the length
of the string, return @samp{NULL}.

@cindex @mnm{atPut} method @idxclscite{String}
@item @mnm{atPut} (@code{int} @var{n}, @code{char} c)
Replace the @var{n}'th character of the receiver with @var{c}.  
Has no effect and returns @code{NULL} if n is greater than the length
of the receiver.  Returns the receiver if successful.

@cindex @mnm{getEnv} method @idxclscite{String}
@item @mnm{getEnv} (@code{char *}@var{envVarName})
Return the value of environment variable @var{envVarName} as the value
of the receiver, or @code{(null).}

@cindex @mnm{length} method @idxclscite{String}
@item @mnm{length} (@code{void})
Return an object of class @code{Integer} with the length of the 
receiver in characters.

@cindex @mnm{match} method @idxclscite{String}
@item @mnm{match} (@code{char *}@var{pattern})
Returns @code{TRUE} if @var{pattern} matches the receiver 
@code{String} regardless of case, false otherwise.

@cindex @mnm{matchCase} method @idxclscite{String}
@item @mnm{matchCase} (@code{char *}@var{pattern})
Returns @code{TRUE} if @var{pattern} matches the receiver case-
sensitively, false otherwise.

@cindex @mnm{printOn} method @idxclscite{String}
@item @mnm{printOn} (@code{char *}@var{fmt}, ...)
Format and print the method's arguments to the receiver.

@cindex @mnm{split} method @idxclscite{String}
@item @mnm{split} (@code{char} @var{delimiter}, @code{char **} @var{resultArray})
Split the receiver at each occurrence of @var{delimiter}, and save the
result in @var{resultArray}.

@cindex @mnm{subString} method @idxclscite{String}
@item @mnm{subString} (@code{int} @var{index}, @code{int} @var{length})
Return the substring of the receiver of @var{length} characters
beginning at @var{index}.  String indexes start at 0.  If @var{index}
+ @var{length} is greater than the length of the receiver, return 
the substring from @var{index} to the end of the receiver.

@anchor{writeFormat--class String}
@cindex @mnm{writeFormat} method @idxclscite{String}
@item @mnm{writeFormat} (@code{char *}@var{fmt},...)
Write the formatted arguments using @var{fmt} to the receiver.
Note that Ctalk stores scalar types as formatted strings.
@xref{Variable arguments}.
@end table

@node Float, Integer, Character, Classes
@iftex
@section @code{Float} Class
@end iftex
@ifnottex
@subheading @code{Float} Class
@end ifnottex
@cindex @code{Float} class

Objects of @code{Float} class represent double precision, floating
point numbers.

@subheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Float}
@item value
The value is the formatted representation of a double precision
floating point number.

@end table

@subheading Methods

@table @code
@cindex @mnm{&&} method @idxclscite{Float}
@item @mnm{&&} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if both operands are
@code{TRUE,} @code{FALSE} otherwise.

@cindex @mnm{=} method @idxclscite{Float}
@item @mnm{=} (@code{double} @var{d})
Set the value of the receiver object to @var{d}.

@cindex @mnm{+} method @idxclscite{Float}
@item @mnm{+} (@code{double} @var{d})
Add @var{d} to the receiver.

@cindex @mnm{-} method @idxclscite{Float}
@item @mnm{-} (@code{double} @var{d})
Subtract @var{d} from the receiver.

@cindex @mnm{*} method @idxclscite{Float}
@item @mnm{*} (@code{double} @var{d})
Multiply the receiver by @var{d}.

@cindex @mnm{/} method @idxclscite{Float}
@item @mnm{*} (@code{double} @var{d})
Divide the receiver by @var{d}.

@cindex @mnm{<} method @idxclscite{Float}
@item @mnm{<} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if the receiver is
less than the argument, @code{FALSE} otherwise.

@cindex @mnm{<=} method @idxclscite{Float}
@item @mnm{<=} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if the receiver is
less than or equal to the argument, @code{FALSE} otherwise.

@cindex @mnm{>} method @idxclscite{Float}
@item @mnm{>} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if the receiver is
greater than the argument, @code{FALSE} otherwise.

@cindex @mnm{>=} method @idxclscite{Float}
@item @mnm{>=} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if the receiver is
greater than or equal to the argument, @code{FALSE} otherwise.

@cindex @mnm{asInteger} method @idxclscite{Float}
@item @mnm{asInteger} (@code{void})
Return the integer portion of the receiver.

@cindex @mnm{||} method @idxclscite{Float}
@item @mnm{||} (@code{double} @var{d})
Return an @code{Integer} that evaluates to @code{TRUE} if either operand is
@code{TRUE,} @code{FALSE} otherwise.

@end table

@node Integer, Boolean, Float, Classes
@iftex
@section @code{Integer} Class
@end iftex
@ifnottex
@subheading @code{Integer} Class
@end ifnottex
@cindex @code{Integer} class

Objects of @code{Integer} class represent signed and unsigned
integers of the C types @code{int} and @code{long int}.

@subheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Integer}
@item value
The value is the formatted representation of the receiver.

@end table

@subheading Methods

@table @code
@cindex @mnm{=} method @idxclscite{Integer}
@item @mnm{=} (@code{int} @var{i})
Set the value of the receiver object to @var{i}.

@cindex @mnm{+} method @idxclscite{Integer}
@item @mnm{+} (@code{int} @var{i})
Add @var{i} and the receiver, as in this example.

@example
intObject = 2;

resultInt = intObject + intObject;
@end example

@cindex @mnm{-} method @idxclscite{Integer}
@item @mnm{-} (@code{int} @var{i})
Subtract @var{i} from the receiver.

@cindex @mnm{*} method @idxclscite{Integer}
@item @mnm{*} (@code{int} @var{i})
Multiply the receiver by @var{i}.

@cindex @mnm{/} method @idxclscite{Integer}
@item @mnm{/} (@code{int} @var{i})
Divide the receiver by @var{i}.

@cindex @mnm{<<} method @idxclscite{Integer}
@item @mnm{<<} (@code{int} @var{i})
Perform an arithmetic left shift on the receiver by the number of 
bits in the argument.

@cindex @mnm{>>} method @idxclscite{Integer}
@item @mnm{>>} (@code{int} @var{i})
Perform an arithmetic right shift on the receiver by the number of
bits in the argument.

@cindex @mnm{&} method @idxclscite{Integer}
@item @mnm{&} (@code{int} @var{i})
Perform a bitwise and of the receiver and the argument.

@cindex @mnm{|} method @idxclscite{Integer}
@item @mnm{|} (@code{int} @var{i})
Perform a bitwise or of the receiver and the argument.

@cindex @mnm{%} method @idxclscite{Integer}
@item @mnm{%} (@code{int }@var{i})
Return an @code{Integer} that is the modulus of the receiver and the
argument. 

@cindex @mnm{^} method @idxclscite{Integer}
@item @mnm{^} (@code{int} @var{i})
Perform a bitwise exclusive or of the receiver and the argument.

@cindex @mnm{asString} method @idxclscite{Integer}
@item @mnm{asString} (@code{void})
Return a @code{String} object of the receiver.

@cindex @mnm{bitComp} method @idxclscite{Integer}
@item @mnm{bitComp} (@code{int} @var{i})
Return the bitwise complement of the receiver.

@cindex @mnm{==} method @idxclscite{Integer}
@item @mnm{==} (@code{int} @var{i})
Return @code{TRUE} if the receiver and the argument are equal, @code{FALSE}
otherwise.

@cindex @mnm{>} method @idxclscite{Integer}
@item @mnm{>} (@code{int} @var{i})
Return @code{TRUE} if the receiver is greater than the argument, @code{FALSE}
otherwise.

@cindex @mnm{<} method @idxclscite{Integer}
@item @mnm{<} (@code{int} @var{i})
Return @code{TRUE} if the receiver is less than the argument, @code{FALSE}
otherwise.

@cindex @mnm{>=} method @idxclscite{Integer}
@item @mnm{>=} (@code{int} @var{i})
Return @code{TRUE} if the receiver is greater than or equal to the argument,
@code{FALSE} otherwise.

@cindex @mnm{<=} method @idxclscite{Integer}
@item @mnm{<=} (@code{int} @var{i})
Return @code{TRUE} if the receiver is less than or equal to the argument,
@code{FALSE} otherwise.

@cindex @mnm{invert} method @idxclscite{Integer}
@item @mnm{invert} (@code{void})
Return @code{TRUE} if the receiver evaluates to @code{FALSE,} @code{FALSE} if the receiver
evaluates to @code{TRUE.}

@cindex @mnm{!=} method @idxclscite{Integer}
@item @mnm{!=} (@code{int} @var{i})
Return @code{TRUE} if the receiver and the argument are not equal, @code{FALSE}
otherwise.

@cindex @mnm{||} method @idxclscite{Integer}
@item @mnm{||} (@code{int} @var{i})
Return @code{TRUE} if the receiver or the argument evaluate to @code{TRUE.}

@cindex @mnm{&&} method @idxclscite{Integer}
@item @mnm{&&} (@code{int} @var{i})
Return @code{TRUE} if the receiver and the argument evaluate to @code{TRUE.}


@end table

@node Boolean, Time, Integer, Classes
@iftex
@section @code{Boolean} Class
@end iftex
@ifnottex
@subheading @code{Boolean} Class
@end ifnottex
@cindex @code{Boolean} class

@code{Boolean} class is mainly used as the return class of methods of
various classes that test equality, like @code{<,} @code{>,}
@code{==,} @code{!=,} and so on.

@node Time, LongInteger, Boolean, Classes
@iftex
@section @code{Time} Class
@end iftex
@ifnottex
@subheading @code{Time} Class
@end ifnottex
@cindex @code{Time} class

Objects of @code{Time} class represent the system or local time.  This
class also implements the methods that convert UTC time into calendar 
time.

The return value of the methods @mnm{gmTime} and @mnm{localTime} is an
@code{Array} that contains the following values.
@example
returnArray at 0    Seconds (0... 59)
returnArray at 1    Minutes (0... 59)
returnArray at 2    Hours (0... 23)
returnArray at 3    Day of the Month (1... 31)
returnArray at 4    Month (0... 11)
returnArray at 5    Year (Number of years since 1900.)
returnArray at 6    Day of the Week (0 = Sunday ... 6 = Saturday)
returnArray at 7    Day of the Year (1... 365)
returnArray at 8    > 0 = Daylight Savings Time; 0 = Standard Time; 
                    < 0 = Not Available
@end example

@subheading Instance Methods
@table @code

@cindex @mnm{cTime} method @idxclscite{Time}
@item @mnm{cTime} (@code{void})
Returns a formatted @code{String} with the date and time of the 
receiver.

The return @code{String} of a @code{cTime} call is formatted as in
this example.
@example
"Sun Jan 6 13:04:00 2008\n" 
@end example

@cindex @mnm{gmTime} method @idxclscite{Time}
@item @mnm{gmTime} (@code{void})
Returns an @code{Array} with the values described above for the
current Greenwich Mean Time.

@cindex @mnm{haveDST} method @idxclscite{Time}
@item @mnm{haveDST} (@code{void})
Return an @code{Integer} that evaluates to True if the system provides
daylight savings time information, False otherwise.

@cindex @mnm{localTime} method @idxclscite{Time}
@item @mnm{localTime} (@code{void})
Returns an @code{Array} with the values described above for the
current local time.

@cindex @mnm{timeZoneName} method @idxclscite{Time}
@item @mnm{timeZoneName} (@code{void})
Return a @code{String} with the name of the time zone provided by the
system.

@cindex @mnm{timeZoneOffset} method @idxclscite{Time}
@item @mnm{timeZoneOffset} (@code{void})
Return an @code{Integer} with the time zone offset in seconds from
GMT.  Not all systems provide this information.

@cindex @mnm{utcTime} method @idxclscite{Time}
@item @mnm{utcTime} (@code{void})
Return an @code{Integer} object containing the current UTC time.

@end table

@node LongInteger, , Time, Classes
@iftex
@section @code{LongInteger} class
@end iftex
@ifnottex
@subheading @code{LongInteger} Class
@end ifnottex
@cindex @code{LongInteger} Class

Objects of @code{LongInteger} class represent signed and unsigned
integers of the C type @code{long long int}.

@subheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{LongInteger}
@item value
The value is the formatted representation of a signed @code{long long int}.

@end table

@subheading Methods

@table @code

@cindex @mnm{!=} method @idxclscite{LongInteger}
@item @mnm{!=} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is not equal to @var{l}.

@cindex @mnm{=} method @idxclscite{LongInteger}
@item @mnm{=} (@code{long long int} @var{l})
Set the value of the receiver to @var{l}.

@cindex @mnm{==} method @idxclscite{LongInteger}
@item @mnm{==} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is equal to @var{l}.

@cindex @mnm{+} method @idxclscite{LongInteger}
@item @mnm{+} (@code{long long int} @var{l})
Add @var{l} to the the receiver.

@cindex @mnm{-} method @idxclscite{LongInteger}
@item @mnm{-} (@code{long long int} @var{l})
Subtract @var{l} from the receiver.

@cindex @mnm{%} method @idxclscite{LongInteger}
@item @mnm{%} (@code{long long int }@var{l})
Return a @code{LongInteger} that is the modulus of the receiver and the
argument. 

@cindex @mnm{&} method @idxclscite{LongInteger}
@item @mnm{&} (@code{long long int} @var{l})
Perform a bitwise AND of the receiver and the operand.

@cindex @mnm{&&} method @idxclscite{LongInteger}
@item @mnm{&&} (@code{long long int} @var{l})
Return @code{TRUE} if both the receiver and the operand evaluate to
@code{TRUE.} 

@cindex @mnm{*} method @idxclscite{LongInteger}
@item @mnm{*} (@code{long long int} @var{l})
Multiply the receiver by @var{l}.

@cindex @mnm{/} method @idxclscite{LongInteger}
@item @mnm{/} (@code{long long int} @var{l})
Divide the receiver by @var{l}.

@cindex @mnm{<} method @idxclscite{LongInteger}
@item @mnm{<} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is less than the operand,
@code{FALSE} otherwise.

@cindex @mnm{<=} method @idxclscite{LongInteger}
@item @mnm{<=} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is less than or equal to the
operand, @code{FALSE} otherwise.

@cindex @mnm{<<} method @idxclscite{LongInteger}
@item @mnm{<<} (@code{int} @var{i})
Shift the receiver left by the number of bits in the operand, an
@code{Integer.} 

@cindex @mnm{>} method @idxclscite{LongInteger}
@item @mnm{>} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is greater than the operand,
@code{FALSE} otherwise.

@cindex @mnm{>=} method @idxclscite{LongInteger}
@item @mnm{>=} (@code{long long int} @var{l})
Return @code{TRUE} if the receiver is greater than or equal to the
operand, @code{FALSE} otherwise.

@cindex @mnm{>>} method @idxclscite{LongInteger}
@item @mnm{>>} (@code{int} @var{l})
Shift the receiver right by the number of bits in the operand, an
@code{Integer.} 

@cindex @mnm{^} method @idxclscite{LongInteger}
@item @mnm{^} (@code{long long int} @var{l})
Perform a bitwise XOR of the receiver and the operand.

@cindex @mnm{bitComp} method @idxclscite{LongInteger}
@item @mnm{bitComp} (@code{void})
Return a bitwise complement of the receiver.

@cindex @mnm{invert} method @idxclscite{LongInteger}
@item @mnm{invert} (@code{void})
Return @code{TRUE} if the receiver evaluates to @code{FALSE,} 
@code{FALSE} if the receiver evaluates to @code{TRUE.}

@cindex @mnm{|} method @idxclscite{LongInteger}
@item @mnm{|} (@code{long long int} @var{l})
Perform a bitwise OR of the receiver and the operand.

@cindex @mnm{||} method @idxclscite{LongInteger}
@item @mnm{|} (@code{long long int} @var{l})
Return @code{TRUE} if either the receiver or the operand evaluate to
@code{TRUE.} 

@end table

@node Symbol, Key, Magnitude, Classes
@iftex
@section @code{Symbol} Class
@end iftex
@ifnottex
@subheading @code{Symbol} Class
@end ifnottex
@cindex @code{Symbol} class

@code{Symbol} class objects represent memory locations.  They can
refer to objects, C variables, buffers, I/O ports, and other data
located in memory.

If you receive an @code{Unimplemented C type} warning, you can store
various types of C data in @code{Symbol} objects. @xref{Objects in
Function Arguments}. 

@subheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Symbol}
@item value
The value is the formatted representation of a hexadecimal pointer
to a memory address.

@end table

@subheading Instance Methods

@table @code

@cindex @mnm{=} method @idxclscite{Symbol}
@item @mnm{=} (@code{void *}@var{v})
Assign the argument's value to the receiver.

@end table

@node Key, , Symbol, Classes
@iftex
@section @code{Key} Class
@end iftex
@ifnottex
@subheading @code{Key} Class
@end ifnottex
@cindex @code{Key} class

Objects of class @code{Key} are key-value pairs.  Other classes and
programs can use @code{Key} objects' names when looking up 
objects.  The value of a key object is a reference to the value object.

@subheading Instance Variables

@table @code

@cindex @code{value} instance variable @idxclscite{Key}
@item value
The value is the formatted representation of a hexadecimal pointer
to a memory address.

@end table

@subheading Instance Methods

@table @code
@cindex @mnm{=} method @idxclscite{Key}
@item @mnm{=} (@code{OBJECT *}@var{value_object})
Assign the argument's value to the receiver.  This method is a synonym
for @mnm{setValue}.

@cindex @mnm{setName} method @idxclscite{Key}
@item @mnm{setName} (@code{char *}@var{key_name})
Set the receiver's name to the argument, a @code{String} object.

@emph{Note:} When you change the name of an object, Ctalk can no
longer refer to it by its previous name.  A program needs to maintain
an alias to the object, like an @code{OBJECT *,} so that it can
refer to the object later.  In the following example, the program
can refer to @code{keyObject} by using @code{key_alias_ptr,}
regardless of the object's name.
@example
Key new keyObject;
OBJECT *key_alias_ptr;
...
key_alias_ptr = KeyObject setName keyNameString;
@end example

@cindex @mnm{setValue} method @idxclscite{Key}
@item @mnm{setValue} (@code{OBJECT *}@var{value_object})
Assign the argument's value to the receiver.  This method is a synonym
of @mnm{=}.

@end table


@node Methods, C, Classes, Top
@iftex
@chapter Methods
@end iftex
@ifnottex
@heading Methods
@end ifnottex
@cindex Methods

Methods in Ctalk are similar to C functions, but the method
declaration syntax provides two additional functions:
@itemize
@item
The declaration specifies the class that the method belongs to.
@item
The statement allows the method to be identified by an alias, so the
method can overload operators.
@end itemize

To declare an instance method, use the @code{instanceMethod} keyword,
as in the following example.

@example
String instanceMethod = set_value (char *s) @{

 ... method statements

@}
@end example

This example declares an instance method, @mnm{=}, which is recognized
by objects that belong to the class @code{String} and its subclasses.
The @code{=} in the declaration overloads C's @code{=} operator, so
that, instead of assigning a value to a C variable, the method sets the value
of its receiver. 

In this example, the receiver is an instance of class @code{String.}

@example
newObject = "Hello, World!";
@end example

If the variable reference immediately preceding @code{=} refers to a C
variable, then @mnm{=} behaves as the C operator, @code{=.}

Ctalk can use most C operators as methods, with the exception of
parentheses and prefix operators.  Receivers always precede the method
message.  

For example, the @code{Integer} methods @mnm{invert} and
@mnm{bitComp} perform the same operations as the C prefix operators
@code{!}  and @code{~.}
@example
int i;              /* C variable. */
Integer new myInt;  /* Ctalk object. */

i = 0;
myInt = 0;

/* These two statements are equivalent. */
printf ("%d", !i); 
printf ("%d", myInt invert).

/* And so are these two statements. */
printf ("%d", ~i);
printf ("%d", myInt bitComp);
@end example


@iftex
@section Declaring Methods
@end iftex
@ifnottex
@subheading Declaring Methods
@end ifnottex
@cindex Methods
@cindex Method declarations

The declaration syntax for instance methods is:

@quotation
@var{classname} @code{instanceMethod} [@var{alias}] @var{funcname} (@var{args}) @{
@var{method body}
@}
@end quotation

and for class methods:

@quotation
@var{classname} @mnm{classMethod} [@var{alias}] @var{funcname} (@var{args}) @{
@var{method body}
@}
@end quotation

If @var{alias} is omitted, Ctalk refers to the method by
@var{funcname.}

In the example at the beginning of this section, if @mnm{=} were
omitted, a program could refer to the method by the message,
@code{set_value.}

With the exception of the primitive methods @mnm{class}, @mnm{new},
@mnm{classMethod}, and @mnm{instanceMethod}, Ctalk declares methods
in its class library, or in the program input. @xref{Classes}.

@iftex
@section Method Parameters
@end iftex
@ifnottex
@subheading Method Parameters
@end ifnottex
@cindex Method parameters

You can use Ctalk class objects to declare method parameters, but you
can also declare parameters using C data types, in order to prevent
class libraries from being loaded recursively.  This is necessary in
many of the basic classes.

Regardless of how you declare method parameters, when the method's
message is sent to an object, Ctalk translates C language arguments
into class objects.

For example, these two declarations are equivalent.  
@example
Integer instanceMethod + add (int i) @{
...
@}

Integer instanceMethod + add (Integer i) @{
...
@}
@end example

Ctalk does not use objects in C function arguments, so if you need to
use objects as parameters, you must write a method instead of a C
function.


@ifnottex
@menu
* Method API::            The method application programming interface.
* Self and super::        How to refer to receivers and superclass methods.
* Class initialization::  How to set class variables at run time.
* Translating::           C to objects and back again.
* Required classes::      Preloading classes that you will need.
* Templates::             Method macros for simple tasks.
* Return values::         How to return objects of various classes.
* Variable arguments::    Calling C library functions with variable arguments.
* Method functions::      Methods that are called as C functions.
* Errors::                Exception and error handling.
* Cautions::              Precautions for using objects with C variables.
* Method keywords::       Ctalk keywords that apply to methods.
* Ctalk library::         Library function reference.
@end menu
@end ifnottex


@node Method API, Self and super, , Methods
@iftex
@section Method Application Programming Interface
@end iftex
@ifnottex
@subheading Method Application Programming Interface
@end ifnottex
@cindex Method API

This section describes the C functions and macros that methods use to
interface with the Ctalk run time libraries and with each other.

At this point, the method API is still developing, and relies heavily
on C library functions.  

This example shows method @mnm{+} of class @code{Integer}, which
adds two Integer objects, creates an object for the result, and
returns the result.

@example
Integer instanceMethod + add (int i) @{

  OBJECT *op1, *op2;

  op1 = self value;
  op2 = i value;

  methodReturnInteger(atoi(op1->__o_value) + atoi(op2->__o_value))
@}
@end example

The keyword @code{self} refers to the receiver of the method.
@xref{Self and super}.

@cindex @mnm{value} method @idxclscite{Object}
The variables @code{op1} and @code{op2} are the @code{value} instance
variables of the receiver and the argument.  Ctalk has a method,
@mnm{value} (class @code{Object}), which returns the @code{value}
instance variable, but you can also refer to instance variables by
sending an instance variable's name as a message to an object.

Internally, the receiver, arguments, and return value of a method are
all @samp{OBJECT *}.  When you use C functions with objects, you use
the members of an OBJECT type, a @code{struct.}  (@xref{OBJECT
typedef}.)  If you declare an object as a C @code{OBJECT *,} then the
method uses it like any other C @code{struct *.}


All methods return an @samp{OBJECT *} as the result.  The macro
@code{methodReturnInteger} defines the object that the method
returns.  @xref{Return values}.

The @mnm{add} method is in @flnm{classes/Integer}.  The file
@flnm{include/object.h} contains the declaration of the @samp{OBJECT}
type.

@node Self and super, Class initialization, Method API, Methods
@iftex
@section @code{self} and @code{super}
@end iftex
@ifnottex
@subheading @code{self} and @code{super}
@end ifnottex
@cindex @code{self} keyword
@cindex @code{super} keyword

The keywords @code{self} and @code{super} refer to the method's
receiver object and a method in a superclass of the receiver's class,
respectively.

@cindex @mnm{+} method @idxclscite{Integer}
Refer to the method @mnm{+} (class @code{Integer}) from the previous
section.  If you call @mnm{+} with the statement below, @code{self} in
the @mnm{+} method would refer to @code{i.}

@example
j = i + 2;
@end example

The @code{super} keyword refers to a method in one of the superclasses
of the receiver.  It is commonly used in constructors. 

For example, if a class implements its own @mnm{new} method that
performs additional initialization for instances of a class, it can
also call @mnm{new} implemented by a superclass.  

@cindex @mnm{new} method @idxclscite{ReadFileStream}
@cindex @mnm{new} method @idxclscite{Object}
This constructor from the @code{ReadFileStream} method, @mnm{new}, also calls
@mnm{new} from class @code{Object.}

@example
ReadFileStream instanceMethod new (char *name) @{

  ReadFileStream super new name;

  __ctalkInstanceVarsFromClassObject (name);

  ReadFileStream classInit;
  
  return name;
@}
@end example

The first statement, @code{ReadFileStream super new name,} calls @mnm{new} from class
@code{Object} before performing its own initialization.

@node Class initialization, Translating, Self and super, Methods
@iftex
@section Class Initialization
@end iftex
@ifnottex
@subheading Class Initialization
@end ifnottex
@cindex Class initialization

Some classes that have class variables require initialization when
the program is run.  For example, class @code{ReadFileStream} needs
to have its class variable @code{stdinStream} set to the
application's @code{stdin} file stream before the program can read
from standard input.  

Classes that require initialization need to define a method,
@code{classInit}, which is called by a constructor when the first
object is created.  An example is the @code{ReadFileStream} method
@mnm{new} from the previous section.

Here is the @mnm{classInit} method for class @code{ReadFileStream}.

@example
ReadFileStream classMethod classInit (void) @{

  OBJECT *classObject,
    *stdinStreamVar,
    *classInitVar;
  char buf[MAXLABEL];

  if (self classInitDone)
    return NULL;

  classObject = __ctalkGetClass ("ReadFileStream");
  stdinStreamVar = __ctalkGetClassVariable ("stdinStream", TRUE);
  
  sprintf (buf, "%p", _IO_stdin);
  __ctalkSetObjectValueVar (stdinStreamVar, buf);

  __ctalkInstanceVarsFromClassObject (stdinStreamVar);
  stdinStream statStream;

  classInitVar = 
    __ctalkCreateObjectInit ("classInitDone", classObject -> __o_name,
				classObject -> __o_superclassname,
				classObject -> scope, "1");
  __ctalkAddInstanceVariable (classObject, "classInitDone", classInitVar);

  return NULL;
@}
@end example

A @code{classInit} method needs to be called only once.  The method
checks the @code{classInitDone} instance variable to determine the
method has already performed the initialization that the class needs.

@node Translating, Required classes, Class initialization, Methods
@iftex
@section Translating C Variables into Object Values
@end iftex
@ifnottex
@subheading Translating C Variables into Object Values
@end ifnottex
@cindex Method API
@cindex __ctalkDecimalIntegerToASCII

The @code{OBJECT} C data type that Ctalk uses internally stores 
objects' values as C @code{char *}'s. 
@xref{OBJECT typedef}.

To store numeric values, you must format them as character strings,
using, for example, @code{sprintf}.  In many cases, however, Ctalk
performs this translation automatically.

@code{Integer} objects can also translate values with @cite{atoi(3)}
or @cite{__ctalkDecimalIntegerToASCII}.  Other scalar data types have
corresponding functions that translate numbers to character strings.

If for some reason you need to translate an object to its C type or
back again, the Ctalk library provides the following functions.

@table @code
@cindex __ctalkToCArrayElement function
@item __ctalkToCArrayElement (OBJECT *@var{o})
Translate the value of an @code{Integer,} @code{Character,}
@code{String,} or @code{LongInteger} array element to a @code{void *}
to its corresponding C data type.

@cindex __ctalkToCCharPtr function
@item __ctalkToCCharPtr (OBJECT *@var{o}, int @var{keep})
Translate the value of a @code{String} object into a C @code{char *.}
If @var{keep} is @code{FALSE}, delete @var{o}.

@cindex __ctalkToCIntArrayElement function
@item __ctalkToCIntArrayElement (OBJECT *@var{o})
Translate the value of an @code{Integer} array element to an
@code{int.}

@cindex __ctalkToCInteger function
@item __ctalkToCInteger (@code{OBJECT *}@var{o}, @code{int} @var{keep_object})
Translate the value of an @code{Integer} array element to an
@code{int.}  If @var{keep_object} is @code{FALSE,} then delete 
the object.

@cindex __ctalk_to_c_char_ptr function
@item __ctalk_to_c_char_ptr (OBJECT *@var{o})
Translate the value of a @code{String} object into a C @code{char *.}

@cindex __ctalk_to_c_double function
@item __ctalk_to_c_double (OBJECT *@var{o})
Translate the value of a @code{Float} object into a C @code{double.}

@cindex __ctalk_to_c_int function
@item __ctalk_to_c_int (OBJECT *@var{o})
Translate the value of an @code{Integer} object into a C @code{int.}

@cindex __ctalk_to_c_longlong function
@item __ctalk_to_c_longlong (OBJECT *@var{o})
Translate the value of a @code{LongInteger} object into a C @code{long
long int.}

@cindex __ctalk_to_c_ptr function
@item __ctalk_to_c_ptr (OBJECT *@var{o})
Translate the value of an object into a C @code{void *.}

@cindex __ctalkCCharPtrToObj function
@item __ctalkCCharPtrToObj (char *@var{s})
Create a @code{String} object with the value @var{s}.

@cindex __ctalkCDoubleToObj function
@item __ctalkCDoubleToObj (double @var{f})
Create a @code{Float} object with the value @var{f}.

@cindex __ctalkCIntToObj function
@item __ctalkCIntToObj (int @var{i})
Create an @code{Integer} object with the value @var{i}.

@cindex __ctalkCLongLongToObj function
@item __ctalkCLongLongToObj (long long int @var{l})
Create a @code{LongInteger} object with the value @var{l}.

@end table

The functions that create objects give the objects the scope of the
function call, either global or local.

@emph{Note:} In future versions of Ctalk, the names of these functions
are likely to change.



@node Required classes, Templates, Translating, Methods
@iftex
@section Required Classes
@end iftex
@ifnottex
@subheading Required Classes
@end ifnottex
@cindex @code{require} keyword

The keyword @code{require} tells @command{ctalk} to preload the class
given as its argument before any other classes or methods.

The following lines appear in the @flnm{ctalklib} library.

@example
require Object;
require Symbol;
require String;
@end example

These statements tell @command{ctalk} to first load the @code{Object}
class and its methods, and then load the class @code{Symbol} and its
methods, and then class @code{String.}  Ctalk loads the class and its
methods at that point in the program, before further processing of the
source file.

The @code{require} keyword always occurs in a global scope; that is,
outside of any method or function.

@node Templates, Return values, Required classes, Methods
@iftex
@section Templates
@end iftex
@ifnottex
@subheading Templates
@end ifnottex
@cindex Templates

@emph{Templates} are simplified methods that are defined as macros and
written completely in C.  They are mainly used as wrapper methods to
functions in C libraries.  Whenever you use a C library function in a
complex Ctalk expression, Ctalk retrieves the template from the library
and registers it as a @code{CFunction} class method. @xref{CFunction}.

@cindex @idxfncite{atoi(3)}
@cindex @mnm{cAtoi} method
You define a C function template just like any other macro, with the
name of the function and the method as the macro body.  Here is the
definition of the @mnm{cAtoi} method, which implements the
@cite{atoi(3)} function.
@example
#define atoi \n\
cAtoi (void *s) @{ \n\
  char buf[MAXLABEL]; \n\
  if (__ctalkIsObject (ARG(0))) \n\
    sprintf (buf, "%d", atoi (__ctalk_to_c_char_ptr (ARG(0)))); \n\
  else \n\
    sprintf (buf, "%d", atoi ((char *)ARG(0))); \n\
  return __ctalkCreateObjectInit ("result", "Integer", \n\
				     "Magnitude", LOCAL_VAR, buf); \n\
@}
@end example

@emph{Note:} The following interface is still in development and is
likely to change in future versions of Ctalk.

When Ctalk sees @code{atoi} in an expression, if it can't simply call
@cite{atoi(3),} it inserts the @mnm{cAtoi} method in the output, and
replaces @code{atoi} with @code{CFunction cAtoi.}  That way, Ctalk can
call the function as a method at run time.

@cindex __ctalk_primitive_method function
@cindex __ctalkDefineClassMethod function
C library functions are registered automatically, using
@code{__ctalk_primitive_method} to define the @code{CFunction} class
if necessary, and @code{__ctalkDefineClassMethod} to register the
method definition with the @code{CFunction} class.

@cindex C functions
@cindex Functions
@cindex Arguments to C functions
Ctalk also creates templates for functions in the input source.  You
can use any C function, variable, or constant as an argument to the
function, as long as the arguments are within the scope of the
function call.

If, for some reason, you need to write a template, you should note the
following.

Templates are simply preprocessed, registered in the program
initialization and included in the output.  That means they are
written completely in C.  You can include parameter definitions in a
template, but they are optional, because, although templates are C
functions, they act as methods and use the same calling mechanism.

@cindex @code{CFunction} class
Ctalk registers templates as @code{CFunction} class methods.  Ctalk
derives the name of the method by uppercasing the first letter of the
function's name, and prepending, ``c,'' to it.  As shown in the
example above, the @cite{atoi(3)} function has the corresponding
method @code{cAtoi.}  However, that is simply a convention, and you
can give a template method whatever name you prefer.

At this time, there is only a simple mechanism to look up templates.
Ctalk looks for templates in the @flnm{classes/libc} directory of the
class library.  After installation this directory is commonly located
in @flnm{/usr/local/include/ctalk/classes/libc} on UNIX systems.  You
must add the template to the library file that corresponds to the
first letter of the function name.  Then you must also register the
function as described below.

@anchor{ARG macro}
@cindex @code{ARG()} macro
If you want to refer to a function parameter in a template, you must
use the @code{ARG(@var{n})} macro, which refers directly to the
arguments passed to the method.  Because arguments are pushed in
reverse order when Ctalk calls a method, @code{ARG(0)} refers to the
@emph{last} argument, @code{ARG(1)} refers to the preceding argument,
and @code{ARG(@var{n})} refers to the first argument.

If you add a template to a library file, you must also add it to the
@code{c99_names} registry in @flnm{lib/clibtmpl.c} in the source code
distribution.  At this time, Ctalk only implements C99 library
functions in that registry.  Refer to the file @flnm{README} in the
Ctalk distribution for instructions on how to submit source code
contributions.

@node Return values, Variable arguments, Templates, Methods
@iftex
@section Return Values
@end iftex
@ifnottex
@subheading Return Values
@end ifnottex
@cindex @code{returnObjectClass}

You should always return a value in a method, even if it is only,
@code{self}, which is a synonym for the receiver object, or
@samp{NULL}.

Methods by default return objects of their own class; that is, an
@code{Integer} method returns a result object of class @code{Integer},
and so on.  

When a method needs to return an object of another class, you can
declare the return class with the keyword, @code{returnObjectClass},
as in this example, which returns the length of a string as an
@code{Integer.}

@example
String instanceMethod length (void) @{

  char *value_end_ptr;
  OBJECT *rcvr;

  returnObjectClass Integer;

  rcvr = self value;

  /*
   *  Strlen () has an OS-dependent return type.
   *  Calculate our own string length as an int.
   */
  value_end_ptr = index (rcvr -> __o_value, '\0');
  methodReturnInteger(value_end_ptr - rcvr -> __o_value)
@}
@end example

The @code{methodReturnInteger} macro defines the object that the
method returns, with the value of the receiver's length.

You can also define return objects manually, but that should seldom be
necessary for basic operations.  Here is an alternative @code{length}
method that defines its result by using C and Ctalk library
functions directly.
@example
String method length (void) @{
  char buf[MAXMSG];
  OBJECT *rcvr, *result_object;

  returnObjectClass Integer;

  rcvr = self value;

  sprintf (buf, "%d", strlen (rcvr -> __o_value));

  result_object = 
    __ctalk_create_object_init ("result", "Integer",
				"Object", rcvr -> scope, buf);
  return result_object;
@}
@end example

If you give a @code{returnObjectClass} statement the argument,
@code{Any,} that indicates the method can return objects of any class,
as in this example.

@example
Array method at (int index) @{
  char buf[MAXLABEL];

  returnObjectClass Any;

  sprintf (buf, "%d", __ctalk_to_c_int (index));
  return __ctalk_getInstanceVariable (self, buf, @code{FALSE});
@}
@end example

@iftex
@subsection Method Return Macros
@end iftex
@ifnottex
@subsubheading Method Return Macros
@end ifnottex

Ctalk defines the following macros for common method return types.

You can use these return values, unless the method needs to perform
some operation on a result, or the result object is part of a
complex expression.

For example, @code{methodReturnSelf} returns the method's receiver
only, not the result of the expression, @code{"self value."}

The objects returned by these macros, with the exception of
@code{methodReturnSelf}, and possibly @code{methodReturnObject,} are
local to the method.

Remember that these return values are implemented as macros, so do not
terminate them with semicolons (@samp{;}).

@table @code

@cindex @code{methodReturnFalse} macro
@item methodReturnFalse
Return a @code{Boolean} object that evaluates to @code{FALSE.}

@cindex @code{methodReturnInteger} macro
@item methodReturnInteger(@code{int} @var{i}) 
Return an @code{Integer} object with the value @var{i}.

@cindex @code{methodReturnNULL} macro
@item methodReturnNULL 
Returns the C value @code{NULL.}

@cindex @code{methodReturnObject} macro
@item methodReturnObject(@var{object})
Return @var{object}.

@cindex @code{methodReturnObjectName} macro
@item methodReturnObjectName(@var{objectname})
Return the object referred to by @var{objectname}.

@cindex @code{methodReturnSelf} macro
@cindex @code{self} keyword
@item methodReturnSelf
Returns the method's receiver, @code{self}.

@cindex @code{methodReturnString} macro
@item methodReturnString(@code{char *}@var{s}) 
Return a @code{String} object with the value @var{s}.

@cindex @code{methodReturnTrue} macro
@item methodReturnTrue
Return a @code{Boolean} object that evaluates to @code{TRUE.}

@end table

@node Variable arguments, Method functions, Return values, Methods
@iftex
@section Variable Arguments
@end iftex
@ifnottex
@subheading Variable Arguments
@end ifnottex
@cindex Variable arguments
@cindex @idxfncite{scanf(3)}
@cindex @idxfncite{sscanf(3)}
@cindex @idxfncite{fscanf(3)}

C functions like @cite{scanf(3),} @cite{sscanf(3),} and
@cite{fscanf(3)} have templates that allow you to call them
with a variable number of arguments.  

If you need to call other C functions that use variable arguments, 
you must call @code{__ctalkLibcFnWithMethodVarArgs} with the
name of the function, the method that contains the function's 
template, and the function's return class.  

For example, here is the code of the template method for
@cite{fscanf(3),} @code{cFscanf} (@code{CFunction} class), without the
preprocessing directives.

@example
cFscanf (FILE *s, char *fmt,...) @{
  EXPR_PARSER *parser;
  OBJECT *result_object;
  parser = __ctalkGetExprParserAt (__ctalkGetExprParserPtr ());
  result_object =
    __ctalkLibcFnWithMethodVarArgs ((int (*)())fscanf, parser -> e_method, "Integer");
  return result_object;
@}
@end example

At run time, the @code{e_method} member of an expression parser
contains the method and its arguments.

The third argument of @code{__ctalkLibcFnWithMethodVarArgs} determines
the class of @code{result_object.}  For C library functions that use
variable arguments, the return class is @code{Integer.}

The typecast @code{(int (*)())} in the first argument in front of
@code{fscanf} is not strictly needed because we know that the number
and types of arguments to @cite{fscanf(3)} (or @cite{scanf(3)} or any
other variable-argument function) might vary from the
@code{__ctalkLibcFnWithMethodVarArgs} prototype, but it tells the
compiler not to print a warning message in that case.

@emph{Note:} This version of Ctalk only allows variable arguments of
pointer types; that is, only the conversion characters @samp{s} and
@samp{c} are allowed.  If you try to perform a scalar conversion; for
example, with @samp{%d}, @samp{%ld}, or @samp{%p} in the format
string, Ctalk issues a warning and returns @code{NULL.}  

@cindex __ctalkCPrintFmtToCtalkFmt function
However, you can call @code{__ctalkCPrintFmtToCtalkFmt}
before @code{__ctalkLibcFnWithMethodVarArgs.}
This preforms print format-argument translations
for the variable argument library functions.
@xref{__ctalkCPrintFmtToCtalkFmt}.

@cindex @mnm{writeFormat} method @idxclscite{WriteFileStream}
@cindex @mnm{writeFormat} method @idxclscite{String}
If you simply need to print formatted output, the
@mnm{writeFormat} methods (@code{String} and
@code{WriteFileStream} classes) perform format-argument
translations automatically.
@xref{writeFormat--class WriteFileStream}, and
@ref{writeFormat--class String}.

@node Method functions, Errors, Variable arguments, Methods
@iftex
@section Method Functions
@end iftex
@ifnottex
@subheading Method Functions
@end ifnottex

@cindex @code{SigHandler} class
Occasionally an application needs to call a method as a function.  One
example of this is a @code{SignalHandler} method that the program
installs as the handler for signals from the operating system.

Methods that use a C calling convention need to do several things
differently than normal methods.
@itemize
@item 
The method needs to use a C variable as its argument.
@item
Because the method can be called with no receivers, Ctalk does not 
perform any of the normal initialization of local and parameter
objects.
@item
The method body needs to be written almost entirely in C.
@end itemize

@cindex @code{__c_arg__} attribute
In order to make Ctalk interpret a method parameter as a C variable, the
method must declare the parameter with the @code{__c_arg__} attribute.

@emph{Note:} C functions that are called by the operating system
generally need only one argument, and the @code{__c_arg__} attribute
only works for methods with a single parameter.

@cindex @code{noMethodInit} keyword
Additionally, to prevent Ctalk from adding local object initialization
code to the method, the method must contain the @code{noMethodInit}
keyword. 

Here is an example of a method that is used as a signal handler, and
installed by the statements in @code{main.}
@example
SignalHandler instanceMethod myHandler (__c_arg__ int signo) @{
  noMethodInit;
  printf ("sigInt handler! Signal %d.\n", signo);
  methodReturnNULL
@}

int main () @{

  SignalHandler new s;

  s setSigInt;
  s installHandler myHandler;
@}
@end example

@cindex @mnm{setSigInt} method @idxclscite{SignalHandler}
The @mnm{setSigInt} method (class @code{SignalHandler}) tells the
@code{SignalHandler} object @code{s} that it is going to handle
@code{SIGINT} signals.  @xref{SignalHandler}, for the other signals
that the class can handle.

The @code{__ctalkNewSignalEventInternal} function can generate and
queue @code{SignalEvent} objects, so the signal handler does not need
to create objects in order to send signal events to the application.
@xref{__ctalkNewSignalEventInternal}.

@node Errors, Cautions, Method functions, Methods
@iftex
@section Exception and Error Handling
@end iftex
@ifnottex
@subheading Exception and Error Handling
@end ifnottex
@cindex Exceptions
@cindex Errors
@cindex Warnings

There are two ways to handle error conditions in Ctalk.  You can
simply print an error or warning message in your code.  An error
message formats the text and data that you provide, the same as in a
@code{printf} statement, and then exits the program.  Here is an
example.
@example
_error ("Program exited with code %d.\n", result_code);
@end example

A @code{_warning} message is similar, but it prints the message and
continues processing.  @xref{errorfuncs}.

The other way to handle errors is with exceptions.  This is the method
you need to use if an error occurs within a method, and the program
needs either to print a warning message, or exit.

@cindex @mnm{pending} method @idxclscite{Exception}
@cindex @mnm{handle} method @idxclscite{Exception}
There are two methods of class @code{Exception} that handle exceptions
in application programs: @mnm{pending} and @code{handle.}  There are
also other API functions, but they are mostly used internally to
translate exceptions into events that application programs can use.

These two methods are generally used together.  The method
@mnm{pending,} if it returns @code{TRUE,} signals that there is an
exception pending.  Then the function @code{handle} handles the event
by executing an exception handler.

Generally, events simply issue error messages.  It is up to you to
determine how the program should handle the exception: by exiting,
trying the procedure again, ignoring the condition, or some other
procedure.  Here is an example.

@example
Exception new e;
...
inputStream openOn fileArg;
if (e pending) @{
   e handle;
  exit (1);
@}
if (inputStream isDir) @{
  printf ("Input is a directory.\n");
  exit (1);
@}
@end example
This is simply the way that Ctalk notifies the application if the
method @code{openOn} (class @code{ReadFileStream}) encountered an
error while opening the file named by its argument, @code{fileArg.}

@cindex @mnm{isDir} method @idxclscite{FileStream}
You should note that the program also checks whether the input is
actually a directory, because opening a directory as if it were a file
does not necessary cause an error condition.  The @mnm{isDir} (class
@code{FileStream}) method is one portable way to check if the input path
is actually a directory.

@cindex @mnm{raiseException} method @idxclscite{SystemErrnoException}
The method @mnm{openOn,} like other methods, raises an exception if
necessary.  It does this with @mnm{raiseException} (class
@code{SystemErrnoException}).

@cindex @code{errno} macro
Ctalk handles most @code{stdio} error codes in this manner.  A program
that uses the @code{ReadFileStream} and @code{WriteFileStream} classes
should rarely need to use the C library's @code{errno} macro, but it
is still available if applications need to check for other errors from
the C libraries.

The Ctalk library also provides exceptions for missing arguments,
undefined methods, and other error conditions. The file,
@flnm{include/except.h,} contains the definitions of Ctalk's
compile and run time exceptions.


@node Cautions, Method keywords, Errors, Methods
@iftex
@section Cautions when Using Arguments with C Library Calls
@end iftex
@ifnottex
@subheading Cautions when Using Arguments with C Library Calls
@end ifnottex

The interface for C functions is in development.  You can use a C
function in a simple expression with any argument, as in the following
example.

@example
op1 = __ctalkGetInstanceVariableByName ("self", "value", TRUE);
@end example

However, if you want to use a C function in a complex expression, then
you must take care that the arguments to the function are C values
that correspond to a Ctalk class, unless the function has a template
written for it in the class library that performs the translations of
specific classes and data types.  @xref{Templates}.

If you use a function in a method, and the compiler generates an,
``implicit declaration,'' warning, you can include the library
function's prototype in either the source file or in
@flnm{classes/ctalklib}.

@iftex
@section Cautions when using @code{Array} class elements in C expressions.
@end iftex
@ifnottex
@subheading Cautions when using @code{Array} class elements in C expressions.
@end ifnottex
@cindex @code{Array} class

If you want to use an @code{Array} element in a C expression, you need
to take care that the value of the element translates to a @code{void
*,} which is the C type that Ctalk returns the values of these
elements as.

That means elements of class @code{LongInteger} might be truncated, and 
@code{Float} class array elements cannot be translated in this manner.  

If array elements of these classes occur in C expressions, Ctalk
prints a warning at run time.

In these cases, it is necessary to convert the values to a compatible
pointer type, for example an object of class @code{String.}

@node Method keywords, Ctalk library, Cautions, Methods
@iftex
@section Method Keywords
@end iftex
@ifnottex
@subheading Method Keywords
@end ifnottex
@cindex Method keywords.

@table @code

@cindex @code{__c_arg__} attribute
@item __c_arg__
Treat the next method argument as a C argument.  @xref{Method functions}.

@cindex @code{classMethod} keyword
@item classMethod
The @code{classMethod} keyword declares a method, as described
above.

@cindex @code{classVariable} keyword
@item classVariable 
Adds a class variable definition to a class.  This 
method can be used globally.  The syntax is:

@quotation
@var{class} classVariable @var{name} [@var{class}] [@var{initial_value}]
@end quotation
For example:

@example
FileStream class ReadFileStream;
ReadFileStream classVariable stdin Symbol 0x0;
@end example

The value of @var{initial_value} can be either a constant or an
expression that evaluates to a constant.

@cindex @code{instanceMethod} keyword
@item instanceMethod
The @code{instanceMethod} keyword declares a method, as described
above.

@cindex @code{instanceVariable} keyword
@item instanceVariable 
Adds an instance variable definition to a class.  This 
method can be used outside a method.  The syntax is:

@quotation
@var{class} instanceVariable @var{name} [@var{class}]
[@var{initial_value}]
@end quotation

For example:

@example
FileStream class ReadFileStream;
ReadFileStream instanceVariable pos LongInteger 0L;
@end example

The value of @var{initial_value} can be either a constant or an
expression that evaluates to a constant.

@cindex @code{noMethodInit} keyword
@item noMethodInit
Do not include method initialization code for the method.
@xref{Method functions}.

@cindex @code{require} keyword
@item require
Require a class to be loaded before any other classes or methods.

@cindex @code{returnObjectClass} keyword
@item returnObjectClass
Set the return class of a method to the argument if it is different
than the receiver class. @xref{Return values}.

@cindex @code{self} keyword
@item self 
Return the method's receiver object.  In version
@value{VERSION}, you can also use @code{self} in arguments as a 
synonym for the receiver of the statement, as in this example.
@example
String new path;
path = "/home/user/joe";

printf ("%s", path subString 1, self length - 1);
@end example

The use of @code{self} in method arguments is experimental in version
@value{VERSION}, and it should be used with caution.

@cindex @code{super} keyword
@item super
The keyword @code{super} has two different meanings.  It can 
modify a method, as in the following example.

@example 
MyReceiverClass super new instanceObject;
@end example

@code{super} can also represent the receiver's superclass
object, so it can appear as a receiver, as in this example.

@example
return super new checksum;
@end example

@end table

@node Ctalk library, , Method keywords, Methods
@iftex
@section Ctalk Library Reference
@end iftex
@ifnottex
@subheading Ctalk Library Reference
@end ifnottex
@cindex Library functions

This section describes some of the Ctalk library functions that you
can use in methods and, in many cases, in Ctalk programs generally.

The file @flnm{classes/ctalklib} contains the prototypes of the
library functions.

@table @code

@cindex __argvName function
@item __argvName (@code{char *}@var{s})
Set the name of the program at run time.  Normally this is the
same as @code{argv[0]}.

@cindex __argvFileName function
@item __argvFileName (@code{void})
Returns the name of the executable program.

@cindex __ctalkAddClassVariable function
@item __ctalkAddClassVariable (@code{OBJECT *}@var{class_object}, @code{char *}@var{name}, @code{OBJECT *}@var{variable_object})
Add a class variable @var{variable_object}to @var{class_object}.

@cindex __ctalkAddInstanceVariable function
@item __ctalkAddInstanceVariable (@code{OBJECT *}@var{object}, @code{char *}@var{name}, @code{OBJECT *}@var{variable_object})
Add an instance variable to an object.  Note that the function
adds a copy of @var{variable_object} to @var{object}.

@cindex __ctalkCCharPtrToObj function
@item __ctalkCCharPtrToObj (@code{char *}@var{s})
Create a String object from a C @code{char *}.

@cindex __ctalkCDoubleToObj function
@item __ctalkCDoubleToObj (@code{double}@var{d})
Create a Float object from a C @code{float} or @code{double}.

@cindex __ctalkCharRadixToChar function
@item __ctalkCharRadixToChar (@code{char *}@var{s})
Return a C string with a lexically correct character - a character
enclosed in single quotes - from the formatted argument.  If @var{s}
is already a character, then no conversion is done.

If @var{s} contains a decimal number of more than one digit, then it
is converted from a decimal integer to a character.

@cindex __ctalkCFUNCReturnClass function
@item __ctalkCFUNCReturnClass (@code{CFUNC *}@var{fn}, @code{char *}@var{buf})
Return in @var{buf} the name of the class that corresponds to
@var{fn}'s return type.

@cindex __ctalkCIntToObj function
@item __ctalkCIntToObj (@code{int} @var{i})
Create an @code{Integer} object from a C @code{int.}

@cindex __ctalkCLongLongToObj function
@item __ctalkCLongLongToObj (@code{long long int} @var{l})
Create a @code{LongInteger} object from a C @code{long long int.}

@cindex __ctalkClassMethodInitReturnClass function
@item __ctalkClassMethodInitReturnClass (@code{char *}@var{rcvr_class}, @code{char *}@var{method_name}, @code{char *}@var{return_class});
Set the return class of @var{method} in @var{rcvr_class} to @var{return_class}.

@cindex __ctalkClassObject function
@item __ctalkClassObject (@code{OBJECT *}@var{object})
Returns the class object of the argument.

@cindex __ctalkCopyVariable function
@item __ctalkCopyCVariable (@code{CVAR *}@var{c})
Return a @code{CVAR *} to a copy of the argument.

@cindex __ctalkCopyObject function
@item __ctalkCopyObject (@code{OBJREF_T} @var{src}, @code{OBJREF_T} @var{dest})
Return an @code{OBJECT *} to a copy of the argument.

@cindex @code{OBJREF} macro
@cindex @mnm{at} method @idxclscite{Array}
@cindex @mnm{atPut} method @idxclscite{AssociativeArray}
@emph{Note:} When copying normal objects, you can translate them to
@code{OBJREF_T} types with the @code{OBJREF} macro.  When copying
method arguments, it is necessary to alias the argument to an object.
See @mnm{at} (class @code{Array}) and @mnm{atPut} (class
@code{AssociativeArray}) for examples.

@anchor{__ctalkCPrintFmtToCtalkFmt}
@cindex __ctalkCPrintFmtToCtalkFmt function
@cindex @idxfncite{printf(3)}
@item __ctalkCPrintFmtToCtalkFmt (@code{char *}@var{c_fmt}, @code{char *}@var{ctalk_fmt})
Translate a C @cite{printf(3)} type format string to a Ctalk
compatible format string.  The function translates the
format characters @code{[diouxXeEfFgGaAcsp],} but it does
not perform translations of field widths or precisions.

@cindex __ctalkCreateArg function
@item __ctalkCreateArg (@code{OBJECT *}@var{receiver}, @code{char *}@var{methodname}, @code{char *}@var{arg_expr})
Create an argument for the following @code{__ctalk_method} or
@code{__ctalk_primitive_method} function call.  Unline
@code{__ctalk_arg}, this function always creates a new object.  Its
primary use is to create local method objects.

@cindex __ctalkCreateObject function 
@item __ctalkCreateObject (@code{char *}@var{name}, @code{char *}@var{class}, @code{char *}@var{superclass}, @code{int} @var{scope})
Create an object without instance variables with name @var{name} 
of class @var{class} and superclass @var{superclass} with scope @var{scope}.

@cindex __ctalkCreateObjectInit function 
@item __ctalkCreateObjectInit (@code{char *}@var{name}, @code{char *}@var{class}, @code{char *}@var{superclass}, @code{int} @var{scope}, @code{char *}@var{value})
Create an with name @var{name} 
of class @var{class} and superclass @var{superclass} with scope
@var{scope} and value @var{value}.

@cindex __ctalkCriticalExceptionInternal function
@cindex @mnm{raiseCriticalException} method @idxclscite{SysErrnoException}
@item __ctalkCriticalExceptionInternal (@code{MESSAGE *}@var{orig}, @code{EXCEPTION} @var{ex}, @code{char *}@var{text})
Raise a critical exception at run time.  The argument @var{orig}
should be @code{NULL.}  This function should be called from a method.
This function saves a snapshot of the @emph{calling method's}
run-time context.

For an example, see @mnm{raiseCriticalException} (class
@code{SysErrnoException}) in the Ctalk class library, which calls
@code{__ctalkCriticalSysErrExceptionInternal,} below.

@cindex __ctalkCriticalSysErrExceptionInternal function
@cindex @code{errno} macro
@item __ctalkCriticalSysErrExceptionInternal (@code{MESSAGE *}@var{orig}, @code{int} @var{errno}, @code{char *}@var{text})
A convenience function that calls
@code{__ctalkCriticalExceptionInternal} with the Ctalk exception that
corresponds to @var{errno}, the C library's error macro.

@cindex __ctalkCVARReturnClass function
@item __ctalkCVARReturnClass (@code{CVAR *}@var{var}, @code{char *}@var{buf})
Return in @var{buf} the name of the class that corresponds to
@var{var}'s data type.

@cindex __ctalkDecimalIntegerToASCII function
@item __ctalkDecimalIntegerToASCII (@code{int} @var{i}, @code{char *}@var{s});
Format an ASCII representation of @var{i}, a decimal integer, in @var{s}.

@cindex __ctalkDecimalLongLongToASCII function
@item __ctalkDecimalLongLongToASCII (@code{long long int} @var{l}, @code{char *}@var{s});
Format an ASCII representation of @var{l}, a decimal long long
integer, in @var{s}.

@cindex __ctalkDefineClassMethod function
@item __ctalkDefineClassMethod (@code{char *}@var{class}, @code{char *}@var{name}, @code{OBJECT *(*)(fn)}, @code{int} @var{required_args});

Define a class method in class @var{class} with name @var{name}, which
calls the function @var{fn}, and requires @var{required_args} arguments.

@cindex __ctalkDefineClassVariable function
@item __ctalkDefineClassVariable (@code{char *}@var{class}, @code{char *}@var{name}, @code{char *}@var{varclass}, @code{char *}@var{init_expr});

Define a class variable in class @var{class} with @var{name}.  
The variable is an object of class @var{varclass} with the initial
value @var{init_expr}.

@cindex __ctalkDefineInstanceMethod function
@item __ctalkDefineInstanceMethod (@code{char *}@var{class}, @code{char *}@var{name}, @code{OBJECT *(*)(fn)}, @code{int} @var{required_args});

Define an instance method in class @var{class} with name @var{name}, which
calls the function @var{fn}, and requires @var{required_args} arguments.

@cindex __ctalkDefineInstanceVariable function
@item __ctalkDefineInstanceVariable (@code{char *}@var{class}, @code{char *}@var{name}, @code{char *}@var{varclass}, @code{char *}@var{init_expr});

Define an instance variable in class @var{class} with @var{name}.  
The variable is an object of class @var{varclass} with the initial
value @var{init_expr}.

@cindex __ctalkDeleteObjectList function
@item __ctalkDeleteObjectList (@code{OBJECT *}@var{object})
Delete an object and any objects that link to it.

@cindex __ctalkDoubleToASCII function
@item __ctalkDoubleToASCII (@code{double} @var{d}, @code{char *}@var{s});
Format an ASCII representation of @var{d}, a double, in @var{s}.

@cindex __ctalkEvalExpr function
@item __ctalkEvalExpr (@code{char *}@var{expr})
Evaluate @var{expr} and return an @code{OBJECT *} to the result.

@cindex __ctalkExceptionInternal function
@item __ctalkExceptionInternal (@code{MESSAGE *}@var{msg}, @code{EXCEPTION} @var{e}, @code{char *}@var{text}) 

Generate an exception @var{e}.  Exceptions are listed in
@flnm{except.h}. If @var{msg} is non-NULL, usually within the
interpreter, record the line and column number of the exception in the
source text.  If @var{text} is non-NULL, add the text to
the error message.  

Programs should handle run-time exceptions as soon as possible after
returning from a method.  The function
@code{__ctalkHandleRunTimeExceptionInternal} is the normal exception
handler, and @code{__ctalkTrapExceptionInternal} determines whether 
an exception has occurred.

@cindex __ctalkFindClassVariable function
@item __ctalkFindClassVariable (@code{char *}@var{varname}, @code{int} @var{warn})
Search the class library for @emph{first occurrence} of the class variable
@var{varname}.  

If @var{warn} is @code{TRUE,} issues a warning if the variable is not found.

@cindex __ctalkExceptionNotifyInternal function
@item __ctalkExceptionNotifyInternal (@code{I_EXCEPTION *}@var{i})
The handler function of most exceptions.  Prints a message including
any text provided as an argument to @code{__ctalkExceptionInternal}.

@cindex __ctalkFindClassMethodByFn function
@item __ctalkFindClassMethodByFn (@code{OBJECT **}@var{rcvr_p}, @code{OBJECT *(*}@var{fn}@code{)()}, @code{int} @var{warn})
Finds a class method by calling @code{__ctalkGetClassMethodByFn} for
the method's receiver and then the receivers of previous method calls.
On success, returns the method, and @var{rcvr_p} contains the address
of the method's receiver.

If @var{warn} is @code{TRUE,} issues a warning if the method is not found.

@cindex __ctalkFindClassMethodByName function
@item __ctalkFindClassMethodByName (@code{OBJECT **}@var{rcvr_p}, @code{char *}@var{name}, @code{int} @var{warn})
Finds a class method by by calling @code{__ctalkGetClassMethodByName}
for the method's receiver and then the receivers of previous method
calls.  On success, returns the method, and @var{rcvr_p} contains the
address of the method's receiver.

If @var{warn} is @code{TRUE,} issues a warning if the method is not found.

@cindex __ctalkFindInstanceMethodByFn function
@item __ctalkFindInstanceMethodByFn (@code{OBJECT **}@var{rcvr_p}, @code{char *}@var{name}, @code{int} @var{warn})
Finds an instance method by calling @code{__ctalkGetInstanceMethodByFn} for
the method's receiver and then the receivers of previous method calls.
On success, returns the method, and @var{rcvr_p} contains the address
of the method's receiver.

If @var{warn} is @code{TRUE,} issues a warning if the method is not found.

@cindex __ctalkFindInstanceMethodByName function
@item __ctalkFindInstanceMethodByName (@code{OBJECT **}@var{rcvr_p}, @code{char *}@var{name}, @code{int} @var{warn})
Finds an instance method by by calling @code{__ctalkGetInstanceMethodByName}
for the method's receiver and then the receivers of previous method
calls.  On success, returns the method, and @var{rcvr_p} contains the
address of the method's receiver.

If @var{warn} is @code{TRUE,} issues a warning if the method is not found.

@anchor{__ctalkGetTemplateCallerCVAR}
@cindex __ctalkGetTemplateCallerCVAR function
@item __ctalkGetTemplateCallerCVAR (@code{char *} @var{name})
If called from within a function template, looks up the @code{CVAR}
@var{name} in the calling function or method.  This function returns a
temporary object with the name and class, superclass, and value that
correspond to the @code{CVAR}'s data type.  The return object persists
until the next time this function is called.

@cindex __ctalkGetClass function
@item __ctalkGetClass (@code{char *} @var{classname})
Get the class object for @var{classname.}

@cindex __ctalkGetClassMethodByFn function
@item __ctalkGetClassMethodByFn (@code{OBJECT *}@var{rcvr}, @code{OBJECT *(*}@var{fn}@code{)(void)}, @code{int} @var{warn})
Return a class method of @var{rcvr's} class with the run-time function
@var{fn.} 

If @var{warn} is @code{TRUE,} issue a warning if the method is not found.

@cindex __ctalkGetClassMethodByName function
@item __ctalkGetClassMethodByName (@code{OBJECT *}@var{rcvr}, @code{char *}@var{name}, @code{int} @var{warn})
Return a class method of @var{rcvr's} class with the name @var{name.} 

If @var{warn} is @code{TRUE,} issue a warning if the method is not found.

@anchor{__ctalkGetExprParserAt}
@cindex __ctalkGetExprParserAt function
@item __ctalkGetExprParserAt (@code{int} @var{idx})
Return the expression parser, which is a struct @samp{EXPR_PARSER}
typedef, at stack index @var{idx.}

@cindex __ctalkGetExprParserPtr function
@item __ctalkGetExprParserPtr (@code{void})
Return the expression parser pointer, and @code{int.}

@cindex __ctalkGetClassVariable function
@item __ctalkGetClassVariable (@code{OBJECT *}@var{receiver}, @code{char *}@var{varname}, @code{int}
@var{warn})
Return the class variable named @var{varname} from the
receiver's class object, or @code{NULL} if the variable does
not exist.  If @var{warn} is @code{TRUE,} issue a warning
message if the variable is not found.

@cindex __ctalkGetInstanceVariable function
@item __ctalkGetInstanceVariable (@code{OBJECT *}@var{receiver}, @code{char *}@var{varname}, @code{int}
@var{warn}) Return the instance variable named @var{varname}
from the receiver, or @code{NULL} if the variable does not
exist.  If @var{warn} is @code{TRUE,} issue a warning
message if the variable is not found.

@cindex __ctalkGetTypeDef function
@item __ctalkGetTypeDef (@code{char *} @var{name})
Return the @code{CVAR} of the typedef @var{name}.

@cindex __ctalkHandleRunTimeException function
@item __ctalkHandleRunTimeException (@code{void})
Execute the exception handler for a pending exception.  The
@mnm{handle} method (class @code{Exception}) calls this function.
@xref{Exception}.

@cindex __ctalkHandleRunTimeExceptionInternal function
@item __ctalkHandleRunTimeExceptionInternal (@code{void})
Execute the exception handler for a pending exception.  If the
exception is generated by an expression, execute the exception handler 
only if further expressions or subexpressions need to be evaluated.

@cindex __ctalkInlineMethod function
@item __ctalkInlineMethod (@code{OBJECT *}@var{rcvr}, @code{METHOD *}@var{method})
Call a method that is an argument to another method.  The class of
@var{rcvr} and the class of @var{method} do not need to be the same.
For an example of the @code{__ctalkInlineMethod}'s use, see @mnm{map}
(@code{Array} class).

@cindex __ctalkIntRadixToDecimal function
@item __ctalkIntRadixToDecimal (@code{char *}@var{intbuf})
Return the integer formatted in @var{intbuf} formatted as a decimal
(base 10) integer.  The function returns a formatted string of the
argument and does not change the value in @var{intbuf.}

@cindex __ctalkInstanceMethodInitReturnClass function
@item __ctalkIntanceMethodInitReturnClass (@code{char *}@var{rcvrclassname}, @code{char *}@var{methodname}, @code{char *}@var{returnclassname})
Set the return class of method @var{methodname} of class
@var{rcvrclassname} to @var{returnclassname}.

@cindex __ctalkIsClassVariableOf function
@item __ctalkIsClassVariableOf (@code{char *}@var{class}, @code{char *}@var{varname})
Returns @code{TRUE} if @var{varname} is a class variable of
@var{class}, @code{FALSE} otherwise.

@cindex __ctalkIsDir function
@item __ctalkIsDir (@code{char *}@var{path})
Returns @code{TRUE} if @var{path} is a directory, @code{FALSE}
otherwise.

@cindex __ctalkIsInstanceVariableOf function
@item __ctalkIsInstanceVariableOf (@code{char *}@var{class}, @code{char *}@var{varname})
Returns @code{TRUE} if @var{varname} is an instance variable of
@var{class}, @code{FALSE} otherwise.

@cindex __ctalkIsObject function
@item __ctalkIsObject (@code{OBJECT *}@var{o})
Return @code{TRUE} if if @var{o} is a valid object, @code{FALSE} otherwise.

@cindex __ctalkIsSubClassOf function
@item __ctalkIsSubClassOf (@code{char *}@var{classname}, @code{char *}@var{superclassname})
Return @code{TRUE} if @var{classname} is a subclass of
@var{superclassname}, @code{FALSE} otherwise.

@cindex __ctalkLibcFnWithMethodVarArgs function
@item __ctalkLibcFnWithMethodVarArgs (@code{int (*}@var{libcfn}@code{)()}, @code{METHOD *}@var{method}, @code{char *}@var{libcfn_return_class})
Call the C library function @var{libcfn} using with its template
method @var{method}.  For C library functions that use @code{stdarg.h}
variable arguments, @var{libcfn_return_class} should be
@code{Integer.}

When evaluating an expression, the currently executing method is
contained in the current
@code{EXPR_PARSER}. @xref{__ctalkGetExprParserAt}.  

@emph{Note:} This version of Ctalk only supports
variable-argument functions on 32-bit Intel platforms.  If you try to
use a variable-argument function on another hardware platform, Ctalk
issues a warning and returns @code{NULL.}

@cindex __ctalkLongLongRadixToDecimal function
@item __ctalkLongLongRadixToDecimal (@code{char *}@var{s})
Convert the radix of the formatted @code{long long int} in @var{s} to 
decimal and return a string containing the formatted @code{long long
int.} 

@cindex __ctalkMethodReturnClass function
@item __ctalkMethodReturnClass 
Set the return class of an instance or class method during method
initialization.

@anchor{__ctalkNewSignalEventInternal}
@cindex __ctalkNewSignalEventInternal function
@item __ctalkNewSignalEventInternal (@code{int} @var{signo}, @code{int} @var{pid}, @code{char *}@var{data})
Generate and queue a @code{SignalEvent} object for signal @var{signo}
with process ID @var{pid}.  The @var{data} argument is a @code{String}
object that the program can use to pass information back to the
application. 

@cindex __ctalkPendingException function
@item __ctalkPendingException (@code{void})
A convenience method for @code{__ctalkTrapException.}  Returns
@code{TRUE} if an exception is pending, @code{FALSE} otherwise.

@anchor{__ctalkPrintObject}
@cindex __ctalkPrintObject function
@item __ctalkPrintObject (@code{char *}@var{objectname})
Print the object named by the argument, and its instance variables, to
standard output for debugging.

@cindex __ctalkReplaceVarEntry function
@item __ctalkReplaceVarEntry (@code{VARENTRY *}@var{varentry}, @code{OBJECT *}@var{new_object})
Replace the object in @var{varentry} with @var{new_object}, and 
return the old object. 

@cindex __ctalkTemplateCallerCVARCleanup function
@item __ctalkTemplateCallerCVARCleanup (@code{void})
Cleans up after a @cite{__ctalkGetTemplateCallerCVAR}
call. @xref{__ctalkGetTemplateCallerCVAR}.  Ctalk calls this function
internally; you should not need to use it in your own programs.

@cindex @code{ARG()} macro
Note that this function does not know about parameter substitution.  If
you want to print an object that is an argument to a method, use the
@code{ARG(@var{n})} macro, and reference the @code{name} member.
@xref{ARG macro}.
@example
__ctalkPrintObject(ARG(0)->__o_name);
@end example

@cindex __ctalkSelfPrintOn function
@item __ctalkSelfPrintOn (void)
Print the calling method's arguments to the receiver.  This 
function is called directly by @mnm{printOn} (class @code{String})
and similar methods. @xref{String}.

@cindex __ctalkSetObjectScope function
@cindex Scope of objects
@item __ctalkSetObjectScope (@code{OBJECT *}@var{object}, @code{int} @var{scope})
Set the scope of @var{object} to @var{scope}.  Ctalk uses the
following scope definitions.
@table @code
@item GLOBAL_VAR
@item LOCAL_VAR
@item ARG_VAR
@item RECEIVER_VAR
@item PROTOTYPE_VAR
@item BLOCK_VAR
@item CREATED_PARAM
@item CVAR_ALIAS_COPY
@end table
Object declared and created with @mnm{new} outside of any function or
method have the scope @code{GLOBAL_VAR.}  Objects created within
functions and methods have the scope @code{LOCAL_VAR.}  Ctalk uses the
other definitions internally.  You should not need to use them
in normal code.

@cindex __ctalkSetObjectValue function
@item __ctalkSetObjectValue (@code{OBJECT *}@var{object}, @code{char *}@var{value})
Set the value of @var{object} to @var{value}.  Note that this function
only sets the value of the object itself, not the value of the
@code{value} instance variable.  For most cases, you should use
@code{__ctalkSetObjectValueVar,} below.

@cindex __ctalkSetObjectValueBuf function
@item __ctalkSetObjectValueBuf (@code{OBJECT *}@var{object}, @code{char *}@var{buf})
Set the @code{value} instance variable to the buffer @var{buf}.
Unlike @code{__ctalkSetObjectValue} and
@code{__ctalkSetObjectValueVar,} this function replaces the value with
@var{buf}, even if @var{buf} is empty, so you can add a random-length
buffer to @var{object}.

@cindex __ctalk_arg function
@item __ctalk_arg (@code{char *}@var{rcvr}, @code{char *}@var{method},@code{void *}@var{arg}
Define an argument for the following @code{__ctalk_method ()} call.  

@cindex __ctalk_arg_cleanup function
@item __ctalk_arg_cleanup (@code{void})
Remove an argument used by the previous @code{__ctalk_method ()} call.

@anchor{errorfuncs}
@cindex _error function
@item _error (@code{char *}@var{fmt}, @code{...})
Issue an error message and exit the program.

@cindex _warning function
@item _warning (@code{char *}@var{fmt}, @code{...})
Issue a warning message.

@cindex substrcpy function
@item substrcpy (@code{char *}@var{dest}, @code{char *}@var{src}, @code{int} @var{start_index}, @code{int} @var{end_index})
Copy a substring of @var{src} from @var{start_index} to
@var{end_index} to @var{dest}.

@cindex substrcat function
@item substrcat (@code{char *}@var{dest}, @code{char *}@var{src}, @code{int} @var{start_index}, @code{int} @var{end_index})
Concatenate the substring of @var{src} from @var{start_index} to
@var{end_index} to @var{dest}.

@cindex TRIM_LITERAL macro
@item TRIM_LITERAL(@var{s})
A macro that trims the quotes from a literal string.  It expands to 
@code{substrcpy (@var{s}, @var{s}, 1, strlen (@var{s}) - 2)}.

@cindex TRIM_CHAR macro 
@item TRIM_CHAR(@var{c})
A macro that trims the quotes from a literal character.  It expands to 
@code{substrcpy (@var{c}, @var{c}, 1, strlen (@var{c}) - 2)}

@cindex TRIM_CHAR_BUF macro 
@item TRIM_CHAR_BUF(@var{s})
A macro that trims nested single quotes from a literal character.
@code{TRIM_CHAR_BUF} also checks whether a single quote (@samp{'}) is
the actual character.

@end table

@node C, Copying, Methods, Top
@iftex
@chapter C Language Features
@end iftex
@ifnottex
@heading C Language Features
@end ifnottex
@cindex C language features

@iftex
This chapter describes @command{ctalk}'s C language features and
its low-level application programming interface.
@end iftex
@ifnottex
This chapter describes @command{ctalk}'s C language features and
its low-level application programming interface.
@end ifnottex

@menu
* Preprocessor::        Compatibility with @command{cpp}.
* C statements::        How to use objects and C in the same programs.
* Control structures::  Objects in loops and conditional statements.
* OBJECT typedef::      Ctalk's @code{OBJECT} type.
* C library functions:: How to use objects with C library functions.
@end menu


@node Preprocessor, C statements, , C
@iftex
@section @command{ctpp,} the @command{ctalk} Preprocessor
@end iftex
@ifnottex
@subheading @command{ctpp,} the @command{ctalk} Preprocessor
@end ifnottex
@cindex Preprocessor
@cindex @command{ctpp} preprocessor
@cindex Include files
@cindex Header files

Information about @command{ctpp}, the Ctalk preprocessor, is contained
in its Texinfo manual, @flnm{ctpp.info}.

The preprocessor is compatible with GNU @command{cpp} and supports ISO
C99 preprocessing features.  This allows you to include C header files
in Ctalk programs and class libraries.  Ctalk caches macros from
include files, so it can use, in the GNU compiler's terminology,
@emph{include once} header files. 

If you have a header file called, for example, @flnm{myheader.h}, you
would wrap the definitions with the following preprocessor directives.

@example

#ifndef _MYHEADER_H
#define _MYHEADER_H
.
. <Your definitions appear here.>
.
#endif /* _MYHEADER_H */
@end example

This makes certain that the preprocessor defines macros, data types,
and other library definitions only once, no matter how many times the
input includes the header file.

@node C statements, Control structures, Preprocessor, C

@iftex
@section Pragmas
@end iftex
@ifnottex
@subheading Pragmas
@end ifnottex
@cindex Pragmas

Ctalk recognizes GCC, G++, and C99 pragmas.  

Pragmas that apply to floating point operations and code generation
are ignored and elided, unless the @samp{--keeppragmas} command line
option is given.  @xref{Invoking}.

Inclusion of a file that contains G++ pragmas causes the preprocessor
to issue a warning if the @samp{-v} option is given, and
@command{ctalk} ignores the file. @xref{Invoking}.

Here is the effect of the GCC and C99 pragmas.

@table @code

@cindex #pragma interface
@cindex #pragma implementation

@item #pragma interface
@item #pragma implementation
The include file is not processed.

@cindex #pragma GCC dependency

@item #pragma GCC dependency @var{file}
Issues a warning if the source file is more recent than @var{file}.

@cindex #pragma GCC poison

@item #pragma GCC poison @var{identifier} ...
@command{ctalk} issues an error and discontinues processing if the
source file contains an identifier given as an argument.

@cindex #pragma GCC system header

@item #pragma GCC system header
The @command{ctalk} preprocessor processes all input files in the
same manner and ignores this pragma.

@cindex #pragma GCC pack
@cindex #pragma STDC FP_CONTRACT
@cindex #pragma STDC FENV_ACCESS
@cindex #pragma STDC CX_LIMITED_RANGE

@item #pragma GCC pack
@item #pragma STDC FP_CONTRACT
@item #pragma STDC FENV_ACCESS
@item #pragma STDC CX_LIMITED_RANGE
@command{ctalk} ignores and elides these pragmas, which apply to
floating point and code generation options, unless the
@samp{--keeppragmas} option is used. @xref{Invoking}.

@end table

@iftex
@section C Expressions
@end iftex
@ifnottex
@subheading C Expressions
@end ifnottex
@cindex C expressions

In version @value{VERSION}, you can use simple constant expressions as
receivers, as in this example.

@example
printf ("%s", "/home/users/joe" subString 1, self length - 1);
@end example

@emph{Warning} - This use of @code{self} is experimental in version
@value{VERSION} and should be used with caution.

You can use a C constant in place of any receiver whose class
corresponds to a basic C data type.  These classes include
@code{Character}, @code{String}, @code{Float}, @code{Integer}, and
@code{LongInteger}.

Expressions like the following work.
@example
if (99 == myInt)
 ...

if ('c' == myInt asCharacter)
 ...

if (3.1416 == pi)
 ...
@end example

The following code examples are equivalent.

@example
myString = "This is a string.";
printf ("%d\n", myString length);
@end example

and,

@example
printf ("%d\n", "This is a string" length);
@end example

However, if you try to use a C variable on the left side of a method
that overloads a C operator, the expression might simply be
interpreted as C code, as in this example.

@example
  String new progName;

  progName = "myprog";

  if (argv[0] == progName) @{
    ...
  @}
@end example

This is because Ctalk does not interpret @code{argv[0]} as a receiver
object, and then interprets @code{==} as a C operator.

@iftex
@section Objects in Function Parameters
@end iftex
@ifnottex
@subheading Objects in Function Parameters
@end ifnottex
@cindex Function parameters

Programs cannot, at this time, use objects as parameters to C 
functions.  If you need to use an object as a parameter, you need
to use a method instead of a function, or translate the object's value
to C. @xref{Translating}.

@iftex
@section Objects in Function Arguments
@end iftex
@ifnottex
@subheading Objects in Function Arguments
@end ifnottex
@cindex Function arguments
@anchor{Objects in Function Arguments}

You can use of Ctalk expressions as C function arguments, but the
values should be treated as read-only, as in this example.

@example
Integer new myIndex;
char buf[255];

myIndex = 0;

/*
 *   This statement works correctly. 
 */
sprintf (buf, "%d", __ctalk_to_c_int (myIndex));

/*
 *   This statement does not work correctly.
 */
sscanf (myString, "%s %s", mySubString1, mySubString2);
@end example

@cindex @code{Unimplemented C type} warning
@cindex @code{Symbol} class
If you receive an @code{Unimplemented C type} warning, it means that
Ctalk does not implement a class that corresponds to the data type.
In these cases, you can generally assign the C variable to an instance
of class @code{Symbol,} and use that as the argument to a function.

@cindex @idxfncite{ctime(3)}
The function @cite{ctime(3)} is a good example. The following program
shows how a Ctalk expression would use a @code{Symbol} object to
represent the address of a @code{time_t} scalar variable, while a C
expression would use an address-of (@samp{&}) operator.
@example
#include <time.h>

int main () @{

  time_t t;
  char timebuf[255];
  String new timeStr;
  Symbol new timeValPtr;

  t = time (NULL);    /* Argument for a C expression.     */
  timeValPtr = t;     /* Argument for a Ctalk expression. */

  strcpy (timebuf, ctime (&t));

  if ((timeStr = ctime (timeValPtr)) == timebuf) @{
    printf ("Pass\n");
  @} else @{
    printf ("Fail\n");
  @}

  printf ("%s\n", timebuf);
  printf ("%s\n", timeStr);

  exit(0);
@}
@end example

The Classes that implement C data types are described in the next
section. 

@iftex
@section C Data Type Classes
@end iftex
@ifnottex
@subheading C Data Type Classes
@end ifnottex

These classes correspond to the basic C types.

@table @code

@cindex @code{char **} C data type
@item Array
@code{char **}

@cindex @code{char} C data type
@item Character
@code{char}

@cindex @code{float} C data type
@cindex @code{double} C data type
@item Float
@code{float} and @code{double}

@cindex @code{int} C data type
@cindex @code{long int} C data type
@item Integer
@code{int} and @code{long int}

@cindex @code{long long int} C data type
@item LongInteger
@code{long long int}

@cindex @code{char *} C data type
@item String
@code{char *}

@end table

@iftex
@section Typedefs in Function Arguments
@end iftex
@ifnottex
@subheading Typedefs in Function Arguments
@end ifnottex
@cindex Typedefs
@cindex @code{time_t} type

Ctalk resolves many of the derived types defined in C99, as well as
incomplete types; however, variables that are of derived types can
still cause unpredictable results, if the variable is of an unusual or
complex type.
 
If you encounter a case where a derived type confuses the parser or
run-time library, the workaround is to declare the type as an
equivalent C type.  For example, if a variable is of type
@code{time_t,} you could equivalently declare it as type @code{long
long int.}

@iftex
@section C Functions in Complex Expressions
@end iftex
@ifnottex
@subheading C Functions in Complex Expressions
@end ifnottex

You can use C functions in complex expressions within conditionals,
as in this example.
@example
int int_fn1 (void) @{
  return 10;
@}

char *add_int_fn_as_string (int a, int b, int c) @{
  static char buf[30];
  sprintf (buf, "%d", a + b + c);
  return buf;
@}

int main () @{

  String new myString1;

  if ((myString1 = add_int_fn_as_string (int_fn1 (), 20, 30)) != "60")
    exit(1);
    
  printf ("%s\n", myString1);

@}
@end example
As long as your function returns one of the C data types @code{int,
char, char *,} or @code{double,} Ctalk can translate the function
output to an object, as well as call the function at run time using
a method call.

If you try to use a C function that returns a complex or derived type,
Ctalk prints a warning and uses @code{Integer} as the default return
class.  In these cases, you should consider writing a method instead.

@emph{Note:} When you use functions in complex expressions, the
function's arguments must also be C variables or expressions.  If you
want to use objects as the arguments to a function, then you must
perform the object-to-C translation manually.

@iftex
@section Debugging with @command{gdb}
@end iftex
@ifnottex
@subheading Debugging with @command{gdb}
@end ifnottex
@cindex Debugging
@cindex @code{ctdb} command
@cindex @code{gdb} command
At this time, Ctalk is not fully compatible with the GNU @command{gdb}
debugger. Due to the amount of library code that Ctalk inserts in the
source file, @command{gdb} does not calculate source lines correctly.  If
you want to debug a Ctalk program or method with @command{gdb}, use the
@samp{-P} command line option to disable line numbering.  You can then
debug the intermediate output, which is normal C that @command{gdb} can
interpret correctly.

The @code{ctdb} command builds Ctalk programs with the correct
arguments for debugging.  Then you can use @code{gdb} to debug the program.

@example
$ ctdb myprog.c
@end example

If you need to debug either @code{ctalk} or the @code{libctalk}
library, then you need to build and install Ctalk without
optimization.  Optimization can remove lines from the installed
programs so that the binaries no longer correspond with the source
code.

@cindex Optimization
To build Ctalk for debugging, configure the package's Makefiles
without the compiler optimization options.
@example
$ ./configure --without-inline-functions --without-optimization
@end example
Then build and install Ctalk with @code{make} and @code{make install.}

Ctalk also has a simple function to print objects for inspection. 
@xref{__ctalkPrintObject}.

@c
@c  Control structures
@c
@node Control structures, OBJECT typedef, C statements, C

@iftex
@section Control Structures
@end iftex
@ifnottex
@subheading Control Structures
@end ifnottex
@cindex @code{if} statements
@cindex @code{for} statements
@cindex @code{while} statements
@cindex @code{do} statements

Generally, Ctalk objects work the same as C variables when
they appear in @code{if}, @code{for}, @code{while}, and @code{do}
statements.

@cindex @code{switch} statements
However, this version of Ctalk cannot use objects within @code{switch}
statement cases.  This is due to the way the parser frames the
statements, and the issue should be resolved in future releases.


@node OBJECT typedef, C library functions, Control structures, C

@heading @code{OBJECT} typedef

@cindex OBJECT typedef

At the lowest level, ctalk declares objects as pointers to an
@code{OBJECT} struct.  You can access an object's members if you
assign an object's value to a C variable of the type @code{OBJECT *},
as in this example.

@example
Object new myObject;
OBJECT *myObjectValue;

myObjectValue = myObject value;

if (!strcmp (myObjectValue -> __o_classname, "Object"))
   printf ("myObjectValues class is, \"Object.\"\n");
@end example

The declaration of the OBJECT type is contained in @flnm{include/object.h}.

@example
typedef struct _object OBJECT;
. . .
struct _object @{
  char sig[16];
  char __o_name[MAXLABEL];
  char __o_classname[MAXLABEL];
  OBJECT *__o_class;
  char __o_superclassname[MAXLABEL];
  OBJECT *__o_superclass;
  OBJECT *__o_p_obj;
  VARENTRY *__o_varentry;
  char *__o_value;
  METHOD *instance_methods,
    *class_methods;
  int scope;
  int nrefs;
  struct _object *classvars;
  struct _object *instancevars;    
  struct _object *next;
  struct _object *prev;
@};
@end example

Note that @code{__o_name}, @code{__o_classname},
@code{__o_superclassname}, and @code{__o_value} are all @code{char *},
even if the object belongs to a class like @code{Integer} or
@code{Float}.  The struct members @code{__o_class} and
@code{__o_superclass} contain pointers to the library class and
superclass entries, which are also objects.

For numeric classes, the @code{value} member contains a formatted
representation of a numeric value.  Examples of directly assigning
values to objects are given in the section about writing methods.
@xref{Method API}.

Ctalk uses the members @code{instance_methods,} @code{class_methods,}
@code{classvars} for class objects.

The @code{sig} member simply contains the string @samp{OBJECT}, and it
is used to check if an @code{OBJECT *} refers to a valid object.

The @code{scope} member describes an object's scope.  The scope can be
one of @code{GLOBAL_VAR}, @code{LOCAL_VAR}, @code{ARG_VAR},
@code{RECEIVER_VAR}, @code{PROTOTYPE_VAR}, or @code{BLOCK_VAR.}

The @code{nrefs} member keeps track of the number of references that
exist to an object at run time.  Every time ctalk creates a reference
to an object, internally ctalk increments @code{nrefs}.  When ctalk
deletes a reference, it decrements @code{nrefs}.  When 
@code{nrefs} drops to zero, @command{ctalk} deletes the object.


@node C library functions, , OBJECT typedef, C
@iftex
@section C Library Functions
@end iftex
@ifnottex
@subheading C Library Functions
@end ifnottex
@cindex C library functions

You can assign the result of a C library function to a Ctalk object,
provided that the return type of the function has a corresponding 
Ctalk class.  

You should prototype C functions.  The library functions in this
section have prototypes defined in the C library headers.  Functions
that do not have prototypes generate warning messages.  Also, in
this version, you should be careful of using a function within a
complex expression that also contains objects.  If you are in doubt,
use a method instead.

Generally, if Ctalk has a method that is analogous to a C library
function, you can use the method with Ctalk objects, although in many
cases you can mix objects and C variables.  Of course, you can still
use any C library function with C data types.

@cindex Xt object classes
@cindex X Window System
@cindex C library compatibility

There are some incompatibilities with more specialized libraries.  For
example, you should take care when using the X Window System Xt
widgets in Ctalk programs, because the widget classes use the some of
the same class names as the Ctalk library.

The following sections describe the C library functions that Ctalk can
use directly.

@menu
* abs::
* acos::
* acosh-asinh-atanh::
* asctime::
* asin::
* atexit::
* atof::
* atoi::
* atol::
* atoll::
* calloc::
* cbrt::
* ceil::
* chdir::
* clock::
* copysign::
* cos::
* cosh::
* ctime::
* difftime::
* erf::
* erfc::
* exp::
* expm1::
* fabs::
* fclose::
* fegetround::
* feholdexcept::
* feof::
* ferror::
* fesetround::
* fetestexcept::
* fflush::
* fgetc::
* fgetpos::
* fgets::
* floor::
* fmod::
* fopen::
* fprintf::
* fputc::
* fputs::
* fread::
* free::
* freopen::
* frexp::
* fscanf::
* fseek::
* fsetpos::
* fstat::
* ftell::
* fwrite::
* getc::
* getchar::
* getcwd::
* getenv::
* getpid::
* gmtime-localtime::
* index-function::
* isalnum-isxdigit::
* labs::
* llabs::
* llrint::
* llround::
* log::
* log10::
* log1p::
* lrint::
* lround::
* malloc::
* memchr::
* memcmp::
* memcpy::
* memmove::
* memset::
* mkdir::
* modf::
* nearbyint::
* perror::
* pow::
* printf::
* raise::
* rand::
* realloc::
* remove::
* rename::
* rindex::
* rint::
* rmdir::
* round::
* scanf::
* sin::
* sinh::
* snprintf::
* sprintf::
* sqrt::
* srand::
* sscanf::
* strcat-strcpy::
* strchr::
* strcoll::
* strspn::
* strerror::
* strftime::
* strlen::
* strncat-strncpy::
* strpbrk::
* strrchr::
* strstr::
* strtod::
* strtok::
* strtoll::
* strxfrm::
* system::
* tan::
* tanh::
* tmpnam::
* tolower::
* toupper::
* trunc::
* ungetc::
* vfprintf::
* vfscanf::
* vprintf::
* vscanf::
* vsnprintf::
* vsprintf::
* vsscanf::
@end menu

@c Need classes:
@c atexit, btowc, bsearch, calloc, lrintf, lrintl, llrintf, 
@c llrintl, localeconv,
@c lrintf, lrintl, lroundf, lroundl, mktime, nearbyintf,
@c nearbyintl, qsort, rewind, rintf, rintl, roundf, roundl, setjmp,
@c sigsetjmp, strtoul, strtoull, time, tmpfile, truncf, truncl
@c
@c Unsupported or inapplicable functions:
@c On Linux - cabs, cacos, cacosh, carg, casin, casinh, catan, catanh,
@c  ccos, ccosh, cerf, cexp, cexp2, cexpm1, cgamma, cimag, clearerr,
@c  clgamma, clog, clog10, clog1p, clog2, conj, cpow, cproj, creal,
@c  csin, csinh, csqrt, ctan, ctanh, exp2, ilogb, mkxtime, nan,
@c  nextafter, remainder, remquo, scalbln, scalbn, strfxtime,
@c  strtof, strtoimax, strtold, strtol, strtoumax, tgamma, zonetime
@c ceilf, ceill, div, fdim, feclearexcept, fegetenv, fegetexceptflag,
@c feraiseexcept, fesetenv, fesetexceptflag, feupdateenv, fgetwc,
@c fgetws, fma, fmax, fputwc, fputws, fwide, fwprintf, fwscanf,
@c iswalnum, iswalpha, iswcntrl, iswctype, iswdigit, iswgraph, 
@c iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit
@c lldiv, log2, logb, mblen, mbrlen, mbrtowc, mbsinit, mbsrtowcs,
@c mbstowcs, mbtowc, swprinft, swscanf, towctrans, towlower, towupper,
@c unwgetc, vfwprintf, vfwscanf, vswprintf, vswscanf, vwprintf,
@c vwscanf, wcrtomb, wcschr, wcscmp, wcscoll, wcscpy, wcscspn,
@c wcsftime, wcsfxtime, wcslen, wcsncat, wcsncmp, wcsncpy, wcspbrk,
@c wcsrchr, wcsrtombs, wcsspn, wcsstr, wcstod, wcstof, wcstoimax,
@c wcstok, wcstol, wcstold, wcstoll, wcstombs, wcstoul, wcstoull,
@c wcstoumax, wcsxfrm, wcstob, wctomb, wctrans, wctype, wmemchr,
@c wmemcmp, wmemcpy, wmemmove, wmemset, wprintf, wscanf
@c
@c Superfluous at least for now.
@c setbuf, setvbuf



@node abs, acos, ,C library functions

@subheading @code{abs} Function
@cindex @idxfncite{abs(3)}
@example

#include <stdlib.h>

Integer new i;

i = abs (3);

@end example

@node acos, acosh-asinh-atanh, abs, C library functions
@subheading @code{acos} Function
@cindex @idxfncite{acos(3)}

@example

#include <math.h>

Integer new i;

i = acos (0.5);

@end example

Ctalk does not check if the argument is outside the range -1 to 1 and
does not check for an error.  Refer to the, @code{acos}, manual page.

@node acosh-asinh-atanh, asctime, acos, C library functions
@subheading @code{acosh,} @code{asinh,} and @code{atanh} Functions
@cindex @idxfncite{acosh(3)}
@cindex @idxfncite{asinh(3)}
@cindex @idxfncite{atanh(3)}

@example

#include <math.h>

Float new myFloat;

myFloat = acosh (2.0);

@end example

Ctalk does not check the range of the arguments or errors.
Refer to the, @cite{acosh(3), asinh(3),} and @cite{atanh(3)}
manual pages.

@node asctime, asin, acosh-asinh-atanh, C library functions

@subheading @code{asctime} Function

@cindex @idxfncite{asctime(3)}

@example

#include <time.h>

time_t t;
struct tm *time_struct;
String new s;

time (&t);
time_struct = localtime (&t);
s = asctime (time_struct);

@end example

@emph{Note:} Ctalk does not have a class corresponding to a
@code{struct tm *.}  An explicit assignment of a @code{struct tm *} to
a @code{Symbol} passes the address to @code{asctime.} @xref{Objects in
Function Arguments}.

@node asin, atexit, asctime, C library functions

@subheading @code{asin} Function

@cindex @idxfncite{asin(3)}

@example
#include <math.h>

Float new f;

f = asin (0.5);
@end example

Note that ctalk does not perform any range checking of the argument.

@node atexit, atof, asin, C library functions
@subheading @code{atexit} Function
@cindex @idxfncite{atexit(3)}
@example 
#include <stdlib.h>

Integer new i;

i = atexit (exitfunc);

@end example

@node atof, atoi, atexit, C library functions
@subheading @code{atof} Function
@cindex @idxfncite{atof(3)}

@example
#include <stdlib.h>

Float new pi;

pi = atof ("3.1416");
@end example

@node atoi, atol, atof, C library functions

@subheading @code{atoi} Function

@cindex @idxfncite{atoi(3)}

@example
#include <stdlib.h>

Integer new i;

i = atoi ("35");
@end example

@node atol, atoll, atoi, C library functions

@subheading @code{atol} Function

@cindex @idxfncite{atol(3)}

@example
#include <stdlib.h>

Integer new i;

i = atol ("35");
@end example

Note that, @code{Integer}, class corresponds to the C types,
@code{int}, and, @code{long int}.

@node atoll, calloc, atol, C library functions

@subheading @code{atoll} Function

@cindex @idxfncite{atoll(3)}

#include <stdlib.h>

LongInteger new i;

i = atoll ("35");

@node calloc, cbrt, atoll, C library functions

@subheading @code{calloc} Function

@cindex @idxfncite{calloc(3)}

@example
#include <stdlib.h>

Integer new n;
Integer new size;
int *intbuf;

n = 10;
size = sizeof (int);

intbuf = calloc (n, size);
@end example

@node cbrt, ceil, calloc, C library functions
@subheading @code{cbrt} Function
@cindex @idxfncite{cbrt(3)}

#include <math.h>

Float new f;

f = cbrt (9.0);

@node ceil, chdir, cbrt, C library functions
@subheading @code{ceil} Function
@cindex @idxfncite{ceil(3)}

#include <math.h>

Float new f;

f = ceil (3.5);

@node chdir, clock, ceil, C library functions
@subheading @code{chdir} Function
@cindex @idxfncite{chdir(3)}

Integer new result;
String new dirName;

dirName = "mySubdir";

result = chdir (mySubdir);

@node clock, copysign, chdir, C library functions
@subheading @code{clock} Function
@cindex @idxfncite{clock(3)}

@example
#include <time.h>

Integer new i;

i = clock ();
@end example

@node copysign, cos, clock, C library functions
@subheading @code{copysign} Function
@cindex @idxfncite{copysign(3)}

@example
#include <math.h>

Float new f;

f = copysign (3.0, -1.0);
@end example

@node cos, cosh, copysign, C library functions
@subheading @code{cos} Function
@cindex @idxfncite{cos(3)}

@example
#include <math.h>

Float new f;

f = cos (45.0);
@end example

@node cosh, ctime, cos, C library functions
@subheading @code{cosh} Function
@cindex @idxfncite{cosh(3)}

@example
#include <math.h>

Float new f;

f = cosh (45.0);
@end example

@node ctime, difftime, cosh, C library functions
@subheading @code{ctime} Function
@cindex @idxfncite{ctime(3)}

@example

#include <time.h>

time_t t;
String new s;

time (&t);
s = ctime (&t);

@end example

@emph{Note:} Ctalk does not have a class corresponding to 
a @code{struct tm *.}  An explicit assignment of a @code{struct tm *} to
a @code{Symbol} passes the address to @code{ctime.} @xref{Objects in
Function Arguments}.


@node difftime, erf, ctime, C library functions
@subheading @code{difftime} Function
@cindex @idxfncite{difftime(3)}

@example

#include <time.h>

Float new f;

f = difftime (time1, time0);

@end example

@node erf, erfc, difftime, C library functions
@subheading @code{erf} Function
@cindex @idxfncite{erf(3)}

@example

#include <math.h>

Float new f;

f = erf (0.5);

@end example

@node erfc, exp, erf, C library functions
@subheading @code{erfc} Function
@cindex @idxfncite{erfc(3)}

@example

#include <math.h>

Float new f;

f = erfc (0.5);

@end example

@node exp, expm1, erfc, C library functions
@subheading @code{exp} Function
@cindex @idxfncite{exp(3)}

@example

#include <math.h>

Float new f;

f = exp (2);

@end example

@node expm1, fabs, exp, C library functions
@subheading @code{expm1} Function
@cindex @idxfncite{expm1(3)}

@example

#include <math.h>

Float new f;

f = expm1 (1.05);

@end example

@node fabs, fclose, expm1, C library functions
@subheading @code{fabs} Function
@cindex @idxfncite{fabs(3)}

@example

#include <math.h>

Float new f;

f = fabs (-1.05);

@end example

@node fclose, fegetround, fabs, C library functions
@subheading @code{fclose} Function
@cindex @idxfncite{fclose(3)}

@example

#include <stdio.h>

Integer new i;

i = fclose (fileHandle);

@end example

@node fegetround, feholdexcept, fclose, C library functions
@subheading @code{fegetround} Function
@cindex @idxfncite{fegetround(3)}

@example

#include <fenv.h>

Integer new i;

i = fegetround ();

@end example

@node feholdexcept, feof, fegetround, C library functions
@subheading @code{feholdexcept} Function
@cindex @idxfncite{feholdexcept(3)}

@example

#include <fenv.h>

Integer new i;

i = feholdexcept (fe_envp);

@end example

@node feof, ferror, feholdexcept, C library functions
@subheading @code{feof} Function
@cindex @idxfncite{feof(3)}

@example

#include <stdio.h>

Integer new i;

i = feof (fileStream);

@end example

@node ferror, fesetround, feof, C library functions
@subheading @code{ferror} Function
@cindex @idxfncite{ferror(3)}

@example

#include <stdio.h>

Integer new i;

i = ferror (fileStream);

@end example

@node fesetround, fetestexcept, ferror, C library functions
@subheading @code{fesetround} Function
@cindex @idxfncite{fesetround(3)}

@example

#include <math.h>

Integer new i;

i = fesetround (mode);

@end example

@node fetestexcept, fflush, fesetround, C library functions
@subheading @code{fetestexcepts} Function
@cindex @idxfncite{fetestexcepts(3)}

@example

#include <math.h>

Integer new i;

i = fetestxcept (exceptions);

@end example

@node fflush, fgetc, fetestexcept, C library functions
@subheading @code{fflush} Function
@cindex @idxfncite{fflush(3)}

@example

#include <stdio.h>

Integer new i;

i = fflush (fileStream);

@end example

@node fgetc, fgetpos, fflush, C library functions
@subheading @code{fgetc} Function
@cindex @idxfncite{fgetc(3)}

@example

#include <stdio.h>

Integer new i;

i = fgetc (fileStream);

@end example

@node fgetpos, fgets, fgetc, C library functions
@subheading @code{fgetpos} Function
@cindex @idxfncite{fgetpos(3)}

@example

#include <stdio.h>

Integer new i;

i = fgetpos (fileStream, pos);

@end example

@node fgets, floor, fgetpos, C library functions
@subheading @code{fgets} Function
@cindex @idxfncite{fgets(3)}

@example

#include <stdio.h>

String new s;

s = fgets (s, s length, fileStream);

@end example

@node floor, fmod, fgets, C library functions
@subheading @code{floor} Function
@cindex @idxfncite{floor(3)}

@example

#include <math.h>

Float new f;

f = floor (3.01);

@end example

@node fmod, fopen, floor, C library functions
@subheading @code{fmod} Function
@cindex @idxfncite{fmod(3)}

@example

#include <math.h>

Float new f;

f = fmod (3.0, 2.0);

@end example

@node fopen, fprintf, fmod, C library functions
@subheading @code{fopen} Function
@cindex @idxfncite{fopen(3)}

@example

#include <stdio.h>

FILE *f

String new path;
String new mode;

path = "/home/user/.profile";
mode = "r";

f = fopen (path, mode);

@end example

@node fprintf, fputc, fopen, C library functions
@subheading @code{fprintf} Function
@cindex @idxfncite{fprintf(3)}

@xref{Variable arguments}.

@node fputc, fputs, fprintf, C library functions
@subheading @code{fputc} Function
@cindex @idxfncite{fputc(3)}

@example

#include <stdio.h>

Integer new myInput;

myInput = fgetc (stdin);
fputc (myInput, stdout);

@end example

@node fputs, fread, fputc, C library functions
@subheading @code{fputc} Function
@cindex @idxfncite{fputc(3)}

@example
#include <stdio.h>

String new myInput;

fgets (myInput, 255, stdin);
fputs (myInput, stdout);
@end example

@node fread, free, fputs, C library functions
@subheading @code{fread} Function
@cindex @idxfncite{fread(3)}

@example
#include <stdio.h>

String new myInput;

myInput = "";

fread (myInput, 255, sizeof (char), stdin);
@end example

@node free, freopen, fread, C library functions
@subheading @code{free} Function
@cindex @idxfncite{free(3)}

Do not use @code{free} with objects.  Use the
@code{__ctalkDeleteObject} library function instead.

@example
Object new myObject;        

__ctalkDeleteObject (myObject);
@end example

@node freopen, frexp, free, C library functions
@subheading @code{freopen} Function
@cindex @idxfncite{freopen(3)}

@example
#include <stdio.h>

FILE *f;

String new path;
String new mode;

path = "/home/user/.profile";
mode = "r";

f2 = freopen (path, mode, stdin);
@end example

@node frexp, fscanf, freopen, C library functions
@subheading @code{frexp} Function
@cindex @idxfncite{frexp(3)}

@example
#include <math.h>

int i_exp_val;
Integer new expInt;
Float new myFloat;
Float new myFraction;

myFloat = "2.5";

myFraction = frexp (myFloat, &i_exp_val);

expInt = i_exp_val;
@end example

@node fscanf, fseek, frexp, C library functions
@subheading @code{fscanf} Function
@cindex @idxfncite{fscanf(3)}

@xref{Variable arguments}.

@cindex @code{stdin}
@cindex @code{stdout}
@cindex @code{stderr}
@cindex @code{stdinStream} @idxclscite{ReadFileStream}
@cindex @code{stdoutStream} @idxclscite{WriteFileStream}
@cindex @code{stderrStream} @idxclscite{WriteFileStream}
@emph{Note:} The C99 standard requires that @code{stdin,}
@code{stdout,} and @code{stderr} should be implemented as
macros, which on some systems (notably Solaris) causes
problems with C-to-object translation.  If Ctalk cannot
register these macros as C variables, then either call
@idxfncite{fscanf(3)} with only C variables, or use a method
with @code{stdoutStream} or @code{stderrStream}
@xref{WriteFileStream}, or @code{stdinStream} @xref{ReadFileStream}.

@node fseek, fsetpos, fscanf, C library functions
@subheading @code{fseek} Function
@cindex @idxfncite{fseek(3)}

@node fsetpos, fstat, fseek, C library functions
@subheading @code{fsetpos} Function
@cindex @idxfncite{fsetpos(3)}

@example
#include <stdio.h>

FILE *f;
String new path;
String new mode;
Integer new offset;
  
path = "/home/user/.profile.new";
mode = "r";


f = fopen (path, mode);

offset = 0L;

fsetpos (f, offset);
@end example

@node fstat, ftell, fsetpos, C library functions
@subheading @code{fstat} Function
@cindex @idxfncite{fstat(3)}

@example
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

String new path;
Integer new result;
struct stat statbuf;

path = "/home/user/.profile";

result = fstat (path, &statbuf);

@end example

@node ftell, fwrite, fstat, C library functions
@subheading @code{ftell} Function
@cindex @idxfncite{ftell(3)}

@example
#include <stdio.h>

Integer new filePos;

filePos = ftell (file);
@end example

@node fwrite, getc, ftell, C library functions
@subheading @code{fwrite} Function
@cindex @idxfncite{fwrite(3)}

@example
#include <stdio.h>

FILE *f;
String new path;
String new mode;
String new promptLine;
  
path = "/home/user/.profile.new";
mode = "a";

f = fopen (path, mode);

promptLine = "PS1=#";

fwrite (promptLine, promptLine length, sizeof (char), f);
@end example

@node getc, getchar, fwrite, C library functions
@subheading @code{getc} Function
@cindex @idxfncite{getc(3)}

@example
#include <stdio.h>

Integer new myInput;

myInput = getc (stdin);

printf ("%c", myInput asCharacter);
@end example

@node getchar, getcwd, getc, C library functions
@subheading @code{getchar} Function
@cindex @idxfncite{getchar(3)}

@example
#include <stdio.h>

Integer new myInput;

myInput = getchar ();

printf ("%c", myInput asCharacter);
@end example

@node getcwd, getenv, getchar, C library functions
@subheading @code{getcwd} Function
@cindex @idxfncite{getcwd(3)}
@example
#include <stdio.h>
String new myString;
getcwd (myString, FILENAME_MAX);
@end example
@emph{Note:} The argument @code{myString} must already be initialized
to hold the entire directory path.  If in doubt, use @code{getCwd}
(class @code{DirectoryStream}) instead. @xref{DirectoryStream}.

@node getenv, getpid, getcwd, C library functions
@subheading @code{getenv} Function
@cindex @idxfncite{getenv(3)}

@example
String new envPath;

envPath = getenv ("PATH");

printf ("%s", envPath);
@end example

@node getpid, gmtime-localtime, getenv, C library functions
@subheading @code{getpid} Function
@cindex @idxfncite{getpid(3)} C Function

@node gmtime-localtime, index-function, getpid, C library functions
@subheading @code{gmtime,} @code{localtime} Functions
@cindex @idxfncite{gmtime(3)} C Function
@cindex @idxfncite{localtime(3)} C Function

@node index-function, isalnum-isxdigit, gmtime-localtime, C library functions
@subheading @code{index} Function
@cindex @idxfncite{index(3)}

@xref{strchr}.

@node isalnum-isxdigit, labs, index-function, C library functions
@subheading @code{isalnum,} @code{isalpha,} @code{isascii,} @code{isblank,} @code{iscntrl,} @code{isdigit,} @code{isgraph,} @code{islower,} @code{isprint,} @code{ispunct,} @code{isspace,} @code{isupper,} @code{isxdigit} Functions
@cindex @idxfncite{isalnum(3)}
@cindex @idxfncite{isalpha(3)}
@cindex @idxfncite{isascii(3)}
@cindex @idxfncite{isblank(3)}
@cindex @idxfncite{iscntrl(3)}
@cindex @idxfncite{isdigit(3)}
@cindex @idxfncite{isgraph(3)}
@cindex @idxfncite{islower(3)}
@cindex @idxfncite{isprint(3)}
@cindex @idxfncite{ispunct(3)}
@cindex @idxfncite{isspace(3)}
@cindex @idxfncite{isupper(3)}
@cindex @idxfncite{isxdigit(3)}
@cindex @mnm{isAlNum} method @idxclscite{Character}
@cindex @mnm{isAlpha} method @idxclscite{Character}
@cindex @mnm{isASCII} method @idxclscite{Character}
@cindex @mnm{isBlank} method @idxclscite{Character}
@cindex @mnm{isCntrl} method @idxclscite{Character}
@cindex @mnm{isDigit} method @idxclscite{Character}
@cindex @mnm{isGraph} method @idxclscite{Character}
@cindex @mnm{isLower} method @idxclscite{Character}
@cindex @mnm{isPrint} method @idxclscite{Character}
@cindex @mnm{isPunct} method @idxclscite{Character}
@cindex @mnm{isSpace} method @idxclscite{Character}
@cindex @mnm{isUpper} method @idxclscite{Character}
@cindex @mnm{isXDigit} method @idxclscite{Character}

Ctalk does not support @flnm{ctype.h} macros portably.  Use the
corresponding method of class @code{Character} instead. 
@xref{Character}.

@example
Ctype.h Macro          Ctalk Method
-------------          ------------
isalnum                isAlNum
isalpha                isAlpha
isascii                isASCII
isblank                isBlank
iscntrl                isCntrl
isdigit                isDigit
isgraph                isGraph
islower                isLower
isprint                isPrint
ispunct                isPunct
isspace                isSpace
isupper                isUpper
isxdigit               isXDigit
@end example

@node labs, llabs, isalnum-isxdigit, C library functions
@subheading @code{labs} Function
@cindex @idxfncite{labs(3)}

@example
#include <stdlib.h>

Integer new myValue;
Integer new myAbsValue;

myAbsValue = labs (myValue);
@end example

@node llabs, llrint, labs, C library functions
@subheading @code{llabs} Function
@cindex @idxfncite{llabs(3)}

@example
#include <stdlib.h>

LongInteger new myValue;
LongInteger new myAbsValue;

myAbsValue = llabs (myValue);
@end example

@node llrint, llround, llabs, C library functions
@subheading @code{llrint} Function
@cindex @idxfncite{llrint(3)}

@example
#include <math.h>

Float new myFloat;
LongInteger new myLongInt;

myFloat = 2.5;

myLongInt = llrint (myFloat);
@end example

@node llround, log, llrint, C library functions
@subheading @code{llround} Function
@cindex @idxfncite{llround(3)}

@example
#include <math.h>

Float new myFloat;
LongInteger new myLongInt;

myFloat = 2.5;

myLongInt = llround (myFloat);
@end example

@node log, log10, llround, C library functions
@subheading @code{log} Function
@cindex @idxfncite{log(3)}

@example
#include <math.h>

Float new myFloat;
Float new myLog;

myFloat = 2.5;

myLog = log (myFloat);
@end example

@node log10, log1p, log, C library functions
@subheading @code{log10} Function
@cindex @idxfncite{log10(3)}

@example
#include <math.h>

Float new myFloat;
Float new myLog;

myFloat = 2.5;

myLog = log10 (myFloat);
@end example

@node log1p, lrint, log10, C library functions
@subheading @code{log1p} Function
@cindex @idxfncite{log1p(3)}

@example
#include <math.h>

Float new myFloat;
Float new myLog;

myFloat = 2.5;

myLog = log1p (myFloat);
@end example

@node lrint, lround, log1p, C library functions
@subheading @code{lrint} Function
@cindex @idxfncite{lrint(3)}

@example
#include <math.h>

Float new myFloat;
Integer new myInt;

myFloat = 2.5;

myLog = lrint (myFloat);
@end example

@node lround, malloc, lrint, C library functions
@subheading @code{lround} Function
@cindex @idxfncite{lround(3)}

@example
#include <math.h>

Float new myFloat;
Integer new myInt;

myFloat = 2.5;

myLog = lround (myFloat);
@end example

@node malloc, memchr, lround, C library functions
@subheading @code{malloc} Function
@cindex @idxfncite{malloc(3)}

@example
#include <stdlib.h>

Integer new size;
int *intbuf

size = sizeof (int) * 10;

memblk = (int *)malloc (size);
@end example

@node memchr, memcmp, malloc, C library functions
@subheading @code{memchr} Function
@cindex @idxfncite{memchr(3)}

@example
#include <string.h>

#define BUFLENGTH 1024

Integer new searchChar;
Integer new length;
char buf[BUFLENGTH], *charptr;

length = BUFLENGTH

strcpy (buf, "Some text.");

searchChar = '.';

charptr = (char *)memchr ((void *)buf, searchChar, length);

@end example

@node memcmp, memcpy, memchr, C library functions
@subheading @code{memcmp} Function
@cindex @idxfncite{memcmp(3)}

@example
#include <string.h>

#define BUFLENGTH 1024

Integer new length;
Integer new result;
char buf1[BUFLENGTH], buf2[BUFLENGTH];

length = BUFLENGTH

strcpy (buf1, "Some text.");
strcpy (buf2, "Some other text.");

result = memcmp ((void *)buf1, (void *)buf2, length);

@end example

@node memcpy, memmove, memcmp, C library functions
@subheading @code{memcpy} Function
@cindex @idxfncite{memcpy(3)}

@example
#include <string.h>

#define BUFLENGTH 1024

Integer new length;
Integer new result;
char buf1[BUFLENGTH], buf2[BUFLENGTH], *charptr;

length = BUFLENGTH

strcpy (buf1, "Some text.");

result = (char *)memcpy ((void *)buf1, (void *)buf2, length);

@end example

@node memmove, memset, memcpy, C library functions
@subheading @code{memmove} Function
@cindex @idxfncite{memmove(3)}

@example
#include <string.h>

#define BUFLENGTH 1024

Integer new length;
Integer new result;
char buf1[BUFLENGTH], buf2[BUFLENGTH], *charptr;

length = BUFLENGTH

strcpy (buf1, "Some text.");

charptr = (char *)memmove ((void *)buf1, (void *)buf2, length);

@end example

@node memset, mkdir, memmove, C library functions
@subheading @code{memset} Function
@cindex @idxfncite{memset(3)}

@example
#include <string.h>

#define BUFLENGTH 1024

Integer new length;
Integer new fillChar;
char buf[BUFLENGTH], *charptr;

length = BUFLENGTH
fillChar = 0;

charptr = (char *)memset ((void *)buf1, fillChar, length);

@end example

@node mkdir, modf, memset, C library functions
@subheading @code{mkdir} Function
@cindex @idxfncite{mkdir(3)}
@example
Integer new r;
String new myDirName;

myDirName = "myDir";

r = mkdir (myDirName);
@end example

@node modf, nearbyint, mkdir, C library functions
@subheading @code{modf} Function
@cindex @idxfncite{modf(3)}

@example
#include <math.h>

double dptr;
Float new x;
Float new frac;

x = 2.54;

frac = modf (x, &dptr);
@end example

@node nearbyint, perror, modf, C library functions
@subheading @code{nearbyint} Function
@cindex @idxfncite{nearbyint(3)}

@example
#include <math.h>

Float new x;
Float new result;

x = 2.53;

result = nearbyint (x);
@end example

@node perror, pow, nearbyint, C library functions
@subheading @code{perror} Function
@cindex @idxfncite{perror(3)}

@example
#include <stdio.h>

String new message;

message = "Program error";

perror (message);
@end example

@node pow, printf, perror, C library functions
@subheading @code{pow} Function
@cindex @idxfncite{pow(3)}

@example
#include <math.h>

Float new x;
Float new exp;
Float new result;

x = 2.5;
exp = 2;

result = pow (x, exp);
@end example

@node printf, raise, pow, C library functions
@subheading @code{printf} Function
@cindex @idxfncite{printf(3)}

@example
#include <stdio.h>

String new message;
String new fmt;

printf (fmt, message);
@end example

@node raise, rand, printf, C library functions
@subheading @code{raise} Function
@cindex @idxfncite{raise(3)}

@example
#include <signal.h>

Integer new signal;
Integer new result;

signal = SIGTERM;

result = raise (signal);
@end example

@node rand, realloc, raise, C library functions
@subheading @code{rand} Function
@cindex @idxfncite{rand(3)}

@example
#include <stdlib.h>

Integer new random;

random = rand ();
@end example

@node realloc, remove, rand, C library functions
@subheading @code{realloc} Function
@cindex @idxfncite{realloc(3)}

@example
#include <stdlib.h>

int *intptr;
Integer new size;

size = sizeof (int *);

intptr = (int *)realloc (NULL, size);

@end example

@node remove, rename, realloc, C library functions
@subheading @code{remove} Function
@cindex @idxfncite{remove(3)}

@example
#include <stdio.h>

String new path;
Integer new result;

path = ``/home/user'';

result = remove (path);

@end example

@node rename, rindex, remove, C library functions
@subheading @code{rename} Function
@cindex @idxfncite{rename(3)}

@example
#include <stdio.h>

String new oldPath;
String new newPath;
Integer new result;

oldPath = "/home/user";
newPath = "/home/joe";

result = rename (oldPath, newPath);

@end example

@node rindex, rint, rename, C library functions
@subheading @code{rindex} Function
@cindex @idxfncite{rindex(3)}

@xref{strrchr}.

@node rint, rmdir, rindex, C library functions
@subheading @code{rint} Function
@cindex @idxfncite{rint(3)}

@example
#include <math.h>

Float new myFloat;
Float new myIntValue;

myFloat = 2.54;

myIntValue = rint (myFloat);

@end example

@node rmdir, round, rint, C library functions
@subheading @code{rmdir} Function
@cindex @idxfncite{rmdir(3)}
@example
r = rmdir (dirToRemove);
@end example

@node round, scanf, rmdir, C library functions
@subheading @code{round} Function
@cindex @idxfncite{round(3)}

@example
#include <math.h>

Float new myFloat;
Float new myIntValue;

myFloat = 2.54;

myIntValue = round (myFloat);

@end example

@node scanf, sin, round, C library functions
@subheading @code{scanf} Function
@cindex @idxfncite{scanf(3)}

@xref{Variable arguments}.

@node sin, sinh, scanf, C library functions
@subheading @code{sin} Function
@cindex @idxfncite{sin(3)}

@example
#include <math.h>

Float new x;
Float new sinX;

x = 2.5;

sinX = sin (x);
@end example

@node sinh, snprintf, sin, C library functions
@subheading @code{sinh} Function
@cindex @idxfncite{sinh(3)}

@example
#include <math.h>

Float new x;
Float new sinX;

x = 2.5;

sinX = sinh (x);
@end example

@node snprintf, sprintf, sinh, C library functions
@subheading @code{snprintf} Function
@cindex @idxfncite{snprintf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{sprintf(3)} instead. @xref{Variable arguments}.

@node sprintf, sqrt, snprintf, C library functions
@subheading @code{sprintf} Function
@cindex @idxfncite{sprintf(3)}

@xref{Variable arguments}.

@node sqrt, srand, sprintf, C library functions
@subheading @code{sqrt} Function
@cindex @idxfncite{sqrt(3)}

@example
#include <math.h>

Array instanceMethod printSquareRoot (void) @{

  Float new squareRoot;
  WriteFileStream classInit;

  /*
   *  Use Ctalk C API library function calls within a C function.
   */
  squareRoot = sqrt(__ctalk_to_c_double(__ctalk_self_internal ()));
  stdoutStream writeStream squareRoot;

  return NULL;
@}

int main () @{

  Array new floatArray;

  floatArray atPut 0, 1.0;
  floatArray atPut 1, 4.0;
  floatArray atPut 2, 9.0;
  floatArray atPut 3, 16.0;
  floatArray atPut 4, 25.0;

  floatArray map printSquareRoot;
  
@}
@end example

@node srand, sscanf, sqrt, C library functions
@subheading @code{srand} Function
@cindex @idxfncite{srand(3)}

@example
#include <stdlib.h>

Integer new seed;

seed = 2;

srand (seed);

@end example

@node sscanf, strcat-strcpy, srand, C library functions
@subheading @code{sscanf} Function
@cindex @idxfncite{sscanf(3)}

@xref{Variable arguments}.

@cindex @code{stdin}
@cindex @code{stdout}
@cindex @code{stderr}
@cindex @code{stdinStream} @idxclscite{ReadFileStream}
@cindex @code{stdoutStream} @idxclscite{WriteFileStream}
@cindex @code{stderrStream} @idxclscite{WriteFileStream}
@emph{Note:} The C99 standard requires that @code{stdin,}
@code{stdout,} and @code{stderr} should be implemented as
macros, which on some systems (notably Solaris) causes
problems with C-to-object translation.  If Ctalk cannot
register these macros as C variables, then either call
@idxfncite{sscanf(3)} with only C variables, or use a method
with @code{stdoutStream} or @code{stderrStream}
@xref{WriteFileStream}, or @code{stdinStream} @xref{ReadFileStream}.

@node strcat-strcpy, strchr, sscanf, C library functions
@subheading @code{strcat,} @code{strcasecmp}, @code{strcmp,} and @code{strcpy} Functions
@cindex @idxfncite{strcat(3)}
@cindex @mnm{cStrcat} method @idxclscite{CFunction}
@cindex @idxfncite{strcasecmp(3)}
@cindex @mnm{cStrcmp} method @idxclscite{CFunction}
@cindex @idxfncite{strcmp(3)}
@cindex @mnm{cStrcmp} method @idxclscite{CFunction}
@cindex @idxfncite{strcpy(3)}
@cindex @mnm{cStrcpy} method @idxclscite{CFunction}

The @cite{strcat(3),} @cite{strcasecmp(3),} @cite{strcmp(3),} and
@cite{strcpy(3)} functions work in most statements.  When necessary,
Ctalk uses @mnm{cStrcat}, @mnm{cStrcasecmp}, @mnm{cStrcmp}, and
@mnm{cStrcpy} (class @code{CFunction}). @xref{CFunction}.

@node strchr, strcoll, strcat-strcpy, C library functions
@subheading @code{strchr} Function
@cindex @idxfncite{strchr(3)}

@example
#include <string.h>

int main () @{

  String new s;
  String new result;

  s = "s1";

  if ((result = strchr (s, '1')) == "1") @{
    printf ("Pass\n");
  @} else @{
    printf ("Fail\n");
  @}

  exit(0);
@}
@end example

@node strcoll, strspn, strchr, C library functions
@subheading @code{strcoll} Function
@cindex @idxfncite{strcoll(3)}

@example
#include <string.h>

String new s1;
String new s2;
Integer new result;

result = strcoll (s1, s2);
@end example

@node strspn, strerror, strcoll, C library functions
@subheading @code{strspn} Function
@cindex @idxfncite{strspn(3)}


@node strerror, strftime, strspn, C library functions
@subheading @code{strerror} Function
@cindex @idxfncite{strerror(3)}


@node strftime, strlen, strerror, C library functions
@subheading @code{strftime} Function
@cindex @idxfncite{strftime(3)}


@node strlen, strncat-strncpy, strftime, C library functions
@subheading @code{strlen} Function
@cindex @idxfncite{strlen(3)}


@node strncat-strncpy, strpbrk, strlen, C library functions
@subheading @code{strncat,} @code{strncmp,} and @code{strncpy} Functions
@cindex @idxfncite{strncat(3)}
@cindex @mnm{cStrncat} method @idxclscite{CFunction}
@cindex @idxfncite{strncasecmp(3)}
@cindex @mnm{cStrncasecmp} method @idxclscite{CFunction}
@cindex @idxfncite{strncmp(3)}
@cindex @mnm{cStrncmp} method @idxclscite{CFunction}
@cindex @idxfncite{strncpy(3)}
@cindex @mnm{cStrncpy} method @idxclscite{CFunction}

The @cite{strncat(3),} @cite{strncasecmp(3),} @cite{strncmp(3),} and
@cite{strncpy(3)} functions work in most statements.  When necessary,
Ctalk uses @mnm{cStrncat,} @mnm{cStrncasecmp,} @mnm{cStrncmp,} and
@mnm{cStrncpy} (class @code{CFunction}). @xref{CFunction}.

@node strpbrk, strrchr, strncat-strncpy, C library functions
@subheading @code{strpbrk} Function
@cindex @idxfncite{strpbrk(3)}

@node strrchr, strstr, strpbrk, C library functions
@subheading @code{strrchr} Function
@cindex @idxfncite{strrchr(3)}

@example
#include <string.h>

String new s1;
Character new searchChar;
String new charptr;

searchChar = '/';
s1 = "/home/user";

charptr = strrchr (s1, searchChar);
@end example


@node strstr, strtod, strrchr, C library functions
@subheading @code{strstr} Function
@cindex @idxfncite{strstr(3)}

@node strtod, strtok, strstr, C library functions
@subheading @code{strtod} Function
@cindex @idxfncite{strtod(3)}


@node strtok, strtoll, strtod, C library functions
@subheading @code{strtok} Function
@cindex @idxfncite{strtok(3)}


@node strtoll, strxfrm, strtok, C library functions
@subheading @code{strtoll} Function
@cindex @idxfncite{strtoll(3)}


@node strxfrm, system, strtoll, C library functions
@subheading @code{strxfrm} Function
@cindex @idxfncite{strxfrm(3)}


@node system, tan, strxfrm, C library functions
@subheading @code{system} Function
@cindex @idxfncite{system(3)}

@example
#include <stdlib.h>

String new commandLine;

commandLine = "ls -lR";

system (commandLine);
@end example


@node tan, tanh, system, C library functions
@subheading @code{tan} Function
@cindex @idxfncite{tan(3)}


@node tanh, tmpnam, tan, C library functions
@subheading @code{tanh} Function
@cindex @idxfncite{tanh(3)}


@node tmpnam, tolower, tanh, C library functions
@subheading @code{tmpnam} Function
@cindex @idxfncite{tmpnam(3)}

@node tolower, toupper, tmpnam, C library functions
@subheading @code{tolower} Function
@cindex @idxfncite{tolower(3)}

The @code{tolower} function may be implemented in a non-portable
manner.  Use the @code{toLower} method instead. 
@c @xref{Character}.


@node toupper, trunc, tolower, C library functions
@subheading @code{toupper} Function
@cindex @idxfncite{toupper(3)}

The @code{toupper} function may be implemented in a non-portable
manner.  Use the @code{toUpper} method instead. 
@c @xref{Character}.


@node trunc, ungetc, toupper, C library functions
@subheading @code{trunc} Function
@cindex @idxfncite{trunc(3)}


@node ungetc, vfprintf, trunc, C library functions
@subheading @code{ungetc} Function
@cindex @idxfncite{ungetc(3)}


@node vfprintf, vfscanf, ungetc, C library functions
@subheading @code{vfprintf} Function
@cindex @idxfncite{vfprintf(3)}
@cindex @idxfncite{printf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{printf(3)} or @code{writeStream} (class
@code{WriteFileStream}) instead.

@node vfscanf, vprintf, vfprintf, C library functions
@subheading @code{vfscanf} Function
@cindex @idxfncite{vfscanf(3)}
@cindex @idxfncite{scanf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{scanf(3)} instead. @xref{Variable arguments}.

@node vprintf, vscanf, vfscanf, C library functions
@subheading @code{vprintf} Function
@cindex @idxfncite{vprintf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{printf(3)} or @code{writeStream} (class
@code{WriteFileStream}) instead.

@node vscanf, vsnprintf, vprintf, C library functions
@subheading @code{vscanf} Function
@cindex @idxfncite{vscanf(3)}
@cindex @idxfncite{scanf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{scanf(3)} instead. @xref{Variable arguments}.

@node vsnprintf, vsprintf, vscanf, C library functions
@subheading @code{vsnprintf} Function
@cindex @idxfncite{vsnprintf(3)}
@cindex @idxfncite{sprintf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{sprintf(3)} instead. @xref{Variable arguments}.

@node vsprintf, vsscanf, vsnprintf, C library functions
@subheading @code{vsprintf} Function
@cindex @idxfncite{vsprintf(3)}
@cindex @idxfncite{sprintf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{sprintf(3)} instead. @xref{Variable arguments}.

@node vsscanf, , vsprintf, C library functions
@subheading @code{vsscanf} Function
@cindex @idxfncite{vsscanf(3)}
@cindex @idxfncite{scanf(3)}

This version of Ctalk does not support the @code{va_list} data type.
You should use @cite{sprintf(3)} instead. @xref{Variable arguments}.

@node Copying, GNU Free Documentation License, C, Top
@iftex
@chapter Copying
@end iftex
@ifnottex
@heading Copying and Distributing Ctalk
@end ifnottex
@cindex Copying
@cindex GNU General Public License
@cindex GNU Lesser General Public License

Ctalk is free software.  You can copy, distribute, and modify Ctalk
under the terms of the GNU General Public License, Version 3 (see,
@flnm{COPYING}, in the Ctalk distribution).  You can also distribute
executable programs which link to the @command{ctalk} run time
libraries under the terms of the GNU Lesser General Public License,
Version 3 (@flnm{COPYING.LIB} in the Ctalk distribution).

@node GNU Free Documentation License, Index, Copying, Top
@iftex
@chapter GNU Free Documentation License
@end iftex
@ifnottex
@heading GNU Free Documentation License
@end ifnottex
@cindex GNU Free Documentation License
@example

                        Version 1.1, March 2000
     Copyright (C) 2000  Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.



  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.


  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you."

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque."

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.


  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.


  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.


  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

     A. Use in the Title Page (and on the covers, if any) a title
     distinct    from that of the Document, and from those of previous
     versions    (which should, if there were any, be listed in the
     History section    of the Document).  You may use the same title
     as a previous version    if the original publisher of that version
     gives permission.
     B. List on the Title Page, as authors, one or more persons or
     entities    responsible for authorship of the modifications in the
     Modified    Version, together with at least five of the principal
     authors of the    Document (all of its principal authors, if it
     has less than five).
     C. State on the Title page the name of the publisher of the
     Modified Version, as the publisher.
     D. Preserve all the copyright notices of the Document.
     E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.
     F. Include, immediately after the copyright notices, a license
     notice    giving the public permission to use the Modified Version
     under the    terms of this License, in the form shown in the
     Addendum below.
     G. Preserve in that license notice the full lists of Invariant
     Sections    and required Cover Texts given in the Document's
     license notice.
     H. Include an unaltered copy of this License.
     I. Preserve the section entitled "History", and its title, and add
     to    it an item stating at least the title, year, new authors, and
       publisher of the Modified Version as given on the Title Page.
     If    there is no section entitled "History" in the Document,
     create one    stating the title, year, authors, and publisher of
     the Document as    given on its Title Page, then add an item
     describing the Modified    Version as stated in the previous
     sentence.
     J. Preserve the network location, if any, given in the Document for
       public access to a Transparent copy of the Document, and
     likewise    the network locations given in the Document for
     previous versions    it was based on.  These may be placed in the
     "History" section.     You may omit a network location for a work
     that was published at    least four years before the Document
     itself, or if the original    publisher of the version it refers
     to gives permission.
     K. In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
      substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.
     L. Preserve all the Invariant Sections of the Document,
     unaltered in their text and in their titles.  Section numbers
     or the equivalent are not considered part of the section titles.
     M. Delete any section entitled "Endorsements."  Such a section
     may not be included in the Modified Version.
     N. Do not retitle any existing section as "Endorsements"    or to
     conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties-for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition
     of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.


  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgements", and any sections entitled "Dedications."  You
     must delete all sections entitled "Endorsements."


  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.


  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.


  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.


  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document 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.


 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation 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.  See
     http://www.gnu.org/copyleft/.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.


ADDENDUM: How to use this License for your documents

   To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

     Copyright (C)  YEAR  YOUR NAME.
     Permission is granted to copy, distribute and/or modify this document
     under the terms of the GNU Free Documentation License, Version 1.1
     or any later version published by the Free Software Foundation;
     with the Invariant Sections being LIST THEIR TITLES, with the
     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
     A copy of the license is included in the section entitled "GNU
     Free Documentation License."

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

@end example

@c
@c  INDEX
@c
@ifnottex
@node Index, , GNU Free Documentation License, Top
@end ifnottex
@chapter Index
@printindex cp
@bye
