<!-- Forthmacs Formatter generated HTML output -->
<html>
<head>
<title>Files</title>
</head>
<body>
<h1>Files</h1>
<hr>
<p>
This chapter describes how to use Risc-OS Forthmacs to manipulate disk files.  
<p>
<p>
<h2>Directory and File Name Conventions</h2>
<p>
Standard RiscOS file name conventions apply in all cases.  In particular, the 
directory abbreviations @ (current directory), ^ (parent directory), $ (root 
directory of the disc), &amp; (user root directory), % (current library) work as 
expected, as do the wild card characters # (match a single character) and * 
(match any sequence of characters).  
<p>
In addition to this, Risc-OS Forthmacs fully supports RiscOS system variables.  <em>Forthmacs$Dir</em> 
and <em>Forthmacs$Path</em> are used as in other RiscOS applications.  
<p>
Forthmacs$Path is used deep inside  <code><A href="_smal_BP#207"> fopen </A></code> 
( _fopen in the current version), so whenever you access a file, it's filename 
is relative to Forthmacs$Path.  Of course you can also specify an entire 
pathname like <em>$.!System.myspecial</em> 
<p>
There is one more feature implemented with better portability in mind.  _fopen 
also looks for some DOS/TOS file extensions ( .fth .exe .dat .doc .ind .txt ) 
and converts it into the corresponding RiscOS pathname.  So you can write 
<br><code>    fload risc_os\cold.fth</code><br>
and you load <em>&lt;Forthmacs$Path&gt;risc_os.cold</em> .  Just have look at 
the metacompiler sources if you have them at hand.  
<p>
<p>
<h2>Interactive File Commands</h2>
<p>
The following commands perform various file operations.  These commands are 
intended for interactive use, rather than use from within programs.  Where 2 or 
more names are shown, all the names are equivalent.  Consult the master glossary 
or use the  <code><A href="_smal_BX#32f"> whatis </A></code> command for more 
information.  
<p>
<p><pre>
cd              Changes the current directory
lib             Changes the current library
delete rm del   Deletes a single file or empty directory
wipe            Deletes one or more objects
rename mv       Changes the name of a file
ls              Lists all the objects in a directory
ll              Lists file information within a directory
lcat            Displays all objects in a library
lex             Displays file information for a library
finfo           Gives full file information about specified objects
mkdir           Creates a new directory
fcount          Adds up the size and number of objects held in files
access          Sets objects access
pwd .dir        Displays the name of the current directory
.dfree          Displays the amount of space left on the disk
copy            Copies files and directories
more            Displays the contents of a file
fload           Interprets a Forth source code file
needs           Conditionally interprets a source code file
append-to-file  Redirects output to the end of a file
to-file         Redirects output to a file
shutdown        Shuts down the filing system
save-forth      Writes an executable forth image to the disk
file-exists?    True if the named file already exists
</pre><p>
<p>
<p>
<h2>Programming Interface to Files</h2>
<p>
A file is a sequence of bytes which may be accessed either sequentially or 
randomly.  Disk files may be accessed either way, and sequential and random 
accesses may be arbitrarily interspersed.  
<p>
<p>
<h2>Addressing</h2>
<p>
The bytes within a file may be thought of as being numbered from 0 up to one 
less than the number of bytes in the file.  Files may be accessed either 
sequentially or randomly, and sequential accesses may be freely interspersed 
with random accesses.  For random accesses to files, the address is specified 
with each access.  The address is a 32-bit number, allowing files to be up to 
2**32 bytes (about 4*10^9).  A file may be thought of as an alternate address 
space, allowing things like meta-compilation to a file.  For sequential access, 
each access starts where the previous one ended.  
<p>
<p>
<h2>Special files</h2>
<p>
Files do not have to be stored on disk.  For example, it is possible to set up a 
file which accesses the keyboard, or a file which accesses a memory buffer.  Not 
all operations are possible on all files, for example it is impossible to write 
to the keyboard.  
<p>
<p>
<h2>Extending files</h2>
<p>
If a write operation is performed when positioned at the end of the file, the 
file will be automatically extended.  
<p>
<p>
<h2>Definitions</h2>
<p>
<p>
<strong>file descriptor</strong> denoted in stack diagrams by "fd".  A number 
that is used to refer to a file once the file has been opened.  
<p>
<strong>file name</strong> denoted in stack diagrams by "filename-pstr".  The 
address of a packed string which is the name of a file.  See "File Names" above.  
<p>
file pointer denoted in stack diagrams by "l.addr".  A 32-bit number which is 
the position in the file (the byte number) where the next sequential access will 
start.  Each file descriptor has a separate file pointer associated with it.  
<p>
File programming interface words: 
<p>
The following words are used to access the bytes within a file.  They are 
grouped by similar function.  For more information, consult the master glossary.  
<p>
<p>
<h2>Preparing a File for Access</h2>
<p>
<p><pre>
fopen            Prepares a disk file for later access
read            Signifies to open the file as an input file
write           Signifies to open the file as an output file
modify          Signifies to open as an input/output file
string-fopen    Prepares a memory file for later access
reading         Prepares an input file for later access
writing         Prepares an output file for later access
read-open       Prepares an input file for later access
write-open      Prepares an output file for later access
new-file        Prepares an output file for later access
appending       Prepares an output file for later access
append-open     Prepares an output file for later access
ifd             User Variable used by reading and read-file
ofd             User Variable used by writing appending etc
fclose          Stops accessing a file
close-files     Closes all currently open files
</pre><p>
<p>
<p>
<h2>Reading and Writing a File</h2>
<p>
<p><pre>
fputc                   Writes a character
fgetc                   Reads a character
file!                   Writes a character
file@                   Reads a character
fputs                   Writes a string
fgets                   Reads a string
fgetword                Reads a space-delimited string
fgettill                Reads a delimited string
fflush                  Cleans out the file buffer
</pre><p>
<p>
<p>
<h2>Positioning within a file</h2>
<p>
<p><pre>
fseek           Changes the position within the file
+fseek          Changes the position within the file
fseek-from-end  Changes the position within the file
ftell           Tells the position within the file
fsize           Tells the size of the file
skipcword       Skips past a character in the file
fexit           Ignore the rest of this file
</pre><p>
<p>
<p>
<h2>Interpreting source code files</h2>
<p>
<p><pre>
"load           Interprets a Forth source code file
(load           Interprets a Forth source code file
</pre><p>
<p>
<p>
<h2>Directory operations</h2>
<p>
<p><pre>
make            Creates a new file
(delete         Deletes a single file or empty directory
(rename         Changes the name of a file
(cd             Changes the current directory
(mkdir          Creates a new directory
(files          Displays file names matching a pattern
(size           Displays the sizes of files matching a pattern
(filetype       Sets the filetype
(filecount      counts number and size of objects
file-protection Contains the attributes for newly-created files
</pre><p>
<p>
<p>
<h2>Executing binary program files</h2>
<p>
<p>
<h2>Shell and cli</h2>
<p>
You may also freely use the RiscOS command line interface.  The following 
commands may be useful and see the glossary for more details.  
<br><code>    "shell sh sh[ getenv</code><br>
<p>
<p>
<h2>File Utilities</h2>
<p>
Several file utility programs are not already compiled into Risc-OS Forthmacs, 
but are provided in source code form.  A file utility program may be loaded with 
the  <code><A href="_smal_BM#204"> fload </A></code> command.  Each file 
contains a description of how to use it.  These utilities provide good examples 
of how to write programs to access files.  
<p>
<p><pre>
extend.runtime
extend.showspace
extend.stackcheck
extend.showstack
extend.arm.runtimer
extend.arm.tasktool
extend.arm.sqroot
lib.xprint
lib.hexify
lib.srec
lib.clock
lib.compatible
lib.blktools
lib.block
lib.blockio
lib.blockld
lib.arm.debug
lib.debug
lib.arm.debugm
risc_os.Versions
risc_os.whatis_doc
risc_os.whatis_ind
!Forthmacs.risc_os.serial_dev
!Forthmacs.lib.Xmodem
!Forthmacs.lib.interval
!Forthmacs.lib.modem+
!Forthmacs.lib.connect
!Forthmacs.tools.modem
tools.debugger
tools.tracer
tools.blocks
tools.modem
</pre><p>
<p>
</body>
</html>
