Apple-2-SW
/
Runge-Kutta-Simulation
mirror of https://github.com/rigreco/Runge-Kutta-Simulation.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Runge-Kutta-Simulation/AppleX/DOCS/cat1.htm

3211 lines
104 KiB
HTML
Raw Blame History

<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<TITLE>Alphabetical Functions - Manx Aztec C 6502 for Apple II ProDOS</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#008000" ALINK="#008000" VLINK="#008000">
<a name=topmenu></a><FONT FACE="Arial" SIZE=3><P>
<B>Manx Aztec C 6502 for Apple II ProDOS
<br>Alphabetical (more or less) Functions</B></FONT>
<FONT FACE="Arial" SIZE=2 COLOR="#000000">
<UL>
<a href="./cat1.htm#intro">Introduction</a><br>
<br>
<a href="./cat1.htm#ACC">access</a><br>
<a href="./cat1.htm#ASS">assert</a><br>
<a href="./cat1.htm#ATO">atof, atoi, atol, ftoa</a><br>
<a href="./cat1.htm#BLA">black, blue, green, violet</a><br>
<a href="./cat1.htm#CIR">circle, set_asp</a><br>
<a href="./cat1.htm#CLO">close</a><br>
<a href="./cat1.htm#CRE">creat</a><br>
<a href="./cat1.htm#CTO">ctop, ptoc</a><br>
<a href="./cat1.htm#DRA">draw, bdrw, gdrw, rdrw, vdrw, lineto, blineto, glineto, rlineto, vlineto</a><br>
<a href="./cat1.htm#EXE">execl, execv, execlp, execvp</a><br>
<a href="./cat1.htm#EXI">exit, _exit</a><br>
<a href="./cat1.htm#EXP">exp, log, log10, pow, sqrt</a><br>
<a href="./cat1.htm#FAB">fabs, floor, ceil</a><br>
<a href="./cat1.htm#FCL">fclose, fflush</a><br>
<a href="./cat1.htm#FEO">feof, ferror, clearerr, fileno</a><br>
<a href="./cat1.htm#FIX">fixnam</a><br>
<a href="./cat1.htm#FOP">fopen, freopen, fdopen</a><br>
<a href="./cat1.htm#FRE">frexp, ldexp, modf</a><br>
<a href="./cat1.htm#FSE">fseek, ftell</a><br>
<a href="./cat1.htm#GET">getenv</a><br>
<a href="./cat1.htm#IOC">ioctl, isatty</a><br>
<a href="./cat1.htm#ISA">isalpha, isupper, islower, isdigit, isalnum, isspace, ispunct, isprint, iscntrl, asascii</a><br>
<a href="./cat1.htm#LSE">lseek</a><br>
<a href="./cat1.htm#MAL">malloc, calloc, realloc, free</a><br>
<a href="./cat1.htm#MKD">mkdir</a><br>
<a href="./cat1.htm#MKT">mktemp</a><br>
<a href="./cat1.htm#MOV">movmem, setmem, swapmem</a><br>
<a href="./cat1.htm#OPE">open</a><br>
<a href="./cat1.htm#PAG">page1, page2</a><br>
<a href="./cat1.htm#PER">perror, errno</a><br>
<a href="./cat1.htm#PPL">plot, bplot, gplot, rplot, vplot</a><br>
<a href="./cat1.htm#PRI">printf, fprintf, sprintf, format</a><br>
<a href="./cat1.htm#PUT">puts, fputs</a><br>
<a href="./cat1.htm#QSO">qsort</a><br>
<a href="./cat1.htm#RAN">ran</a><br>
<a href="./cat1.htm#REA">read</a><br>
<a href="./cat1.htm#REN">rename</a><br>
<a href="./cat1.htm#SBR">sbrk, brk, rsvstk</a><br>
<a href="./cat1.htm#SCA">scanf, fscanf, sscanf</a><br>
<a href="./cat1.htm#SCR">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</a><br>
<a href="./cat1.htm#SET">setjmp, longjmp</a><br>
<a href="./cat1.htm#SIN">sinh, cosh, tanh</a><br>
<a href="./cat1.htm#STR">strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen,
index, rindex</a><br>
<a href="./cat1.htm#SYS">_system</a><br>
<a href="./cat1.htm#TEX">text, hgr, fscreen, mscreen</a><br>
<a href="./cat1.htm#TIM">time, get_time, ctime, localtime, gmtime, asctime</a><br>
<a href="./cat1.htm#TMP">tmpnam</a><br>
<a href="./cat1.htm#TOU">toupper, tolower</a><br>
<a href="./cat1.htm#UNG">ungetc</a><br>
<a href="./cat1.htm#UNL">unlink</a><br>
<a href="./cat1.htm#WRI">write</a><br>
</UL>
<HR>
<a name=intro></a><b>Introduction</b>
<BR>
<BR>
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!
<BR>
<BR>
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:
<PRE><FONT SIZE=2>
/* Apple // and UNIX function */ or
/* Apple // and UNIX utility */
</PRE></FONT>
The contact information in the release notes for the electronic manual is as follows, but
Manx Software Systems have apparently since faded from existence:
<BR>
<BR>
Manx Software Systems<BR>
P.O. Box 55<BR>
Shrewsbury, N.J 07701
<BR>
<BR>
Phade Software<BR>
Inh. Frank Gadegast<BR>
Schierker Strasse 39<BR>
1000 Berlin 44 - Germany
<BR>
<BR>
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.
<BR>
<BR>
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.
<BR>
<BR>
<b>Licence and Disclaimer</b>
<BR>
<BR>
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.
<BR>
<BR>
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.
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=ACC></a><b> NAME access</b><br><br>
access - determine accessibility of a file or directory
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
int access (filename, mode) /* Apple // function */
char *filename;
int mode;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=ASS></a><b> NAME assert</b><br><br>
assert - verify program assertion
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;assert.h&gt; /* Apple // function */
assert (expr)
int expr;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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 &lt;assert.h&gt;.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=ATO></a><b> NAME atof, atoi, atol, ftoa</b><br><br>
atof, atoi, atol - convert ASCII to numbers
<br><br>
ftoa - convert floating point to ASCII
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=BLA></a><b> NAME black, blue, green, violet</b><br><br>
black, blue, green, violet - color selection functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
black() /* Apple // functions */
blue()
green()
violet()
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, line, mode, page, plotchar, point
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=CIR></a><b> NAME circle, set_asp</b><br><br>
circle, set_asp - circle-drawing functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
circle (x, y, rad) /* Apple // functions */
int x, y, rad;
set_asp (xasp, yasp)
int xasp, yasp;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
color, line, mode, page, plotchar, point
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=CLO></a><b> NAME close</b><br><br>
close - close a device or file
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
close (fd) /* Apple // and UNIX function */
int fd;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
If close fails, it returns -1 and sets an error code in the global integer
errno. Otherwise it returns 0 as its value.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
open, creat, errno
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=CRE></a><b> NAME creat</b><br><br>
creat - creat a new file
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
creat (name, pmode) /* Apple // and UNIX function */
char *name;
int pmode;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
If creat fails, it returns -1 as its value and sets a code in the global
integer errno.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=CTO></a><b> NAME ctop, ptoc</b><br><br>
ctop, ptoc - C <-> Pascal string functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
char *ctop (str) /* Apple // functions */
char *str;
char *ptoc (str)
char *str;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=DRA></a><b> NAME draw, bdrw, gdrw, rdrw, vdrw, lineto, blineto, glineto, rlineto, vlineto</b><br><br>
draw, bdrw, gdrw, rdrw, vdrw,<br>
lineto, blineto, glineto, rlineto, vlineto - line-drawing functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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)
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, color, mode, page, plotchar, point
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=EXE></a><b> NAME </b><br><br>
execl, execv, execlp, execvp - program activation functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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, ...;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
If an exec function call fails, for example because the file doesn't exist,
it will return -1 as its value.
</PRE></FONT>
<b> BUGS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=EXI></a><b> NAME exit, _exit</b><br><br>
exit, _exit
<br>
<br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
exit (code) /* Apple // and UNIX functions */
_exit (code)
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=EXP></a><b> NAME exp, log, log10, pow, sqrt</b><br><br>
exp, log, log10, pow, sqrt
<br>
<br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;math.h&gt; /* 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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FAB></a><b> NAME fabs, floor, ceil</b><br><br>
fabs, floor, ceil - absolute value, floor, ceiling routines
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;math.h&gt; /* Apple // and UNIX functions */
double fabs (x)
double x;
double floor (x)
double x;
double ceil (x)
double x;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FCL></a><b> NAME fclose, fflush</b><br><br>
fclose, fflush - close or flush a stream
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* Apple // and UNIX functions */
fclose (stream)
FILE *stream;
fflush (stream)
FILE *stream;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno, exit
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FEO></a><b> NAME feof, ferror, clearerr, fileno</b><br><br>
feof, ferror, clearerr, fileno - stream status inquiries
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* Apple // and UNIX functions */
feof (stream)
FILE *stream;
ferror (stream)
FILE *stream;
clearerr (stream)
FILE *stream;
fileno (stream)
FILE *stream;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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".
</PRE></FONT>
<b> SEE ALSO </b><br><br>
open, error
<BR>
<BR>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FIX></a><b> NAME fixnam</b><br><br>
fixnam - convert file name to fully-qualified name
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
fixnam (in_name, buf) /* Apple // ProDOS function */
char *in_name;
char *buf;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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)
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FOP></a><b> NAME fopen, freopen, fdopen</b><br><br>
fopen, freopen, fdopen - open a stream
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* 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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
creat, errno, open
<br>
<br>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
The following example demonstrates how fopen can be used in a program:
#include &lt;stdio.h&gt;
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 &lt;stdio.h&lt;
main()
{
FILE *fp;
fp = freopen ("dskfile", "w+", stdout);
printf ("This message is going to dskfile\n");
}
Here is a program which uses fdopen:
#include &lt;stdio.h&gt;
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);
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FRE></a><b> NAME frexp, ldexp, modf</b><br><br>
frexp, ldexp, modf - build and rebuild real numbers
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;math.h&gt; /* 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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=FSE></a><b> NAME fseek, ftell</b><br><br>
fseek, ftell - reposition a stream
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* Apple // and UNIX funcions */
int fseek (stream, offset, origin)
FILE *stream;
long offset;
int origin;
long ftell (stream)
FILE *stream;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno, lseek
<br>
<br>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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);
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=GET></a><b> NAME getenv</b><br><br>
getenv - get value of environment variable
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
char *getenv (name) /* Apple // ProDOS SHELL function */
char *name;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=IOC></a><b> NAME ioctl, isatty</b><br><br>
ioctl, isatty - device i/o utilities
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;sgtty.h&gt; /* Apple // and UNIX functions
ioctl (fd, cmd, stty)
FILE *fd,
char *cmd;
struct sgttyb *stty;
isatty (fd)
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=ISA></a><b> NAME isalpha, isupper, islower, isdigit, isalnum,
isspace, ispunct, isprint, iscntrl, asascii</b><br><br>
isalpha, isupper, islower, isdigit, isalnum,<br>
isspace, ispunct, isprint, iscntrl, asascii - character test functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;ctype.h&gt; /* Apple // and UNIX functions */
isalpha (c)
char c;
...
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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)
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=LSE></a><b> NAME lseek</b><br><br>
lseek - change current position within file
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
long lseek (fd, offset, origin) /* Apple // and UNIX functions */
int fd;
long offset;
int origin;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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).
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno, fseek
<br>
<br>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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);
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=MAL></a><b> NAME malloc, calloc, realloc, free</b><br><br>
malloc, calloc, realloc, free - memory allocation
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=MKD></a><b> NAME mkdir</b><br><br>
mkdir - make directory
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
mkdir (name) /* Apple // ProDOS and UNIX function */
char *name;
mkdir dir [dir ...] /* Apple // ProDOS SHELL utility */
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=MKT></a><b> NAME mktemp</b><br><br>
mktemp - make a unique file name
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
char *mktemp (template) /* Apple // function */
char *template;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
tmpfile, tmpname
<br>
<br>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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 &lt;stdio.h&gt;
main()
{
char *fname, *mktemp();
FILE *fp, fopen();
fname = mktemp ("abcXXX.XXX") == 0)
if (!*fname)
{
printf ("mktemp failed");
exit (-1);
}
else fp = fopen (fname, "w");
...
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=MOV></a><b> NAME movmem, setmem, swapmem</b><br><br>
movmem, setmem, swapmem
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=OPE></a><b> NAME open</b><br><br>
open
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;fcntl.h&gt; /* Apple // and UNIX function */
open (name, mode, param3)
char *name;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<br>
<br>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
If open encounters an error, it returns -1 and sets the global integer
errno to a symbolic value which identifies the error.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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");
}
...
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PAG></a><b> NAME page1, page2</b><br><br>
page1, page2 - page-selection functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
page1() /* Apple // functions */
page2()
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
page1 and page2 enable the primary and secondary pages, respectively.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, color, line, mode, plotchar, point
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PER></a><b> NAME perror, errno</b><br><br>
perror, errno - system error messages
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
int perror (s) /* Apple // and UNIX functions */
char *s;
#include &lt;errno.h&gt;
extern int errno;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
perror returns 0 if errno contains a valid value, otherwise, it returns -1
without printing a message.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PLO></a><b> NAME plotchar</b><br><br>
plotchar - plot character
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
plotchar (c, x, y) /* Apple // function */
int c, x, y;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
plotchar displays the printable char c on the primary Hi-res graphic page,
at the location having coordinates (x, y).
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, color, line, mode, page, point
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PPL></a><b> NAME plot, bplot, gplot, rplot, vplot</b><br><br>
plot, bplot, gplot, rplot, vplot - point-plotting functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
plot (x, y) /* Apple // functions */
bplot (x, y)
gplot (x, y)
rplot (x, y)
vplot (x, y)
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, color, line ,mode, page, plotchar
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PRI></a><b> NAME printf, fprintf, sprintf, format</b><br><br>
printf, fprintf, sprintf, format - formatted output conversion functions
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* 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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
All functions return -1 as their value, if the conversion fails.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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);
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=PUT></a><b> NAME puts, fputs</b><br><br>
puts, fputs - put a character string on a stream
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* Apple // and UNIX funcions */
puts (s)
char *s;
fputs (s, stream)
char *s;
FILE *stream;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
If an error occur, these functions return EOF (-1) and set an error code in
the global integer errno.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
aputc, errno, putc
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=QSO></a><b> NAME qsort</b><br><br>
qsort - sort an array of records in memory
<br>
<br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
qsort (array, number, width, func) /* Apple // and UNIX function */
char *array;
unsigned number;
unsigned width;
int (*func)();
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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 &lt;stdio.h&gt;
#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&lt;MAXLINES; ++numlines)
{
if (gets (buf) == NULL) break;
lines[numlines] = malloc (LINESIZE);
strcpy (lines[numlines], buf);
}
qsort (lines, numlines, 2, cmp);
for (i=0; i&lt;numlines; ++i) printf ("%s\n", lines[i]);
}
cmp (a, b)
char **a, **b;
{
return strcmp (*a, *b);
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=RAN></a><b> NAME ran</b><br><br>
ran - random number generator
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
double ran () /* Apple // and UNIX function */
double randl (x)
double x;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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 .
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=REA></a><b> NAME read</b><br><br>
read - read from device or file without buffering
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
read (fd, buf, bufsize) /* Apple // and UNIX function */
int fd;
char *buf;
int bufsize;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno, close, fread, open
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=REN></a><b> NAME rename</b><br><br>
rename - rename a disk file
<br><br>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
rename (oldname, newname) /* Apple // function */
char *oldname;
char *newname;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SBR></a><b> NAME sbrk, brk, rsvstk</b><br><br>
sbrk, brk, rsvstk - heap management functions
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
void *sbrk (size) /* Apple // functions */
brk (ptr)
void *ptr;
rsvstk (size)
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
The functions malloc, free, etc implement a dynamic buffer- alloction
scheme using the sbrk function.
<BR>
<BR>
The standard i/o functions usally call malloc and free to allocate and
release buffers for use by i/o streams.
<BR>
<BR>
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.
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SCA></a><b> NAME scanf, fscanf, sscanf</b><br><br>
scanf, fscanf, sscanf - formatted input conversion
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* 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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SCR></a><b> 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</b><br><br>
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
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SET></a><b> NAME setjmp, longjmp</b><br><br>
setjmp, longjmp - non-local goto
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;setjmp.h&gt; /* Apple // and UNIX funcion */
setjmp (env)
jmp_buf env;
longjmp (env, val)
jmp_buf env;
int val;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> EXAMPLES </b><br><br>
<PRE><FONT SIZE=2>
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 &lt;setjmp.h&gt;
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);
...
}
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SIN></a><b> NAME sinh, cosh, tanh</b><br><br>
sinh, cosh, tanh - hyperbolic functions
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;math.h&gt; /* Apple // and UNIX functions */
double sinh (x)
double x;
double cosh (x)
double x;
double tanh (x)
double x;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
These functions compute the hyperbolic of their arguments.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=STR></a><b> NAME strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen,
index, rindex</b><br><br>
strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen,
index, rindex - string operations
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
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;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=SYS></a><b> NAME _system</b><br><br>
_system - issues ProDOS function call
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;sysfunc.h&gt; /* Apple // ProDOS function */
_system (func)
int func;
<b> DESCRIPTION </b><br><br>
_system issues the function call whose number is func, using as the
parameter area the globally-accessible character array named _sys_parm.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
_system returns as its value the value that ProDOS returned in register A.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=TEX></a><b> NAME text, hgr, fscreen, mscreen</b><br><br>
text, hgr, fscreen, mscreen - mode-selection functions
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
text() /* Apple // functions */
hgr()
fscreen()
mscreen()
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
circle, color, line, page, plotchar, point
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=TIM></a><b> NAME time, get_time, ctime, localtime, gmtime, asctime</b><br><br>
time, get_time, ctime, localtime, gmtime, asctime - time functions
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
long time (tloc) /* Apple // and UNIX functions */
long *tloc;
get_time (buf)
struct tm *buf;
char *ctime (clock)
long *clock;
#include &lt;time.h&gt;
struct tm *localtime (clock)
long *clock;
struct tm *gmtime (clock)
long *clock;
char *asctime (tm)
struct tm *tm;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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 */
};
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=TMP></a><b> NAME tmpnam</b><br><br>
tmpnam - create a name for a temporary file
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
char *tmpnam (s) /* Apple // function */
char *s;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
tmpnam returns as its value a pointer to the resulting string.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
tmpfile, mktemp
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=TOU></a><b> NAME toupper, tolower</b><br><br>
toupper, tolower - char conversion functions
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
toupper (c) /* Apple // and UNIX functions */
char c;
tolower (c)
char c;
#include &lt;ctype.h&gt;
_toupper (c)
int c;
_tolower (c)
int c;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=UNG></a><b> NAME ungetc</b><br><br>
ungetc - push a character back into input stream
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
#include &lt;stdio.h&gt; /* Apple // and UNIX function */
ungetc (c, stream)
int c;
FILE *stream;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
ungetc returns c as its value, otherwise it returns EOF (-1).
</PRE></FONT>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=UNL></a><b> NAME unlink</b><br><br>
unlink - remove a file
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
unlink (name) /* Apple // function */
char *name;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
unlink erases a file.
name is a pointer to a character string containing the name of the file to
be erased.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
errno
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<a name=WRI></a><b> NAME write</b><br><br>
write - unbuffered access to device or file
<BR>
<BR>
<b> SYNOPSIS </b><br><br>
<PRE><FONT SIZE=2>
write (fd, buf, bufsize) /* Apple // and UNIX function */
int fd;
char *buf;
int bufsize;
</PRE></FONT>
<b> DESCRIPTION </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> DIAGNOSTICS </b><br><br>
<PRE><FONT SIZE=2>
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.
</PRE></FONT>
<b> SEE ALSO </b><br><br>
close, creat, errno, open, read
<br>
<br>
<a href="./cat1.htm#topmenu">&lt;&lt; Back to Top</a>
<br>
<br>
<HR>
<center>
&copy; Copyright Phade Software 1999<br>
Released as FreeWare December 1999<br>
</center>
<!-- the end -->
</FONT>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink