/* Apple // and UNIX function */ or
        /* Apple // and UNIX utility */

int access (filename, mode)                         /* Apple // function */
char *filename;
int mode;

access determines whether a  file or directory can  be accessed in the  way
that  the calling function wants to access it.  It can also be used to just
test for the existence of a file or directory.

filename points to the name of the file or directory; this name  optionally
contains  the drive and path of directories  that must be passed through to
get to the file or directory.  If the drive component isn't specified,  the
file  or directory is assumed  to reside on the  default drive. If the path
component isn't specified, the  file or directory is  assumed to reside  in
the current directory on the specified drive.

mode is an int that specifies the type of access desired:

    mode    meaning

    4       read
    2       write
    1       execute (if a file) or search (if a directory)
    0       check existence of the file or directory.

If the existence of  the file or directory  is being checked (ie,  mode=0),
access  returns 0 if  the file exists and  -1 if it  doesn't. In the latter
case, access also  sets the  symbolic value  ENOENT in  the global  integer
errno.

When  access is called to determine if a  file can be accessed in a certain
way (ie, mode isn't 0). access returns 0 if the file can be accessed in the
desired  manner; otherwise,  it returns  -1 and sets  a code  in the global
integer errno that defines why the access is not permitted.

When asked, access says that a directory can be read or written; this means
that  a program can create  and delete files on  the directory, not that it
can directly read or write the directory itself.

The symbolic values that access  may set in errno  when it's called with  a
non-zero mode parameter are:

    errno      meaning

    ENOTDIR    A component of the path prefix is not a directory.
    ENOENT     The file or directory doesn't exist.
    EACCES     The file  or directory  can't  be  accessed  in  the desired
               manner.

#include <assert.h>                                 /* Apple // function */

assert (expr)
int expr;

assert  is  usefull  for putting  diagnostic  messages in  a  program. When
executed, it will determine whether the  expression expr is true or  false.
If false, it prints the message

    Assertion failed: expr, file fff line lnnn

where fff is the name of the source file  and nnn is the line number of the
assert statement.

To prevent assertion statements from  being compiled in a program,  compile
the program with the option -DNDEBUG, or place the statement #define NDEBUG
ahead of the statement #include <assert.h>.

double atof (cp)                          /* Apple // and UNIX functions */
char *cp;

atoi (cp)
char *cp;

long atol (cp)
char *cp;

ftoa (val, buf, precision, type)
double val;
char *buf;
int precision;
int type;

atof, atoi, and atol convert a string of text characters pointed at by  the
argument cp to double, integer, and long represantations.

atof  recognizes  a string  containing leading  blanks  and tabs,  which it
skips, then an optional sign, then a string of digits optionally containing
a decimal point, then an optional 'e' or 'E' followed be an optional signed
integer.

atoi and atol recognize a string containing leading blanks and tabs,  which
are ignored, then an optional sign, then a string of digits.

ftoa converts a double precision floating point number to ASCII. val is the
number to be converted and buf points to the buffer where the ASCII  string
will  be placed. precision specifies  the number of digits  to the right of
the decimal point. type specifies the format:  0 for 'E' format, 1 for  'F'
format, 2 for 'G' format.

atof and ftoa are in the library m.lib, the other functions are in c.lib.

black()                                            /* Apple // functions */

blue()

green()

violet()

Each of  these functions  sets the  screen in  Hi-res, full-screen  graphic
mode, using the primary graphics page, and clears the screen.

The  entire screen will  be a single  color, as determined  by the function
that is called. For example, calling green makes the entire screen green.

circle (x, y, rad)                                 /* Apple // functions */
int x, y, rad;

set_asp (xasp, yasp)
int xasp, yasp;

circle draws an oval  on the primary hi-res  graphics page, with center  at
(x,y).  By default, the horizontal and vertical  radii of the oval are both
rad, resulting in circle drawing a circle.

set_asp controls the eccentricity (ie, the "ovalness") of the figure  drawn
by  circle: circle draws an oval whose  horizontal radius is rad * xasp and
whose vertical radius is rad  * yasp, where xasp  and yasp have the  values
defined  by the last call to set_asp.  If set_asp isn't called, circle will
use the value  1 for xasp  and yasp, resulting  in a circle  of radius  rad
being drawn.

close (fd)                                 /* Apple // and UNIX function */
int fd;

close closes a device or disk file which is opened for unbuffered i/o.

The parameter fd is the file descriptor associated with the file or device.
If the device or file was explicity  opened by the program by calling  open
or creat, fd is the file descriptor returned by open or creat.

If  close fails, it returns -1 and sets an error code in the global integer
errno. Otherwise it returns 0 as its value.

creat (name, pmode)                        /* Apple // and UNIX function */
char *name;
int pmode;

There are two  descriptions of this  function: The one  you're now  reading
describes its implementation on the Apple //.

creat creates a file and opens it for unbuffered, write-only access. If the
file already exists, it is truncated so that nothing is in it (this is done
by erasing and then creating the file).

creat  returns as its value an integer called a "file descriptor". Whenever
a call is made to one of  the unbuffered i/o functions to access the  file,
its file descriptor must be included in the function's parameters.

name  is a pointer to a character string which is the name of the device or
file to be opened.

For most systems, pmode is optional: if specified, it's ignored. It  should
be   included,  however,  for  programs  for  which  UNIX-compatibility  is
required, since the UNIX creat function  requires it. Int this case,  pmode
should have the ocal value 0666.

For  ProDOS  programs, the  pmode parameter  of the  creat function  is the
file's access mode. The meanings  of the bits in  this parameter (bit 0  is
the least significant bit, bit 15 is the most significant):

    Bit number    Meaning

    0             File can be read
    1             File can be written
    2-4           Reserved
    5             File modified since last backup
    6             File can be renamed
    7             File can be deleted
    8-15          Unused

Thus,  to create a file on which all types of operations are permitted, set
its mode parameter to 0xC3.

For DOS 3.3 programs, pmode is the file's type. Type codes:

    Param3,hex    File type

    00            Text
    01            Integer basic
    02            Applesoft basic
    04            Binary
    08            Relocatable
    10            S-type file
    20            A-type file
    40            B-type file

If  creat fails, it returns -1  as its value and sets  a code in the global
integer errno.

char *ctop (str)                                   /* Apple // functions */
char *str;

char *ptoc (str)
char *str;

ProDOS expects character strings to be in Pascal format, in which a  string
consists  of  a leading  byte containing  the number  of characters  in the
string, followed by the characters in the string. In C, on the other  hand,
a character string consists of the characters followed by a null character.

ctop  and ptoc convert a string from C  form to Pascal form and from Pascal
form to C form,  respectively. The converted  string overlays the  original
string, and the function returns a pointer to the converted string.

drw (x1, y1, x2, y2)                               /* Apple // functions */
bdrw (x1, y1, x2, y2)
gdrw (x1, y1, x2, y2)
rdrw (x1, y1, x2, y2)
vdrw (x1, y1, x2, y2)

lineto (x, y)
blineto (x, y)
glineto (x, y)
rlineto (x, y)
vlineto (x, y)

These  functions draw straight  lines on the  primary Hi-res graphics page.
The "drw" functions  (ie, the first  five functions) draw  a line from  the
point whose coordinates are (x1, y1) to (x2, y2), differing in the color of
the line, as follows:

    Function    Color

    drw         white
    bdrw        blue
    gdrw        green
    rdrw        red
    vdrw        violet

The "drw" functions set the global variables _oldx and _oldy to x2 and  y2,
respectively.

The  "lineto" functions (ie, the last five  functions) draw a line from the
point whose coordinates are  (_oldx, _oldy) to the  point (x, y), and  then
set _oldx and _oldy to x and y, respectively. These functions differ in the
color of the drawn line like above.

execv (name, argv)                                      /* UNIX function */
char *name, *arg[];

execvp (name, argv)                                /* Apple // functions */
char *name, *arg[];

execl (name, arg0, arg1, arg2, ..., argn, 0)
char *name, *arg0, *arg1, *arg2, ...;

execlp (name, arg0, arg1, arg2, ..., argn, 0)
char *name, *arg0, *arg1, *arg2, ...;

These functions load, and transfer  control to another program. The  called
program is loaded on top of the calling program; thus, if the exec function
succeeds, it doesn't return to the caller.

The functions can be called by PRG programs: that is, by programs that  can
only  be run in the SHELL environment.  The functions can start any type of
program, including  those  that  have  not been  created  using  the  Aztec
software.

The  functions can also  be called by  BIN programs, when  the programs are
running in  the  SHELL environment.  However,  unlike BIN  programs,  these
functions  can't be used outside the SHELL environment; thus, you should be
wary about using these functions in a BIN program.

The Parameters:

name is the name of  the file containing the program  to be loaded. It  can
optionally  specify, using  the standard ProDOS  syntax, the  complete or a
partial path of directories that must be passed through to get to the file.

The exec functions  can pass  arguments to  the called  program. execl  and
execlp  build a command line  by containing the string  pointed at by arg1,
arg2, and so on. If a C program is being called, its main function will see
arg0  as argv[0], arg1  as argv[1], and  so on. By  convention, arg0 is the
name of the program being called.

execv and execvp built a command line by concatenating the strings  pointed
at  by argv[0],  argv[1], and  so on. The  argv array  must be  have a null
pointer as  its last  entry.  If a  C program  is  being called,  its  main
function  will  see  the  calling function's  argv[i]  as  its  argv[i]. By
convention argv[0] is the name of the program being called.

The Functions:

execl and execv load  a program from the  specified file: execl is  usefull
when  a fixed number of  arguments are being passed  to a program. execv is
usefull for programs which are passed a variable number of arguments.

execlp and  execvp search  a list  of  directories for  the program  to  be
loaded,  beginning with the current directory.  If the program isn't there,
the directories specified in the PATH environment variable are searched.

Passing Open Files and Devices:

When  both  the  calling and  the  called  programs are  of  type  PRG, the
following comments describe the  passing of open  file and devices  between
the programs:

    *    File that are left open for unbuffered i/o in  the calling program
         will be open for  unbuffered i/o in the  called program, and  will
         have the same file descriptors.

    *    Except for files that are associated  with the  stdin, stdout, and
         stderr standard i/o devices,  file left open  for standard i/o  in
         the  calling program won't be open  for standard i/o in the called
         program, although  they will  be open  for unbuffered  i/o:  thus,
         before  a PRG program activates another using an exec function, it
         should cause the buffered data  for files opened for standard  i/o
         to  be  written  to  disk,  using  either  the  fclose  or  fflush
         functions.

    *    The  standard  input, standard output, and standard error  devices
         are open  in the called program to the same devices or files as in
         the  calling  program. For the reasons  discussed above,  care  is
         needed  when  either the calling or  called program accesses these
         logical devices using standard i/o calls.

When both programs are not of type  PRG, open files and devices can not  be
passed between the programs.

If an exec function call fails, for example because the file doesn't exist,
it will return -1 as its value.

You can  have problems,  if the  called program  is half-loaded  and a  for
example  BAD MEDIA error occurs, cause  it will damage the calling program.
To prevent this verify the called program before you use one of these  exec
functions.

exit (code)                               /* Apple // and UNIX functions */

_exit (code)

exit and  _exit  terminate the  execution  of  a program  and  restart  the
operating  system-type  program that  activated the  program (that  is, the
SHELL or the Basic Intepreter). exit closes files opened for both  standard
and  unbuffered i/o, calling fclose to  close each file opened for standard
i/o, and then calling close to close any files opened for unbuffered i/o.
_exit doesn't close any standard or unbuffered i/o.

For a PRG program, code is its return code. The return code is set to 0 for
a PRG program that  terminates by either  explicity or implicity  returning
from its main function. An exec file that starts a PRG program can test the
program's return code and act accordingly.

The return code  of a  BIN program  is always  0, regardless  of the  value
specified in the call to exit or _exit.

#include <math.h>                         /* Apple // and UNIX functions */

double exp (x)
double x;

double log (x)
double x;

double log10 (x)
double x;

double pow (x, y)
double x;
double y;

double sqrt (x)
double x;

exp returns the exponential function of x.

log returns  the  natural  logarithm  of  x;  log10  returns  the  base  10
logarithm.

pow returns x ** y (x to the y-th power).

sqrt returns the square root of x.

If  a function can't perform the computation,  it sets an error code in the
global integer errno and returns  an arbitrary value; otherwise it  returns
the  computed value  without modifying  errno. The  symbolic values  wich a
function can place  in errno  are EDOM,  signifying that  the argument  was
invalid,  and ERANGE,  meaning that the  value of the  function couldn't be
computed. These codes are defined in the file errno.h.

The following table lists, for each  function, the error codes that can  be
returned,  the function value for that error, and the meaning of the error.
The symbolic values are defined in the file math.h.

    Funtion    Error    f(x)    Meaning

    exp        ERANGE   HUGE    x > LOGHUGE
    exp        ERANGE   0.0     x < LOGTINY
    log        EDOM     -HUGE   x <= 0
    log10      EDOM     -HUGE   x <= 0
    pow        EDOM     -HUGE   x < 0, x = y = 0
    pow        ERANGE   HUGE    y * log (x) > LOGHUGE
    pow        ERANGE   0.0     y * log (x) < LOGTINY
    sqrt       EDOM     0.0     x < 0.0

#include <math.h>                         /* Apple // and UNIX functions */

double fabs (x)
double x;

double floor (x)
double x;

double ceil (x)
double x;

fabs returns the absolute value of x.

floor returns the largest integer not greater than x.

ceil returns the smallest integer not less than x.

#include <stdio.h>                        /* Apple // and UNIX functions */

fclose (stream)
FILE *stream;

fflush (stream)
FILE *stream;

fclose informs  the  system  that  the user's  program  has  completed  its
buffered  i/o operations on a device or file which it had previously opened
(by calling fopen), fclose  releases the control  blocks and buffers  which
had  allocated to device or file. Also, when a file is being closed, fclose
writes any internally buffered information to the file.

fclose is automatically called by exit

fflush causes any buffered  information for the named  output stream to  be
written to that file. The stream remains open.

If  fclose or fflush  is successful, it  returns 0 as  its value. Otherwise
they return -1, and an error code is set in the global integer errno.

#include <stdio.h>                        /* Apple // and UNIX functions */

feof (stream)
FILE *stream;

ferror (stream)
FILE *stream;

clearerr (stream)
FILE *stream;

fileno (stream)
FILE *stream;

feof returns non-zero when  end-of-file is reached  on the specified  input
stream, and zero otherwise.

ferror  returns non-zero when an error has occured on the specified stream,
and zero  otherwise.  Unless  cleared be  clearerr,  the  error  indication
remains set until the stream is closed.

clearerr resets an error indication on the specified stream.

fileno returns the file descriptor associated with the stream.

These functions are defined as macros in the file "stdio.h".

fixnam (in_name, buf)                       /* Apple // ProDOS function */
char *in_name;
char *buf;

fixnam converts the file name pointed at by in_name into a  fully-qualified
name  consisting of the  file name itself prefixed  by the directories that
must be passed through to get to the file. in_name can use "." to refer  to
the current directory, and ".." to refer to a parent directory.

For  example, suppose that the  current directory being /work/source/input.
The first call to fixnam that follows places /work/source/input/indvr.c  in
input. The second places /work/source/output/outdvr.c in outbuf.

    fixnam ("indevr.c", input)
    fixnam ("../output/outdvr.c", outbuf)

fixnam returns 0  if successful. If  the input file  name contains so  many
".."  references that the resultant directory  is above the root directory,
fixnam  sets  EINVAL in  the global  integer errno  and returns  -1 as  its
value.

#include <stdio.h>                        /* Apple // and UNIX functions */

FILE *fopen (filename, mode)
char *filename;
char *mode;

FILE *freopen (filename, mode, stream)
char *filename;
char *mode;
FILE *stream;

FILE *fopen (fd, mode)
int fd;
char *mode;

These  functions prepare a device  or disk file for  access by the standard
i/o functions;  this is  called "opening"  the device  or file.  A file  or
device which has been opened by one of these functions is called a stream.

fopen  is the most basic of these  functions: it simply opens the device or
file specified by the filename parameter  for access specified by the  mode
parameter. These parameters are described below.

freopen  substitutes the named device or file  for the device or file which
was previously associated with the  specified stream. It closes the  device
or  file which was  originally associated with the  stream. It is typically
used to  associate  devices and  files  with the  preopened  stream  stdin,
stdout, and stderr.

fdopen  opens a device or file for unbuffered i/o which has been previously
opened by one of the unbuffered open functions open and creat.

The parameter filename is a pointer to a character string which is the name
of the device or file to be opened.

mode points to a character string which specifies how the user's program
intends to access the stream. The choices are as follows:

    Mode    Meaning

    r       Open for reading only. If a file is opened, it is positioned at
            the  first  character in  it. If  the file  or device  does not
            exist, NULL is returned.

    w       Open with  writing  only. If  a file  is  opened  which already
            exist,  it is  truncated to zero  length. If the  file does not
            exist, it is created.

    a       Open for  appending. The  calling program is granted write-only
            access  to  the  stream.  The  current  file  position  is  the
            character after the  last character  in the file.  If the  file
            does not exist, it is created.

    x       Open for  writing. The  file  must  not previously  exist. This
            option is not supported by UNIX.

    r+      Open for reding  and  writing. Same as "r", but  the stream may
            also be written to.

    w+      Open for writing  and reading. Same as "w",  but the stream may
            also be read: different from "r+" in the creation of a new file
            and loss of any previous one.

    a+      Open for appending and reading. Same as "a", but the stream may
            also  be  read; different  from  "r+" in  file  positioning and
            creation.

    x+      Open for  writing  and reading. Same as  "x", but  the file can
            also be read.

On  system which  don't keep  track of  the last  character in  a file (for
example CP/M and Apple DOS), not all files can be correctly positioned when
opened in append mode.

If  the file  or device  is successfully  opened, these  functions return a
pointer, called a "file pointer" to a structure of type FILE. This  pointer
is  included in the list  or parameters to buffered  i/o functions, such as
getc or putc, which the user's program calls to access the stream.

freopen returns stream as its value.

If the file or device cannot be opened, NULL is returned and an error  code
is set in the global integer errno.

The following example demonstrates how fopen can be used in a program:

    #include <stdio.h>

    main (argc, argv)
    char *argv[];
    {
        FILE *fopen();
        FILE *fp;

        if ((fp = fopen (argv[1], argv[2])) == NULL)
        {
            printf ("You asked me to open %s", argv[1]);
            printf (" in the %s mode", argv[2]);
            printf (" but I can't !\n");
        }
        else printf ("%s is open\n", argv[1]);

        ...

    }

Here is a program which uses freopen:

    #include <stdio.h<

    main()
    {
        FILE *fp;

        fp = freopen ("dskfile", "w+", stdout);
        printf ("This message is going to dskfile\n");
    }

Here is a program which uses fdopen:

    #include <stdio.h>

    dopen_it (fd)
    int fd;                            /* value returned by call to open */
    {
        FILE *fp;

        if ((fp = fdopen (fd, "r+")) == NULL)
            printf ("can't open file for r+\n");
        else return (fp);
    }

#include <math.h>                         /* Apple // and UNIX functions */

double frexp (value, eptr)
double value;
int *eptr;

double ldexp (value, exp)
double value;

double modf (value, iptr)
double value;
double *iptr;

Given value, frexp computes integers x and n such that value = x * 2** x. x
is returned as the value of frexp, and n is stored in the int field pointed
at by eptr.

ldexp returns the double quantity value * 2** exp.

modf  returns as its value the positive fractional part of value and stores
the integer part in the double field pointed at by iptr.

#include <stdio.h>                         /* Apple // and UNIX funcions */

int fseek (stream, offset, origin)
FILE *stream;
long offset;
int origin;

long ftell (stream)
FILE *stream;

fseek sets  the "current  position" of  a file  which has  been opened  for
unbuffered i/o. The current position is the byte location at which the next
input or output will begin.

stream is the stream identifier associated with the file, and was  returned
by fopen when the file was opened.

offset  and origin together specify the  current position: the new position
is at  the  signed  distance  offset  bytes  from  the  beginning,  current
position,  or end of the  file, depending on whether origin  is 0, 1, or 2,
respectively.

offset can  be  positive or  negative,  to  position after  or  before  the
specified  origin, respectively,  with the  limitation that  you can't seek
before the beginning or the file.

ftell returns  the  number of  bytes  from  the beginning  to  the  current
position of the file associated with stream.

For some operating systems (for example, CP/M and Apple DOS) a file may not
be able to be correctly posioned relative to its end.

If fseek is successful,  it will return zero.  Otherwise it will return  -1
for  improper  seeks. In  this case,  an error  code is  set in  the global
integer errno.

The following routine is equivalent to opening a file in "a+" mode:

    a_plus (filename)
    char *filename;
    {
        FILE *fp;
        FILE *fopen ();

        if ((fp = fopen (filename, "r+")) == NULL)
            fp = fopen (filename, "w+");
        fseek (fp, 0L,2);

        /* position 1 byte past last character */

    }

To  set the current  position back 5 characters  before the present current
position, the following call can be used:

    fseek (fp, -5L, 1);

char *getenv (name)                    /* Apple // ProDOS SHELL function */
char *name;

getenv,  returns  a pointer  to the  character  string associated  with the
environment variable name, or 0 if the variable isn't in the environment.

The character string is in a dynamically-alocated buffer; this buffer  will
be released when the next call is made to getenv.

getenv can be called by PRG programs: that is, by programs that can only be
run in the SHELL environment.  It can also be  called by BIN programs  that
are  running in the SHELL environment. However, unlike BIN programs, getenv
cannot be used outside of the  SHELL environment, thus, you should be  wary
of calling getenv in a BIN program.

#include <sgtty.h>                           /* Apple // and UNIX functions

ioctl (fd, cmd, stty)
FILE *fd,
char *cmd;
struct sgttyb *stty;

isatty (fd)

ioctl sets and determines the mode of the console.

The  parameter fd is a file decriptor associated with the console. On UNIX,
this parameter defines  the file  decriptor associated with  the device  to
which the ioctl call applies.

The  parameter cmd defines the action to be performed by ioctl. It can have
these values:

    Value        Meaning

    TIOCGETP     Fetch  the  console  parameters  and  store  them  in  the
                 structure pointed at by stty.

    TIOCSETP     Set the  console  parameters  according  to  the structure
                 pointed at by stty.

    TIOCSETN     Equivalent to TIOCSETP.

The argument stty  points to  a structure  named sgttyb  that contains  the
following fields:

    int sg_flags;
    char sg_erase;
    char sg_kill;

The order of these fields is system-dependent.

The  sg_flags is supported be  all systems, while the  other fields are not
supported be some systems.

    Value    Meaning of sg-flags

    RAW      Set raw  mode (turns off the  other options). By  default, raw
             mode is disabled.

    CBREAK   Return each character as soon  as typed. By  default, CREAK is
             disabled.

    ECHO     Echo input characters to the display. By default  echo mode is
             enabled.

    CRMOD    Map CR  to LF  on  input; convert  LF  to CR-LF  on output. By
             default crmod is enabled.

More  than one flag can specified in a single call to ioctl; the values are
simply 'or'ed together.  If the RAW  mode option is  selected, none of  the
other options have any effect.

isatty  returns non-zero if  the file descriptor fd  is associated with the
console, and zero otherwise.

#include <ctype.h>                        /* Apple // and UNIX functions */

isalpha (c)
char c;

...

These macros classify ASCII-coded integer values by table lookup, returning
nonzero if  the integer  is in  the catagory,  zero otherwise.  isascii  is
defined for all integer values. The others are defined only when isascii is
true and on the single non-ASCII value EOF (-1).

    isascii    c is an ASCII character, code less then 0x100
    isalpha    c is a letter
    isupper    c is an upper case letter
    islower    c is a lower case letter
    isdigit    c is a digit
    isalnum    c is an alphanumeric character
    isspace    c is a space, tab, carriage return, newline or formfeed
    ispunct    c is a punctuation character
    isprint    c is a printing character, valued 0x20 (space) through  0x7e
               (tilde)
    iscntrl    c is a delete character (0xFF) or ordinary control character
               (value less than 0x20)

long lseek (fd, offset, origin)           /* Apple // and UNIX functions */
int fd;
long offset;
int origin;

lseek  sets  the current  prosition of  a  file which  has been  opened for
unbuffered i/o. This position determines  where the next character will  be
read or written.

fd is the file descriptor associated with the file.

The  current position is  set to the  location specified by  the offset and
origin parameters, as follows:

    *    If origin is 0, the  current position  is set to offset bytes from
         the beginning of the file.

    *    If origin  is  1,  the  current  position  is  set  to the current
         position plus offset.

    *    If origin is 2, the current position is set to the end of the file
         plus offset.

The  offset can be  positive or negative,  to position after  or before the
specified origin, respectively.

Positioning of a  file relative  to its end  (that is,  calling lseek  with
origin  set  to 2)  cannot always  be  correctly done  on all  systems (for
example, CP/M and Apple DOS).

If lseek is successful,  it will return  the new position  in the file  (in
bytes  from the beginning of the file). Otherwise, it will return -1 as its
value and set an error  code in the global integer  errno. errno is set  to
EBADF  if the file descriptor  is invalid. It will be  set to EINVAL if the
offset parameter is  invalid or  if the  requested position  if before  the
beginning of the file.

1.  To seek to the beginning of a file:

        lseek (fd, 0L, 0);

    lseek will return the value zero (0) since the current position in the
    file is character (or byte) number zero.

2.  To seek to the character following the last character in the file:

        pos = lseek (fd, 0L, 2);

    The variable pos will  contain the current position  of the end of  the
    file, plus one.

3.  To seek backwards five bytes:

        lseek (fd, -5L, 1);

    The third parameter, 1, sets the origin at the current position in  the
    file,  The offset is -5.  The new position will  be the origin plus the
    offset. So the effect of this call is to move backward a total of  five
    characters.

4.  To skip characters when reading in a file:

        read (fd, buf, count);
        lseek (fd, 5L, 1);
        read (fd, buf, count);

char *malloc (size)                       /* Apple // and UNIX functions */
unsigned size;

char *calloc (nelem, elemsize)
unsigned nelem;
unsigned elemsize;

char *realloc (ptr, size)
char *ptr;
unsigned size;

free (ptr)
char *ptr;

These functions are used to allocate  memory from the "heap", that is,  the
section of memory for dynamic storage allocation.

malloc allocates a block of size bytes, and returns a pointer to it.

calloc allocates a single block of memory which can contain nelem elements,
each elemsize bytes  big, and  returns a pointer  to the  beginning of  the
block. Thus, the allocated block will contain (nelem * elemsize) bytes. The
block is initialized to zeroes.

realloc changes the  size of the  block pointed  at by ptr  to size  bytes,
returning  a  pointer to  the  block. If  necessary,  a new  block  will be
allocated of the requested size, and the data from the original block moved
into  it. The block passed to realloc can have been freed, provided that no
intervening calls to calloc, malloc, or realloc have been made.

free deallocates  a  block of  memory  which was  previously  allocated  by
malloc,  calloc, or realloc, this space  is the available for reallocation.
The argument ptr to free is a pointer to the block.

malloc and  free maintain  a circular  list of  free blocks.  When  called,
malloc  searches this list beginning with the last block freed or allocated
coalescing adjacent free blocks as it searches. It allocates a buffer  from
the  list large enough free block that it encounters. If this search fails,
it calls sbrk to get more memory for use by these functions.

malloc, calloc  and  realloc return  a  null pointer  (0)  if there  is  no
available  block  of memory.  free  returns -1  if  it's passed  an invalid
pointer.

mkdir (name)                        /* Apple // ProDOS and UNIX function */
char *name;

mkdir dir [dir ...]                 /* Apple // ProDOS SHELL utility */

mkdir creates the directory named name.

name can optionally specify, using the standard ProDOS syntax, the complete
or partial sequence of  directories that must be  passed through to get  to
the directory that is to be the parent of the directory.

If  no error occurs, mkdir  returns 0 as its value.  If an error occurs, it
sets a code in the global int errno and returns -1 as its value.

char *mktemp (template)                             /* Apple // function */
char *template;

mktemp  replaces the character string pointed  at by template with the name
of a non-existent file, and returns as its value a pointer to the string.

The string pointed at by template should  look like a file name whose  last
few characters are Xs with an optional imbedded period.

mktemp  repaces the Xs with  the letter followed by  digits. The digits are
set to  the address  of the  programs _main  function. The  letter will  be
between  'A' and 'Z', and will be  chosen such that the resulting character
string isn't the name of an existsting file.

For a given character  string, mktemp will try  to convert the string  into
one  of 26 file names. If all of  these files exist, mktemp will repace the
first character pointed at by template with a null character.

The following program calls mktemp to get a chracter string that it can use
as  a file name. If the program's  _main function begins at decimal address
1234,   the  generated  name  will  be  on  of  the  strings   abcA001.234,
abcB001.234,  ... abcZ001.234. If all the strings that mktemp considers are
names of existing  files, mktemp will  replace the first  character of  the
string passed to it, a in this case, with 0.

    #include <stdio.h>

    main()
    {
        char *fname, *mktemp();
        FILE *fp, fopen();

        fname = mktemp ("abcXXX.XXX") == 0)
        if (!*fname)
        {
            printf ("mktemp failed");
            exit (-1);
        }
        else fp = fopen (fname, "w");

        ...

    }

movmem (src, dest, length)                         /* Apple // functions */
char *src;
char *dest;
int length;

setmem (area, length, value)
char *area;
int length;
int value;

swapmem (s1, s2, length)
char *s1;
char *s2;
int length;

movmem  copies length characters from the block of memory pointed at by src
to that pointed at by dest.

movmem copies in such a way that the resulting block of characters at  dest
equals the original block at src.

setmem  sets the character value in each  byte of the block of memory which
begins at area and continues for length bytes.

swapmem swaps the block of memory pointed  at by s1 and s2. The blocks  are
length bytes long.

#include <fcntl.h>                         /* Apple // and UNIX function */

open (name, mode, param3)
char *name;

open opens a device or file for unbuffered i/o. It returns an integer value
called a file descriptor  wich is used  to identify the  file or device  in
subsequent calls to unbuffered i/o functions.

name  is a pointer to a character string  wich is the name of the device or
file to be opened.

mode specifies  how the  user's program  intends to  access the  file.  The
choices are as follows:

    Mode        Meaning

    O_RDONLY    read only
    O_WRONLY    write only
    O_RDWR      read and write
    O_CREAT     creat file, then open it
    O_TRUNC     truncate file, the open it
    O_EXCL      cause open to  fail   if  file  already  exists; used  with
                O_CREAT
    O_APPEND    positions file for appending data

These open  modes are  integer  constants defined  in the  file  "fcntl.h".
Altough  the true values of these constants can  be used in a given call to
open, use of the symbolic names  ensures compatibility with UNIX and  other
systems.

The  calling program must  specify the type of  access desired by including
exactly one of O_RDONLY,  O_WRONLY, and O_RDWR in  the mode parameter.  The
three remaining values are optional. They may be included by adding them to
the mode parameter, as in the examples below.

By default the open will fail if the  file to be opened does not exist.  To
cause  the file to be  created when it does  not already exist, specify the
O_CREAT option. If O_EXCL  is given in addition  to O_CREAT, the open  will
fail if the file already exists; otherwise, the file is created.

If  the O_TRUNC  option is  pecified, the  file will  be truncated  so that
nothing is in it. The truncation  is performed by simply erasing the  file,
if  it exists,  and then creating  it. So  it is not  an error  to use this
option when the file does not exist.

Note that when O_TRUNC is used, O_CREAT is not needed.

If O_APPEND is specified, the current  position for the file (that is,  the
position  at which the next  data transfer begin) is set  to the end of the
file. For systems which don't keep track of the last character written to a
file  (for example, CP/M and Apple  DOS), this positioning cannot always be
correctly done. Also this option is not supported by Unix.

When  open is  used to create  a file under  ProDOS, param 3  is the file's
access mode. The  meanings of the  param3 bits,  where bit 0  is the  least
significant bit, bit 15 is the most significant:

    Bit number    Meaning

    0             File can be read
    1             File can be written
    2-4           Reserved
    5             File modified since last backup
    6             File can be renamed
    7             File can be deleted
    8-15          Unused

Thus,  to create a file on which all types of operations are permitted, set
its mode parameter to 0xC3.

When open is used to creat a file under DOS 3.3, param3 is the file's type:

    Param3,hex    File type

    00            Text
    01            Integer basic
    02            Applesoft basic
    04            Binary
    08            Relocatable
    10            S-type file
    20            A-type file
    40            B-type file

If  open does  not detect an  error, it  returns an integer  called a "file
descriptor". This value is used to identify the open file during unbuffered
i/o operations. The file descriptor is very different from the file pointer
which is returned by fopen for use with buffered i/o functions.

If open encounters  an error,  it returns -1  and sets  the global  integer
errno to a symbolic value which identifies the error.

1.  To open the file testfile for read-only access:

        fd = open ("testfile", O_RDONLY, 0);

    The  third parameter of open is not  important in this case, since open
    won't create the file. If testfile does not exist open will just return
    -1 and set errno to ENOENT.

2.  To open the file  sub1 on ProDOS in read-write  mode, allowing it to be
    deleted, read, written and renamed:

        fd = open ("sub1", O_RDWR + O_CREAT, 0xC3);

    If the file does not exist, it will be created and then opened.

3.  The following program opens a ProDOS  file whose name  is given on  the
    command line. The file must not already exist.

        main (argc, argv)
        char **argv;
        {
            int fd;

            fd = open (*++argv, O_WRONLY + O_CREAT + O_EXCL, 0xC3);
            if (fd == -1)
            {
                if (errno == EEXIST) printf ("file already exist\n");
                else if (errno == ENOENT) printf ("unable to open file\n");
                     else printf ("open error\n");
            }

            ...

        }

page1()                                            /* Apple // functions */

page2()

page1 and page2 enable the primary and secondary pages, respectively.

int perror (s)                            /* Apple // and UNIX functions */
char *s;

#include <errno.h>

extern int errno;

When  a library function detects  an error, it will  generally set an error
code, which is a positive integer,  in the global integer errno and  return
an appropriate, function-dependent value.

The extern declaration of errno is in "errno.h".

When  an error occurs, perror  can be called to  write a message describing
the error  on  the standard  error  device.  The message  consists  of  the
following:

    *    s, the string pointed at by the argument to perror,
    *    a colon and a blank,
    *    the sys_errlist  message  corresponding  to  the  current value of
         errno,
    *    a newline chracter.

perror returns 0 if errno contains a valid value, otherwise, it returns  -1
without printing a message.

plotchar (c, x, y)                                  /* Apple // function */
int c, x, y;

plotchar  displays the printable char c on the primary Hi-res graphic page,
at the location having coordinates (x, y).

plot (x, y)                                        /* Apple // functions */
bplot (x, y)
gplot (x, y)
rplot (x, y)
vplot (x, y)

These functions plot a  point on the primary  Hi-res page, at the  location
(x, y). They differ in the color of the point:

    Function    Color

    drw         white
    bdrw        blue
    gdrw        green
    rdrw        red
    vdrw        violet

#include <stdio.h>                         /* Apple // and UNIX funcions */

printf (fmp [,arg] ... )
char *fmt;

fprintf (stream, fmp [,arg] ... )
FILE *stream;
char *fmt;

sprintf (buffer, fmp [,arg] ... )
char *buffer;
char *fmt;

format (func, fmt, argptr)
int (*func)();
char *fmt;
unsigned *argptr;

These  functions  convert  and  format  their  arguments  (arg  or  argptr)
according to the format specification fmt. They differ in what they do with
the formatted result:

printf outputs the result to the standard output stream, stdout.

fprintf outputs the result to the  stream specified in its first  argument,
stream.

sprintf  palaces the result in the buffer pointed at by its first argument,
buffer, and terminates the result with the null character, ' '.

format calls the function func with each character of the result. In  fact,
printf,  fprintf, and  sprintf call  format with  each character  that they
generate.

These functions are in both c.lib and m.lib, the difference being that  the
c.lib  version don't support floating point conversions. Hence, if floating
point conversion is required, the m.lib  version must be used. If  floating
point conversion isn't required, either version can be used. To use m.lib's
version, m.lib must be  specified before c.lib at  the time the program  is
linked.

The  character string  pointed at by  the fmt parameter,  which directs the
print functions, contains  two types of  items: Ordinary characters,  which
are  simply output, and conversion specifications, each of which causes the
conversion and ouput of the next successive arg.

A conversion specification begins with the character % and continues with:

    *    An optional minus sign (-)  which specifies left adjustment of the
         converted value in the output field.

    *    An optional  digit  string specifying  the  'field  width' for the
         conversion. If the converted value has fewer characters than this,
         enough blank characters will be output to make the total number of
         characters  output equals the field  width. If the converted value
         has more characters than  the field width,  it will be  truncated.
         The  blanks are output before or after the value, depending on the
         presence or absence of the left adjustment indicator. If the field
         width digits have a leading 0, 0 is used as a pad character rather
         than blank.

    *    A optional period, '.', which seperates  the field  width from the
         following field.

    *    An  optional  digit  string specifying  a  precision, for floating
         point conversions, this specifies the  number of digits to  appear
         after  the decimal  point; for character  string conversions, this
         specifies the maximum number  of characters to  be printed from  a
         string.

    *    Optionally, the  character  L, which  specifies  that a conversion
         which normally is  performed on  an int is  to be  performed on  a
         long. This applies to the d, o, and x conversions.

    *    A  character  which  specifies  the  type   of  conversion  to  be
         performed.

A field width or precision  may be * instead  of a number, specifying  that
the  next available arg, which must be  an int, supplies the field width or
precision:

The conversion character are:

    d, o, x    The int in  the corresponding  arg is  converted to decimal,
               octal, or hexadeciaml notation, respectively, and output.

    u          The unsigned integer arg is converted to decimal notation.

    c          The character arg is output. Null characters are ignored.

    s          The characters in the  string pointed  at  by arg are output
               until a null character or the number of characters indicates
               by  the precision  is reached. If  the precision  is zero or
               missing, all characters in the string, up to the terminating
               null, are output.

    f          The float or double  arg is converted to decimal notation in
               the style '[-]ddd.ddd'. The number of d's after the  decimal
               point  is  equal to  the precision  given in  the conversion
               specification. If the precision  is missing, it defaults  to
               six  digits. If the  precision is explicitly  0, the decimal
               point is also not printed.

    e          The  float  or  double  arg   is  converted  to   the  style
               '[-]d.ddde[-]dd',  where  there  is  one  digit  before  the
               decimal point and the number after is equal to the precision
               given.  If  the precision  is  missing, it  defaults  to six
               digits.

    g          The float or double  arg  is  printed  in  style d, f, or e,
               whichever gives full precision in minimum space.

    %          Output a %. No argument is converted.

All functions return -1 as their value, if the conversion fails.

1.  The following program fragment:

        char *name;
        float amt;

        printf ("Your total, %s, is $%f\n", name, amt);

    will print a message of the form

        Your total, Alfred, is $3.120000

    Since the precision of the %f conversion wasn't specified, it defaulted
    to six digits to the rigth of the decimal point.

2.  This example modifies example  1 so  that the  field width  for the  %s
    conversion  is three characters,  and the field  width and precision of
    the %f conversion are  10 and 2, respectively.  The %f conversion  will
    also use 0 as a pad character, rather than blank.

        char *name;
        float amt;

        printf "Your total ,%3s, is $%10.2f\n", name, amt);

4.  This example demonstrates how  to use  the format  function by  listing
    printf, which calls format with each character that it generates:

        printf (fmt, args)
        char *fmt;
        unsigned args;
        {
            extern int putchar ();
            format (putchar, fmt, &args);
        }

#include <stdio.h>                         /* Apple // and UNIX funcions */

puts (s)
char *s;

fputs (s, stream)
char *s;
FILE *stream;

puts  writes the  null-terminated string s  to the  standard output stream,
stdout, and then an end-of-line  sequence. It returns a non-negative  value
if no error occur.

fputs  copies the null-terminated string s  to the specified output stream.
It returns 0 if no error occur.

Both functions write to the stream using  aputc on an Apple //. Thus,  they
can only be used to write text.

Note  that puts  and fputs  differ in this  way: On  encountering a newline
character, puts writes an end-of-line sequence and fputs doesn't.

If an error occur, these functions return EOF (-1) and set an error code in
the global integer errno.

qsort (array, number, width, func)         /* Apple // and UNIX function */
char *array;
unsigned number;
unsigned width;
int (*func)();

qsort sorts an array of elements using Hoare's Quicksort algorithm.

array is a  pointer to  the array  to be sorted.  number is  the number  of
records  to be sorted.  width is the  size in bytes  of each array element.
func is a pointer for a comparision of two array elements.

func is passed pointers to the two elements being compared. It must  return
an  integer less than, equal to, or greater than zero, depending on whether
the first argument is to be considered less than, equal to, or greater than
the second.

The Aztec linker, LN, can generate a file of text containing a symbol table
for a program. Each line of the file contains an address at which a  symbol
is located, followed by a space, followed by the symbol name. The following
program reads such  a symbol  table from the  standard input,  sorts it  by
address, and writes it to standard output.

    #include <stdio.h>

    #define LINESIZE 16
    #define MAXLINES 2000

    char *lines[MAXLINES];
    char *malloc;

    main()
    {
        int i;
        int numlines;
        int cmp();
        char buf[LINESIZE];

        for (numlines=0; numlines<MAXLINES; ++numlines)
        {
            if (gets (buf) == NULL) break;
            lines[numlines] = malloc (LINESIZE);
            strcpy (lines[numlines], buf);
        }
        qsort (lines, numlines, 2, cmp);
        for (i=0; i<numlines; ++i) printf ("%s\n", lines[i]);
    }

    cmp (a, b)
    char **a, **b;
    {
        return strcmp (*a, *b);
    }

double ran ()                              /* Apple // and UNIX function */

double randl (x)
double x;

ran returns as its value a random number between 0.0 and 1.0 .

randl returns as its value a random number beteen 0.0 and x .

read (fd, buf, bufsize)                    /* Apple // and UNIX function */
int fd;
char *buf;
int bufsize;

read  reads characters from a device or disk file which has been previously
opened by a call to open or  creat. In most cases, the information is  read
directly into the caller's buffer buf.

fd  is the file descriptor which was returned to the caller when the device
or file was opened.

buf is a pointer to the buffer into which the information is to be placed.

bufsize is the number of characters to be transferred.

If read is  successful, it returns  as its value  the number of  characters
transferred.  If  the returned  value is  zero,  then end-of-file  has been
reached,  immediately,  with  no  bytes   read.  If  the  operation   isn't
successful, read returns -1 and places a code in the global integer errno.

rename (oldname, newname)                           /* Apple // function */
char *oldname;
char *newname;

rename changes the name of a file (and volume or directory under ProDOS).

oldname is a pointer  to a character string  containing the old file  name,
and newname is a pointer to a character string containing to new name of
the file.

If successful, rename returns 0  as its value, if not  it returns -1. If  a
file  with the new  name already exist,  rename sets E_EXIST  in the global
integer errno and returns -1 as its value without renaming the file.

void *sbrk (size)                                  /* Apple // functions */

brk (ptr)
void *ptr;

rsvstk (size)

sbrk  and brk  provide an elementary  means of  allocating and deallocating
space from the heap.  More sophisticated buffer  management schemes can  be
built  using these functions;  for example, the  standard functions malloc,
free, etc  call sbrk  to get  heap space,  wich they  then manage  for  the
calling functions.

sbrk  increments a pointer, called the  'heap pointer', by size bytes, and,
if successful, returns the value that the pointer had on entry.  Initially,
the  heap pointer points to the base of  the heap. size is a signed int; if
it is negative, the heap pointer is decremented by the specified amount and
the  value that it had on entry is returned. Thus, you must be careful when
calling sbrk: if you  try to pass  it a value greater  than 32K, sbrk  will
interpret  it as a negative number,  and decrement the heap pointer instead
of incrementing it.

brk sets the heap pointer tp ptr, and returns 0 if successful.

rsvstk sets the heap-stack  boundary size bytes below  the current tock  of
stack, thus changing the amount of space allocated to the stack and heap.

If an sbrk or brk request would make the heap space pointer go past the end
of the heap, the  function will return -1  as its value, without  modifying
the heap space pointer.

#include <stdio.h>                        /* Apple // and UNIX functions */

scanf (format [,pointer] ... )
char *format;

fscanf (stream, format [,pointer] ... )
FILE *stream;
char *format;

sscanf (buffer, format [,pointer] ... )
char *buffer;
char *format;

These  functions convert a string or stream of text characters, as directed
by the control  string pointed at  by the format  parameter, and place  the
results in the field pointed at by the pointer parameters.

scanf gets text from the standard input stream, stdin.

fscanf gets text from the stream specified in its first parameter, stream.

sscanf gets text from the buffer pointed at by its first parameter, buffer.

These  functions are in both c.lib and m.lib, the difference being that the
c.lib version don't support floating point conversions. Hence, if  floating
point  conversion is required, the m.lib  version must be used. If floating
point conversion isn't required, either version can be used. To use m.lib's
version,  m.lib must be specified  before c.lib at the  time the program is
linked.

The control  string pointed  at by  format contains  the following  control
items:

    *    Conversion specifications.

    *    'White space' characters (space, tab, newline).

    *    Ordinary characters; that  is, characters  which  aren't part of a
         conversion specification and which aren't white space.

A scan function  works its way  through a control  string, trying to  match
each  control item to a  portion of the input  stream or buffer. During the
matching process, it fetches characters one at a time from the input.  When
a  character is fetched which isn't  appropriate for the control item being
matched, the scan function pushes it  back into the input stream or  buffer
and  finishes processing  the current  control item.  This is  pushing back
frequently gives  unexpected results  when a  stream is  being accessed  by
other  i/o  functions, such  as getc,  as  well as  the scan  function. The
examples below demonstrates some of the problems that can occur.

The scan function terminates when it first fails to match a control item or
when  the end of the  input stream or buffer is  reached. It returns as its
value the number of matched conversion  specifications, or EOF (-1) if  the
end of the input stream or buffer was reached.

Matching 'white space' characters:

    When a white space character is encountered in the control string,  the
    scan  function fetches input characters until the first non-white-space
    character is read.  The non-white-space character  is pushed back  into
    the  input  and the  scan function  proceeds  to the  next item  in the
    control string.

Matching ordinary characters:

    If an ordinary character is encountered in the control string, the scan
    function  fetches the next input character,  If it matches the ordinary
    character, the scan function simply proceeds to the next control string
    item. If it doesn't match, the scan function terminates.

Matching conversion specification:

    When  a conversion specification is  encountered in the control string,
    the scan function first skips leading  white space on the input  stream
    or  buffer. It then fetches characters  from the stream or buffer until
    encountering   one   that   is   inappropriate   for   the   conversion
    specification. This character is pushed back into the input.

    If  the conversion specification  didn't request assignment suppression
    (discussed below), the character string which was read is converted  to
    the  format specified  by the  conversion specification,  the result is
    placed in the location pointed at by the current pointer argument,  and
    the  next  pointer argument  becomes  current. The  scan  function then
    proceeds to the next control string item.

    If   assignment   suppression   was   requested   by   the   conversion
    specification,  the  scan  function simply  ignores  the  fetched input
    characters and proceeds to the next control item.

Details of input conversion:

    A conversion specification consists of:

        *    The character '%', which  tells the  scan function that it has
             encountered a conversion specification.

        *    Optionally, the assignment suppression character '*'.

        *    Optionally, a field  width; that  is,  a number specifying the
             maximum number of characters to be fetched for the conversion.

        *    A conversion character, specifying the  type of  conversion to
             be performed.

    If  the  assignment suppression  character is  present in  a conversion
    specification, the scan  function will  fetch characters as  if it  was
    going  to perform the conversion, ignore  them, and proceed to the next
    control string item.

    The following conversion characters are supported:

        %    A single '%' is exepted in the input; no assignment is done.

        d    A decimal  integer  is  expected;  the  input  digit string is
             converted to binary  and the  result placed in  the int  field
             pointed at by the current pointer argument.

        o    An octal integer is expected; the corresponding pointer should
             point to an int  field in which the  converted result will  be
             placed.

        x    A hexadeciaml integer is expected; the converted value will be
             placed in the int field pointed at by the current pointer
             argument.

        s    A sequence of  characters delimited  by white space characters
             is expected;  they, plus  a  terminating null  character,  are
             placed  in  the character  string  pointed at  by  the current
             pointer argument.

        c    A character  is  expected. It  is  placed  in  the  char field
             pointed  at  by  the  current pointer.  The  normal  skip over
             leading white space is not done;  to read s single char  after
             skipping  leading  white  space, use  '%1s'.  The  field width
             parameter is ignored, so this  conversion can be used only  to
             read a single character.

        [    A sequence of  characters, optionally  preceded by white space
             but not  terminated  by white  space  is expected.  The  input
             characters,  plus a terminating null  character, are placed in
             the  character  string  pointed  at  by  the  current  pointer
             argument. The left bracket is followed by:

                 * Optionally, a '^' or '~' character.
                 * A set of characters.
                 * A rigth bracket, ']'.

             If  the  first character  in the  set  isn't ^  or ~,  the set
             specifies characters which are allowed; characters are fetched
             from the input until one is read which isn't in the set.

             If the first character in the set is ^ or ~, the set specifies
             characters which aren't allowed; characters are fetched from
             the input until one is read which is in the set.

        e    A floating  point  number  is  expected.  The  input string is
             converted to floating  point format  and stored  in the  float
             field  pointed at by  the current pointer  argument. The input
             format for floating  point numbers consists  of an  optionally
             signed  string of digits, possibly containing a decimal point,
             optionally followed by an exponent filed consisting of an E or
             e followed by an optionally signed digit.

1.  In this program fragment,  scanf is used to read  values for the int x,
    the float y, and a character string into the char array z:

        int x;
        float y;
        char z[50];

        scanf ("%d%f%s", &x, &y, z);

    The input line

        32 75.36e-1 rufus

    will  assign 32 to x, 7.536 to y, and "rufus" to z. scanf will return 3
    as its  value, signifying  that  three conversion  specifications  wree
    matched.

    The  three input strings must be delimited by 'white space' characters;
    that is, by blank, tab, and newline characters. Thus, the three  values
    could also be entered on seperate lines, with the white space character
    newline used to seperate the values.

2.  This example  discusses the problem  which may arise  when mixing scanf
    and other input operations on the same stream.

    In  the previous  example, the character  string entered  for the third
    variable, z,  must also  be  delimited by  white space  characters.  In
    particular,  it  must  be  terminated  by  a  space,  tab,  or  newline
    character. The  first  such  character  read  by  scanf  while  getting
    characters  for z will be 'pushed back' into the standard input stream.
    When another read of stdin is made later, the first character  returned
    will be the white space character which was pushed back.

    This  'pushing back' can  lead to unexpected  results for programs that
    read stdin  with  functions in  addition  to scanf.  Suppose  that  the
    program  in the first example wants ot issue a gets call to read a line
    from stdin, following the scanf to  stdin. scanf will have left on  the
    input stream the white space character which terminated the third value
    read by scanf. If this character is a newline, then gets will return  a
    null  string, because the  first character it reads  is the pushed back
    newline, the character which terminates  gets. This is most likely  not
    what the program had in mind when it called gets.

    It  is usally unadvisable to mix scanf  and other input operations on a
    single stream.

3.  This example discusses the behavior of scanf when there are white space
    characters in the control string.

    The  control  string  in the  first  example was  "%d%f%s".  It doesn't
    contain any  white  space, since  scanf,  when attempting  to  match  a
    conversion  specification, will  skip leading  white space.  There's no
    harm in having white  space before the  %d, between the  %d and %f,  or
    between  the %f and %s. However,  placing a white space character after
    the %s can  have unexpected results.  In this case,  scanf will,  after
    having  read a character string for  z, keep reading characters until a
    non-white-space character is read. This  forces the operator to  enter,
    after  the three values for  x, y, and z,  a non-white space character;
    until this is done, scanf will not terminate.

    The programmer  might place  a  newline character  at  the end  of  the
    control  string,  mistakenly  thinking that  this  will  circumvent the
    problem  discussed in example 2. One  migth think that scanf will treat
    the newline as it  would an ordinary character  in the control  string;
    that  is,  that  scanf will  search  for, and  remove,  the terminating
    newline character from  the input  stream after  it has  matched the  z
    variable.  However, this  is incorrect, and  should be  remembered as a
    common misinterpretation.

4.  scanf only  reads input it  can match.  If, for the  first example, the
    input had been

        32 rufus 75.36e-1

    scanf  would  have  returned with  value  1, signifying  that  only one
    conversion specification had been matched. x would have the value 32, y
    and  z would be unchanged. All characters in the input stream following
    the 32 would still be in the input stream, waiting to be read.

5.  One common  problem  in using  scanf  involves  mismatching  conversion
    specifications  and their corresponding arguments. If the first example
    had declared y  to be a  double, then one  of the following  statements
    would have been required:

        scanf ("%d%1f%s", &x, &y, z);

    or

        scanf ("%d%F%s", &x, &y, z);

    to tell scanf that the floating point variable was a double rather than
    a float.

6.  Another  common problem in using scanf involves paasing scanf the value
    of  a variable rather than its address.  The following call to scanf is
    incorrect:

        int x;
        float y;
        char z[50];

        scanf ("%d%f%s", x, y, z);

    scanf has been passed the value containing in x and y, and the  address
    of  z, but it requires the address of all three variables. The "address
    of" operator, &, is  requiered as a prefix  to x and y.  Since z is  an
    array,  its address is automatically passed to scanf, so z doesn't need
    the & prefix, although it won't hurt if it is given.

7.  Consider the following program fragment:

        int x;
        float y;
        char z[50];

        scanf ("%2d%f%*d%[1234567890]", &x, &y, z);

    When given the following input:

        12345 678 90a65

    scanf  will assign 12 to x, 345.0 to  y, skip 678, and place the string
    '90' in z.  The next  call to  getchar will return  'a' and  that IS  a
    problem.

scr_beep()                                         /* Apple // functions */
scr_bs()
scr_tab()
scr_lf()
scr_cursup()
scr_cursrt()
scr_cr()
scr_clear()
scr_home()
scr_eol()
scr_linsert()
scr_ldelete()
scr_cinsert()
scr_cdelete()
scr_curs (lin, col)
int lin, col;

These  functions can be called by command programs to manipulate screens of
text. For example, there  are functions to clear  the screen, position  the
cursor, and insert and delete characters and lines.

These functions can be used in conjunction with the normal standard i/o und
unbuffered i/o functions to diplay characters on the console.

scr_beep rings the keyboard bell.

scr_bs moves the  cursor back  one character space,  without modifying  the
character that was backspaced over.

scr_tab moves the cursor right one tab stop.

scr_lf  moves the  cursor down on  line, scolling  if at the  bottom of the
screen.

scr_cursup moves the cursor up without changing its column location.

scr_cursrt moves the  cursor right one  character space, without  modifying
the character that was spaced over.

scr_cr causes a carriage return.

scr_clear clears the screen and homes the cursor.

scr_home homes the cursor to the upper left hand corner of the screen.

scr_eol  erases the line at  which the cursor is  located, from the current
cursor prosition to the end of the line.

scr_linsert inserts a blank line at  the cursor location, moving the  lines
below the cursor down one line.

scr_ldelete  deletes the line at the cursor location, moving the lines blow
the  cursor up  one line  and placing  a blank  line at  the bottom  of the
screen.

scr_cinsert inserts  a space  at the  cursor location,  shifting right  one
character the characters in the line wich are on the right of the cursor.

scr_cdelete deletes the character at the cursor location, shifting left one
character the characters in the line which are on the right of the cursor.

scr_curs moves the cursor to the line  and column specified by the lin  and
col parameters, respectively.

#include <setjmp.h>                         /* Apple // and UNIX funcion */

setjmp (env)
jmp_buf env;

longjmp (env, val)
jmp_buf env;
int val;

These  functions  are useful  for dealing  with  errors encountered  by the
low-level funcions of a program.

setjmp saves its stack  environment in the memory  block pointed at by  env
and return 0 as its value.

longjmp causes execution to continue as if the last call to setjmp was just
terminating with value val. val cannot be zero.

The parameter env is a  pointer to a block of  memory which can be used  be
setjmp and longjmp. The block must be defined using the typedef jmp_buf.

WARNING:

    longjmp  must not  be called without  env having been  initialized by a
    call to setjmp. It also must not be called if the function that  called
    setjmp has since returned.

In the following example, the function getall builds a record pertaining to
a customer  and  returns  the pointer  to  the  record if  no  errors  were
encountered and 0 otherwise.

getall  calls  other  functions  which  actually  build  the  record. These
functions in turn call other functions, which in turn ...

getall defines, by  calling setjmp, a  point to which  these functions  can
branch  if an unrecoverable error occurs.  The low level functions abort by
calling longjmp with a non-zero value.

If a low  level function aborts,  execution continues in  getall as if  its
call  to setjmp had just terminated with  a non-zero value. Thus by testing
the value  returned  by  setjmp  getall can  determine  whether  setjmp  is
terminating because a low level function aborted.

    #include <setjmp.h>

    jmp_buf envbuf;                  /* environment saved here by setjmp */

    getall (ptr)
    char *ptr;                       /* ptr to record to be build */
    {
        if (setbuf (envbuf))         /* a low level function has aborted */
            return 0;
        getfield1 (ptr);
        getfield2 (ptr);
        getfield3 (ptr);

        return ptr;
    }

Here's one of the low level functions:

    getsubfld21 (ptr)
    char *ptr;
    {
        ...

        if (error) longjmp (envbuf, -1);

        ...

    }

#include <math.h>                         /* Apple // and UNIX functions */

double sinh (x)
double x;

double cosh (x)
double x;

double tanh (x)
double x;

These functions compute the hyperbolic of their arguments.

If  the absolute  value of  the argument  to sinh  or cosh  is greater than
348.6, the function sets  the symbolic value ERANGE  in the global  integer
errno and returns a huge value. This code is defined in the file "errno.h".

If  no  error  occurs,  the function  returns  the  computed  value without
modifying errno.

char *strcat (s1, s2)                     /* Apple // and UNIX functions */
char *s1;
char *s2;

char *strncat (s1, s2, n)
char *s1;
char *s2;
int n;

char *strcmp (s1, s2)
char *s1;
char *s2;

char *strncmp (s1, s2, n)
char *s1;
char *s2;
int n;

char *strcpy (s1, s2)
char *s1;
char *s2;

char *strncpy (s1, s2, n)
char *s1;
char *s2;
int n;

int strlen (s)
char *s;

char *index (s, c)
char *s;
char c;

char *rindex (s, c);
char *s;
char c;

These functions operate on null-terminated strings, as follows:

strcat  appends a copy of string s2 to  string s1. strncat copies at most n
characters. Both terminate  the resulting  string with  the null  character
('\0') and return a pointer to the first character of the resulting string.

strcmp  compares its  two arguments  and returns  an integer  greater than,
equal, of  less than  zero, according  as s1  is lexicographically  greater
than,  equal to,  or less  then s2. strncmp  makes the  same comparison but
looks at n characters at most.

strcpy copies string s2  to s1 stopping after  the null character has  been
moved.  strncpy copies  exactly n  characters: if  s2 contains  less than n
characters, null characters will be appended to the resulting string  until
n characters have been moved; if s2 contains n or more characters, only the
first n will be moved, and the rsulting string will be null terminated.

strlen  returns the number of  characters which occur in  s up to the first
null character.

index returns a pointer to the first occurance of the character c in string
s, or zero if c isn't in the string.

rindex returns a pointer to the last occurance of the character c in string
s, or zero if c isn't in the string.

#include <sysfunc.h>                         /* Apple // ProDOS function */

_system (func)
int func;
 DESCRIPTION 


_system  issues  the  function call  whose  number  is func,  using  as the
parameter area the globally-accessible character array named _sys_parm.

_system returns as its value the value that ProDOS returned in register A.

text()                                             /* Apple // functions */

hgr()

fscreen()

mscreen()

text sets the screen in text mode.

hgr sets the screen in Hi-res graphic mode. Unlike the Color functions, hgr
doesn't  clear the  screen. Note,  that the  80-column-card mode  is better
stopped  before  you  use  this  function,  otherwise  you  will  get   the
double-hires page.

fscreen  gives a full screen to work  with in the graphics mode. This means
that you have a 280 by 192 matrix to work with.

mscreen sets the screen in mixed text  and Hi-res modes. In this mode,  the
four  lines at the bottom  of the screen are used  to display text, and the
remainder of the screen (a 280 by 160 matrix) is in Hi-res mode.

long time (tloc)                          /* Apple // and UNIX functions */
long *tloc;

get_time (buf)
struct tm *buf;

char *ctime (clock)
long *clock;

#include <time.h>

struct tm *localtime (clock)
long *clock;

struct tm *gmtime (clock)
long *clock;

char *asctime (tm)
struct tm *tm;

time and  get_time  return the  date  and time,  which  they get  from  the
operating  system. The other functions convert the date and time, which are
passed as arguments, to another format.

time returns the  current date  and time  packed into  a long  int. If  its
argument  tloc is a non-null, the return  value is also stored in the field
pointed at by the  argument. The format  of the value  returned by time  is
described below.

get_time  returns the current date and time in the buffer pointed at by its
argument, buf. The format of this buffer is described below.

ctime, localtime, and gmtime  convert a date and  time pointed at by  their
argument, which is in a format such as returned by time to another format:

    ctime converts the time to a 26-chracter ASCII string of the form

        Mon Apr 30 10:04:52 1984\n\0

    localtime  and gmtime  unpack the  date and  time into  a structure and
    return a pointer to it. The structure, named tm, is described below and
    defined in the header file "time.h".

    asctime  converts a date and time pointed  at by its argument, which is
    in a  structure  such  as  returned  by  localtime  and  gmtime,  to  a
    26-character ASCII string in the same form as returned by ctime.

    The  long  int returned  by time  and passed  to ctime,  localtime, and
    gmtime has the following  form (bit 0 is  the least significant bit  in
    the field, bit 31 the most significant):

        Bits    Meaning

        00-07   minute
        08-15   hour
        16-20   day
        21-24   month
        25-31   year

The structure returned  by get_time,  localtime and gmtime,  and passed  to
asctime, has the following format:

    struct tm
    {
        short tm_sec;      /* seconds */
        short tm_min;      /* minutes */
        short tm_hour;     /* hours */
        short tm_mday;     /* day of the month */
        short tm_mon;      /* month */
        short tm_year;     /* year since 1900 */
        short tm_wday;     /* day of the week (0 = Sunday) */
        short tm_yday;     /* day of year */
        short tm_isdst;    /* not used */
        short tm_hsec;     /* hundredths of seconds */
    };

char *tmpnam (s)                                    /* Apple // function */
char *s;

tmpnam  creates  a character  string  that can  be used  as  the name  of a
temporary file. The generated string is not the name of an existing file.

s optionally points to an area into which the name will be generated.  This
must  contain at least L-tmpnam bytes, where L_tmpnam is a constant defined
in "stdio.h".

s can also be a NULL pointer. In  this case, the name will be generated  in
an  internal  array. The  contents of  this array  are destroyed  each time
tmpnam is called with a NULL argument.

The generated name is prefixed with the string that is associated with  the
symbol  P_tmpnam; this symbol is defined  in "stdio.h". In the distribution
version of  "stdio.h", P_tmpnam  is  a null  string;  this results  in  the
generated  name specifying  a file  that will  be allocated  in the current
directory.

tmpnam returns as its value a pointer to the resulting string.

toupper (c)                               /* Apple // and UNIX functions */
char c;

tolower (c)
char c;

#include <ctype.h>

_toupper (c)
int c;

_tolower (c)
int c;

toupper converts a lower case character to upper case: if c is a lower case
character,  toupper  returns  its  upper  case  equivalent  as  its  value,
otherwise c is returned.

tolower converts an upper case  character to lower case:  if c is an  upper
case  character, tolower returns its lower  case equivalent, otherwise c is
returned.

toupper and tolower do not require the header file "ctype.h".

_toupper  and  _tolower  are  macro   versions  of  toupper  and   tolower,
respectively. They are defined in "ctype.h". The difference between the two
sets of  functions  is that  the  macro version  will  sometimes  translate
non-alphabetic characters, whereas the function versions don't.

#include <stdio.h>                         /* Apple // and UNIX function */

ungetc (c, stream)
int c;
FILE *stream;

ungetc pushes the character  c back into the  input stream. That  character
will be returned by the next getc call on that stream.

Only one character of pushback is quaranteed. EOF cannot be pushed back.

ungetc returns c as its value, otherwise it returns EOF (-1).

unlink (name)                                       /* Apple // function */
char *name;

unlink erases a file.

name  is a pointer to a character string containing the name of the file to
be erased.

unlink returns 0 if successful, otherwise -1 if it couldn't erase the  file
and places a code in the global integer errno decribing the error.

write (fd, buf, bufsize)                   /* Apple // and UNIX function */
int fd;
char *buf;
int bufsize;

write  writes characters to a device or disk file which has been previously
opened be a call to open or creat. The characters are written to the device
or file directly from the caller's buffer.

fd  is the file despriptor which was returned to the caller when the device
or file was opened.

buf is a pointer to the buffer containing the characters to be written.

bufsize is the number of characters to be written.

If the operation was successful, write  returns as its value the number  of
characters  written, otherwise  write returns -1  and places a  code in the
global integer errno.