Manx Aztec C 6502 for Apple II ProDOS
Alphabetical (more or less) Functions
/* Apple // and UNIX function */ or /* Apple // and UNIX utility */The contact information in the release notes for the electronic manual is as follows, but Manx Software Systems have apparently since faded from existence:
int access (filename, mode) /* Apple // function */ char *filename; int mode;DESCRIPTION
access determines whether a file or directory can be accessed in the way that the calling function wants to access it. It can also be used to just test for the existence of a file or directory. filename points to the name of the file or directory; this name optionally contains the drive and path of directories that must be passed through to get to the file or directory. If the drive component isn't specified, the file or directory is assumed to reside on the default drive. If the path component isn't specified, the file or directory is assumed to reside in the current directory on the specified drive. mode is an int that specifies the type of access desired: mode meaning 4 read 2 write 1 execute (if a file) or search (if a directory) 0 check existence of the file or directory. If the existence of the file or directory is being checked (ie, mode=0), access returns 0 if the file exists and -1 if it doesn't. In the latter case, access also sets the symbolic value ENOENT in the global integer errno. When access is called to determine if a file can be accessed in a certain way (ie, mode isn't 0). access returns 0 if the file can be accessed in the desired manner; otherwise, it returns -1 and sets a code in the global integer errno that defines why the access is not permitted. When asked, access says that a directory can be read or written; this means that a program can create and delete files on the directory, not that it can directly read or write the directory itself. The symbolic values that access may set in errno when it's called with a non-zero mode parameter are: errno meaning ENOTDIR A component of the path prefix is not a directory. ENOENT The file or directory doesn't exist. EACCES The file or directory can't be accessed in the desired manner.SEE ALSO
#include <assert.h> /* Apple // function */ assert (expr) int expr;DESCRIPTION
assert is usefull for putting diagnostic messages in a program. When executed, it will determine whether the expression expr is true or false. If false, it prints the message Assertion failed: expr, file fff line lnnn where fff is the name of the source file and nnn is the line number of the assert statement. To prevent assertion statements from being compiled in a program, compile the program with the option -DNDEBUG, or place the statement #define NDEBUG ahead of the statement #include <assert.h>.<< Back to Top
double atof (cp) /* Apple // and UNIX functions */ char *cp; atoi (cp) char *cp; long atol (cp) char *cp; ftoa (val, buf, precision, type) double val; char *buf; int precision; int type;DESCRIPTION
atof, atoi, and atol convert a string of text characters pointed at by the argument cp to double, integer, and long represantations. atof recognizes a string containing leading blanks and tabs, which it skips, then an optional sign, then a string of digits optionally containing a decimal point, then an optional 'e' or 'E' followed be an optional signed integer. atoi and atol recognize a string containing leading blanks and tabs, which are ignored, then an optional sign, then a string of digits. ftoa converts a double precision floating point number to ASCII. val is the number to be converted and buf points to the buffer where the ASCII string will be placed. precision specifies the number of digits to the right of the decimal point. type specifies the format: 0 for 'E' format, 1 for 'F' format, 2 for 'G' format. atof and ftoa are in the library m.lib, the other functions are in c.lib.<< Back to Top
black() /* Apple // functions */ blue() green() violet()DESCRIPTION
Each of these functions sets the screen in Hi-res, full-screen graphic mode, using the primary graphics page, and clears the screen. The entire screen will be a single color, as determined by the function that is called. For example, calling green makes the entire screen green.SEE ALSO
circle (x, y, rad) /* Apple // functions */ int x, y, rad; set_asp (xasp, yasp) int xasp, yasp;DESCRIPTION
circle draws an oval on the primary hi-res graphics page, with center at (x,y). By default, the horizontal and vertical radii of the oval are both rad, resulting in circle drawing a circle. set_asp controls the eccentricity (ie, the "ovalness") of the figure drawn by circle: circle draws an oval whose horizontal radius is rad * xasp and whose vertical radius is rad * yasp, where xasp and yasp have the values defined by the last call to set_asp. If set_asp isn't called, circle will use the value 1 for xasp and yasp, resulting in a circle of radius rad being drawn.SEE ALSO
close (fd) /* Apple // and UNIX function */ int fd;DESCRIPTION
close closes a device or disk file which is opened for unbuffered i/o. The parameter fd is the file descriptor associated with the file or device. If the device or file was explicity opened by the program by calling open or creat, fd is the file descriptor returned by open or creat.DIAGNOSTICS
If close fails, it returns -1 and sets an error code in the global integer errno. Otherwise it returns 0 as its value.SEE ALSO
creat (name, pmode) /* Apple // and UNIX function */ char *name; int pmode;DESCRIPTION
There are two descriptions of this function: The one you're now reading describes its implementation on the Apple //. creat creates a file and opens it for unbuffered, write-only access. If the file already exists, it is truncated so that nothing is in it (this is done by erasing and then creating the file). creat returns as its value an integer called a "file descriptor". Whenever a call is made to one of the unbuffered i/o functions to access the file, its file descriptor must be included in the function's parameters. name is a pointer to a character string which is the name of the device or file to be opened. For most systems, pmode is optional: if specified, it's ignored. It should be included, however, for programs for which UNIX-compatibility is required, since the UNIX creat function requires it. Int this case, pmode should have the ocal value 0666. For ProDOS programs, the pmode parameter of the creat function is the file's access mode. The meanings of the bits in this parameter (bit 0 is the least significant bit, bit 15 is the most significant): Bit number Meaning 0 File can be read 1 File can be written 2-4 Reserved 5 File modified since last backup 6 File can be renamed 7 File can be deleted 8-15 Unused Thus, to create a file on which all types of operations are permitted, set its mode parameter to 0xC3. For DOS 3.3 programs, pmode is the file's type. Type codes: Param3,hex File type 00 Text 01 Integer basic 02 Applesoft basic 04 Binary 08 Relocatable 10 S-type file 20 A-type file 40 B-type fileDIAGNOSTICS
If creat fails, it returns -1 as its value and sets a code in the global integer errno.<< Back to Top
char *ctop (str) /* Apple // functions */ char *str; char *ptoc (str) char *str;DESCRIPTION
ProDOS expects character strings to be in Pascal format, in which a string consists of a leading byte containing the number of characters in the string, followed by the characters in the string. In C, on the other hand, a character string consists of the characters followed by a null character. ctop and ptoc convert a string from C form to Pascal form and from Pascal form to C form, respectively. The converted string overlays the original string, and the function returns a pointer to the converted string.<< Back to Top
drw (x1, y1, x2, y2) /* Apple // functions */ bdrw (x1, y1, x2, y2) gdrw (x1, y1, x2, y2) rdrw (x1, y1, x2, y2) vdrw (x1, y1, x2, y2) lineto (x, y) blineto (x, y) glineto (x, y) rlineto (x, y) vlineto (x, y)DESCRIPTION
These functions draw straight lines on the primary Hi-res graphics page. The "drw" functions (ie, the first five functions) draw a line from the point whose coordinates are (x1, y1) to (x2, y2), differing in the color of the line, as follows: Function Color drw white bdrw blue gdrw green rdrw red vdrw violet The "drw" functions set the global variables _oldx and _oldy to x2 and y2, respectively. The "lineto" functions (ie, the last five functions) draw a line from the point whose coordinates are (_oldx, _oldy) to the point (x, y), and then set _oldx and _oldy to x and y, respectively. These functions differ in the color of the drawn line like above.SEE ALSO
execv (name, argv) /* UNIX function */ char *name, *arg[]; execvp (name, argv) /* Apple // functions */ char *name, *arg[]; execl (name, arg0, arg1, arg2, ..., argn, 0) char *name, *arg0, *arg1, *arg2, ...; execlp (name, arg0, arg1, arg2, ..., argn, 0) char *name, *arg0, *arg1, *arg2, ...;DESCRIPTION
These functions load, and transfer control to another program. The called program is loaded on top of the calling program; thus, if the exec function succeeds, it doesn't return to the caller. The functions can be called by PRG programs: that is, by programs that can only be run in the SHELL environment. The functions can start any type of program, including those that have not been created using the Aztec software. The functions can also be called by BIN programs, when the programs are running in the SHELL environment. However, unlike BIN programs, these functions can't be used outside the SHELL environment; thus, you should be wary about using these functions in a BIN program. The Parameters: name is the name of the file containing the program to be loaded. It can optionally specify, using the standard ProDOS syntax, the complete or a partial path of directories that must be passed through to get to the file. The exec functions can pass arguments to the called program. execl and execlp build a command line by containing the string pointed at by arg1, arg2, and so on. If a C program is being called, its main function will see arg0 as argv[0], arg1 as argv[1], and so on. By convention, arg0 is the name of the program being called. execv and execvp built a command line by concatenating the strings pointed at by argv[0], argv[1], and so on. The argv array must be have a null pointer as its last entry. If a C program is being called, its main function will see the calling function's argv[i] as its argv[i]. By convention argv[0] is the name of the program being called. The Functions: execl and execv load a program from the specified file: execl is usefull when a fixed number of arguments are being passed to a program. execv is usefull for programs which are passed a variable number of arguments. execlp and execvp search a list of directories for the program to be loaded, beginning with the current directory. If the program isn't there, the directories specified in the PATH environment variable are searched. Passing Open Files and Devices: When both the calling and the called programs are of type PRG, the following comments describe the passing of open file and devices between the programs: * File that are left open for unbuffered i/o in the calling program will be open for unbuffered i/o in the called program, and will have the same file descriptors. * Except for files that are associated with the stdin, stdout, and stderr standard i/o devices, file left open for standard i/o in the calling program won't be open for standard i/o in the called program, although they will be open for unbuffered i/o: thus, before a PRG program activates another using an exec function, it should cause the buffered data for files opened for standard i/o to be written to disk, using either the fclose or fflush functions. * The standard input, standard output, and standard error devices are open in the called program to the same devices or files as in the calling program. For the reasons discussed above, care is needed when either the calling or called program accesses these logical devices using standard i/o calls. When both programs are not of type PRG, open files and devices can not be passed between the programs.DIAGNOSTICS
If an exec function call fails, for example because the file doesn't exist, it will return -1 as its value.BUGS
You can have problems, if the called program is half-loaded and a for example BAD MEDIA error occurs, cause it will damage the calling program. To prevent this verify the called program before you use one of these exec functions.<< Back to Top
exit (code) /* Apple // and UNIX functions */ _exit (code)DESCRIPTION
exit and _exit terminate the execution of a program and restart the operating system-type program that activated the program (that is, the SHELL or the Basic Intepreter). exit closes files opened for both standard and unbuffered i/o, calling fclose to close each file opened for standard i/o, and then calling close to close any files opened for unbuffered i/o. _exit doesn't close any standard or unbuffered i/o.DIAGNOSTICS
For a PRG program, code is its return code. The return code is set to 0 for a PRG program that terminates by either explicity or implicity returning from its main function. An exec file that starts a PRG program can test the program's return code and act accordingly. The return code of a BIN program is always 0, regardless of the value specified in the call to exit or _exit.<< Back to Top
#include <math.h> /* Apple // and UNIX functions */ double exp (x) double x; double log (x) double x; double log10 (x) double x; double pow (x, y) double x; double y; double sqrt (x) double x;DESCRIPTION
exp returns the exponential function of x. log returns the natural logarithm of x; log10 returns the base 10 logarithm. pow returns x ** y (x to the y-th power). sqrt returns the square root of x.DIAGNOSTICS
If a function can't perform the computation, it sets an error code in the global integer errno and returns an arbitrary value; otherwise it returns the computed value without modifying errno. The symbolic values wich a function can place in errno are EDOM, signifying that the argument was invalid, and ERANGE, meaning that the value of the function couldn't be computed. These codes are defined in the file errno.h. The following table lists, for each function, the error codes that can be returned, the function value for that error, and the meaning of the error. The symbolic values are defined in the file math.h. Funtion Error f(x) Meaning exp ERANGE HUGE x > LOGHUGE exp ERANGE 0.0 x < LOGTINY log EDOM -HUGE x <= 0 log10 EDOM -HUGE x <= 0 pow EDOM -HUGE x < 0, x = y = 0 pow ERANGE HUGE y * log (x) > LOGHUGE pow ERANGE 0.0 y * log (x) < LOGTINY sqrt EDOM 0.0 x < 0.0SEE ALSO
#include <math.h> /* Apple // and UNIX functions */ double fabs (x) double x; double floor (x) double x; double ceil (x) double x;DESCRIPTION
fabs returns the absolute value of x. floor returns the largest integer not greater than x. ceil returns the smallest integer not less than x.<< Back to Top
#include <stdio.h> /* Apple // and UNIX functions */ fclose (stream) FILE *stream; fflush (stream) FILE *stream;DESCRIPTION
fclose informs the system that the user's program has completed its buffered i/o operations on a device or file which it had previously opened (by calling fopen), fclose releases the control blocks and buffers which had allocated to device or file. Also, when a file is being closed, fclose writes any internally buffered information to the file. fclose is automatically called by exit fflush causes any buffered information for the named output stream to be written to that file. The stream remains open.DIAGNOSTICS
If fclose or fflush is successful, it returns 0 as its value. Otherwise they return -1, and an error code is set in the global integer errno.SEE ALSO
#include <stdio.h> /* Apple // and UNIX functions */ feof (stream) FILE *stream; ferror (stream) FILE *stream; clearerr (stream) FILE *stream; fileno (stream) FILE *stream;DESCRIPTION
feof returns non-zero when end-of-file is reached on the specified input stream, and zero otherwise. ferror returns non-zero when an error has occured on the specified stream, and zero otherwise. Unless cleared be clearerr, the error indication remains set until the stream is closed. clearerr resets an error indication on the specified stream. fileno returns the file descriptor associated with the stream. These functions are defined as macros in the file "stdio.h".SEE ALSO
fixnam (in_name, buf) /* Apple // ProDOS function */ char *in_name; char *buf;DESCRIPTION
fixnam converts the file name pointed at by in_name into a fully-qualified name consisting of the file name itself prefixed by the directories that must be passed through to get to the file. in_name can use "." to refer to the current directory, and ".." to refer to a parent directory.EXAMPLES
For example, suppose that the current directory being /work/source/input. The first call to fixnam that follows places /work/source/input/indvr.c in input. The second places /work/source/output/outdvr.c in outbuf. fixnam ("indevr.c", input) fixnam ("../output/outdvr.c", outbuf)DIAGNOSTICS
fixnam returns 0 if successful. If the input file name contains so many ".." references that the resultant directory is above the root directory, fixnam sets EINVAL in the global integer errno and returns -1 as its value.<< Back to Top
#include <stdio.h> /* Apple // and UNIX functions */ FILE *fopen (filename, mode) char *filename; char *mode; FILE *freopen (filename, mode, stream) char *filename; char *mode; FILE *stream; FILE *fopen (fd, mode) int fd; char *mode;DESCRIPTION
These functions prepare a device or disk file for access by the standard i/o functions; this is called "opening" the device or file. A file or device which has been opened by one of these functions is called a stream. fopen is the most basic of these functions: it simply opens the device or file specified by the filename parameter for access specified by the mode parameter. These parameters are described below. freopen substitutes the named device or file for the device or file which was previously associated with the specified stream. It closes the device or file which was originally associated with the stream. It is typically used to associate devices and files with the preopened stream stdin, stdout, and stderr. fdopen opens a device or file for unbuffered i/o which has been previously opened by one of the unbuffered open functions open and creat. The parameter filename is a pointer to a character string which is the name of the device or file to be opened. mode points to a character string which specifies how the user's program intends to access the stream. The choices are as follows: Mode Meaning r Open for reading only. If a file is opened, it is positioned at the first character in it. If the file or device does not exist, NULL is returned. w Open with writing only. If a file is opened which already exist, it is truncated to zero length. If the file does not exist, it is created. a Open for appending. The calling program is granted write-only access to the stream. The current file position is the character after the last character in the file. If the file does not exist, it is created. x Open for writing. The file must not previously exist. This option is not supported by UNIX. r+ Open for reding and writing. Same as "r", but the stream may also be written to. w+ Open for writing and reading. Same as "w", but the stream may also be read: different from "r+" in the creation of a new file and loss of any previous one. a+ Open for appending and reading. Same as "a", but the stream may also be read; different from "r+" in file positioning and creation. x+ Open for writing and reading. Same as "x", but the file can also be read. On system which don't keep track of the last character in a file (for example CP/M and Apple DOS), not all files can be correctly positioned when opened in append mode.DIAGNOSTICS
If the file or device is successfully opened, these functions return a pointer, called a "file pointer" to a structure of type FILE. This pointer is included in the list or parameters to buffered i/o functions, such as getc or putc, which the user's program calls to access the stream. freopen returns stream as its value. If the file or device cannot be opened, NULL is returned and an error code is set in the global integer errno.SEE ALSO
The following example demonstrates how fopen can be used in a program: #include <stdio.h> main (argc, argv) char *argv[]; { FILE *fopen(); FILE *fp; if ((fp = fopen (argv[1], argv[2])) == NULL) { printf ("You asked me to open %s", argv[1]); printf (" in the %s mode", argv[2]); printf (" but I can't !\n"); } else printf ("%s is open\n", argv[1]); ... } Here is a program which uses freopen: #include <stdio.h< main() { FILE *fp; fp = freopen ("dskfile", "w+", stdout); printf ("This message is going to dskfile\n"); } Here is a program which uses fdopen: #include <stdio.h> dopen_it (fd) int fd; /* value returned by call to open */ { FILE *fp; if ((fp = fdopen (fd, "r+")) == NULL) printf ("can't open file for r+\n"); else return (fp); }<< Back to Top
#include <math.h> /* Apple // and UNIX functions */ double frexp (value, eptr) double value; int *eptr; double ldexp (value, exp) double value; double modf (value, iptr) double value; double *iptr;DESCRIPTION
Given value, frexp computes integers x and n such that value = x * 2** x. x is returned as the value of frexp, and n is stored in the int field pointed at by eptr. ldexp returns the double quantity value * 2** exp. modf returns as its value the positive fractional part of value and stores the integer part in the double field pointed at by iptr.<< Back to Top
#include <stdio.h> /* Apple // and UNIX funcions */ int fseek (stream, offset, origin) FILE *stream; long offset; int origin; long ftell (stream) FILE *stream;DESCRIPTION
fseek sets the "current position" of a file which has been opened for unbuffered i/o. The current position is the byte location at which the next input or output will begin. stream is the stream identifier associated with the file, and was returned by fopen when the file was opened. offset and origin together specify the current position: the new position is at the signed distance offset bytes from the beginning, current position, or end of the file, depending on whether origin is 0, 1, or 2, respectively. offset can be positive or negative, to position after or before the specified origin, respectively, with the limitation that you can't seek before the beginning or the file. ftell returns the number of bytes from the beginning to the current position of the file associated with stream. For some operating systems (for example, CP/M and Apple DOS) a file may not be able to be correctly posioned relative to its end.DIAGNOSTICS
If fseek is successful, it will return zero. Otherwise it will return -1 for improper seeks. In this case, an error code is set in the global integer errno.SEE ALSO
The following routine is equivalent to opening a file in "a+" mode: a_plus (filename) char *filename; { FILE *fp; FILE *fopen (); if ((fp = fopen (filename, "r+")) == NULL) fp = fopen (filename, "w+"); fseek (fp, 0L,2); /* position 1 byte past last character */ } To set the current position back 5 characters before the present current position, the following call can be used: fseek (fp, -5L, 1);<< Back to Top
char *getenv (name) /* Apple // ProDOS SHELL function */ char *name;DESCRIPTION
getenv, returns a pointer to the character string associated with the environment variable name, or 0 if the variable isn't in the environment. The character string is in a dynamically-alocated buffer; this buffer will be released when the next call is made to getenv. getenv can be called by PRG programs: that is, by programs that can only be run in the SHELL environment. It can also be called by BIN programs that are running in the SHELL environment. However, unlike BIN programs, getenv cannot be used outside of the SHELL environment, thus, you should be wary of calling getenv in a BIN program.<< Back to Top
#include <sgtty.h> /* Apple // and UNIX functions ioctl (fd, cmd, stty) FILE *fd, char *cmd; struct sgttyb *stty; isatty (fd)DESCRIPTION
ioctl sets and determines the mode of the console. The parameter fd is a file decriptor associated with the console. On UNIX, this parameter defines the file decriptor associated with the device to which the ioctl call applies. The parameter cmd defines the action to be performed by ioctl. It can have these values: Value Meaning TIOCGETP Fetch the console parameters and store them in the structure pointed at by stty. TIOCSETP Set the console parameters according to the structure pointed at by stty. TIOCSETN Equivalent to TIOCSETP. The argument stty points to a structure named sgttyb that contains the following fields: int sg_flags; char sg_erase; char sg_kill; The order of these fields is system-dependent. The sg_flags is supported be all systems, while the other fields are not supported be some systems. Value Meaning of sg-flags RAW Set raw mode (turns off the other options). By default, raw mode is disabled. CBREAK Return each character as soon as typed. By default, CREAK is disabled. ECHO Echo input characters to the display. By default echo mode is enabled. CRMOD Map CR to LF on input; convert LF to CR-LF on output. By default crmod is enabled. More than one flag can specified in a single call to ioctl; the values are simply 'or'ed together. If the RAW mode option is selected, none of the other options have any effect. isatty returns non-zero if the file descriptor fd is associated with the console, and zero otherwise.<< Back to Top
#include <ctype.h> /* Apple // and UNIX functions */ isalpha (c) char c; ...DESCRIPTION
These macros classify ASCII-coded integer values by table lookup, returning nonzero if the integer is in the catagory, zero otherwise. isascii is defined for all integer values. The others are defined only when isascii is true and on the single non-ASCII value EOF (-1). isascii c is an ASCII character, code less then 0x100 isalpha c is a letter isupper c is an upper case letter islower c is a lower case letter isdigit c is a digit isalnum c is an alphanumeric character isspace c is a space, tab, carriage return, newline or formfeed ispunct c is a punctuation character isprint c is a printing character, valued 0x20 (space) through 0x7e (tilde) iscntrl c is a delete character (0xFF) or ordinary control character (value less than 0x20)<< Back to Top
long lseek (fd, offset, origin) /* Apple // and UNIX functions */ int fd; long offset; int origin;DESCRIPTION
lseek sets the current prosition of a file which has been opened for unbuffered i/o. This position determines where the next character will be read or written. fd is the file descriptor associated with the file. The current position is set to the location specified by the offset and origin parameters, as follows: * If origin is 0, the current position is set to offset bytes from the beginning of the file. * If origin is 1, the current position is set to the current position plus offset. * If origin is 2, the current position is set to the end of the file plus offset. The offset can be positive or negative, to position after or before the specified origin, respectively. Positioning of a file relative to its end (that is, calling lseek with origin set to 2) cannot always be correctly done on all systems (for example, CP/M and Apple DOS).DIAGNOSTICS
If lseek is successful, it will return the new position in the file (in bytes from the beginning of the file). Otherwise, it will return -1 as its value and set an error code in the global integer errno. errno is set to EBADF if the file descriptor is invalid. It will be set to EINVAL if the offset parameter is invalid or if the requested position if before the beginning of the file.SEE ALSO
1. To seek to the beginning of a file: lseek (fd, 0L, 0); lseek will return the value zero (0) since the current position in the file is character (or byte) number zero. 2. To seek to the character following the last character in the file: pos = lseek (fd, 0L, 2); The variable pos will contain the current position of the end of the file, plus one. 3. To seek backwards five bytes: lseek (fd, -5L, 1); The third parameter, 1, sets the origin at the current position in the file, The offset is -5. The new position will be the origin plus the offset. So the effect of this call is to move backward a total of five characters. 4. To skip characters when reading in a file: read (fd, buf, count); lseek (fd, 5L, 1); read (fd, buf, count);<< Back to Top
char *malloc (size) /* Apple // and UNIX functions */ unsigned size; char *calloc (nelem, elemsize) unsigned nelem; unsigned elemsize; char *realloc (ptr, size) char *ptr; unsigned size; free (ptr) char *ptr;DESCRIPTION
These functions are used to allocate memory from the "heap", that is, the section of memory for dynamic storage allocation. malloc allocates a block of size bytes, and returns a pointer to it. calloc allocates a single block of memory which can contain nelem elements, each elemsize bytes big, and returns a pointer to the beginning of the block. Thus, the allocated block will contain (nelem * elemsize) bytes. The block is initialized to zeroes. realloc changes the size of the block pointed at by ptr to size bytes, returning a pointer to the block. If necessary, a new block will be allocated of the requested size, and the data from the original block moved into it. The block passed to realloc can have been freed, provided that no intervening calls to calloc, malloc, or realloc have been made. free deallocates a block of memory which was previously allocated by malloc, calloc, or realloc, this space is the available for reallocation. The argument ptr to free is a pointer to the block. malloc and free maintain a circular list of free blocks. When called, malloc searches this list beginning with the last block freed or allocated coalescing adjacent free blocks as it searches. It allocates a buffer from the list large enough free block that it encounters. If this search fails, it calls sbrk to get more memory for use by these functions.DIAGNOSTICS
malloc, calloc and realloc return a null pointer (0) if there is no available block of memory. free returns -1 if it's passed an invalid pointer.<< Back to Top
mkdir (name) /* Apple // ProDOS and UNIX function */ char *name; mkdir dir [dir ...] /* Apple // ProDOS SHELL utility */DESCRIPTION
mkdir creates the directory named name. name can optionally specify, using the standard ProDOS syntax, the complete or partial sequence of directories that must be passed through to get to the directory that is to be the parent of the directory.DIAGNOSTICS
If no error occurs, mkdir returns 0 as its value. If an error occurs, it sets a code in the global int errno and returns -1 as its value.<< Back to Top
char *mktemp (template) /* Apple // function */ char *template;DESCRIPTION
mktemp replaces the character string pointed at by template with the name of a non-existent file, and returns as its value a pointer to the string. The string pointed at by template should look like a file name whose last few characters are Xs with an optional imbedded period. mktemp repaces the Xs with the letter followed by digits. The digits are set to the address of the programs _main function. The letter will be between 'A' and 'Z', and will be chosen such that the resulting character string isn't the name of an existsting file.DIAGNOSTICS
For a given character string, mktemp will try to convert the string into one of 26 file names. If all of these files exist, mktemp will repace the first character pointed at by template with a null character.SEE ALSO
The following program calls mktemp to get a chracter string that it can use as a file name. If the program's _main function begins at decimal address 1234, the generated name will be on of the strings abcA001.234, abcB001.234, ... abcZ001.234. If all the strings that mktemp considers are names of existing files, mktemp will replace the first character of the string passed to it, a in this case, with 0. #include <stdio.h> main() { char *fname, *mktemp(); FILE *fp, fopen(); fname = mktemp ("abcXXX.XXX") == 0) if (!*fname) { printf ("mktemp failed"); exit (-1); } else fp = fopen (fname, "w"); ... }<< Back to Top
movmem (src, dest, length) /* Apple // functions */ char *src; char *dest; int length; setmem (area, length, value) char *area; int length; int value; swapmem (s1, s2, length) char *s1; char *s2; int length;DESCRIPTION
movmem copies length characters from the block of memory pointed at by src to that pointed at by dest. movmem copies in such a way that the resulting block of characters at dest equals the original block at src. setmem sets the character value in each byte of the block of memory which begins at area and continues for length bytes. swapmem swaps the block of memory pointed at by s1 and s2. The blocks are length bytes long.<< Back to Top
#include <fcntl.h> /* Apple // and UNIX function */ open (name, mode, param3) char *name;DESCRIPTION
open opens a device or file for unbuffered i/o. It returns an integer value called a file descriptor wich is used to identify the file or device in subsequent calls to unbuffered i/o functions. name is a pointer to a character string wich is the name of the device or file to be opened. mode specifies how the user's program intends to access the file. The choices are as follows: Mode Meaning O_RDONLY read only O_WRONLY write only O_RDWR read and write O_CREAT creat file, then open it O_TRUNC truncate file, the open it O_EXCL cause open to fail if file already exists; used with O_CREAT O_APPEND positions file for appending data These open modes are integer constants defined in the file "fcntl.h". Altough the true values of these constants can be used in a given call to open, use of the symbolic names ensures compatibility with UNIX and other systems. The calling program must specify the type of access desired by including exactly one of O_RDONLY, O_WRONLY, and O_RDWR in the mode parameter. The three remaining values are optional. They may be included by adding them to the mode parameter, as in the examples below. By default the open will fail if the file to be opened does not exist. To cause the file to be created when it does not already exist, specify the O_CREAT option. If O_EXCL is given in addition to O_CREAT, the open will fail if the file already exists; otherwise, the file is created. If the O_TRUNC option is pecified, the file will be truncated so that nothing is in it. The truncation is performed by simply erasing the file, if it exists, and then creating it. So it is not an error to use this option when the file does not exist. Note that when O_TRUNC is used, O_CREAT is not needed. If O_APPEND is specified, the current position for the file (that is, the position at which the next data transfer begin) is set to the end of the file. For systems which don't keep track of the last character written to a file (for example, CP/M and Apple DOS), this positioning cannot always be correctly done. Also this option is not supported by Unix. When open is used to create a file under ProDOS, param 3 is the file's access mode. The meanings of the param3 bits, where bit 0 is the least significant bit, bit 15 is the most significant: Bit number Meaning 0 File can be read 1 File can be written 2-4 Reserved 5 File modified since last backup 6 File can be renamed 7 File can be deleted 8-15 Unused Thus, to create a file on which all types of operations are permitted, set its mode parameter to 0xC3. When open is used to creat a file under DOS 3.3, param3 is the file's type: Param3,hex File type 00 Text 01 Integer basic 02 Applesoft basic 04 Binary 08 Relocatable 10 S-type file 20 A-type file 40 B-type file If open does not detect an error, it returns an integer called a "file descriptor". This value is used to identify the open file during unbuffered i/o operations. The file descriptor is very different from the file pointer which is returned by fopen for use with buffered i/o functions.SEE ALSO
If open encounters an error, it returns -1 and sets the global integer errno to a symbolic value which identifies the error.EXAMPLES
1. To open the file testfile for read-only access: fd = open ("testfile", O_RDONLY, 0); The third parameter of open is not important in this case, since open won't create the file. If testfile does not exist open will just return -1 and set errno to ENOENT. 2. To open the file sub1 on ProDOS in read-write mode, allowing it to be deleted, read, written and renamed: fd = open ("sub1", O_RDWR + O_CREAT, 0xC3); If the file does not exist, it will be created and then opened. 3. The following program opens a ProDOS file whose name is given on the command line. The file must not already exist. main (argc, argv) char **argv; { int fd; fd = open (*++argv, O_WRONLY + O_CREAT + O_EXCL, 0xC3); if (fd == -1) { if (errno == EEXIST) printf ("file already exist\n"); else if (errno == ENOENT) printf ("unable to open file\n"); else printf ("open error\n"); } ... }<< Back to Top
page1() /* Apple // functions */ page2()DESCRIPTION
page1 and page2 enable the primary and secondary pages, respectively.SEE ALSO
int perror (s) /* Apple // and UNIX functions */ char *s; #include <errno.h> extern int errno;DESCRIPTION
When a library function detects an error, it will generally set an error code, which is a positive integer, in the global integer errno and return an appropriate, function-dependent value. The extern declaration of errno is in "errno.h". When an error occurs, perror can be called to write a message describing the error on the standard error device. The message consists of the following: * s, the string pointed at by the argument to perror, * a colon and a blank, * the sys_errlist message corresponding to the current value of errno, * a newline chracter.DIAGNOSTICS
perror returns 0 if errno contains a valid value, otherwise, it returns -1 without printing a message.<< Back to Top
plotchar (c, x, y) /* Apple // function */ int c, x, y;DESCRIPTION
plotchar displays the printable char c on the primary Hi-res graphic page, at the location having coordinates (x, y).SEE ALSO
plot (x, y) /* Apple // functions */ bplot (x, y) gplot (x, y) rplot (x, y) vplot (x, y)DESCRIPTION
These functions plot a point on the primary Hi-res page, at the location (x, y). They differ in the color of the point: Function Color drw white bdrw blue gdrw green rdrw red vdrw violetSEE ALSO
#include <stdio.h> /* Apple // and UNIX funcions */ printf (fmp [,arg] ... ) char *fmt; fprintf (stream, fmp [,arg] ... ) FILE *stream; char *fmt; sprintf (buffer, fmp [,arg] ... ) char *buffer; char *fmt; format (func, fmt, argptr) int (*func)(); char *fmt; unsigned *argptr;DESCRIPTION
These functions convert and format their arguments (arg or argptr) according to the format specification fmt. They differ in what they do with the formatted result: printf outputs the result to the standard output stream, stdout. fprintf outputs the result to the stream specified in its first argument, stream. sprintf palaces the result in the buffer pointed at by its first argument, buffer, and terminates the result with the null character, ' '. format calls the function func with each character of the result. In fact, printf, fprintf, and sprintf call format with each character that they generate. These functions are in both c.lib and m.lib, the difference being that the c.lib version don't support floating point conversions. Hence, if floating point conversion is required, the m.lib version must be used. If floating point conversion isn't required, either version can be used. To use m.lib's version, m.lib must be specified before c.lib at the time the program is linked. The character string pointed at by the fmt parameter, which directs the print functions, contains two types of items: Ordinary characters, which are simply output, and conversion specifications, each of which causes the conversion and ouput of the next successive arg. A conversion specification begins with the character % and continues with: * An optional minus sign (-) which specifies left adjustment of the converted value in the output field. * An optional digit string specifying the 'field width' for the conversion. If the converted value has fewer characters than this, enough blank characters will be output to make the total number of characters output equals the field width. If the converted value has more characters than the field width, it will be truncated. The blanks are output before or after the value, depending on the presence or absence of the left adjustment indicator. If the field width digits have a leading 0, 0 is used as a pad character rather than blank. * A optional period, '.', which seperates the field width from the following field. * An optional digit string specifying a precision, for floating point conversions, this specifies the number of digits to appear after the decimal point; for character string conversions, this specifies the maximum number of characters to be printed from a string. * Optionally, the character L, which specifies that a conversion which normally is performed on an int is to be performed on a long. This applies to the d, o, and x conversions. * A character which specifies the type of conversion to be performed. A field width or precision may be * instead of a number, specifying that the next available arg, which must be an int, supplies the field width or precision: The conversion character are: d, o, x The int in the corresponding arg is converted to decimal, octal, or hexadeciaml notation, respectively, and output. u The unsigned integer arg is converted to decimal notation. c The character arg is output. Null characters are ignored. s The characters in the string pointed at by arg are output until a null character or the number of characters indicates by the precision is reached. If the precision is zero or missing, all characters in the string, up to the terminating null, are output. f The float or double arg is converted to decimal notation in the style '[-]ddd.ddd'. The number of d's after the decimal point is equal to the precision given in the conversion specification. If the precision is missing, it defaults to six digits. If the precision is explicitly 0, the decimal point is also not printed. e The float or double arg is converted to the style '[-]d.ddde[-]dd', where there is one digit before the decimal point and the number after is equal to the precision given. If the precision is missing, it defaults to six digits. g The float or double arg is printed in style d, f, or e, whichever gives full precision in minimum space. % Output a %. No argument is converted.DIAGNOSTICS
All functions return -1 as their value, if the conversion fails.EXAMPLES
1. The following program fragment: char *name; float amt; printf ("Your total, %s, is $%f\n", name, amt); will print a message of the form Your total, Alfred, is $3.120000 Since the precision of the %f conversion wasn't specified, it defaulted to six digits to the rigth of the decimal point. 2. This example modifies example 1 so that the field width for the %s conversion is three characters, and the field width and precision of the %f conversion are 10 and 2, respectively. The %f conversion will also use 0 as a pad character, rather than blank. char *name; float amt; printf "Your total ,%3s, is $%10.2f\n", name, amt); 4. This example demonstrates how to use the format function by listing printf, which calls format with each character that it generates: printf (fmt, args) char *fmt; unsigned args; { extern int putchar (); format (putchar, fmt, &args); }<< Back to Top
#include <stdio.h> /* Apple // and UNIX funcions */ puts (s) char *s; fputs (s, stream) char *s; FILE *stream;DESCRIPTION
puts writes the null-terminated string s to the standard output stream, stdout, and then an end-of-line sequence. It returns a non-negative value if no error occur. fputs copies the null-terminated string s to the specified output stream. It returns 0 if no error occur. Both functions write to the stream using aputc on an Apple //. Thus, they can only be used to write text. Note that puts and fputs differ in this way: On encountering a newline character, puts writes an end-of-line sequence and fputs doesn't.DIAGNOSTICS
If an error occur, these functions return EOF (-1) and set an error code in the global integer errno.SEE ALSO
qsort (array, number, width, func) /* Apple // and UNIX function */ char *array; unsigned number; unsigned width; int (*func)();DESCRIPTION
qsort sorts an array of elements using Hoare's Quicksort algorithm. array is a pointer to the array to be sorted. number is the number of records to be sorted. width is the size in bytes of each array element. func is a pointer for a comparision of two array elements. func is passed pointers to the two elements being compared. It must return an integer less than, equal to, or greater than zero, depending on whether the first argument is to be considered less than, equal to, or greater than the second.EXAMPLES
The Aztec linker, LN, can generate a file of text containing a symbol table for a program. Each line of the file contains an address at which a symbol is located, followed by a space, followed by the symbol name. The following program reads such a symbol table from the standard input, sorts it by address, and writes it to standard output. #include <stdio.h> #define LINESIZE 16 #define MAXLINES 2000 char *lines[MAXLINES]; char *malloc; main() { int i; int numlines; int cmp(); char buf[LINESIZE]; for (numlines=0; numlines<MAXLINES; ++numlines) { if (gets (buf) == NULL) break; lines[numlines] = malloc (LINESIZE); strcpy (lines[numlines], buf); } qsort (lines, numlines, 2, cmp); for (i=0; i<numlines; ++i) printf ("%s\n", lines[i]); } cmp (a, b) char **a, **b; { return strcmp (*a, *b); }<< Back to Top
double ran () /* Apple // and UNIX function */ double randl (x) double x;DESCRIPTION
ran returns as its value a random number between 0.0 and 1.0 . randl returns as its value a random number beteen 0.0 and x .<< Back to Top
read (fd, buf, bufsize) /* Apple // and UNIX function */ int fd; char *buf; int bufsize;DESCRIPTION
read reads characters from a device or disk file which has been previously opened by a call to open or creat. In most cases, the information is read directly into the caller's buffer buf. fd is the file descriptor which was returned to the caller when the device or file was opened. buf is a pointer to the buffer into which the information is to be placed. bufsize is the number of characters to be transferred.DIAGNOSTICS
If read is successful, it returns as its value the number of characters transferred. If the returned value is zero, then end-of-file has been reached, immediately, with no bytes read. If the operation isn't successful, read returns -1 and places a code in the global integer errno.SEE ALSO
rename (oldname, newname) /* Apple // function */ char *oldname; char *newname;DESCRIPTION
rename changes the name of a file (and volume or directory under ProDOS). oldname is a pointer to a character string containing the old file name, and newname is a pointer to a character string containing to new name of the file.DIAGNOSTICS
If successful, rename returns 0 as its value, if not it returns -1. If a file with the new name already exist, rename sets E_EXIST in the global integer errno and returns -1 as its value without renaming the file.SEE ALSO
void *sbrk (size) /* Apple // functions */ brk (ptr) void *ptr; rsvstk (size)DESCRIPTION
sbrk and brk provide an elementary means of allocating and deallocating space from the heap. More sophisticated buffer management schemes can be built using these functions; for example, the standard functions malloc, free, etc call sbrk to get heap space, wich they then manage for the calling functions. sbrk increments a pointer, called the 'heap pointer', by size bytes, and, if successful, returns the value that the pointer had on entry. Initially, the heap pointer points to the base of the heap. size is a signed int; if it is negative, the heap pointer is decremented by the specified amount and the value that it had on entry is returned. Thus, you must be careful when calling sbrk: if you try to pass it a value greater than 32K, sbrk will interpret it as a negative number, and decrement the heap pointer instead of incrementing it. brk sets the heap pointer tp ptr, and returns 0 if successful. rsvstk sets the heap-stack boundary size bytes below the current tock of stack, thus changing the amount of space allocated to the stack and heap.EXAMPLES
If an sbrk or brk request would make the heap space pointer go past the end of the heap, the function will return -1 as its value, without modifying the heap space pointer.SEE ALSO
#include <stdio.h> /* Apple // and UNIX functions */ scanf (format [,pointer] ... ) char *format; fscanf (stream, format [,pointer] ... ) FILE *stream; char *format; sscanf (buffer, format [,pointer] ... ) char *buffer; char *format;DESCRIPTION
These functions convert a string or stream of text characters, as directed by the control string pointed at by the format parameter, and place the results in the field pointed at by the pointer parameters. scanf gets text from the standard input stream, stdin. fscanf gets text from the stream specified in its first parameter, stream. sscanf gets text from the buffer pointed at by its first parameter, buffer. These functions are in both c.lib and m.lib, the difference being that the c.lib version don't support floating point conversions. Hence, if floating point conversion is required, the m.lib version must be used. If floating point conversion isn't required, either version can be used. To use m.lib's version, m.lib must be specified before c.lib at the time the program is linked. The control string pointed at by format contains the following control items: * Conversion specifications. * 'White space' characters (space, tab, newline). * Ordinary characters; that is, characters which aren't part of a conversion specification and which aren't white space. A scan function works its way through a control string, trying to match each control item to a portion of the input stream or buffer. During the matching process, it fetches characters one at a time from the input. When a character is fetched which isn't appropriate for the control item being matched, the scan function pushes it back into the input stream or buffer and finishes processing the current control item. This is pushing back frequently gives unexpected results when a stream is being accessed by other i/o functions, such as getc, as well as the scan function. The examples below demonstrates some of the problems that can occur. The scan function terminates when it first fails to match a control item or when the end of the input stream or buffer is reached. It returns as its value the number of matched conversion specifications, or EOF (-1) if the end of the input stream or buffer was reached. Matching 'white space' characters: When a white space character is encountered in the control string, the scan function fetches input characters until the first non-white-space character is read. The non-white-space character is pushed back into the input and the scan function proceeds to the next item in the control string. Matching ordinary characters: If an ordinary character is encountered in the control string, the scan function fetches the next input character, If it matches the ordinary character, the scan function simply proceeds to the next control string item. If it doesn't match, the scan function terminates. Matching conversion specification: When a conversion specification is encountered in the control string, the scan function first skips leading white space on the input stream or buffer. It then fetches characters from the stream or buffer until encountering one that is inappropriate for the conversion specification. This character is pushed back into the input. If the conversion specification didn't request assignment suppression (discussed below), the character string which was read is converted to the format specified by the conversion specification, the result is placed in the location pointed at by the current pointer argument, and the next pointer argument becomes current. The scan function then proceeds to the next control string item. If assignment suppression was requested by the conversion specification, the scan function simply ignores the fetched input characters and proceeds to the next control item. Details of input conversion: A conversion specification consists of: * The character '%', which tells the scan function that it has encountered a conversion specification. * Optionally, the assignment suppression character '*'. * Optionally, a field width; that is, a number specifying the maximum number of characters to be fetched for the conversion. * A conversion character, specifying the type of conversion to be performed. If the assignment suppression character is present in a conversion specification, the scan function will fetch characters as if it was going to perform the conversion, ignore them, and proceed to the next control string item. The following conversion characters are supported: % A single '%' is exepted in the input; no assignment is done. d A decimal integer is expected; the input digit string is converted to binary and the result placed in the int field pointed at by the current pointer argument. o An octal integer is expected; the corresponding pointer should point to an int field in which the converted result will be placed. x A hexadeciaml integer is expected; the converted value will be placed in the int field pointed at by the current pointer argument. s A sequence of characters delimited by white space characters is expected; they, plus a terminating null character, are placed in the character string pointed at by the current pointer argument. c A character is expected. It is placed in the char field pointed at by the current pointer. The normal skip over leading white space is not done; to read s single char after skipping leading white space, use '%1s'. The field width parameter is ignored, so this conversion can be used only to read a single character. [ A sequence of characters, optionally preceded by white space but not terminated by white space is expected. The input characters, plus a terminating null character, are placed in the character string pointed at by the current pointer argument. The left bracket is followed by: * Optionally, a '^' or '~' character. * A set of characters. * A rigth bracket, ']'. If the first character in the set isn't ^ or ~, the set specifies characters which are allowed; characters are fetched from the input until one is read which isn't in the set. If the first character in the set is ^ or ~, the set specifies characters which aren't allowed; characters are fetched from the input until one is read which is in the set. e A floating point number is expected. The input string is converted to floating point format and stored in the float field pointed at by the current pointer argument. The input format for floating point numbers consists of an optionally signed string of digits, possibly containing a decimal point, optionally followed by an exponent filed consisting of an E or e followed by an optionally signed digit.EXAMPLES
1. In this program fragment, scanf is used to read values for the int x, the float y, and a character string into the char array z: int x; float y; char z[50]; scanf ("%d%f%s", &x, &y, z); The input line 32 75.36e-1 rufus will assign 32 to x, 7.536 to y, and "rufus" to z. scanf will return 3 as its value, signifying that three conversion specifications wree matched. The three input strings must be delimited by 'white space' characters; that is, by blank, tab, and newline characters. Thus, the three values could also be entered on seperate lines, with the white space character newline used to seperate the values. 2. This example discusses the problem which may arise when mixing scanf and other input operations on the same stream. In the previous example, the character string entered for the third variable, z, must also be delimited by white space characters. In particular, it must be terminated by a space, tab, or newline character. The first such character read by scanf while getting characters for z will be 'pushed back' into the standard input stream. When another read of stdin is made later, the first character returned will be the white space character which was pushed back. This 'pushing back' can lead to unexpected results for programs that read stdin with functions in addition to scanf. Suppose that the program in the first example wants ot issue a gets call to read a line from stdin, following the scanf to stdin. scanf will have left on the input stream the white space character which terminated the third value read by scanf. If this character is a newline, then gets will return a null string, because the first character it reads is the pushed back newline, the character which terminates gets. This is most likely not what the program had in mind when it called gets. It is usally unadvisable to mix scanf and other input operations on a single stream. 3. This example discusses the behavior of scanf when there are white space characters in the control string. The control string in the first example was "%d%f%s". It doesn't contain any white space, since scanf, when attempting to match a conversion specification, will skip leading white space. There's no harm in having white space before the %d, between the %d and %f, or between the %f and %s. However, placing a white space character after the %s can have unexpected results. In this case, scanf will, after having read a character string for z, keep reading characters until a non-white-space character is read. This forces the operator to enter, after the three values for x, y, and z, a non-white space character; until this is done, scanf will not terminate. The programmer might place a newline character at the end of the control string, mistakenly thinking that this will circumvent the problem discussed in example 2. One migth think that scanf will treat the newline as it would an ordinary character in the control string; that is, that scanf will search for, and remove, the terminating newline character from the input stream after it has matched the z variable. However, this is incorrect, and should be remembered as a common misinterpretation. 4. scanf only reads input it can match. If, for the first example, the input had been 32 rufus 75.36e-1 scanf would have returned with value 1, signifying that only one conversion specification had been matched. x would have the value 32, y and z would be unchanged. All characters in the input stream following the 32 would still be in the input stream, waiting to be read. 5. One common problem in using scanf involves mismatching conversion specifications and their corresponding arguments. If the first example had declared y to be a double, then one of the following statements would have been required: scanf ("%d%1f%s", &x, &y, z); or scanf ("%d%F%s", &x, &y, z); to tell scanf that the floating point variable was a double rather than a float. 6. Another common problem in using scanf involves paasing scanf the value of a variable rather than its address. The following call to scanf is incorrect: int x; float y; char z[50]; scanf ("%d%f%s", x, y, z); scanf has been passed the value containing in x and y, and the address of z, but it requires the address of all three variables. The "address of" operator, &, is requiered as a prefix to x and y. Since z is an array, its address is automatically passed to scanf, so z doesn't need the & prefix, although it won't hurt if it is given. 7. Consider the following program fragment: int x; float y; char z[50]; scanf ("%2d%f%*d%[1234567890]", &x, &y, z); When given the following input: 12345 678 90a65 scanf will assign 12 to x, 345.0 to y, skip 678, and place the string '90' in z. The next call to getchar will return 'a' and that IS a problem.<< Back to Top
scr_beep() /* Apple // functions */ scr_bs() scr_tab() scr_lf() scr_cursup() scr_cursrt() scr_cr() scr_clear() scr_home() scr_eol() scr_linsert() scr_ldelete() scr_cinsert() scr_cdelete() scr_curs (lin, col) int lin, col;DESCRIPTION
These functions can be called by command programs to manipulate screens of text. For example, there are functions to clear the screen, position the cursor, and insert and delete characters and lines. These functions can be used in conjunction with the normal standard i/o und unbuffered i/o functions to diplay characters on the console. scr_beep rings the keyboard bell. scr_bs moves the cursor back one character space, without modifying the character that was backspaced over. scr_tab moves the cursor right one tab stop. scr_lf moves the cursor down on line, scolling if at the bottom of the screen. scr_cursup moves the cursor up without changing its column location. scr_cursrt moves the cursor right one character space, without modifying the character that was spaced over. scr_cr causes a carriage return. scr_clear clears the screen and homes the cursor. scr_home homes the cursor to the upper left hand corner of the screen. scr_eol erases the line at which the cursor is located, from the current cursor prosition to the end of the line. scr_linsert inserts a blank line at the cursor location, moving the lines below the cursor down one line. scr_ldelete deletes the line at the cursor location, moving the lines blow the cursor up one line and placing a blank line at the bottom of the screen. scr_cinsert inserts a space at the cursor location, shifting right one character the characters in the line wich are on the right of the cursor. scr_cdelete deletes the character at the cursor location, shifting left one character the characters in the line which are on the right of the cursor. scr_curs moves the cursor to the line and column specified by the lin and col parameters, respectively.<< Back to Top
#include <setjmp.h> /* Apple // and UNIX funcion */ setjmp (env) jmp_buf env; longjmp (env, val) jmp_buf env; int val;DESCRIPTION
These functions are useful for dealing with errors encountered by the low-level funcions of a program. setjmp saves its stack environment in the memory block pointed at by env and return 0 as its value. longjmp causes execution to continue as if the last call to setjmp was just terminating with value val. val cannot be zero. The parameter env is a pointer to a block of memory which can be used be setjmp and longjmp. The block must be defined using the typedef jmp_buf. WARNING: longjmp must not be called without env having been initialized by a call to setjmp. It also must not be called if the function that called setjmp has since returned.EXAMPLES
In the following example, the function getall builds a record pertaining to a customer and returns the pointer to the record if no errors were encountered and 0 otherwise. getall calls other functions which actually build the record. These functions in turn call other functions, which in turn ... getall defines, by calling setjmp, a point to which these functions can branch if an unrecoverable error occurs. The low level functions abort by calling longjmp with a non-zero value. If a low level function aborts, execution continues in getall as if its call to setjmp had just terminated with a non-zero value. Thus by testing the value returned by setjmp getall can determine whether setjmp is terminating because a low level function aborted. #include <setjmp.h> jmp_buf envbuf; /* environment saved here by setjmp */ getall (ptr) char *ptr; /* ptr to record to be build */ { if (setbuf (envbuf)) /* a low level function has aborted */ return 0; getfield1 (ptr); getfield2 (ptr); getfield3 (ptr); return ptr; } Here's one of the low level functions: getsubfld21 (ptr) char *ptr; { ... if (error) longjmp (envbuf, -1); ... }<< Back to Top
#include <math.h> /* Apple // and UNIX functions */ double sinh (x) double x; double cosh (x) double x; double tanh (x) double x;DESCRIPTION
These functions compute the hyperbolic of their arguments.DIAGNOSTICS
If the absolute value of the argument to sinh or cosh is greater than 348.6, the function sets the symbolic value ERANGE in the global integer errno and returns a huge value. This code is defined in the file "errno.h". If no error occurs, the function returns the computed value without modifying errno.SEE ALSO
char *strcat (s1, s2) /* Apple // and UNIX functions */ char *s1; char *s2; char *strncat (s1, s2, n) char *s1; char *s2; int n; char *strcmp (s1, s2) char *s1; char *s2; char *strncmp (s1, s2, n) char *s1; char *s2; int n; char *strcpy (s1, s2) char *s1; char *s2; char *strncpy (s1, s2, n) char *s1; char *s2; int n; int strlen (s) char *s; char *index (s, c) char *s; char c; char *rindex (s, c); char *s; char c;DESCRIPTION
These functions operate on null-terminated strings, as follows: strcat appends a copy of string s2 to string s1. strncat copies at most n characters. Both terminate the resulting string with the null character ('\0') and return a pointer to the first character of the resulting string. strcmp compares its two arguments and returns an integer greater than, equal, of less than zero, according as s1 is lexicographically greater than, equal to, or less then s2. strncmp makes the same comparison but looks at n characters at most. strcpy copies string s2 to s1 stopping after the null character has been moved. strncpy copies exactly n characters: if s2 contains less than n characters, null characters will be appended to the resulting string until n characters have been moved; if s2 contains n or more characters, only the first n will be moved, and the rsulting string will be null terminated. strlen returns the number of characters which occur in s up to the first null character. index returns a pointer to the first occurance of the character c in string s, or zero if c isn't in the string. rindex returns a pointer to the last occurance of the character c in string s, or zero if c isn't in the string.<< Back to Top
#include <sysfunc.h> /* Apple // ProDOS function */ _system (func) int func; DESCRIPTIONDIAGNOSTICS
_system issues the function call whose number is func, using as the parameter area the globally-accessible character array named _sys_parm.
_system returns as its value the value that ProDOS returned in register A.<< Back to Top
text() /* Apple // functions */ hgr() fscreen() mscreen()DESCRIPTION
text sets the screen in text mode. hgr sets the screen in Hi-res graphic mode. Unlike the Color functions, hgr doesn't clear the screen. Note, that the 80-column-card mode is better stopped before you use this function, otherwise you will get the double-hires page. fscreen gives a full screen to work with in the graphics mode. This means that you have a 280 by 192 matrix to work with. mscreen sets the screen in mixed text and Hi-res modes. In this mode, the four lines at the bottom of the screen are used to display text, and the remainder of the screen (a 280 by 160 matrix) is in Hi-res mode.SEE ALSO
long time (tloc) /* Apple // and UNIX functions */ long *tloc; get_time (buf) struct tm *buf; char *ctime (clock) long *clock; #include <time.h> struct tm *localtime (clock) long *clock; struct tm *gmtime (clock) long *clock; char *asctime (tm) struct tm *tm;DESCRIPTION
time and get_time return the date and time, which they get from the operating system. The other functions convert the date and time, which are passed as arguments, to another format. time returns the current date and time packed into a long int. If its argument tloc is a non-null, the return value is also stored in the field pointed at by the argument. The format of the value returned by time is described below. get_time returns the current date and time in the buffer pointed at by its argument, buf. The format of this buffer is described below. ctime, localtime, and gmtime convert a date and time pointed at by their argument, which is in a format such as returned by time to another format: ctime converts the time to a 26-chracter ASCII string of the form Mon Apr 30 10:04:52 1984\n\0 localtime and gmtime unpack the date and time into a structure and return a pointer to it. The structure, named tm, is described below and defined in the header file "time.h". asctime converts a date and time pointed at by its argument, which is in a structure such as returned by localtime and gmtime, to a 26-character ASCII string in the same form as returned by ctime. The long int returned by time and passed to ctime, localtime, and gmtime has the following form (bit 0 is the least significant bit in the field, bit 31 the most significant): Bits Meaning 00-07 minute 08-15 hour 16-20 day 21-24 month 25-31 year The structure returned by get_time, localtime and gmtime, and passed to asctime, has the following format: struct tm { short tm_sec; /* seconds */ short tm_min; /* minutes */ short tm_hour; /* hours */ short tm_mday; /* day of the month */ short tm_mon; /* month */ short tm_year; /* year since 1900 */ short tm_wday; /* day of the week (0 = Sunday) */ short tm_yday; /* day of year */ short tm_isdst; /* not used */ short tm_hsec; /* hundredths of seconds */ };<< Back to Top
char *tmpnam (s) /* Apple // function */ char *s;DESCRIPTION
tmpnam creates a character string that can be used as the name of a temporary file. The generated string is not the name of an existing file. s optionally points to an area into which the name will be generated. This must contain at least L-tmpnam bytes, where L_tmpnam is a constant defined in "stdio.h". s can also be a NULL pointer. In this case, the name will be generated in an internal array. The contents of this array are destroyed each time tmpnam is called with a NULL argument. The generated name is prefixed with the string that is associated with the symbol P_tmpnam; this symbol is defined in "stdio.h". In the distribution version of "stdio.h", P_tmpnam is a null string; this results in the generated name specifying a file that will be allocated in the current directory.DIAGNOSTICS
tmpnam returns as its value a pointer to the resulting string.SEE ALSO
toupper (c) /* Apple // and UNIX functions */ char c; tolower (c) char c; #include <ctype.h> _toupper (c) int c; _tolower (c) int c;DESCRIPTION
toupper converts a lower case character to upper case: if c is a lower case character, toupper returns its upper case equivalent as its value, otherwise c is returned. tolower converts an upper case character to lower case: if c is an upper case character, tolower returns its lower case equivalent, otherwise c is returned. toupper and tolower do not require the header file "ctype.h". _toupper and _tolower are macro versions of toupper and tolower, respectively. They are defined in "ctype.h". The difference between the two sets of functions is that the macro version will sometimes translate non-alphabetic characters, whereas the function versions don't.<< Back to Top
#include <stdio.h> /* Apple // and UNIX function */ ungetc (c, stream) int c; FILE *stream;DESCRIPTION
ungetc pushes the character c back into the input stream. That character will be returned by the next getc call on that stream. Only one character of pushback is quaranteed. EOF cannot be pushed back.DIAGNOSTICS
ungetc returns c as its value, otherwise it returns EOF (-1).<< Back to Top
unlink (name) /* Apple // function */ char *name;DESCRIPTION
unlink erases a file. name is a pointer to a character string containing the name of the file to be erased.DIAGNOSTICS
unlink returns 0 if successful, otherwise -1 if it couldn't erase the file and places a code in the global integer errno decribing the error.SEE ALSO
write (fd, buf, bufsize) /* Apple // and UNIX function */ int fd; char *buf; int bufsize;DESCRIPTION
write writes characters to a device or disk file which has been previously opened be a call to open or creat. The characters are written to the device or file directly from the caller's buffer. fd is the file despriptor which was returned to the caller when the device or file was opened. buf is a pointer to the buffer containing the characters to be written. bufsize is the number of characters to be written.DIAGNOSTICS
If the operation was successful, write returns as its value the number of characters written, otherwise write returns -1 and places a code in the global integer errno.SEE ALSO