Manx Aztec C 6502 for Apple II ProDOS
Alphabetical (more or less) Functions

Introduction
access
assert
atof, atoi, atol, ftoa
black, blue, green, violet
circle, set_asp
close
creat
ctop, ptoc
draw, bdrw, gdrw, rdrw, vdrw, lineto, blineto, glineto, rlineto, vlineto
execl, execv, execlp, execvp
exit, _exit
exp, log, log10, pow, sqrt
fabs, floor, ceil
fclose, fflush
feof, ferror, clearerr, fileno
fixnam
fopen, freopen, fdopen
frexp, ldexp, modf
fseek, ftell
getenv
ioctl, isatty
isalpha, isupper, islower, isdigit, isalnum, isspace, ispunct, isprint, iscntrl, asascii
lseek
malloc, calloc, realloc, free
mkdir
mktemp
movmem, setmem, swapmem
open
page1, page2
perror, errno
plot, bplot, gplot, rplot, vplot
printf, fprintf, sprintf, format
puts, fputs
qsort
ran
read
rename
sbrk, brk, rsvstk
scanf, fscanf, sscanf
scr_beep, 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
setjmp, longjmp
sinh, cosh, tanh
strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex
_system
text, hgr, fscreen, mscreen
time, get_time, ctime, localtime, gmtime, asctime
tmpnam
toupper, tolower
ungetc
unlink
write

Introduction
This is an HTML version of the electronic manual for Manx Aztec C for Apple II ProDOS released as freeware by Phade Software December 1999. The release notes for the electronic manual indicate that the electronic manual contains the same information as the paper manual distributed by Manx Software Systems with the compiler. However, they also indicate that if you are using the AZTEC PLUS release you should use the electronic manual rather than the paper manual supplied by Manx. Welcome to the wonderfully confusing World of Aztec C!
The release notes for the electronic manual also indicate that the following notation in the synopsis part of a manual page only means that the function or utility is available both in UNIX and on the Apple II, but despite that fact, the description for that function or utility may differ between the Apple II and UNIX versions:

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

The contact information in the release notes for the electronic manual is as follows, but Manx Software Systems have apparently since faded from existence:
Manx Software Systems
P.O. Box 55
Shrewsbury, N.J 07701
Phade Software
Inh. Frank Gadegast
Schierker Strasse 39
1000 Berlin 44 - Germany
The HTML version (this document and others) was produced by Canadian Software Developer Bill Buckels by reformatting the Phade Software UNIX style man pages from the elctronic manual into consolidated HTML documents after converting these from Apple II text to IBM text. The original format has been preserved as much as practically possible, and the content of the Phade Software electronic manual remains apparently intact and unaltered in its transition to HTML.
The main benefits of the HTML version are that you can view the information in the man pages on a single HTML document using a web browser in the relative comfort of a modern user interface and can use your web browsers "Find on this Page" feature to search through the content to easily locate information using your own search criteria. This is much easier than using the unix style man utility which can only search on key topics and will only display a single topic at a time.
Licence and Disclaimer
This is a derivative work and as such the licencing by the original authors applies. Bill Buckels makes no claims of ownership whatsoever for the content of this document, and further assumes no liability for the results its use.
You may use the information in this document in any way you find useful (subject to the original authors restrictions and apparently there aren't any), provided that you agree that Bill Buckels has no warranty obligations or liability resulting from said use in any way whatsoever. If you don't agree, don't use this document.
<< Back to Top

NAME access
access - determine accessibility of a file or directory
SYNOPSIS

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

DESCRIPTION

    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.

SEE ALSO
errno
<< Back to Top

NAME assert
assert - verify program assertion
SYNOPSIS

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

    assert (expr)
    int expr;

DESCRIPTION

    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>.

<< Back to Top

NAME atof, atoi, atol, ftoa
atof, atoi, atol - convert ASCII to numbers
ftoa - convert floating point to ASCII
SYNOPSIS

    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;

DESCRIPTION

    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.

<< Back to Top

NAME black, blue, green, violet
black, blue, green, violet - color selection functions
SYNOPSIS

    black()                                            /* Apple // functions */

    blue()

    green()

    violet()

DESCRIPTION

    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.

SEE ALSO
circle, line, mode, page, plotchar, point
<< Back to Top

NAME circle, set_asp
circle, set_asp - circle-drawing functions
SYNOPSIS

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

    set_asp (xasp, yasp)
    int xasp, yasp;

DESCRIPTION

    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.

SEE ALSO
color, line, mode, page, plotchar, point
<< Back to Top

NAME close
close - close a device or file
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

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

SEE ALSO
open, creat, errno
<< Back to Top

NAME creat
creat - creat a new file
SYNOPSIS

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

DESCRIPTION

    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

DIAGNOSTICS

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

<< Back to Top

NAME ctop, ptoc
ctop, ptoc - C <-> Pascal string functions
SYNOPSIS

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

    char *ptoc (str)
    char *str;

DESCRIPTION

    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.

<< Back to Top

NAME draw, bdrw, gdrw, rdrw, vdrw, lineto, blineto, glineto, rlineto, vlineto
draw, bdrw, gdrw, rdrw, vdrw,
lineto, blineto, glineto, rlineto, vlineto - line-drawing functions
SYNOPSIS

    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)

DESCRIPTION

    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.

SEE ALSO
circle, color, mode, page, plotchar, point
<< Back to Top

NAME
execl, execv, execlp, execvp - program activation functions
SYNOPSIS

    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, ...;

DESCRIPTION

    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.

DIAGNOSTICS

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

BUGS

    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.

<< Back to Top

NAME exit, _exit
exit, _exit
SYNOPSIS

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

    _exit (code)

DESCRIPTION

    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.

DIAGNOSTICS

    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.

<< Back to Top

NAME exp, log, log10, pow, sqrt
exp, log, log10, pow, sqrt
SYNOPSIS

    #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;

DESCRIPTION

    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.

DIAGNOSTICS

    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

SEE ALSO
errno
<< Back to Top

NAME fabs, floor, ceil
fabs, floor, ceil - absolute value, floor, ceiling routines
SYNOPSIS

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

    double fabs (x)
    double x;

    double floor (x)
    double x;

    double ceil (x)
    double x;

DESCRIPTION

    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.

<< Back to Top

NAME fclose, fflush
fclose, fflush - close or flush a stream
SYNOPSIS

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

    fclose (stream)
    FILE *stream;

    fflush (stream)
    FILE *stream;

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
errno, exit
<< Back to Top

NAME feof, ferror, clearerr, fileno
feof, ferror, clearerr, fileno - stream status inquiries
SYNOPSIS

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

    feof (stream)
    FILE *stream;

    ferror (stream)
    FILE *stream;

    clearerr (stream)
    FILE *stream;

    fileno (stream)
    FILE *stream;

DESCRIPTION

    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".

SEE ALSO
open, error
<< Back to Top

NAME fixnam
fixnam - convert file name to fully-qualified name
SYNOPSIS

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

DESCRIPTION

    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.

EXAMPLES

    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)

DIAGNOSTICS

    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.

<< Back to Top

NAME fopen, freopen, fdopen
fopen, freopen, fdopen - open a stream
SYNOPSIS

    #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;

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
creat, errno, open
EXAMPLES

    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);
        }

<< Back to Top

NAME frexp, ldexp, modf
frexp, ldexp, modf - build and rebuild real numbers
SYNOPSIS

    #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;

DESCRIPTION

    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.

<< Back to Top

NAME fseek, ftell
fseek, ftell - reposition a stream
SYNOPSIS

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

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

    long ftell (stream)
    FILE *stream;

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
errno, lseek
EXAMPLES

    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);

<< Back to Top

NAME getenv
getenv - get value of environment variable
SYNOPSIS

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

DESCRIPTION

    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.

<< Back to Top

NAME ioctl, isatty
ioctl, isatty - device i/o utilities
SYNOPSIS

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

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

    isatty (fd)

DESCRIPTION

    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.

<< Back to Top

NAME isalpha, isupper, islower, isdigit, isalnum, isspace, ispunct, isprint, iscntrl, asascii
isalpha, isupper, islower, isdigit, isalnum,
isspace, ispunct, isprint, iscntrl, asascii - character test functions
SYNOPSIS

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

    isalpha (c)
    char c;

    ...

DESCRIPTION

    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)

<< Back to Top

NAME lseek
lseek - change current position within file
SYNOPSIS

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

DESCRIPTION

    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).

DIAGNOSTICS

    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.

SEE ALSO
errno, fseek
EXAMPLES

    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);

<< Back to Top

NAME malloc, calloc, realloc, free
malloc, calloc, realloc, free - memory allocation
SYNOPSIS

    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;

DESCRIPTION

    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.

DIAGNOSTICS

    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.

<< Back to Top

NAME mkdir
mkdir - make directory
SYNOPSIS

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

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

DESCRIPTION

    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.

DIAGNOSTICS

    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.

<< Back to Top

NAME mktemp
mktemp - make a unique file name
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
tmpfile, tmpname
EXAMPLES

    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");

            ...

        }

<< Back to Top

NAME movmem, setmem, swapmem
movmem, setmem, swapmem
SYNOPSIS

    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;

DESCRIPTION

    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.

<< Back to Top

NAME open
open
SYNOPSIS

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

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

DESCRIPTION

    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.

SEE ALSO
errno
DIAGNOSTICS

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

EXAMPLES

    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");
                }

                ...

            }

<< Back to Top

NAME page1, page2
page1, page2 - page-selection functions
SYNOPSIS

    page1()                                            /* Apple // functions */

    page2()

DESCRIPTION

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

SEE ALSO
circle, color, line, mode, plotchar, point
<< Back to Top

NAME perror, errno
perror, errno - system error messages
SYNOPSIS

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

    #include <errno.h>

    extern int errno;

DESCRIPTION

    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.

DIAGNOSTICS

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

<< Back to Top

NAME plotchar
plotchar - plot character
SYNOPSIS

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

DESCRIPTION

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

SEE ALSO
circle, color, line, mode, page, point
<< Back to Top

NAME plot, bplot, gplot, rplot, vplot
plot, bplot, gplot, rplot, vplot - point-plotting functions
SYNOPSIS

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

DESCRIPTION

    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

SEE ALSO
circle, color, line ,mode, page, plotchar
<< Back to Top

NAME printf, fprintf, sprintf, format
printf, fprintf, sprintf, format - formatted output conversion functions
SYNOPSIS

    #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;

DESCRIPTION

    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.

DIAGNOSTICS

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

EXAMPLES

    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);
            }

<< Back to Top

NAME puts, fputs
puts, fputs - put a character string on a stream
SYNOPSIS

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

    puts (s)
    char *s;

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

DESCRIPTION

    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.

DIAGNOSTICS

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

SEE ALSO
aputc, errno, putc
<< Back to Top

NAME qsort
qsort - sort an array of records in memory
SYNOPSIS

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

DESCRIPTION

    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.

EXAMPLES

    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);
        }

<< Back to Top

NAME ran
ran - random number generator
SYNOPSIS

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

    double randl (x)
    double x;

DESCRIPTION

    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 .

<< Back to Top

NAME read
read - read from device or file without buffering
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
errno, close, fread, open
<< Back to Top

NAME rename
rename - rename a disk file
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
errno
<< Back to Top

NAME sbrk, brk, rsvstk
sbrk, brk, rsvstk - heap management functions
SYNOPSIS

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

    brk (ptr)
    void *ptr;

    rsvstk (size)

DESCRIPTION

    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.

EXAMPLES

    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.

SEE ALSO
The functions malloc, free, etc implement a dynamic buffer- alloction scheme using the sbrk function.
The standard i/o functions usally call malloc and free to allocate and release buffers for use by i/o streams.
Your program can safely mix calls to the malloc functions, standard i/o calls, and calls to sbrk and brk, as long as your calls to sbrk and brk don't decrement the heap pointer. Mixing sbrk and brk calls that decrement the heap pointer with calls to the malloc functions and/or the stadard i/o functions is dangerous and probably shouldn't be done by normal programs.
<< Back to Top

NAME scanf, fscanf, sscanf
scanf, fscanf, sscanf - formatted input conversion
SYNOPSIS

    #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;

DESCRIPTION

    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.

EXAMPLES

    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.

<< Back to Top

NAME scr_beep, 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
scr_beep, 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 - screen manipulation functions
SYNOPSIS

    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;

DESCRIPTION

    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.

<< Back to Top

NAME setjmp, longjmp
setjmp, longjmp - non-local goto
SYNOPSIS

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

    setjmp (env)
    jmp_buf env;

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

DESCRIPTION

    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.

EXAMPLES

    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);

            ...

        }

<< Back to Top

NAME sinh, cosh, tanh
sinh, cosh, tanh - hyperbolic functions
SYNOPSIS

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

    double sinh (x)
    double x;

    double cosh (x)
    double x;

    double tanh (x)
    double x;

DESCRIPTION

    These functions compute the hyperbolic of their arguments.

DIAGNOSTICS

    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.

SEE ALSO
errno
<< Back to Top

NAME strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex
strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, index, rindex - string operations
SYNOPSIS

    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;

DESCRIPTION

    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.

<< Back to Top

NAME _system
_system - issues ProDOS function call
SYNOPSIS

    #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.

DIAGNOSTICS

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

<< Back to Top

NAME text, hgr, fscreen, mscreen
text, hgr, fscreen, mscreen - mode-selection functions
SYNOPSIS

    text()                                             /* Apple // functions */

    hgr()

    fscreen()

    mscreen()

DESCRIPTION

    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.

SEE ALSO
circle, color, line, page, plotchar, point
<< Back to Top

NAME time, get_time, ctime, localtime, gmtime, asctime
time, get_time, ctime, localtime, gmtime, asctime - time functions
SYNOPSIS

    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;

DESCRIPTION

    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 */
        };

<< Back to Top

NAME tmpnam
tmpnam - create a name for a temporary file
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

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

SEE ALSO
tmpfile, mktemp
<< Back to Top

NAME toupper, tolower
toupper, tolower - char conversion functions
SYNOPSIS

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

    tolower (c)
    char c;

    #include <ctype.h>

    _toupper (c)
    int c;

    _tolower (c)
    int c;

DESCRIPTION

    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.

<< Back to Top

NAME ungetc
ungetc - push a character back into input stream
SYNOPSIS

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

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

DESCRIPTION

    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.

DIAGNOSTICS

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

<< Back to Top

NAME unlink
unlink - remove a file
SYNOPSIS

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

DESCRIPTION

    unlink erases a file.

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

DIAGNOSTICS

    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.

SEE ALSO
errno
<< Back to Top

NAME write
write - unbuffered access to device or file
SYNOPSIS

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

DESCRIPTION

    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.

DIAGNOSTICS

    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.

SEE ALSO
close, creat, errno, open, read
<< Back to Top

© Copyright Phade Software 1999
Released as FreeWare December 1999