Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!rosevax!ems!nis!stag!daemon
From: daemon@stag.UUCP
Newsgroups: comp.sys.atari.st
Subject: file i/o functions
Message-ID: <255@stag.UUCP>
Date: Thu, 12-Nov-87 12:29:35 EST
Article-I.D.: stag.255
Posted: Thu Nov 12 12:29:35 1987
Date-Received: Sun, 15-Nov-87 12:01:27 EST
Sender: daemon@stag.UUCP
Lines: 88


  Hopefully the following will help clear up the confusion about file i/o
functions...

  Fread() is one of the macros which calls Gemdos through trap #1.  This is
an exerpt from the <osbind.h> file containing there macros:

#define	Fcreate(fn,mode)		gemdos(0x3C,fn,mode)
#define	Fopen(fn,mode)			gemdos(0x3D,fn,mode)
#define	Fclose(h)			gemdos(0x3E,h)
#define	Fread(h,cnt,buf)		gemdos(0x3F,h,cnt,buf)
#define	Fwrite(h,cnt,buf)		gemdos(0x40,h,cnt,buf)
#define	Fdelete(fn)			gemdos(0x41,fn)
#define	Fseek(where,h,how)		gemdos(0x42,where,h,how)

  These functions work much like the standard low-level i/o calls.  They
use a small integer (returned by Fcreate/Fopen) called a file handle to
refer to the file (the 'h' parameter in other calls).  As was mentioned,
the parameter order is different from the standard low-level i/o calls,
and the 'cnt' parameters are long values rather than the int than is normally
used.  The following are macros which define some of the low-level i/o
calls in terms of their Gemdos equivalents.

#define	open(filename,iomode)	((int)gemdos(0x3D,filename,iomode))
#define	close(h)		((int)gemdos(0x3E,h))
#define	read(h,data,len)	((int)gemdos(0x3F,h,((long)(len)),data))
#define	write(h,data,len)	((int)gemdos(0x40,h,((long)(len)),data))
#define	lread(h,data,len)	(gemdos(0x3F,h,len,data))
#define	lwrite(h,data,len)	(gemdos(0x40,h,len,data))
#define	unlink(filename)	((int)gemdos(0x41,filename))
#define	lseek(h,where,how)	gemdos(0x42,where,h,how)
#define	tell(h)			gemdos(0x42,0L,h,1)

  The creat() call is notably missing from the above due to a bug in the
underlying gemdos 0x3C function which sometimes creates a new file with the
same name as an existing file instead of overwriting the old file.  Thus
creat() is implemented as a function something like this:

int creat(filename, pmode)
	register char *filename;
	register int pmode;
{
	register int rv;

	rv = Fdelete(filename);
	if((rv == 0) || (rv == -33))	/* SUCCESS or FILE-NOT-FOUND */
		rv = Fcreate(filename, pmode);
	return(rv);
}

  Now we come to the fread()/fwrite() functions.  These are standard i/o
functions which deal with STREAMS rather than simply with FILE HANDLES.
Unlike the above, these functions provided buffering and translation of
newlines, if desired.  They are used with fopen()/fclose() functions.
The fopen() function returns a pointer to a FILE structure, which contains
information about the stream that was opened.  The fopen() function also
handles the open()/creat() distinction, creat()ing a file if is doesn't
already exists, etc.  As was said before, this kind of processing does
make the i/o a little slower, but also easier to use.  The fputc()/fgetc()
functions are normally used with streams (getchar()/putchar() are written
in terms of fputc()/fgetc()) to do i/o a character at a time, while
internally buffering the calls to prevent a system call for every character
processed (which would be slow).  The fread()/fwrite() functions do
block i/o on streams, and are buffered just like single characters.

  In summary, you should avoid using Gemdos calls directly, since it is not
portable and it doesn't gain you any speed.  Use the low-level i/o if you're
really concerned about speed and use the stream i/o functions if you're
doing mostly character or string i/o and/or want the buffering done efficiently
for you.

  The preceeding examples were taken from the dLibs public domain standard
library for Alcyon C.  This implmentation is far freer of bugs and much
more efficient in general than the Alcyon/DRI libraries.  dLibs also contains
many Un*x standard functions which were not included in Alcyon/DRI.  You
can get a copy of dLibs with complete source code and documentation by
sending $3 to:

		Dale Schumacher
		399 Beacon Ave.
		St. Paul MN 55104

  Of course, I won't refuse donations of >$3, but I need to at least break
even with buying the disks and mailers and sending them.

                Dale Schumacher
                ..ihnp4!meccts!stag!syntel!dal
                (alias: Dalnefre')