3211 lines
104 KiB
HTML
3211 lines
104 KiB
HTML
<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"><< 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"><< 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 <assert.h> /* 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 <assert.h>.
|
|
</PRE></FONT>
|
|
<a href="./cat1.htm#topmenu"><< 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"><< 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"><< 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"><< 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"><< 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"><< 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"><< 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"><< 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"><< 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"><< 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 <math.h> /* Apple // and UNIX functions */
|
|
|
|
double exp (x)
|
|
double x;
|
|
|
|
double log (x)
|
|
double x;
|
|
|
|
double log10 (x)
|
|
double x;
|
|
|
|
double pow (x, y)
|
|
double x;
|
|
double y;
|
|
|
|
double sqrt (x)
|
|
double x;
|
|
</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"><< 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 <math.h> /* 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"><< 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 <stdio.h> /* 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"><< 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 <stdio.h> /* 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"><< 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"><< 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 <stdio.h> /* Apple // and UNIX functions */
|
|
|
|
FILE *fopen (filename, mode)
|
|
char *filename;
|
|
char *mode;
|
|
|
|
FILE *freopen (filename, mode, stream)
|
|
char *filename;
|
|
char *mode;
|
|
FILE *stream;
|
|
|
|
FILE *fopen (fd, mode)
|
|
int fd;
|
|
char *mode;
|
|
</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 <stdio.h>
|
|
|
|
main (argc, argv)
|
|
char *argv[];
|
|
{
|
|
FILE *fopen();
|
|
FILE *fp;
|
|
|
|
if ((fp = fopen (argv[1], argv[2])) == NULL)
|
|
{
|
|
printf ("You asked me to open %s", argv[1]);
|
|
printf (" in the %s mode", argv[2]);
|
|
printf (" but I can't !\n");
|
|
}
|
|
else printf ("%s is open\n", argv[1]);
|
|
|
|
...
|
|
|
|
}
|
|
|
|
Here is a program which uses freopen:
|
|
|
|
#include <stdio.h<
|
|
|
|
main()
|
|
{
|
|
FILE *fp;
|
|
|
|
fp = freopen ("dskfile", "w+", stdout);
|
|
printf ("This message is going to dskfile\n");
|
|
}
|
|
|
|
Here is a program which uses fdopen:
|
|
|
|
#include <stdio.h>
|
|
|
|
dopen_it (fd)
|
|
int fd; /* value returned by call to open */
|
|
{
|
|
FILE *fp;
|
|
|
|
if ((fp = fdopen (fd, "r+")) == NULL)
|
|
printf ("can't open file for r+\n");
|
|
else return (fp);
|
|
}
|
|
</PRE></FONT>
|
|
<a href="./cat1.htm#topmenu"><< 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 <math.h> /* Apple // and UNIX functions */
|
|
|
|
double frexp (value, eptr)
|
|
double value;
|
|
int *eptr;
|
|
|
|
double ldexp (value, exp)
|
|
double value;
|
|
|
|
double modf (value, iptr)
|
|
double value;
|
|
double *iptr;
|
|
</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"><< 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 <stdio.h> /* 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"><< 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"><< 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 <sgtty.h> /* 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"><< 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 <ctype.h> /* 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"><< 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"><< 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"><< 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"><< 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 <stdio.h>
|
|
|
|
main()
|
|
{
|
|
char *fname, *mktemp();
|
|
FILE *fp, fopen();
|
|
|
|
fname = mktemp ("abcXXX.XXX") == 0)
|
|
if (!*fname)
|
|
{
|
|
printf ("mktemp failed");
|
|
exit (-1);
|
|
}
|
|
else fp = fopen (fname, "w");
|
|
|
|
...
|
|
|
|
}
|
|
</PRE></FONT>
|
|
<a href="./cat1.htm#topmenu"><< 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"><< 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 <fcntl.h> /* 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"><< 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"><< 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 <errno.h>
|
|
|
|
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"><< 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"><< 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"><< 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 <stdio.h> /* Apple // and UNIX funcions */
|
|
|
|
printf (fmp [,arg] ... )
|
|
char *fmt;
|
|
|
|
fprintf (stream, fmp [,arg] ... )
|
|
FILE *stream;
|
|
char *fmt;
|
|
|
|
sprintf (buffer, fmp [,arg] ... )
|
|
char *buffer;
|
|
char *fmt;
|
|
|
|
format (func, fmt, argptr)
|
|
int (*func)();
|
|
char *fmt;
|
|
unsigned *argptr;
|
|
</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"><< 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 <stdio.h> /* 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"><< 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 <stdio.h>
|
|
|
|
#define LINESIZE 16
|
|
#define MAXLINES 2000
|
|
|
|
char *lines[MAXLINES];
|
|
char *malloc;
|
|
|
|
main()
|
|
{
|
|
int i;
|
|
int numlines;
|
|
int cmp();
|
|
char buf[LINESIZE];
|
|
|
|
for (numlines=0; numlines<MAXLINES; ++numlines)
|
|
{
|
|
if (gets (buf) == NULL) break;
|
|
lines[numlines] = malloc (LINESIZE);
|
|
strcpy (lines[numlines], buf);
|
|
}
|
|
qsort (lines, numlines, 2, cmp);
|
|
for (i=0; i<numlines; ++i) printf ("%s\n", lines[i]);
|
|
}
|
|
|
|
cmp (a, b)
|
|
char **a, **b;
|
|
{
|
|
return strcmp (*a, *b);
|
|
}
|
|
|
|
</PRE></FONT>
|
|
<a href="./cat1.htm#topmenu"><< 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"><< 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"><< 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"><< 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"><< 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 <stdio.h> /* Apple // and UNIX functions */
|
|
|
|
scanf (format [,pointer] ... )
|
|
char *format;
|
|
|
|
fscanf (stream, format [,pointer] ... )
|
|
FILE *stream;
|
|
char *format;
|
|
|
|
sscanf (buffer, format [,pointer] ... )
|
|
char *buffer;
|
|
char *format;
|
|
</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"><< 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"><< 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 <setjmp.h> /* 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 <setjmp.h>
|
|
|
|
jmp_buf envbuf; /* environment saved here by setjmp */
|
|
|
|
getall (ptr)
|
|
char *ptr; /* ptr to record to be build */
|
|
{
|
|
if (setbuf (envbuf)) /* a low level function has aborted */
|
|
return 0;
|
|
getfield1 (ptr);
|
|
getfield2 (ptr);
|
|
getfield3 (ptr);
|
|
|
|
return ptr;
|
|
}
|
|
|
|
Here's one of the low level functions:
|
|
|
|
getsubfld21 (ptr)
|
|
char *ptr;
|
|
{
|
|
...
|
|
|
|
if (error) longjmp (envbuf, -1);
|
|
|
|
...
|
|
|
|
}
|
|
|
|
</PRE></FONT>
|
|
<a href="./cat1.htm#topmenu"><< 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 <math.h> /* 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"><< 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"><< 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 <sysfunc.h> /* 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"><< 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"><< 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 <time.h>
|
|
|
|
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"><< 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"><< 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 <ctype.h>
|
|
|
|
_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"><< 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 <stdio.h> /* 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"><< 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"><< 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"><< Back to Top</a>
|
|
<br>
|
|
<br>
|
|
<HR>
|
|
|
|
<center>
|
|
© Copyright Phade Software 1999<br>
|
|
Released as FreeWare December 1999<br>
|
|
</center>
|
|
<!-- the end -->
|
|
</FONT>
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|
|
|