home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
291.lha
/
CcLib_v1.2
/
cclib.doc
< prev
next >
Wrap
Text File
|
1989-10-07
|
117KB
|
3,334 lines
Documentation for CClib.library V1.2
Copyright (C) 1989 by Robert W. Albrecht, All Rights Reserved.
Software and Documentation written and distributed by:
Robert W. Albrecht Jr.
1457 Zion Way
Ventura, CA 93003, USA
-------------------------------------------------------------------------
INTRODUCTION
This is an implementation of the standard C library, with a few extra
goodies thrown in, that is done as an Amiga loadable library. This
allows many applications to share the same library code, saving disk
space, and probably RAM if more than one application is running at a
time. The other advantage of the library is that as improvements are
made to it improvements are made to the programs that use it, and the
programmer doesn't even have to know about it. From the very early Amiga
days I have thought that this should have been done by CBM, but it
wasn't, and I was a little suprised that no one else had either. Well,
after I started I found out why it hadn't been done; It is real tricky
to make the C library re-entrant. Also it turns out that there are over
one hundred and forty functions in the library.
My motivation behind doing this project was that I needed a large
scientific application to be able to run effectivly on a single floppy
Amiga 500 system, and still have space left over for data files. Since
the only way to do what I wanted to do was to eliminate the overhead of
the C library from every program in the package, I had to write this
library.
THIS IS NOT PUBLIC DOMAIN. You can however create public domain programs
that use it, but you MUST pay a $50 license fee for Version 2.0 or above
to use it with commercial software. For the $50 license fee you will
also get a library used for writing C programs with an "Object Oriented"
style. This library has objects for Windows, Buttons, Keyins, and many
more. Also the objects library will allow you to write interactive
programs much faster, and of better quality, than you could without it.
Also included in the object library is a help facility that allows the
user to press the right mouse button and get help for the object the
mouse pointer is over. So if you are a commercial software developer
or just a home hobbiest you will want a copy of Version 2.0.
If anyone is interested in translating the software and/or documentation
to another language, I would be very interested. Please write me at
the above address if you are interested in the project. We might be
able to work out some kind of deal where you would get 100% of the
net receipts for the first 20 licenses, or something like that. I
would be particularly be interested in German, French, and Italian.
-------------------------------------------------------------------------
CONTENTS
I) LICENSE
Transfer
Backup Copies
Term
Robert W. Albrecht's rights
Disclaimer of other Warranties, and Liabilities
II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
III) FUNCTION DOCUMENTATION
1) SUPPORT FUNCTIONS
2) STREAM I/O FUNCTIONS
3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS
4) CHARACTER TEST MACROS
5) STRING FUNCTIONS
6) MEMORY OPERATION FUNCTIONS
7) FORMAT CONVERSION FUNCTIONS
8) MEMORY ALLOCATION FUNCTIONS
9) LINKED LIST FUNCTIONS
10) SORTING FUNCTIONS
11) TIME FUNCTIONS
IV) INSTALLATION
V) THE NUKELIB PROGRAM
VI) RELEASE INFORMATION
VII) NOTES ON LATTICE C
VIII) REVISION HISTORY
IX) COPYRIGHTS AND TRADEMARKS
-------------------------------------------------------------------------
I) LICENSE
Robert W. Albrecht is the exclusive owner of the enclosed Software
and Documentation. You are granted non-exclusive license to use the
Software and Documentation, but you are not the owner of them.
Your right to use the Software and Documentation under this
agreement is the "License". "You" means the individual or legal
entity whose agent receives this software and accepts this Agreement.
"Software" means the computer program recorded on the floppy-disk or
other media, any update to them Robert W. Albrecht may later provide
you, and any back-up copies made. "Documentation" means the user
manual and other materials packaged with this Software.
Transfer
You may transfer the license for the use of the Software or
Documentation to another person free of charge. No charge may
be made for the Software or Documentation, this includes Public
Domain Disks and Shareware Disks. If you are the distributor of
Public Domain disks and you wish to distribute the software at
a nominal charge please send a stamped self-addressed envelope
along with a letter stating your intent to the above address, all
reasonable requests will be granted. Also this version of
CClib.library can NOT be distributed with commercial software.
In order to distribute CClib.library with your commercial software
you MUST pay the one time $50 license fee for Version 2.0 or above
of CClib.library.
Backup Copies
Make as many copies as you want.
Term
The license is effective for twenty (20) years from the time you
receive the software. You may terminate the license at any time by
returning all software and documentation.
Robert W. Albrecht's rights.
The CClib.library Software and Documentation is protected by copyright,
trade secret and trademark laws. You may not disclose the Software or
Documentation to others, except as allowed in this license agreement,
or remove or alter ownership, trademark and copyright notices on
Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO
PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE
OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF
THE LICENSE AGREEMENT.
Disclaimer of other Warranties, and Liabilities.
THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE
SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS".
ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE
PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL
OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES
OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION,
OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL,
INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE
SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY.
Some states do not allow the exclusion or limitation of implied
warranties or liability for incedental or consequential damages so
the above exclusion and limitation may not apply to you. IN ADDITON
TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR
DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE
AND DOCUMENTATION.
-------------------------------------------------------------------------
II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
The implementation of this library is designed to be as transparent as
possible to the C programmer, but is good to be aware of the actions that
are taken by the library accomplish this.
The actual code for most of the standard C library functions is in the
file CClib.library. This is a standard Amiga dynamic link library (DLL)
and can be shared by many application programs at the same time. For the
library to work correctly it must be installed in the LIBS: directory of
your system disk.
DLL's on the Amiga are accessed through the OpenLibrary and CloseLibrary
system (Exec) functions. When a library is opened with the OpenLibrary
function, and it is not yet loaded into RAM, Amiga DOS will go to the
LIBS: directory and load the library specified in the OpenLibrary
function. The OpenLibrary function will return the memory location of
the Library structure for the requested library, this is called the
Library Base Pointer (LBP). A table of jump instructions is located at a
negative offset to the LBP and the actual functions in the library are
accessed through this table. For each function in CClib.library there is
a connection routine in CClib.lib that will allow the application
program access to the functions in the library. The connection routines
contain two 68000 instructions: move the LBP into address register A6,
and jump to an entry in the table of jump instructions in the library.
The offset from the LBP that gets jumped to in the DLL depends on the
specific function in the library. All of these details are, of course,
transparent to the normal user of CClib.library. In order to make the
interface to the C language more efficient, the convention of placing
arguments to functions in registers was not used. Instead the
C calling convention of placing arguments on the stack in reverse
order was followed. This greatly simplified the connection routines
that get linked into your application.
To create an implementation of the C library that is as transparent as
possible to the application the _main function, or initialization code,
and the _exit function, had to be re-written such that the _main
function opens the C library and the _exit function closes the C
library. For this reason these routines could not be included in the
DLL. You must link with the special version of _main and _exit that are
contained in the file _main.o. The _main routine must also set up stdin,
stdout, and stderr for the application, as well as handle the Amiga
Workbench environment. Also if your program needs access to functions in
the DLL that use floating point numbers the _main routine must open the
IEEE floating point library and give a pointer to this library to
CClib.library. As you may know there are a number of different floating
point options on the Amiga.
In order to implement floating point operations in the DLL it was
necessacary to choose just one of the possible floating point options of
the Amiga. The one that is used by the DLL is the
MathIeeeDoubBas.library. The reason for using this one is that it is has
standard 64 bit IEEE floating point numbers and there is a version of
this library for the 68881 and 68882 MPUs. This means that users of
Aztec C will have to link with ma32.lib if there are any floating point
operations in the application. For users of the DLL who will have no
need for floating point numbers in their application the global short
integer _math can be declared with a value of zero and
MathIeeeDoubBas.library will not be loaded by the _main function. The
whole reason for the Ieee floating point number requirement comes from the
fact that the code for the DLL can be shared by many applications. There
are other restrictions as well that arise from this fact.
The C data type 'int' is a 32 bit quantity. The reason that ints are 32
bits instead of 16 bits is that the 68000 is a 32 bit processor and ints
are 32 bits in Lattice C. Aztec C has compiler switches that make ints
32 bits. The DLL really doesn't care what an int is inside your program
but it does care what the arguments passed to it's functions are. When
an argument is passed to a CClib function it must be promoted to an int
before being put on the stack, if it is smaller that an int. In Aztec C
the easest way to ensure this is to use the +L compiler switch. Another
way to handle this is to cast 8 and 16 bit arguments to a 32 bit
quantity.
Another issue that arises from the fact that the DLL code is shared, is
the problem of re-entrancy. CClib must not modify it's own data in such
a way it can't be re-used by another application, but some functions in
any C library implementation must, by nature, use global data. For
instance the heap memory manager must keep track of a list of free
memory blocks, and must do so in a way that is transparent to the
application. It would not due for all of the users of the DLL to share
the same free memory list. This means that the DLL must allocate a block
of memory for each of it's users and somehow know which block to use. It
turns out that there is a very simple way to implement this on the
Amiga. Every Amiga task must have a Task structure associated with it so
that Exec can keep track of it. To obtain a pointer to the currently
running task you call the Exec function FindTask with an argument of
zero. Also there is an unused member of the Task structure called
tc_UserData. When the DLL initializes your task it allocates some memory
from Exec and makes tc_UserData point to that memory. Whenever you call
a CClib function that requires the use of global data it acceses the
memory block attached to your task's tc_UserData field. For this reason
you had better not mess around with your task's tc_UserData member and
expect CClib to work.
The implementation of file handles and FILE pointers is quite different
than the implementation in other C libraries. Most C libraries keep a
static array of FILE structures and a static array of file handles. This
method is just fine for systems which have a built-in limit as to the
number of open files a single task can have, but it doesn't make any
sense for a computer that has no such limitation. For this reason the
FILE structures and file handles are implemented as linked lists in
the DLL. This improvement does have one side effect though, there are
no pre-opened file handles, for example 1 is not the low-level file handle
for stdio. Instead of hard-coding the low-level file handles you will
have to use the fileno() macro defined in stdio.h, for example:
write(fileno(stdin),"Hello World",11L);
Despite these restrictions due to the implementation of the library
it is hoped that you will find this library useful. Be sure to look at
the example programs for more information.
-------------------------------------------------------------------------
III) FUNCTION DOCUMENTATION
The documentation of the functions in the library follows this format:
-------------------------------------------------------------------------
Name: The name of the C function or macro [MACRO] =
this is a macro
Synopsis: The outline of the function with the type of the argumets
and the return value.
Function: What actions are taken by this function.
Arguments: An explanation of the arguments to this function.
Return: The return value of the function, and what indicates an
error condition. It is also indicated if any global variables
are set by this function.
See Also: Other documentation that will lead to a further understanding
of the function.
-------------------------------------------------------------------------
1) SUPPORT FUNCTIONS
Some of these functions are not a normal part of a C library but are
used to support this implementation. Other functions are here because
they don't fit into another category.
-------------------------------------------------------------------------
Name: abort MACRO
Synopsis: #include "stdlib.h"
void abort()
Function: This is a macro that causes abnormal program termination. It
is equivalent to exit(EXIT_FAILURE).
See Also: exit
-------------------------------------------------------------------------
Name: atexit MACRO
Synopsis: #include "stdlib.h"
void atexit( func )
void (*func)();
Function: Sets the atexit function that is executed when the program
terminates through a call to exit or _exit. Any existing
atexit function is over-written. This is defined as a macro
in stdlib.h.
Arguments: func - a pointer to your atexit function
See Also: exit
-------------------------------------------------------------------------
Name: ClearAbortFunc
Synopsis: void ClearAbortFunc()
Function: Clears the break signal abort function. A call to this function
will disable program termination when a ^C or a break is sent
to it with the AmigaDOS break command.
See Also: SetAbortFunc
-------------------------------------------------------------------------
Name: ClearSTDIO
Synopsis: void ClearSTDIO()
Function: Returns resources to the system that were used by a process
using CClib.library. All files are closed and all allocated
memory is freed. The task's tc_UserData field is re-set to
it's original condition.
See Also: SetSTDIO, SetupSTDIO
-------------------------------------------------------------------------
Name: closeall
Synopsis: void closeall()
Function: Closes all opened stream files and low-level files.
See Also: ClearSTDIO
-------------------------------------------------------------------------
Name: cli_parse
Synopsis: void cli_parse(ud,alen,aptr)
task_UserData *ud;
long alen;
char *aptr;
Function: Parses the command line arguments into argc and argv for
the main routine. Called only when the program is executed
from the CLI.
Arguments: ud - a pointer to the task's user data structure.
alen - the length of the command string passed to the program
from AmigaDOS.
aptr - a pointer to the command string passed to the program from
AmigaDOS.
See Also: wb_parse
-------------------------------------------------------------------------
Name: exit and _exit()
Synopsis: void exit(code) void _exit(code)
long code; long code;
Function: Causes normal program termination. The atexit() function is
executed Open files and streams are closed and flushed, memory
is de-allocated and returned to the system. Exit may also be
called when a break signal is received from Amiga DOS.
Arguments: code - the return code of the program. The values EXIT_SUCCESS
and EXIT_FAILURE may also be used.
See Also: abort, atexit
-------------------------------------------------------------------------
Name: GetSTDIO
Synopsis task_UserData *GetSTDIO()
Function: Gets a pointer to the block of memory used for global data
for this task. This function is written in assembly language
because it is used quite frequently by the library. The
task_UserData structure is defined in iolib.h.
Return: A pointer to the task's user data block, or NULL if it isn't
initialized yet.
See Also: SetSTDIO
-------------------------------------------------------------------------
Name: scdir
Synopsis: char *scdir(pattern)
char *pattern;
Function: This function is used to support wild card file names using
'*' and '?' where '*' matches any number of characters and
'?' matches any single character. To use the function simply
pass the pattern to the function and keep calling it until
NULL is returned. For example:
while( name = scdir("*.c") ) do_something(name);
Warning: This function allocates memory from the system that is not
freed until it returns NULL. So that the memory gets returned
to the system be sure keep calling it until NULL is returned,
if you don't the memory will remain allocated until the program
exits. Also the file pattern is irrelavent after the first call
to scdir because it remembers the pattern in it's own memory.
The memory used by scdir is pointed to by
task_UserData.scdir_mem and if you wish to scan another directory
before the current one is finished you can save this pointer,
set it to NULL, scan the other directory, restore the pointer
and then keep calling scdir until NULL is returned.
Arguments: pattern - the file name pattern.
Return: A pointer to a file name that matches the pattern or NULL.
-------------------------------------------------------------------------
Name: SetAbortFunc
Synopsis: void SetAbortFunc(func)
long (*func)();
Function: Sets the break signal abort function. Whenever a break signal
is detected from AmigaDOS, sent either by a ^C from the console
or from an AmigaDOS break command, the library will see if there
is an abort function, and if there is it will be executed with
the signals that caused it to be executed as an argument. The
signals will be in a 32 bit integer. During normal operation
the function _exit is the abort function, however you may wish
to set it to something else so that you can clean up whatever
your application is doing at the time. If you intend to exit
from the program call the exit or _exit functions, not the
AmigaDOS Exit function, or else resources allocated by
the library will not be de-allocated.
Arguments: func - a pointer to the abort function to be used when a
break signal is received.
See Also: ClearAbortFunc
-------------------------------------------------------------------------
Name: SetSTDIO
Synopsis: long SetSTDIO()
Function: Allocates memory for a task_UserData structure and attaches
it to the tc_UserData field of the task structure.
Return: Zero is returned if the operation was a success, otherwise
one is returned.
See Also: SetupSTDIO
-------------------------------------------------------------------------
Name: SetupSTDIO
Synopsis: long SetupSTDIO(ud,in,out,err,errno,bsize,ctyp,mathbase)
FILE **in, **out, **err;
long *errno, *bsize;
char **ctyp;
void *mathbase;
long alen;
char *aptr;
struct WBStartup *wbm;
void (*_xit)();
Function: Gives the library access to global variables that reside in the
application program and opens standard input, output and error
streams and allocates the SetSTDIO to allocate the memory that
is pointed to by task->tc_UserData. Standard I/O will not be
opened for programs run from the workbench that have no
"WINDOW" tooltype in their tool icon, or for programs run
from the workbench by projects.
Arguments: in, out, err - memory locations where pointers to the standard
stream files are stored in the application program.
errno - the memory location where the global variable errno
is stored.
bsize - the memory location where the global variable blocksize
is stored. blocksize is used by the heap manager to determine the
minimum size of the memory blocks to be allocated from AmigaDOS.
ctyp - this is the 'type' array that is used by the macros in
ctype.h. The array is actually in the library and the
application just gets a pointer to it.
mathbase - The address of the MathIeeDoubBas library base pointer
to be used for programs that use floating point numbers.
alen - the length of the command line passed to the program by
the CLI process, if run from the CLI.
aptr - a pointer to the command line passed to the program by the
CLI process, if run form the CLI.
wbm - a pointer to the workbench startup message sent by the
workbench program. This will be used by wb_parse to open a
standard I/O window for the application if the Tooltype
"WINDOW" is set.
_xit - a pointer to the applications exit routine. This is set
to be exit() by the _main routine.
Return: One is returned if all of the initialization was successful,
otherwise zero is returned.
-------------------------------------------------------------------------
Name: system MACRO
Synopsis: #include "stdlib.h"
system(command)
char *command;
Function: Executes a command as if it was typed in on the CLI command
line. The RUN command must be in the path or in the C: directory
for this function to work.
Arguments: command - The command to execute, for example:
system("FORMAT DRIVE DH0: NAME TRASHED") will format
your hard drive immediatly without asking.
Return: Zero is returned on failure.
-------------------------------------------------------------------------
Name: wb_parse
long wb_parse(ud, wbmsg)
task_UserData *ud;
struct WBStartup **wbmsg;
Function: Checks the Tool Types of the icon associated with this program.
If the Tool Type WINDOW is found a window is opened using the
Tool Type's value. This window is used for standard input and
output. If the WINDOW tool type is not found then a program
run from the workbench will have NO standard input, output, and
error, and any attempt to write to these non-existant devices
will almost certainly cause a system crash. A good example of
a valid tool type would be:
WINDOW=CON:20/10/300/100/WindowTitle
Arguments: ud - a pointer to the task's task_UserData structure.
wbmsg - a pointer to the workbench startup message for this
program.
Return: Non-zero is returned if a window was opened for standard
input and output.
See Also: cli_parse
-------------------------------------------------------------------------
2) STREAM I/O FUNCTIONS
These functions send and receive bytes from "streams". A stream is the
data type FILE that is defined in stdio.h. Some of the functions
are implemented as macros that are defined in stdio.h. Other functions
read and write to the standard pre-opened stream files "stdin", "stdout"
and "stderr". When an error occurs with one of these functions the
global variable errno will contain further information.
-------------------------------------------------------------------------
Name: agetc
Synopsis: short agetc(fp)
FILE *fp;
Function: Gets one character from the designated stream. This function
is here to support existing implementations of the C library
and should not be used in new code.
Arguments: fp - a pointer to the stream file to receive input from.
Return: The character received as input, of EOF if the end of the
file has been reached, or if an error has occured.
See Also: getc
-------------------------------------------------------------------------
Name: aputc
Synopsis: short aputc(c,fp)
short c;
FILE *fp;
Function: Writes one character to the specified stream. This function is
here to support existing implementations of the C library and
should not be used in new code.
Arguments: c - the character to write
fp - the stream to write to.
Return: EOF is returned on error.
See Also: putc
-------------------------------------------------------------------------
Name: clearerr MACRO
Synopsis: #include "stdio.h"
int clearerr(fp)
FILE *fp;
Function: Clears end of file and error indicators in a stream.
Arguments: fp - pointer to a stream file
See Also: feof, ferror
-------------------------------------------------------------------------
Name: fclose
Synopsis: long fclose(fp)
FILE *fp;
Function: Closes a stream file.
Arguments: fp - stream file to close
Return: Zero is returned if the operation was successful, otherwise
non-zero is returned.
See Also: fopen
-------------------------------------------------------------------------
Name: fdopen
Synopsis: FILE *fdopen(fh,fmode)
long fh;
char *fmode;
Function: Creates a stream file from a low-level file handle.
This function is here to support existing C library
implementations and should not be used in new code.
Arguments: fh - the low-level file handle
fmode - not used in this implementation, but used to contain the
file open modes.
Return: A pointer to the new stream file is returned, otherwise NULL.
See Also: fopen
-------------------------------------------------------------------------
Name: feof MACRO
Synopsis: #include "stdio.h"
int feof(fp)
FILE *fp;
Function: Tests for end of file.
Arguments: fp - pointer to a stream file
Return: Retuns non-zero if the end of file bit is set in the stream.
-------------------------------------------------------------------------
Name: ferror MACRO
Synopsis: #include "stdio.h"
int ferror(fp)
FILE *fp;
Function: Tests for file error.
Arguments: fp - pointer to a stream file
Return: Returns non-zero if the error bit is set in the stream.
-------------------------------------------------------------------------
Name: fflush
Synopsis: long fflush(fp)
FILE *fp;
Function: Causes buffered but unwritten data to be written on an output
file. The operation is undefined for input streams.
Arguments: fp - the stream file to flush
Return: EOF is returned on a write error, otherwise zero is returned.
-------------------------------------------------------------------------
Name: fgetc MACRO
Synopsis: #include "stdio.h"
int fgetc(fp)
FILE *fp;
Function: Gets one character from the designated stream.
Arguments: fp - a pointer to the stream file to receive input from.
Return: The character received as input, of EOF if the end of the
file has been reached, or if an error has occured.
See Also: getc
-------------------------------------------------------------------------
Name: fgetpos
Synopsis: #inlude "stdio.h"
long fgetpos(fp,pos)
FILE *fp;
fpos_t *pos;
Function: Saves the current position in a stream file into a variable
that is suitable for a call to fsetpos.
Arguments: fp - stream to get the current position of
pos - current position is saved to this address. The data
type fpos_t is defined in stdio.h.
Return: Non-zero is returned on an error.
See Also: fsetpos
-------------------------------------------------------------------------
Name: fgets
Synopsis: char *fgets(buf,n,fp)
char *buf;
long n;
FILE *fp;
Function: Reads at most n-1 bytes from a stream file into an array,
if a '\n' character is encountered it is included
in the array which is then NULL terminated.
Arguments: buf - pointer to the array of bytes to store the input.
n - maximum number of bytes to read.
fp - pointer to the stream file to read from.
Return: buf is returned unless the end of file is reached or an error
occurs in which case NULL is returned.
See Also: fputs
-------------------------------------------------------------------------
Name: fopen
Synopsis: FILE *fopen(fname,fmode)
char *fname;
char *fmode;
Function: Opens a sream file.
Arguments: fname - the name of the file to open. The file name may be up
to FILENAME_MAX characters long.
fmode - the mode to open the file in. Legal values include:
"r" open a file for reading
"w" create a file for writing, discard contents if any.
"a" append; open or create a file for writing at the end.
"r+" open a file for update, reading and writing)
"w+" create a file for update, discard previous contents
"a+" append; open or create a file for update, write at end
Optionally a 'b' may be added to the open mode, but this is not
needed for the Amiga system because there is no distinction
between text files and binary files.
Return: A pointer to a stream file is returned, if an error occurs NULL
is returned.
See Also: fclose
-------------------------------------------------------------------------
Name: fprintf
Synopsis: long fprintf(fp,fmt,...)
FILE *fp;
char *fmt;
Function: Sends formatted output to a stream file. For a more detailed
description of formatted output please see printf.
Arguments: fp - pointer to the stream file
fmt - format to print the arguments with.
... - a variable number of arguments that is specified in fmt.
Return: The number of characters written is returned.
See Also: printf
-------------------------------------------------------------------------
Name: fputc MACRO
Synopsis: #include "stdio.h"
int fputc(c,fp)
short c;
FILE *fp;
Function: Writes one character to the specified stream.
Arguments: c - character to write
fp - stream to write to
Return: EOF is returned on error
See Also: putc
-------------------------------------------------------------------------
Name: fputs
Synopsis: long fputs(string,fp)
char *string;
FILE *fp;
Function: Sends a string to the specified stream file.
Arguments: string - NULL terminated string to send.
fp - stream to send the string to.
Return: EOF is returned on error, otherwise > 0.
See Also: fgets
-------------------------------------------------------------------------
Name: fread
Synopsis: #include "stdio.h"
size_t fread(buf,size,nobj,fp)
void *buf;
size_t size;
size_t nobj;
FILE *fp;
Function: Reads from a stream into an array at most nobj elements of
size. (number of bytes = size*nobj).
Arguments: buf - buffer to store the data
size - size of each element to read
nobj - number of elements to read
fp - stream to read from
Return: The number of elements read, which may be less than nobj due
to an end of file or error condition.
See Also: fwrite
-------------------------------------------------------------------------
Name: freopen
Synopsis: FILE *freopen(fname, fmode, oldfp)
char *fname;
char *fmode;
FILE *oldfp;
Function: Re-opens a stream file with a different name and possibly a
different file mode. It is most commonly used to re-direct
stdin, stdout, and stderr.
Arguments: fname - name of the stream to open
fmode - mode to open the stream in. See the description of
fopen for the legal file modes.
oldfp - the stream to re-open.
Return: A pointer to the new stream is returned if the operation was
successful, otherwise NULL is returned.
See Also: fopen
-------------------------------------------------------------------------
Name: fscanf
Synopsis: long fscanf(fp,fmt,...);
FILE *fp;
char *fmt;
Function: Reads formatted input from a stream. For a further explanation
of formatted input please see scanf.
Arguments: fp - stream to read the formatted input from.
fmt - format of the arguments to be read.
... - a variable number of arguments that are specified in fmt.
Each of the arguments to fscanf must be a pointer.
Return: The number of items converted and assigned is returned.
See Also: scanf
-------------------------------------------------------------------------
Name: fseek
Synopsis: #include "stdio.h"
long fseek(fp,offset,origin)
FILE *fp;
long offset;
long origin;
Function: Sets the position in a stream relative to "origin".
Arguments: fp - stream to set the position of.
offset - offset in bytes to set the position to.
origin - position realtive to which the new position will
be set. The values for origin may be SEEK_SET (beginning),
SEEK_CUR, (current position), SEEK_END (end of file).
Return: Non-zero is returned when an error occurs.
See Also: ftell, fsetpos
-------------------------------------------------------------------------
Name: fsetpos
Synopsis: long fsetpos(fp,pos)
FILE *fp;
fpos_t *pos;
Function: Positions a stream to a position saved by fgetpos.
Arguments: fp - stream to set the position of.
pos - pointer to the position saved by fgetpos.
Return: Non-zero is returned when an error occurs.
See Also: fseek
-------------------------------------------------------------------------
Name: ftell
Synopsis: long ftell(fp)
FILE *fp;
Arguments: fp - a stream file.
Return: Returns the current file position, of -1 if an error occurs.
See Also: fgetpos
-------------------------------------------------------------------------
Name: fwrite
Synopsis: #include "stdio.h"
size_t fwrite(buf,size,nobj,fp)
void *buf;
size_t size, nobj;
FILE *fp;
Function: Writes from an array to a stream, at most nobj elements of size
size are written.
Arguments: buf - array to write from.
size - size of the elements to write.
nobj - number of elements to write.
fp - stream to write to.
Return: The number of element written is returned, which is less than
nobj on error.
See Also: fread
-------------------------------------------------------------------------
Name: getbuff
Synopsis: void getbuff(fp)
FILE *fp;
Function: Allocates the standard sized buffer for buffered input and
output. The function must be called before any reading or
writing is done. It will be called for you otherwise.
Arguments: fp - stream to attach the buffer to.
See Also: setvbuf
-------------------------------------------------------------------------
Name: getc
Synopsis: short getc(fp)
FILE *fp;
Function: Gets one character from the designated stream.
Arguments: stream - a pointer to the stream file to receive input from.
Return: The character received as input, of EOF if the end of the
file has been reached, or if an error has occured.
See Also: fgetc
-------------------------------------------------------------------------
Name: getchar MACRO
Synopsis: #include "stdio.h"
short getchar();
Function: Reads one character from the standard input.
Return: The character received as input, of EOF if the end of the
file has been reached, or if an error has occured.
See Also: getc
-------------------------------------------------------------------------
Name: getchar
Synopsis: #define NOMACROS
#include stdio.h or short getchar();
short getchar();
Function: Reads one character from the standard input.
Return: The character received as input, of EOF if the end of the
file has been reached, or if an error has occured.
See Also: getc
-------------------------------------------------------------------------
Name: gets
Synopsis: char *gets(buf)
char *buf;
Function: Reads a line from the standard input. The newline '\n' is
replaced by a '\0'.
Arguments: buf - array of characters where the input line is stored.
Return: Returns buf unless end of file or an error occurs in which
case NULL is returned.
See Also: puts,fputs
-------------------------------------------------------------------------
Name: getw
Synopsis: short getw(fp)
FILE *fp;
Function: Reads a 16 bit word from the specified stream.
Arguments: fp - stream to read the word from.
Return: EOF is returned on error, otherwise the data read from the
stream is returned.
See Also: putw
-------------------------------------------------------------------------
Name: mktemp
Synopsis: char *mktemp(buf)
Function: Creates a temporary file name from a template whose last few
characters are 'X'. For example "BOBXXXX.XX".
Arguments: buf - template to create the file name from.
Return: buf is returned.
See Also: tmpnam
-------------------------------------------------------------------------
Name: perror
Synopsis: long perror(msg)
char *msg;
Function: Prints an error message corresponding to the number in errno
along with a message you provide to stderr.
Arguments: msg - supplimental error message, or NULL if you don't have one.
Return: Zero is returned on success, -1 is returned if the error number
in errno has no corresponding error message or if an error
error occurs with the execution of perror.
See Also: puterr
-------------------------------------------------------------------------
Name: printf
Synopsis: long printf(fmt,...)
char *fmt;
Function: Writes formatted output to stdout under control of a
format string.
Arguments: fmt - format of the following arguments.
fmt contains two things, regular characters which are copied
to stdout, and conversion specifications, each of which causes
conversion and printing of the next argument in the variable
argument list. Every conversion specification begins with a
'%' character and ends with a converson character. Before the
conversion character there may be one or more modifiers. Below
is a list of the modifiers in the order that they must appear.
1) Flags (in any order) [-+0 ]
'-' specifies left justification within the field
'+' specifies that the number will be printed with a sign
' ' space is printed if the first character isn't a sign
'0' for numeric conversions leading zeros will be printed
instead of spaces
'#' is NOT supported yet
2) Field Width [0123456789]
The minimum field width that the converted argument will
be printed in. The argument may be printed in a wider field
if it would overflow the field. If the converted argument
has fewer characters it will be padded with spaces, unless
zeros are specified.
3) A period, [.]
seperating the field width from the precision.
4) Precision number [0123456789]
o For character strings; specifies the maximum number of
characters to be printed.
o For floating point numbers in e, E, or f formats the number
of digits to be printed after the decimal point.
o For floating point numbers in the G or g formats the number
of significant digits to be printed.
o For integral numbers the minimum number of digits to be
printed, leading zeros will be added if the number isn't
big enough to be prited.
5) Argument length specifier [lh]
If the length specifier is not present then the argument
is taken to be the short ('h') form.
For integral values:
The length specifier is completly optional for integral values
because all 16 bit arguments must be promoted to a 32 bit
quantity before passing them to a CClib.library function.
o 'l' prints the argument as long or unsigned long.
o 'h' prints the argument as short or unsigned short.
For floating point values:
o 'h' prints the argument as a float.
o 'l' prints the argument as a double.
o 'L' is NOT supported due to the lack of the long double
data type on the Amiga.
Printf conversion characters.
d, i signed decimal number
o unsigned octal number
x, X unsigned hexadecimal number using lowercase letters
for 'x' and upper case letters for 'X'
u unsigned decimal number
c a single character
s a NULL terminated string
f float or double depending on the length specifier to
be printed with a fixed decimal point
e, E float or double depending on the length specifier to
be printed in exponential notation
g, G float or double depending on the length specifier to
be printed with whatever is shorter, 'e' of 'f'
format
p print as a pointer (this is really the same as
'x' format on the Amiga).
n this is NOT supported yet, but should put the
number of characters printed so far into the
argument.
% prints the '%' character
Return: The number of characters printed is returned or negative
if an error occurs.
See Also: fprintf, vprintf, vfprintf
-------------------------------------------------------------------------
Name: putc
Synopsis: short putc(c,fp)
short c;
FILE *fp;
Function: Writes one byte to the specified stream.
Arguments: c - character to write
fp - stream to write to
Return: EOF is returned on error
See Also: getc
-------------------------------------------------------------------------
Name: putchar MACRO
Synopsis: #include "stdio.h"
short putchar(c)
short c;
Function: Writes one character to the standard output.
Arguments: c - the character to write
Return: EOF is returned on error.
See Also: putc
-------------------------------------------------------------------------
Name: putchar
Synopsis: #defile NOMACROS 1
#include "stdio.h" or short putchar(c)
short putchar(c) short c;
short c;
Function: Writes one character to the standard output.
Arguments: c - the character to write
Return: EOF is returned on error.
See Also: putc
-------------------------------------------------------------------------
Name: puterr
Synopsis: short puterr(c)
short c;
Function: Writes one character to stderr.
Arguments: c - character to write
Return: EOF is returned on error
See Also: perror
-------------------------------------------------------------------------
Name: puts
Synopsis: short puts(str)
char *str;
Function: Writes a NULL terminated string and a newline ('\n') character
to stdout.
Arguments: str - string to write
Return: EOF is returned on error
See Also: gets
-------------------------------------------------------------------------
Name: putw
Synopsis: unsigned short putw(w,fp)
unsigned short w;
FILE *fp;
Function: Writes a 16 bit word to the specified stream.
Arguments: w - word to write
fp - stream to write to
Return: w is returned when no error occurs, otherwise EOF.
See Also: putc
-------------------------------------------------------------------------
Name: remove MACRO
Synopsis: #include "stdio.h"
long remove(fname)
char *fname;
Function: Deletes a file.
Arguments: fname - name of the file to delete
Return: Non-zero is returned on error.
See Also: unlink
-------------------------------------------------------------------------
Name: rename
Synopsis: long rename(oldfname,newfname)
char *oldfname;
char *newfname;
Function: Renames a file. In AmigaDOS files may be renamed across
directories but not across volumes. For example
rename("RAM:t/junk","RAM:t/stuff/junk); would be legal but
rename("RAM:t/junk","DF0:junk"); would not be.
Arguments: oldfname - name of the file to rename
newfname - new name of the file
Return: Non-zero is returned on error.
-------------------------------------------------------------------------
Name: rewind MACRO
Synopsis: #include "stdio.h"
void rewind(fp)
FILE *fp;
Function: Sets the position of a stream file to the beginning of the file.
Arguments: fp - stream file pointer
See Also: fseek
-------------------------------------------------------------------------
Name: scanf
Synopsis: long scanf(fmt,...)
char *fmt;
Function: Reads formatted input from stdin under control of a format
string.
Arguments: fmt - format conversion string. The format sring is used to
direct the interpretation of input. The format string may
contain;
1) whitespace (blanks and tabs) which is ignored.
2) Characters other that % which are expected to match
the next non-whitespace character of input.
3) All conversion specifications are preceeded with a '%'
character.
4) Field Width [0123456789]
Specifies the maimum width of a field.
5) Argument length specifier [lh]
The argument length specifier determines the size of the
variable pointed to by the corresponding argument.
If the length specifier is not present then the argument
is taken to be the short ('h') form.
For integral values:
o 'l' converts the input as long or unsigned long.
o 'h' converts the input as short or unsigned short.
For floating point values:
o 'h' converts the argument as a float.
o 'l' converts the argument as a double.
o 'L' is NOT supported due to the lack of the long double
data type on the Amiga.
6) Conversion specifications. Each conversion specification
determines the conversion of the next field of input. Unless
the suppression character '*' is used the input is stored in
the next variable corresponding to the next argument. For
each variable conversion continues until a whitespace
character is encountered, or until the number of characters
specified in the maximum field width of the conversion specification
are encountered.
Scanf conversion characters.
d, i signed decimal number
o unsigned octal number
x unsigned hexadecimal number
u unsigned decimal number
c input characters are placed in the indicated array
up to the number specified in the field width; the
default is 1, No '\0' os added. %c will convert the
next character INCLUDING whitespace. To read the
next non-whitespace character use %1s.
s a NULL terminated string
e,f,g float or double depending on the length specifier
p pointer (this is really the same as 'x' format
on the Amiga).
n this is NOT supported yet, but should put the
number of characters read so far into the
argument.
[...] Null terminated string. Matches the longest
non-empty string of input characters from the set
of characters between brackets. The string is NULL
terminated. []...] includes ']' in the set.
[^...] Null terminated string. Matches the longest
non-empty string of input characters NOT from the
set of characters between the brackets. The string
in NULL terminated. [^]...] excludes ']' from the
set.
% the '%' character, no assignment is made
... - a variable number of arguments each of which is a pointer
to a variable whose type is determined by the contents of
the format string.
Return: The number of items converted and assigned (stored) is
returned. If an error occurs or if end of file is reached
EOF is returned.
See Also: fscanf, sscanf, printf
-------------------------------------------------------------------------
Name: setbuf MACRO
Synopsis: #include "stdio.h"
void setbuf(fp,buf)
FILE *fp;
char *buf;
Function: If buf is NULL buffering for this stream is eliminated,
otherwise setbuf is the same as setvbuf(fp,buf,_IOFBF,BUFSIZ).
Arguments: fp - stream file pointer
buf - buffer to set
See Also: setvbuf
-------------------------------------------------------------------------
Name: setvbuf
Synopsis: #include "stdio.h"
long setvbuf(fp,buf,mode,size)
FILE *fp;
char *buf;
long mode;
size_t size;
Function: Controls buffering for a stream by attaching an application
specific buffer to the stream. If setvbuf is to be used then
it must be called before any reading or writing is done on the
stream.
Arguments: fp - stream to add the buffer to
buf - buffer to be used, if the buf argument is NULL then a
buffer will be allocated for the stream using malloc that is the
size specified by the size argument.
mode - the mode of buffering, _IOFBF causes full buffering,
_IOLBF should cause the buffering of text lines but is the same
as _IOFBF for this implementation, _IONBF causes no buffering.
size - size of the buffer provided or to be allocated.
Return: Non-zero is returned for any error.
See Also: setbuf
-------------------------------------------------------------------------
Name: sprintf
Synopsis: long sprintf(buf,fmt,...)
char *buf;
char *fmt;
Function: Prints formatted output to a NULL terminated string under control
of a format string.
Arguments: buf - buffer to write the output to
fmt - format string, see the documentation for the printf
function for a description of the format string.
... - variable number of arguments under control of the
format string.
Return: The number of characters printed not including the NULL
terminator.
See Also: printf
-------------------------------------------------------------------------
Name: sscanf
Synopsis: long sscanf(str,fmt,...)
char *str, *fmt;
Function: Identical to scanf except that input characters are taken
from the string str instead of stdin.
Arguments: str - string to take input from
fmt - format string, see documentation for the scanf function
... - variable number of arguments each of which is a pointer
Return: The number of items converted and assigned (stored) is
returned.
See Also: scanf
-------------------------------------------------------------------------
Name: stat
Synopsis: #include "stat.h"
long stat(fname,stat)
char *fname;
struct stat *stat;
Function: Retrieves information about a file.
Arguments: fname - name of the file to get the information about
stat - structure to hold the results. The stat structure
is described below;
struct stat
{
unsigned short st_attr;
long st_mtime;
long st_size;
};
st_attr - file attributes which may be or'd together including:
This Bit On Means
ST_DELETE - file is NOT deletable
ST_EXECUTE - file is NOT executable
ST_WRITE - file is NOT writeable
ST_READ - file is NOT readable
ST_ARCHIVE - file HAS been archived
A warning about attribute bits; It is unsafe to assume that
the other bits available in the attribute field will be un-used.
This is because they may be used in future implementations of
the Amiga operating system. This has already happened in the
case of the ST_ARCHIVE bit.
st_mtime - File modification date, in seconds since Jan, 1 1978
st_size - of file in bytes
Return: Non-zero is returned on error.
-------------------------------------------------------------------------
Name: tmpfile
Synopsis: FILE *tmpfile()
Function: Creates a temporary stream file.
Return: A pointer to the new stream file, or NULL if an error occurs.
See Also: tmpnam
-------------------------------------------------------------------------
Name: tmpnam
Synopsis: #include "stdio.h"
char *tmpnam(buf)
char *buf;
Function: Creates a string that is not the name of an existing file.
Arguments: buf - buffer to store the string in. This buffer must be at
least L_tmpnam characters long. If this argument is NULL then
a pointer to a "static" string is returned. This string may be
over-written by other calls to cclib.library functions, so
it is best to make a local copy of the string or immediatly
open a file using this string.
Return: buf, or a pointer to the "static" area of memory used by tmpnam.
The "static" memory is really located in the task_UserData
structure for your process.
See Also: tmpfile
-------------------------------------------------------------------------
Name: ungetc
Synopsis: short ungetc(c,fp)
short c;
FILE *fp;
Function: Pushes a single character 'c' back into a stream file where it
will be read as the next character of input. c may not be EOF.
Arguments: c - character to put
fp - stream to push into
Return: The character puched back is returned, EOF on error.
See Also: getc
-------------------------------------------------------------------------
Name: vfprintf
Synopsis: long vfprintf(fp,fmt,arg)
FILE *fp;
char *fmt;
va_list arg;
Function: Works the same as fprintf except that the variable argument
list has been replaced by arg, which is a pointer into the
stack. vfprintf is useful for implementing your own functions
that use variable argument lists. Here is an example of a
function you could write using a variable number of arguments:
yourfprintf(fp,ymsg,fmt,arg)
FILE *fp;
char *ymsg, *fmt;
int arg;
{
fprintf(fp,"Your Message: %s ",ymsg);
vfprintf(fp,fmt,(va_list)&arg);
}
You could call this function like this:
yourfprintf(fp,"Oops","%s %d","The number was",10);
And the output would be:
Your Message: Oops The number was 10
Arguments: fp - pointer to stream
fmt - format string, see printf for a complete discription
arg - pointer to the first argument in a variable argument list
Return: The number of characters written is returned, or negative
if an error occured.
See Also: printf
-------------------------------------------------------------------------
Name: vprintf
Synopsis: long vprintf(fmt,arg)
char *fmt;
va_list arg;
Function: Works the same as printf except that the variable argument
list has been replaced by arg, which is a pointer into the
stack. See vfprintf to find out how to use arg.
Arguments: fmt - format string, see printf for a complete discription
arg - pointer to the first argument in a variable argument list
Return: The number of characters written is returned, or negative
if an error occured.
See Also: printf, vfprintf
-------------------------------------------------------------------------
Name: vsprintf
Synopsis: long vsprintf(buf,fmt,arg)
char *buf, *fmt;
va_list arg;
Function: Works the same as sprintf except that the variable argument
list has been replaced by arg, which is a pointer into the
stack. See vfprintf to find out how to use arg.
Arguments: fmt - format string, see printf for a complete discription
arg - pointer to the first argument in a variable argument list
Return: The number of characters written is returned, or negative
if an error occured.
See Also: printf, vfprintf
-------------------------------------------------------------------------
3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS. Many of these functions
have become widely used and must be supported even though they are not
part of the ANSI standard C library.
-------------------------------------------------------------------------
Name: access
Synopsis: long access(fname,mode)
char *fname;
long mode;
Function: Tells if a file or directory can be used for a particular
purpose.
Arguments: fname - the name of the file or directory.
mode - asks for a certain type of access for the file or
directory. mode = 4 (read access), 2 = write access, 1 =
executable program, 0 = test for existance of the file.
Return: Zero is returned if the requested accecc rights can be granted,
otherwise -1 is retuned.
See Also:
-------------------------------------------------------------------------
Name: close
Synopsis: long close(fd)
long fd;
Function: Closes the specified low-level file.
Arguments: fd - the descriptor for the low-level file obtained from
open().
Return: Zero is returned if the close was successful, -1 is returned if
an error occured.
See Also: open
-------------------------------------------------------------------------
Name: creat
Synopsis: long creat(fname,mode)
char *fname;
long mode;
Function: creats a new file called 'fname'. This function is equivalent to:
open(fname, O_WRONLY|O_TRUNC|O_CREAT, mode).
Arguments: fname - the name of the file to create.
Return: A file descriptor that can be used by the low-level I/O
functions is returned. If an error occurs -1 is returned.
See Also: open
-------------------------------------------------------------------------
Name: fileno MACRO
Synopsis: #include "stdio.h"
long fileno(fp)
FILE *fp;
Function: Gets the low-level file descriptor for a stream file. This is
most commonly used on non-bufferd streams such as stdin, stdout
and stderr.
Arguments: fp - stream file pointer
Return: The file descrioptor for the stream file is returned.
-------------------------------------------------------------------------
Name: isatty
Synopsis: long isatty(fd)
long fd;
Function: Determines if a file descriptor is attached to an interactive
device (virtual terminal) such as CON: or RAW:.
Arguments: fd - file descriptor returned from open etc.
Return: Non-zero is retuned if the file descriptor is an interactive
device.
-------------------------------------------------------------------------
Name: lseek
Synopsis: long lseek(fd,offset,origin)
long fd;
long offset;
unsigned long origin;
Function: Sets the current position in a file.
Arguments: fd - file descriptor for the file.
offset - number of bytes to position the file from the origin.
origin - 0 is beginning of the file, 1 is current position,
2 is end of the file.
Return: The new position in the file, or -1 on error.
See Also: fseek
-------------------------------------------------------------------------
Name: open
Synopsis: #include "fcntl.h"
long open(fname,flag,mode)
char *fname;
long flag;
long mode;
Function: Opens a file for low-level I/O.
Arguments: fname - name of the file to open, may include path name as well.
flag - specifies how the file is to be opened. The acceptable
values (listed in fcntl.h) are listed below:
O_RDONLY - open for reading only
O_WRONLY - open for writing only
O_RDWR - open for reading and writing
O_CREAT - open the file after creating it
O_TRUNC - remove contents then open the file
O_EXCL - open fails if the file exists or'd with O_CREAT
O_APPEND - open for appending only
These flags may be or'd together to giver further meanings,
for example:
O_WRONLY|O_TRUNC - open for writing, nuke existing files
O_RDWR|O_APPEND - open for reading and appending
Return: fd - descriptor for the open file. This file descriptor is
really a pointer to a FileDesc structure that is defined in
iolib.h. The FileDesc structure is linked into the OpenFiles
list attached to the task_UserData structure for your process.
This is so that the library can close all of your open files
before your process is terminated.
See Also: close
-------------------------------------------------------------------------
Name: read
Synopsis: long read(fd,buf,size)
long fd;
char *buf;
long size;
Function: Reads bytes from a low-level file.
Arguments: fd - file descriptor for the low-level file
buf - buffer to store the data read from the file
size - number of bytes to read
Return: The number of bytes read is returned, -1L is returned on error
or end of file. errno will be set on an error.
See Also: open, write
-------------------------------------------------------------------------
Name: unlink
Synopsis: long unlink(fname)
char *fname;
Function: Deletes a file.
Arguments: fname - name of the file to delete
Return: Non-zero is returned on error.
See Also: remove
-------------------------------------------------------------------------
Name: write
Synopsis: long write(fd,buf,n)
long fd;
char *buf;
long n;
Function: Low-level write to a file.
Arguments: fd - low-level file descriptor obtained from open.
buf - buffer to write
n - number bytes to write
Return: The number of bytes actually written, which may be less than n,
is returned. -1 is returned on error.
See Also: open, read
-------------------------------------------------------------------------
4) CHARACTER TEST MACROS. All of these macros are defined in the
file "ctype.h". They access a static array that is located in
cclib.library. At initialization time a pointer is taken to this
static array and that pointer is used for the characher test macros.
Because the array is located in shared memory it would be unwise to
change it's contents.
-------------------------------------------------------------------------
#include "ctype.h"
All of the macros take a character or integral value as an argument and
"return" an int that is non-zero if the test passes.
isalpha(c) - a letter a-z or A-Z
isupper(c) - upper case letter A-Z
islower(c) - lower case letter a-z
isdigit(c) - decimal digit 0-9
isxdigit(c) - hexadecimal digit 0-9 or a-f or A-F
isalnum(c) - alphanumeric 0-9 or a-z or A-Z
isspace(c) - space, formfeed, newline, carrige return, tab, v-tab
ispunct(c) - printing character except space letter or digit
iscntrl(c) - control character
isprint(c) - printable character spece included
isgraph(c) - printing character except space
isascii(c) - member of the ASCII character set
The following macros don't do character tests but character conversions
and are commonly found in ctype.h. The "return" values are the converted
character.
toascii(c) - converts a character to ASCII
tolower(c) - converts upper case letters to lower case
toupper(c) - converts lower case letters to upper case
-------------------------------------------------------------------------
5) STRING FUNCTIONS. These functions operate on NULL terminated
strings. A NULL terminated string is an array of type char
whose last element is '\0' (zero).
-------------------------------------------------------------------------
Name: bcpl_strcpy
Synopsis: char *bcpl_strcpy(str,bstr)
char *str;
BSTR *bstr;
Function: Copies a BCPL string into a C string. BCPL is the language that
much of Amiga DOS was written in, and strings are different.
First BCPL adresses only point to long words so... ptr =
bcpl_ptr << 2 and BCPL strings start with a character count and
then the number of characters in the string. This function is
provided so that you can access strings in Amiga DOS data
structures.
Arguments: str - pointer to the character array where the BCPL string is
to be placed.
bstr - BCPL pointer to a BCPL string.
Return: str is returned.
-------------------------------------------------------------------------
Name: index
Synopsis: char *index(str,c)
char *str;
short c;
Function: Finds the first occurence of a character in a string.
Arguments: str - string to search
c - character to search for
Return: A pointer to the found character of NULL if the character
was not found.
See Also: strchr
-------------------------------------------------------------------------
Name: rindex
Synopsis: char *rindex(str,c)
char *str;
short c;
Function: Finds the last occurence of a character in a string.
Arguments: str - string to search
c - character to search for
Return: A pointer to the found character of NULL if the character
was not found.
See Also: strrchr
-------------------------------------------------------------------------
Name: stpcrlf
Synopsis: char stpcrlf(str)
char *str;
Function: Strips carriage return of linefeed characters from a string.
At the first encounter of a '\r' or '\n' character that
character is replaced by a '\0' (NULL terminator.
Arguments: str - string to strip
Return: str is returned
-------------------------------------------------------------------------
Name: strcat
Synopsis: char *strcat(dest,source)
char *dest;
char *source;
Function: Concatenates two strings. The destination string is assumed to
be long enough to hold the concatenation.
Arguments: dest - string to concatenate onto
source - string to concatenate from
Return: dest, the result, is returned
See Also: strcpy
-------------------------------------------------------------------------
Name: strchr
Synopsis: char *strchr(str,c)
char *str;
short c;
Function: Finds the first occurence of a character in a string.
Arguments: str - string to search
c - character to search for
Return: A pointer to the found character of NULL if the character
was not found.
-------------------------------------------------------------------------
Name: strcmp
Synopsis: short strcmp(str1,str2)
char *str1, *str2;
Function: Compares two strings.
Arguments: str1, str2 - strings to compare
Return: Negative is returned if str1 < str2, zero is returned if
str1 == str2, positive is returned if str1 > str2.
See Also: strncmp, strcmpa
-------------------------------------------------------------------------
Name: strcmpa
Synopsis: char *strcmpa(str1,str2)
char *str1, *str2;
Function: Compares two strings, ignoring the case of the letters. For
example: 0 == strcmpa("BOB","bob");
Arguments: str1, str2 - strings to compare
Return: Negative is returned if str1 < str2, zero is returned if
str1 == str2, positive is returned if str1 > str2.
See Also: strncmp, strcmp
-------------------------------------------------------------------------
Name: strcpy
Synopsis: char *strcpy(dest,source)
char *dest, *source;
Function: Copies one string onto another, the NULL terminator is copied.
Arguments: dest - destination string
source - source string
Return: dest is returned
See Also: strncpy
-------------------------------------------------------------------------
Name: strcspn
Synopsis: long strcspn(str,reject)
char *str, *reject;
Function: Finds the length of a string not consisting of characters
in another string.
Arguments: str - string to search
reject - string of characters that str is searched for
Return: Length of prefix of str consisting of characters NOT in reject.
See Also: strspn
-------------------------------------------------------------------------
Name: strerror
Synopsis: char *strerror(err)
long err;
Arguments: err - an error code, usually the global variable errno
Return: Returns a string corresponding to an error number.
-------------------------------------------------------------------------
Name: strlen
Synopsis: long strlen(str)
char *str;
Function: Computes the length of string.
Arguments: str - string to compute the length of
Return: Length of the string
-------------------------------------------------------------------------
Name: strncat
Synopsis: char *strncat(dest,source,n)
char *dest, *source;
long n;
Function: Concatenates up to n characters onto dest from source.
Arguments: dest - destination string
source - source string
n - maximum number of characters to concatenate
Return: dest is returned.
See Also: strcat
-------------------------------------------------------------------------
Name: strncmp
Synopsis: short strncmp(str1,str2,n)
char *str1, *str2;
long n;
Function: Compare at most n characters of two strings.
Arguments: str1, str2 - strings to compare
n - maximum number of characters to copy
Return: Negative is returned if str1 < str2, zero is returned if
str1 == str2, positive is returned if str1 > str2.
See Also: strcmpa, strcmp
-------------------------------------------------------------------------
Name: strncpy
Synopsis: char *strncpy(dest,source,n)
char *dest, *source;
long n;
Function: Copies at most n characters from source to dest. The string is
NULL terminated.
Arguments: dest - destination string
source - source string
n - maximum number of characters to copy
Return: dest is returned
See Also: strcpy
-------------------------------------------------------------------------
Name: strnrv
Synopsis: char *strnrv(str,n)
char *str;
long n;
Function: Reverses at most n characters of a string. For example
strnrv("Hello World",5) => "olleH World".
Arguments: str - string to reverse
n - maximum length of the string to reverse
Return: str is returned
See Also: strrv
-------------------------------------------------------------------------
Name: strpbrk
Synopsis: char *strpbrk(str,search)
char *str, *search;
Function: Searches for one of a string of characters in a string.
Arguments: str - string to search
search - string of characters to search for
Return: A pointer to the first character of str belonging to search is
returned, if no match is found NULL is returned.
See Also: strspn
-------------------------------------------------------------------------
Name: strrchr
Synopsis: char *strrchr(str,c)
char *str;
short c;
Function: Finds the last occurence of a character in a string.
Arguments: str - string to search
c - string to search for
Return: A pointer to the last occurence of c in str is returned, if
no match is found NULL is returned.
See Also: strchr
-------------------------------------------------------------------------
Name: strrv
Synopsis: char *strrv(str)
char *str;
Function: Reverses the characters in a string. For example:
strrv("Kasak") => "kasaK"
Arguments: str - string to reverse
Return: str is returned
See Also: strnrv
-------------------------------------------------------------------------
Name: strspn
Synopsis: long strspn(str,search)
char *str, *search;
Function: Finds the length of a string consisting of characters
in another string.
Arguments: str - string to search
search - string of characters that str is searched for
Return: Length of prefix of str consisting of characters in search.
See Also: strcspn
-------------------------------------------------------------------------
Name: strstr
Synopsis: char *strstr(str,search)
char *str;
char *search;
Function: Finds a string in another string.
Arguments: str - string to search
search - string to search for
Return: Returns a pointer to the string in str that matches search,
if the string is not found NULL is returned.
-------------------------------------------------------------------------
Name: strtok
Synopsis: char *strtok(str,delim)
char *str;
char *delim;
Function: A sequence of calls splits the string str into tokens, each
delimited by a character in delim. The first call to strtok
must be with a non-NULL str argument. The argument is remembered
by strtok for subsequent calls. The first token is found by
searching for characters not in delim. When a token is found
the character just after the token is over-written with a NULL
and a pointer to the token is returned. Each subsequent call to
strtok, indicated by a NULL str argument, will return the next
token in str. NULL is returned when there are no further tokens
in str.
Arguments: str - string to split tokens out of
delim - string consisting of legal delimiters
Return: Tokens split out from the string are returned, or NULL when
there are no more tokens in the string.
-------------------------------------------------------------------------
Name: strupr
Synopsis: char *strupr(str)
char *str;
Function: Converts a string to all upper case letters.
Arguments: str - string to convert
Return: str is returned
-------------------------------------------------------------------------
6) MEMORY OPERATION FUNCTIONS. These functiuons have become common
for most implementations of the C library. They all operate
on blocks of memory of a certain size instead of null terminated
strings as with the string functions.
-------------------------------------------------------------------------
Name: bcpm
Synopsis: short bcmp(ptr1,ptr2,size)
void *ptr1, *ptr2;
long size;
Function: Compares two blocks of memory.
Arguments: ptr1, ptr2 - pointers to two blocks of memory to compare
size - maximum number of bytes to compare
Return: Negative is returned if ptr1 > ptr2, zero is returned if
ptr1 == ptr2, positive is returned if ptr1 < ptr2.
See Also: memcmp
-------------------------------------------------------------------------
Name: bcopy
Synopsis: void bcopy(source,dest,size)
void *source, *dest;
long size;
Function: Copies a block of memory making sure that overlapping blocks
are copied correctly.
Arguments: source - pointer to source block of memory
dest - pointer to destination block of memory
size - number of bytes to copy
See Also: memcpy
-------------------------------------------------------------------------
Name: bzero
Synopsis: void bzero(ptr,size)
void *ptr;
long size;
Function: Sets a block of memory to all zeros.
Arguments: ptr - pointer to block of memory
size - number of bytes to set to zero
See Also: memset
-------------------------------------------------------------------------
Name: memccpy
Synopsis: void *memccpy(dest,source,stop,size)
void *dest, *source;
unsigned short stop;
long size;
Function: Copies a block of memory until a certain byte is reached or
until the maximum number of bytes is reached.
Arguments: dest - pointer to block of memory to copy to
source - pointer to block of memory to copy from
stop - if the stop character is encoutered then the copy
operation is stopped after the stop character is copied to
the destination block.
size - maximum number of bytes to copy
Return: If the stop character is encountered then a pointer to the
next byte after the stop character is returned, if the stop
character is never encounterd then NULL is returned.
-------------------------------------------------------------------------
Name: memchr
Synopsis: void *memchr(ptr,chr,size)
void *ptr;
unsigned short chr;
long size;
Function: Finds a character in a block of memory.
Arguments: ptr - block of memory to search
chr - character to search for
size - maximum number of bytes to search
Return: If the character is found then a pointer to it is returned.
NULL is returned if the character is not found.
-------------------------------------------------------------------------
Synopsis: short memcmp(ptr1,ptr2,size)
void *ptr1, *ptr2;
long size;
Function: Compares two blocks of memory.
Arguments: ptr1, ptr2 - pointers to two blocks of memory to compare
size - maximum number of bytes to compare
Return: Negative is returned if ptr1 < ptr2, zero is returned if
ptr1 == ptr2, positive is returned if ptr1 > ptr2.
-------------------------------------------------------------------------
Name: memcpy
Synopsis: void *memcpy(dest,source,size)
void *dest, *source;
long size;
Function: Copies a block of memory making sure that overlapping blocks
are copied correctly.
Arguments: dest - pointer to destination block of memory
source - pointer to source block of memory
size - number of bytes to copy
Return: dest is returned
-------------------------------------------------------------------------
Name: memmove MACRO
Synopsis: #include "string.h"
void *memmove(dest,source,size)
void *dest, *source;
long size;
Function: Copies a block of memory making sure that overlapping blocks
are copied correctly.
Arguments: dest - pointer to destination block of memory
source - pointer to source block of memory
size - number of bytes to copy
Return: dest is returned
-------------------------------------------------------------------------
Name: memset
Synopsis: void *memset(ptr,chr,long)
void *ptr;
unsigned short chr;
long size;
Function: Sets all bytes in a block of memory to a single value.
Arguments: ptr - pointer to a block of memory
chr - value to set each byte to
size - number of bytes to set
Return: ptr is returned
-------------------------------------------------------------------------
Name: memswap
Synopsis: void memswap(ptr1,ptr2,size)
void *ptr1, *ptr2;
long size;
Function: Swaps the contents of two blocks of memory.
Arguments: ptr1, ptr2 - blocks of memory to swap
size - number of bytes to swap
-------------------------------------------------------------------------
7) FORMAT CONVERSION FUNCTIONS. Conversions from numbers to
ASCII characters and back.
-------------------------------------------------------------------------
Name: atof
Synopsis: double atof(str)
char *str;
Function: Converts a character string representing a floating point number
into an IEEE format double precision floating pointer number.
Arguments: str - string to convert
Return: A floating point number, zero is returned if no conversion can
be made.
-------------------------------------------------------------------------
Name: atoi
Synopsis: short atoi(str)
char *str;
Function: Converts a string representing an integer into a short integer.
Arguments: str - string to convert
Return: A short integer, zero is returned if no conversion can be made.
See Also: stoa
-------------------------------------------------------------------------
Name: atol
Synopsis: long atol(str)
char *str;
Function: Converts a string representing an integer into a long integer.
Arguments: str - string to convert
Return: A long integer, zero is returned if no conversion can be made.
See Also: ltoa
-------------------------------------------------------------------------
Name: ltoa
Synopsis: void ltoa(n,str)
long n;
char *str;
Function: Converts a long integer into a string.
Arguments: n - number to convert
str - string to store the result in
See Also: atol
-------------------------------------------------------------------------
Name: stoa
Synopsis: void ltoa(n,str)
short n;
char *str;
Function: Converts a short integer into a string.
Arguments: n - number to convert
str - string to store the result in
See Also: atoi
-------------------------------------------------------------------------
8) MEMORY ALLOCATION FUNCTIONS. These functions include the standard
heap managment functions as well as lower level functions that were
used to implement the heap managment system. When the program that
has allocated memory through the functions in this section terminates
execution through the exit function all memory allocated from Amiga
DOS is returned to the system. All of the heap managment functions
will try to allocate memory first from FAST memory and then from CHIP
RAM. To allocate memory that is guaranteed to be CHIP RAM (accesable
by the Amiga custom chips) you can use the _alloc() function. The
heap manager operates by allocating blocks of memory from Amiga DOS
in large chunks, then it breaks these blocks up into the sizes that
are requested through heap memory allocation functions. The minimum
size of the blocks allocated from Amiga DOS can be controlled
directly by declaring a global long integer called blocksize and
setting it to some value. The default value for blocksize is 256
blocks (2K bytes), in increments of 8 bytes. Each time the heap
manager allocates memory from Amiga DOS the blocksize variable is
checked, which makes it possible to change the variable on the fly.
-------------------------------------------------------------------------
Name: be_free
Synopsis: void be_free(ptr,size)
void *ptr;
long size;
Function: Makes static memory available to malloc and calloc. If you have
static data structures that will NEVER be used as such again
then you can add them to the free memory list with this
function. If you write into the data pointed to by ptr after
you have added that block to the free memory list then you
stand a good chance of corrupting the free memory list. When the
free memory list for your task is corrupt the system will
when you try to access it with calloc, malloc, or free.
Arguments: ptr - pointer to the block of memory to give to the heap
manager.
size - size of the block of memory
-------------------------------------------------------------------------
Name: calloc
Synopsis: void *calloc(nobj,size)
unsigned long nobj, size;
Function: Allocates and sets to zero an area of memory that is at least
nobj * size bytes. This is a standard C function.
Arguments: nobj - number of objects to allocate
size - size of each object to allocate
Return: A pointer to the newly allocated block of memory. NULL is
returned when the block of memory can't be provided.
See Also: malloc
-------------------------------------------------------------------------
Name: free
Synopsis: free(ptr)
void *ptr;
Function: Returns a block of memory allocated through malloc, calloc or
realloc to the heap manager for future use. This is a
standard C function.
Arguments: ptr - pointer to the block of memory obtained from malloc, calloc
or realloc.
See Also: be_free
-------------------------------------------------------------------------
Name: freeall
Synopsis: freeall()
Function: Returns ALL of the memory allocated by any of the functions
in this section to the system and re-initializes the free
memory list for the heap manager. This will also free all of
the memory used by any files that may be open. Normally this
function is only called when the program has called the exit
function.
-------------------------------------------------------------------------
Name: heap_alloc
Synopsis: void *heap_alloc(size)
long size;
Function: Allocates memory from the heap manager. This function is
used internally to implement malloc and calloc.
Arguments: size - size in bytes of the requested block of memory
Return: A pointer to the newly allocated block of memory. NULL is
returned when the block of memory can't be provided.
See Also: malloc, calloc
-------------------------------------------------------------------------
Name: heap_free
Synopsis: void heap_free(ptr)
void *ptr;
Function: Returns memory to the free list of the heap manager. This
function is used internally to implement free().
Arguments: ptr - pointer to a block of memory obtained from heap_alloc.
See Also: free
-------------------------------------------------------------------------
Name: malloc
Synopsis: void *malloc(size)
unsigned long size;
Function: Allocates memory from the heap manager that is at least
"size" bytes. This is a standard C function.
Arguments: size - size of the requested block of memory
Return: A pointer to the newly allocated block of memory. NULL is
returned when the block of memory can't be provided.
See Also: free
-------------------------------------------------------------------------
Name: malloc_size
Synopsis: unsigned long malloc_size(ptr)
void *ptr;
Function: Computes the number of bytes in an allocated block of memory
that was obtained from malloc, calloc, realloc, or heap_alloc.
The size is rounded up to the nearest eight bytes.
Arguments: ptr - a pointer to the allocated block of memory.
Return: The size of the allocated block is returned.
-------------------------------------------------------------------------
Name: realloc
Synopsis: void *realloc(ptr,newsize)
void *ptr;
unsigned long newsize;
Function: Changes the size of a block block of memory. The contents will
be un-changed up to the minimum of the old and new sizes. The
block of memory can be freed using free() prior to a call to
realloc so long as no intervening calls to any of the heap
managment functions is made. In order to make enough space
for a larger block of memory is may be necessary to move the
block. This is a standard C function.
Arguments: ptr - pointer to the block of memory to change the size of
Return: A pointer to the new block of memory is returned or NULL if the
request can't be satisfied.
See Also: free
-------------------------------------------------------------------------
Name: sbrk
Synopsis: void *sbrk(size)
unsigned long size;
Function: Allocates memory through Amiga DOS and attaches the block
of memory to the allocated memory list for the current task.
This is a lower level function than the heap managment
functions. The sbrk function has become a standard part of many
C libraries.
Arguments: size - size in bytes of the requested block of memory
Return: A pointer to the newly allocated block of memory is returned, or
-1L if the request can't be satisfied.
-------------------------------------------------------------------------
Name: _alloc
Synopsis: void _alloc(ud,size,requirements)
task_UserData *ud;
long size;
long requirements;
Function: Allocates memory from Amiga DOS and links it into the allocated
memory list for your task. This is the lowest level of memory
allocation available through this library and is used to
implement all of the other memory allocation functions. The
task_UserData pointer can be obtained by a call to GetSTDIO.
Arguments: ud - pointer to the task_UserData structure for your task
size - size in bytes of the memory to be allocated
requirements - memory requirements as described in
exec/memory.h, 0L being just any old block of memory.
The requirements are used directly in a call to the Amiga
AllocMem function.
Return: A pointer to the new block of memory is returned or NULL if the
request can't be satisfied.
See Also: _fre
-------------------------------------------------------------------------
Name: _fre
Synopsis: void _fre(ud,ptr)
task_UserData *ud;
void *ptr;
Function: Frees a block of memory allocated by _alloc or sbrk.
The task_UserData pointer can be obtained by a call to GetSTDIO.
Arguments: ud - pointer to the task_UserData structure for your task
ptr - pointer to a block of memory obtained from _alloc or sbrk.
-------------------------------------------------------------------------
Name: _freall
Synopsis: void _freall(ud)
task_UserData *ud;
Function: Returns all memory allocated by through any of the functions
in this section to Amiga DOS, but does NOT re-initialize the
free list used by the heap manager. The task_UserData pointer
can be obtained by a call to GetSTDIO.
Arguments: ud - pointer to the task_UserData structure for your task
-------------------------------------------------------------------------
9) LINKED LIST FUNCTIONS. Linked lists are used internally in
CClib.library and since the linked list functions are already
in the library they were made public. The structure definitions
for linked lists and nodes are in stdlist.h.
-------------------------------------------------------------------------
Name: add_head
Synopsis: void *add_head(l,size)
_list *l;
long size;
Function: Allocates and clears to zero memory from the heap manager for
a _node structure plus "size" bytes. The node is then added
to the beginning of the linked list.
Arguments: l - linked list to add to
size - size in bytes of the data for this node
Return: A pointer to the data for this node is returned, or NULL if
there is not enough memory.
See Also: remv_node
-------------------------------------------------------------------------
Name: add_tail
Synopsis: void *add_tail(l,size)
_list *l;
long size;
Function: Allocates and clears to zero memory from the heap manager for
a _node structure plus "size" bytes. The node is then added
to the end of the linked list.
Arguments: l - linked list to add to
size - size in bytes of the data for this node
Return: A pointer to the data for this node is returned, or NULL if
there is not enough memory.
See Also: remv_node
-------------------------------------------------------------------------
Name: inst_node
Synopsis: _node *inst_node(size)
long size;
Function: Allocates and clears to zero memory from the heap manager for
a _node structure plus "size" bytes. This function is used
by all of the functions that create a new node.
Arguments: size - size in bytes of the data for this node
Return: A pointer to the new node is returned, or NULL if there isn't
enough memory.
-------------------------------------------------------------------------
Name: put_head
Synopsis: void put_head(l,n)
_list *l;
_node *n;
Function: Adds a node at the beginning of a linked list.
Arguments: l - linked list to add to
n - node to add to the linked list
See Also: remv_head
-------------------------------------------------------------------------
Name: put_tail
Synopsis: void put_tail(l,n)
_list *l;
_node *n;
Function: Adds a node at the end of a linked list.
Arguments: l - linked list to add to
n - node to add to the linked list
See Also: remv_tail
-------------------------------------------------------------------------
Name: remv_head
Synopsis: void *remv_head(l,data)
_list *l;
void **data;
Function: Removes a node from the beginning of a linked list and gives
a pointer to the data for that node. The memory for the
node is not freed.
Arguments: l - linked list to remove from
data - pointer to a memory location where a pointer to the
data for the node will be stored after removing the node
from the beginning of the list
Return: A pointer to the block of memory that was allocated for the
node and its data is returned, or NULL if there are no more
nodes on the list. This memory should be freed using the
free function. For example:
_list *l;
char *data, *ptr;
.
.
.
if( ptr = remv_head(l,&data) )
free(ptr)
See Also: add_head
-------------------------------------------------------------------------
Name: remv_list
Synopsis: void remv_list(l)
_list *l;
Function: Frees all memory associated with a linked list by calling
free for every nide in the list and then for the list
header.
Arguments: l - linked list to free, it is assumed that all of the nodes
on the list and the list header itself are allocated using
heap_alloc, malloc, calloc, or realloc.
-------------------------------------------------------------------------
Name: remv_node
Synopsis: void *remv_node(l,data)
_list *l;
void *data;
Function: Removes a node from a list by first scanning the list for the
data associated with the node and then removing the node from
the list.
Arguments: l - pointer to the list to remove the node from.
data - pointer to the data associated with the node to be
removed
Return: A pointer to the memory allocated for the node and it's data
is returned, NULL is returned if the node with the specified
data can't be found on the list. The pointer can then be used
to free the node and it's data, for example:
if( ptr = remv_node(l,data) )
free(ptr);
-------------------------------------------------------------------------
Name: remv_tail
Synopsis: void *remv_tail(l,data)
_list *l;
void **data;
Function: Removes a node from the end of a linked list and gives
a pointer to the data for that node. The memory for the
node is not freed.
Arguments: l - linked list to remove from
data - pointer to a memory location where a pointer to the
data for the node will be stored after removing the node
from the end of the list
Return: A pointer to the block of memory that was allocated for the
node and its data is returned, or NULL if there are no more
nodes on the list. This memory should be freed using the
free function.
See Also: add_tail
-------------------------------------------------------------------------
Name: r_node
Synopsis: void *r_node(l,n,data)
_list *l;
_node *n;
void **data;
Function: Removes a specific node from a linked list and gives a pointer
to the data for the node.
Arguments: l - linked list to remove the node from
n - node to remove from the list
data - a pointer to the data for this node is stored here
Return: n is returned, or NULL if the list is empty
See Also: remv_node
-------------------------------------------------------------------------
10) SORTING FUNCTIONS, these are all modifications of
C. A. R. Hoare's quicksort algorithm. Two of the functions
are written in C and a third is written in 68000 assembler
for speed.
-------------------------------------------------------------------------
Name: qsort
Synopsis: void qsort(base,n,size,cmp)
void *base;
unsigned long n, size;
short (*cmp)();
Function: Sorts into ascending order an array base[0]...base[n-1] of
objects of size "size".
Arguments: base - pointer to the first element in the array of elements
tp sort.
n - number of elements to sort
size - size of each element of the array
cmp - pointer to comparison function. The comparison function
is passed a pointer to two elements of the array and returns
zero if the two elements are equivalent, negative must be
returned if the first element is less than the second and
and positive must be returned if the first element is greater
than the second. To sort in the opposite order negative is
returned if the first element is greater than the second and
positive is returned if the first element is less than the
second. Here is an example of a comparison function that
will sort strings in descending order:
short cmp(str1,str2)
char *str1, *str2;
{
return( strcmp(str2,str1) );
}
-------------------------------------------------------------------------
Name: quicksort
Synopsis: void quicksort(n,comp,swap,ptr)
unsigned long n;
short (*comp)();
void (*swap)();
void *ptr;
Function: The quicksort function uses the same sorting algorithm as
qsort but it is designed to sort anything, not just arrays
in memory.
Arguments: n - number of elements to sort.
comp - comparison function. The comparison function is passed
the index of the two elements to compare and an auxilery
pointer that you provide. It returns zero if the two elements
are equivalent, negative must be returned if the first element
is less than the second and and positive must be returned if
the first element is greater than the second. To sort in the
opposite order negative is returned if the first element is
greater than the second and positive is returned if the first
element is less than the second.
swap - swaps two elements. The swap function is passed the
index of the two elements to swap and an auxilery pointer you
provide.
ptr - auxilery pointer, can point to anything. This variable
is passed to the comp and swap functions in order to facilitate
the writing of re-entrant code.
Example: Here is an example of a code fragment that would sort a
disk file that consists of records of employees:
include "stdio.h"
#include "stdlib.h"
typedef struct /* employee record */
{
char name[80];
char ssn[20];
} Employee;
typedef struct /* auxillery buffer */
{
FILE *fp;
Employee e1, e2;
unsigned long i1, i2;
} ESortBuf;
static void read_record(fp,i,e) /* reads a single record */
FILE *fp;
unsigned long i;
Employee *e;
{
if( fseek(fp,(long)i*sizeof(Employee),SEEK_SET) )
exit(EXIT_FAILURE);
if( !fread(e,sizeof(Employee),1L,fp) )
exit(EXIT_FAILURE);
}
static void write_record(fp,i,e) /* writes a record to a file */
FILE *fp;
unsigned long i;
Employee *e;
{
if( fseek(fp,(long)i*sizeof(Employee),SEEK_SET) )
exit(EXIT_FAILURE);
if( !fwrite(e,sizeof(Employee),1L,fp) )
exit(EXIT_FAILURE);
}
static void load_records(i1,i2,e) /* loads records */
unsigned long i1, i2;
ESortBuf *e;
{
if( e->i1 != i1 )
{
read_record(e->fp,i1,&e->e1);
e->i1 = i1;
}
if( e->i2 != i2 )
{
read_record(e->fp,i2,&e->e2);
e->i2 = i2;
}
}
static void swap(i1,i2,e) /* swaps two records */
unsigned long i1, i2;
ESortBuf *e;
{
unsigned long iswap;
load_records(i1,i2,e);
write_record(e->fp,i2,&e->e1);
write_record(e->fp,i1,&e->e2);
iswap = e->i1;
e->i1 = e->i2;
e->i2 = iswap;
}
static short comp(i1,i2,e) /* compares two records */
unsigned long i1, i2;
ESortBuf *e;
{
load_records(i1,i2,e);
return( strcmp(e->e1.name,e->e2.name) );
}
void employee_sort(fp,size) /* callable function */
FILE *fp;
unsigned long size;
{
ESortBuf e;
e.fp = fp; /* attach file pointer */
e.i1 = e.i2 = size+1; /* set to invalid */
quicksort(size,comp,swap,&e);
}
-------------------------------------------------------------------------
Name: vquicksort
Synopsis: void vquicksort(n,comp,swap)
unsigned short n;
short (*comp();
void (*swap)();
Function: The vquicksort function is much the same as the quicksort
function except that only up to 64K elements can be sorted
and there is no auxilery argument pointer. Vquicksort is
written in 100% hand optomized assembly language, hence it's
name, very quicksort.
Arguments: n - number of elements to sort.
comp - comparison function. The comparison function is passed
the index of the two elements to compare. It returns zero if
the two elements are equivalent, negative must be returned if
the first element is less than the second and and positive must
be returned if the first element is greater than the second. To
sort in the opposite order negative is returned if the first
element is greater than the second and positive is returned if
the first element is less than the second.
swap - swaps two elements. The swap function is passed the
index of the two elements to swap.
See Also: quicksort
-------------------------------------------------------------------------
11) TIME FUNCTIONS. These are the standard time functions as
described in K&R edition II. Most of these functions use typedefs
and structure definitions that are found in time.h. The tm structure
is explained here.
struct tm
{
short tm_sec; seconds after the minute
short tm_min; minutes after the hour
short tm_hour; hours since midnight
short tm_mday; day of the month
short tm_mon; months since January
short tm_year; years since 1900
short tm_wday; days since sunday
short tm_yday; days since January, 1
short tm_isdst; Not Used
};
-------------------------------------------------------------------------
Name: asctime
Synopsis: char *asctime(tm)
struct tm *tm;
Function: Converts the time in the structure tm to a string of the
form: Sun Jan 1 12:00:00 1989
Arguments: tm - structure obtained from localtime
Return: A pointer to a string is returned. The string is in "static"
memory and may be overwritten by other calls.
See Also: localtime
-------------------------------------------------------------------------
Name: clock
Synopsis: clock_t clock()
Function: Obtains the number of ticks since program execution.
Return: The number of ticks that have passed since the program was
first executed is returned. clock()/CLOCK_TCK gives the time
in seconds.
-------------------------------------------------------------------------
Name: ctime
Synopsis: char *ctime(t)
time_t *t;
Function: Equivalent to asctime(localtime(t)).
Arguments: t - pointer to a time_t obtained from time().
Return: A pointer to a string is returned. The string is in "static"
memory and may be overwritten by other calls.
See Also: asctime, localtime, time
-------------------------------------------------------------------------
Name: difftime
Synopsis: long difftime(t1,t2)
time_t t1, t2;
Function: Obtains the difference between two times in seconds.
t2 - t1.
Arguments: t1, t2 - times to take the difference of
Return: Time difference in seconds.
See Also: time
-------------------------------------------------------------------------
Name: gmtime
Synopsis: struct tm *gmtime(t)
time_t *t;
Function: Same as localtime because Coordinated Universal Time is not
readily available on the amiga.
Arguments: t - pointer to a time_t obtained from time().
Return: Same as localtime.
-------------------------------------------------------------------------
Name: localtime
Synopsis: struct tm *localtime(t)
time_t *t;
Function: Fills out a tm structure from the time obtained from time().
Arguments: t - pointer to a time_t obtained from time().
Return: A tm structure is returned. This structure is located in
"static" memory and will be overwritten by later calls. For
an explanation of the tm structure see the heading for this
section.
See Also: time
-------------------------------------------------------------------------
Name: mktime
Synopsis: time_t mktime(tm)
struct tm *tm;
Function: This function is the opposite of localtime, it converts a
tm structure into a time_t.
Arguments: tm - pointer to a tm structure
Return: A time_t that can be used by the other time functions is
returned.
-------------------------------------------------------------------------
Name: strftime
Synopsis: size_t strftime(s,smax,fmt,tm)
char *s;
size_t smax;
char *fmt;
struct tm *tm;
Function: Formats date and time information into a string according to
a format string.
Arguments: s - string to store the result
smax - maximum number of characters to place in the string
fmt - format string, ordinary characters including the NULL
terminator are copied to the result string. Format specifiers
have the the following possible values:
%a abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%c local date and time representation
%d day of the month
%H hour, 24 hour clock
%I hour, 12 hour clock
%j day of the year, 1-366
%m month, 1-12
%M minute, 00-59
%p AM or PM
%S second 00-59
%U week number of year 00-53
%w weekday, 0-6
%W same as U
%x local date representation
%X local time representation
%y year without century
%Y year with century
%Z "Local"
%% '%'
Return: The number of characters written excluding the NULL terminator
is returned, zero is returned if the result string would be
overflowed.
-------------------------------------------------------------------------
Name: time
Synopsis: time_t time(t)
time_t *t;
Function: Obtains the current time, if the t argument is not NULL then
the time is also assigned to *t.
Arguments: t - pointer to variable to store the current time, or NULL.
Return: The current time is returned.
-------------------------------------------------------------------------
IV) INSTALLATION
In order to use CClib.library you will first have to install the
provided header files in a directory. Some of these header files
have the same name as the ones used by your C and you will have to
make sure that the CClib.library header files are found first. The
best way to assure this is to use the -I or -i option of the compiler.
When using floating point you will have to use the +FI or -fi options
to ensure that IEEE floating point numbers are used, and you will
have to link with the appropriate IEEE floating point library, ma.lib
or lcmieee.lib. Before a prorgam that is linked with the CCLib.library
can execute properly you must copy the file CCLib.library into the
libs: directory on your system disk.
For Aztec C
When you link your program you will have to make sure that it gets
linked in this order: _main.o yourstuff.o ... cclib.lib.... It would
also be a good idea to look at the makefile for the test program;
test.mke.
For Lattice C
When you link your program you will have to make sure that it gets
linked in this order: cc.o lcmain.o yourstuff.o ... lcclib.lib.... It
would also be a good idea to look at the makefile for the test program;
test.lmk.
-------------------------------------------------------------------------
V) THE NUKELIB PROGRAM
The nukelib program is used to remove a library from memory. The
syntax of the program is very simple;
NukeLib <library name>
for example:
NukeLib CClib.library
This will clear CClib.library from memory if no applications are using
it at the time.
-------------------------------------------------------------------------
VI) RELEASE INFORMATION
This release contains:
cclib.doc This Documentation
cclib.lib Aztec 3.6 compatable library of connection routines
lcclib.lib Lattice 5.02 library of connection routines
CClib.library The loadable Amiga C library
nukelib Utility program
test Test program, (written in Aztec)
_main.o Aztec _main replacement
lcmain.o Lattice _main replacement
cc.o Modified Lattice startup routine
source (dir) Source code directory
test.c test program
test.mke Aztec makefile
test.lmk Lattice makefile
_main.c Aztec _main routine
lcmain.c Lattice _main routine
include (dir) Include files required for CClib.library
alloc.h assert.h ccfunc.h ctype.h
errno.h fcntl.h heapmem.h iolib.h
limits.h stat.h stdarg.h stdio.h
stdlib.h stdlist.h string.h time.h
con.zoo Source for connection routine library
Contents of con.zoo ...
Actual Connection routines
102.con 108.con 114.con 120.con 126.con 132.con
138.con 144.con 150.con 156.con 162.con 168.con
172.con 180.con 186.con 192.con 198.con 204.con
210.con 216.con 222.con 228.con 234.con 240.con
246.con 252.con 258.con 264.con 270.con 276.con
282.con 288.con 294.con 30.con 300.con 306.con
312.con 318.con 324.con 330.con 336.con 342.con
348.con 354.con 36.con 360.con 366.con 372.con
378.con 384.con 390.con 396.con 402.con 408.con
414.con 42.con 420.con 426.con 432.con 438.con
444.con 450.con 456.con 462.con 468.con 474.con
48.con 480.con 486.con 492.con 498.con 504.con
510.con 516.con 522.con 528.con 534.con 54.con
540.con 546.con 552.con 558.con 564.con 570.con
576.con 582.con 588.con 594.con 60.con 600.con
606.con 612.con 618.con 624.con 630.con 636.con
642.con 648.con 654.con 66.con 660.con 666.con
672.con 678.con 684.con 690.con 696.con 702.con
714.con 72.con 720.con 726.con 732.con 738.con
744.con 750.con 756.con 762.con 768.con 774.con
78.con 780.con 786.con 792.con 798.con 804.con
810.con 816.con 822.con 84.con 90.con 96.con
all.con Concatenation of connection routines
blocksize.c Contains blocksize global variable
cclib.mke Aztec makefile for library
cclib.lmk Lattice makefile for library
libfile Command file for Lattice librarian
mclibcon.i Metacomco Assembler include file
aclibcon.i Aztec Assembler include file
lclibcon.i Lattice Assembler include file
cclibcon.i Aztec Assembler include file
math.c Contains _math global variable
-------------------------------------------------------------------------
VII) NOTES ON LATTICE C
There is now full support for the Lattice compiler. However due to
some unforseen complications the Lattice startup code had to be
changed in order for this to work. There is an object module called
cc.o that should be used as the replacement for the standard Lattice
startup routine (c.o).
The specific problem with the startup code was this: For programs
that were executed from the CLI the Lattice startup code would place
the name of the program into the commnad string that was passed to
_main and since CCLib.library already does this for you it was
unnecessary to do this in the startup code. The symptoms of the
problem were that argv[0] and argv[1] were both set to the name of
the program. The problem with Workbench programs was far more
serious, the Lattice startup code would reply to the workbench
message after CClib.library had already done so, causing a system
crash.
Because of copyright problems the source for the modified c.a (cc.a)
can't be included here, but since the only changes are commented out
lines, I will list which lines were commented out. If you wish you
may want to do this to c.a so that you have the source to the startup
code. The lines commented out of c.a are: 189-198, 201-206, 227-229,
247-283, and 323-336. In addition the label 'main' on line 283 was
moved to line 284.
If you are doing any floating point in your program it is best to use
IEEE floating point numbers. This is supported by the -fi compiler
switch and lcmieee.lib. This will give you the advantage of extra
speed if you run on a machine with a math coprocessor. IEEE is the
only type used by CCLib.library.
There are new makefiles used for the Lattice compiler. All of the
Lattice makefiles end with .lmk, where the Aztec makefiles end
with .mke.
Lattice 5 supports function prototypes where Aztec 3.6a does not.
The CCLib.library include files can use function prototypes if the
symbol ANSIC is defined. Be sure to include the CCLib.Library
include files ahead of the standard Lattice and Amiga include files.
Thanks to Kevin Kenny for help in creating the Lattice version of
the connection routines and startup code.
-------------------------------------------------------------------------
VIII) REVISION HISTORY
8/89 - V1.0 Initial release, beta testing.
9/89 - V1.1 Major bug fixes, documentation released, extensive testing,
time functions added, nukelib program added.
10/89 - V1.1 Release 2 Support for Lattice C added,
doumentation improvements.
10/89 - V1.2 A bug was fixed where programs that were executed from the
workbench with no tooltype of the form
WINDOW=CON:10/10/100/100/Title would fail because the startup
code had required that standard I/O be opened. Now for workbench
programs with no CON: window the standard I/O will not be opened.
-------------------------------------------------------------------------
IX) COPYRIGHTS AND TRADEMARKS
Aztec C is a trademark of Manx Software Systems.
Lattice C is a trademark of Lattice Inc.
Amiga is a trademark of Commodore Business Machines Inc.
-------------------------------------------------------------------------