home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / forthmacs / htmldocs / !Forthmacs / docs / html / files < prev    next >
Encoding:
Text File  |  1996-02-23  |  8.9 KB  |  254 lines
  1. <!-- Forthmacs Formatter generated HTML output -->
  2. <html>
  3. <head>
  4. <title>Files</title>
  5. </head>
  6. <body>
  7. <h1>Files</h1>
  8. <hr>
  9. <p>
  10. This chapter describes how to use Risc-OS Forthmacs to manipulate disk files.  
  11. <p>
  12. <p>
  13. <h2>Directory and File Name Conventions</h2>
  14. <p>
  15. Standard RiscOS file name conventions apply in all cases.  In particular, the 
  16. directory abbreviations @ (current directory), ^ (parent directory), $ (root 
  17. directory of the disc), & (user root directory), % (current library) work as 
  18. expected, as do the wild card characters # (match a single character) and * 
  19. (match any sequence of characters).  
  20. <p>
  21. In addition to this, Risc-OS Forthmacs fully supports RiscOS system variables.  <em>Forthmacs$Dir</em> 
  22. and <em>Forthmacs$Path</em> are used as in other RiscOS applications.  
  23. <p>
  24. Forthmacs$Path is used deep inside  <code><A href="_smal_BP#207"> fopen </A></code> 
  25. ( _fopen in the current version), so whenever you access a file, it's filename 
  26. is relative to Forthmacs$Path.  Of course you can also specify an entire 
  27. pathname like <em>$.!System.myspecial</em> 
  28. <p>
  29. There is one more feature implemented with better portability in mind.  _fopen 
  30. also looks for some DOS/TOS file extensions ( .fth .exe .dat .doc .ind .txt ) 
  31. and converts it into the corresponding RiscOS pathname.  So you can write 
  32. <br><code>    fload risc_os\cold.fth</code><br>
  33. and you load <em><Forthmacs$Path>risc_os.cold</em> .  Just have look at 
  34. the metacompiler sources if you have them at hand.  
  35. <p>
  36. <p>
  37. <h2>Interactive File Commands</h2>
  38. <p>
  39. The following commands perform various file operations.  These commands are 
  40. intended for interactive use, rather than use from within programs.  Where 2 or 
  41. more names are shown, all the names are equivalent.  Consult the master glossary 
  42. or use the  <code><A href="_smal_BX#32f"> whatis </A></code> command for more 
  43. information.  
  44. <p>
  45. <p><pre>
  46. cd              Changes the current directory
  47. lib             Changes the current library
  48. delete rm del   Deletes a single file or empty directory
  49. wipe            Deletes one or more objects
  50. rename mv       Changes the name of a file
  51. ls              Lists all the objects in a directory
  52. ll              Lists file information within a directory
  53. lcat            Displays all objects in a library
  54. lex             Displays file information for a library
  55. finfo           Gives full file information about specified objects
  56. mkdir           Creates a new directory
  57. fcount          Adds up the size and number of objects held in files
  58. access          Sets objects access
  59. pwd .dir        Displays the name of the current directory
  60. .dfree          Displays the amount of space left on the disk
  61. copy            Copies files and directories
  62. more            Displays the contents of a file
  63. fload           Interprets a Forth source code file
  64. needs           Conditionally interprets a source code file
  65. append-to-file  Redirects output to the end of a file
  66. to-file         Redirects output to a file
  67. shutdown        Shuts down the filing system
  68. save-forth      Writes an executable forth image to the disk
  69. file-exists?    True if the named file already exists
  70. </pre><p>
  71. <p>
  72. <p>
  73. <h2>Programming Interface to Files</h2>
  74. <p>
  75. A file is a sequence of bytes which may be accessed either sequentially or 
  76. randomly.  Disk files may be accessed either way, and sequential and random 
  77. accesses may be arbitrarily interspersed.  
  78. <p>
  79. <p>
  80. <h2>Addressing</h2>
  81. <p>
  82. The bytes within a file may be thought of as being numbered from 0 up to one 
  83. less than the number of bytes in the file.  Files may be accessed either 
  84. sequentially or randomly, and sequential accesses may be freely interspersed 
  85. with random accesses.  For random accesses to files, the address is specified 
  86. with each access.  The address is a 32-bit number, allowing files to be up to 
  87. 2**32 bytes (about 4*10^9).  A file may be thought of as an alternate address 
  88. space, allowing things like meta-compilation to a file.  For sequential access, 
  89. each access starts where the previous one ended.  
  90. <p>
  91. <p>
  92. <h2>Special files</h2>
  93. <p>
  94. Files do not have to be stored on disk.  For example, it is possible to set up a 
  95. file which accesses the keyboard, or a file which accesses a memory buffer.  Not 
  96. all operations are possible on all files, for example it is impossible to write 
  97. to the keyboard.  
  98. <p>
  99. <p>
  100. <h2>Extending files</h2>
  101. <p>
  102. If a write operation is performed when positioned at the end of the file, the 
  103. file will be automatically extended.  
  104. <p>
  105. <p>
  106. <h2>Definitions</h2>
  107. <p>
  108. <p>
  109. <strong>file descriptor</strong> denoted in stack diagrams by "fd".  A number 
  110. that is used to refer to a file once the file has been opened.  
  111. <p>
  112. <strong>file name</strong> denoted in stack diagrams by "filename-pstr".  The 
  113. address of a packed string which is the name of a file.  See "File Names" above.  
  114. <p>
  115. file pointer denoted in stack diagrams by "l.addr".  A 32-bit number which is 
  116. the position in the file (the byte number) where the next sequential access will 
  117. start.  Each file descriptor has a separate file pointer associated with it.  
  118. <p>
  119. File programming interface words: 
  120. <p>
  121. The following words are used to access the bytes within a file.  They are 
  122. grouped by similar function.  For more information, consult the master glossary.  
  123. <p>
  124. <p>
  125. <h2>Preparing a File for Access</h2>
  126. <p>
  127. <p><pre>
  128. fopen            Prepares a disk file for later access
  129. read            Signifies to open the file as an input file
  130. write           Signifies to open the file as an output file
  131. modify          Signifies to open as an input/output file
  132. string-fopen    Prepares a memory file for later access
  133. reading         Prepares an input file for later access
  134. writing         Prepares an output file for later access
  135. read-open       Prepares an input file for later access
  136. write-open      Prepares an output file for later access
  137. new-file        Prepares an output file for later access
  138. appending       Prepares an output file for later access
  139. append-open     Prepares an output file for later access
  140. ifd             User Variable used by reading and read-file
  141. ofd             User Variable used by writing appending etc
  142. fclose          Stops accessing a file
  143. close-files     Closes all currently open files
  144. </pre><p>
  145. <p>
  146. <p>
  147. <h2>Reading and Writing a File</h2>
  148. <p>
  149. <p><pre>
  150. fputc                   Writes a character
  151. fgetc                   Reads a character
  152. file!                   Writes a character
  153. file@                   Reads a character
  154. fputs                   Writes a string
  155. fgets                   Reads a string
  156. fgetword                Reads a space-delimited string
  157. fgettill                Reads a delimited string
  158. fflush                  Cleans out the file buffer
  159. </pre><p>
  160. <p>
  161. <p>
  162. <h2>Positioning within a file</h2>
  163. <p>
  164. <p><pre>
  165. fseek           Changes the position within the file
  166. +fseek          Changes the position within the file
  167. fseek-from-end  Changes the position within the file
  168. ftell           Tells the position within the file
  169. fsize           Tells the size of the file
  170. skipcword       Skips past a character in the file
  171. fexit           Ignore the rest of this file
  172. </pre><p>
  173. <p>
  174. <p>
  175. <h2>Interpreting source code files</h2>
  176. <p>
  177. <p><pre>
  178. "load           Interprets a Forth source code file
  179. (load           Interprets a Forth source code file
  180. </pre><p>
  181. <p>
  182. <p>
  183. <h2>Directory operations</h2>
  184. <p>
  185. <p><pre>
  186. make            Creates a new file
  187. (delete         Deletes a single file or empty directory
  188. (rename         Changes the name of a file
  189. (cd             Changes the current directory
  190. (mkdir          Creates a new directory
  191. (files          Displays file names matching a pattern
  192. (size           Displays the sizes of files matching a pattern
  193. (filetype       Sets the filetype
  194. (filecount      counts number and size of objects
  195. file-protection Contains the attributes for newly-created files
  196. </pre><p>
  197. <p>
  198. <p>
  199. <h2>Executing binary program files</h2>
  200. <p>
  201. <p>
  202. <h2>Shell and cli</h2>
  203. <p>
  204. You may also freely use the RiscOS command line interface.  The following 
  205. commands may be useful and see the glossary for more details.  
  206. <br><code>    "shell sh sh[ getenv</code><br>
  207. <p>
  208. <p>
  209. <h2>File Utilities</h2>
  210. <p>
  211. Several file utility programs are not already compiled into Risc-OS Forthmacs, 
  212. but are provided in source code form.  A file utility program may be loaded with 
  213. the  <code><A href="_smal_BM#204"> fload </A></code> command.  Each file 
  214. contains a description of how to use it.  These utilities provide good examples 
  215. of how to write programs to access files.  
  216. <p>
  217. <p><pre>
  218. extend.runtime
  219. extend.showspace
  220. extend.stackcheck
  221. extend.showstack
  222. extend.arm.runtimer
  223. extend.arm.tasktool
  224. extend.arm.sqroot
  225. lib.xprint
  226. lib.hexify
  227. lib.srec
  228. lib.clock
  229. lib.compatible
  230. lib.blktools
  231. lib.block
  232. lib.blockio
  233. lib.blockld
  234. lib.arm.debug
  235. lib.debug
  236. lib.arm.debugm
  237. risc_os.Versions
  238. risc_os.whatis_doc
  239. risc_os.whatis_ind
  240. !Forthmacs.risc_os.serial_dev
  241. !Forthmacs.lib.Xmodem
  242. !Forthmacs.lib.interval
  243. !Forthmacs.lib.modem+
  244. !Forthmacs.lib.connect
  245. !Forthmacs.tools.modem
  246. tools.debugger
  247. tools.tracer
  248. tools.blocks
  249. tools.modem
  250. </pre><p>
  251. <p>
  252. </body>
  253. </html>
  254.