home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / filemanager / softlinks_1 / !SoftLinks / !Help < prev    next >
Text File  |  1996-09-17  |  18KB  |  461 lines
  1. > !SoftLinks.!Help
  2.  
  3. Name:     SoftLinks
  4. Purpose:  Symbolic file links
  5. Author:   Martin Würthner
  6. Status:   FREEWARE
  7. Version:  1.31 (27-Sep-1996)
  8.  
  9. New features of version 1.30:
  10. -----------------------------
  11. - modified for StrongARM compatibility
  12. - links are shorter now: they only take the length of the source file's
  13.   full path name
  14. - new SWIs: SoftLinks_CreateLink, SoftLinks_LinksOff, SoftLinks_LinksOn,
  15.             SoftLinks_LinksStatus
  16. - new *-commands: *LinksOff, *LinksOn, *LinksStatus, *CreateLink,
  17.                   *CheckLink
  18. - RISC OS 2 no longer supported
  19. - improved, RISC OS 3 Style Guide compliant user interface
  20.  
  21.  
  22. What are symbolic file links ?
  23. ------------------------------
  24.  
  25. Sometimes I wish I could have one file at several locations on my
  26. hard disc. Simply copying the file does not solve the problem as
  27.  
  28. 1) the copy takes up disc space
  29. 2) the copy is not updated if the original file is edited
  30.  
  31. Symbolic file links overcome both these problems.
  32.  
  33. A file link looks like a file but it is in fact a reference to a different
  34. file (the so-called source file), which may be on another disc or even on
  35. another filing system. It takes almost no disc space (basically the length
  36. of the source file's path name). The term symbolic (or soft) file link
  37. comes from the Unix world. SoftLinks implements symbolic links which means
  38. that the link contains the path name of the source file, and whenever the
  39. link is accessed (e.g. opened for reading), the symolic linking mechanism
  40. substitutes the source files's path name for the name of the link before
  41. the operation is performed on the file. To the outside world, however, it
  42. still seems as if the operation was performed on the file link.
  43.  
  44. The link behaves like a copy of the source file, i.e. you cannot distinguish
  45. the file link from the source file it references. This means that you see
  46. all the characteristics of the source file (e.g. its length, its file type
  47. etc.) in the Filer window.
  48.  
  49. If you access the link, the source file is accessed instead. This means that
  50. if you double click on the link, the source file is run. If you load the
  51. link in an application, the source file is loaded instead. However, it still
  52. looks as if you loaded the link (e.g. the title bar in !Edit shows the name
  53. of the link).
  54.  
  55. You can do anything with a file link that you can do with a normal file,
  56. the whole concept is completely transparent, i.e. applications are not
  57. aware that they access a link instead of a file.
  58.  
  59. So you can, e.g. load a link into !Edit, edit it and re-save it. This
  60. actually alters the source file (but see below for access control).
  61.  
  62. Note that in the Desktop there is no way to find out whether a file
  63. is an actual file or only a link. On the command line, you can use
  64. *CheckLink <filename> to check or use *LinksOff to temporarily switch
  65. of symbolic linking. Note that RISC OS caches directory data, so even
  66. after switching off linking you may see the properties of the source file
  67. in the Filer window instead of those of the link. You may have to close
  68. and re-open the directory window to force RISC OS to re-read the
  69. directory data. A link appears as an untyped file while linking is switched
  70. off or while the SoftLinks module is not loaded.
  71.  
  72. Another possibility to check whether a file is a link or not is to drag the
  73. file onto the window of the !SoftLinks application which will display the
  74. name of the source file if the file is a link.
  75.  
  76. There are also SWI calls SoftLinks_FollowLink and SoftLinks_Off which
  77. correspond to *CheckLink and *LinksOff. See below for further information.
  78.  
  79.  
  80. SoftLinks and directories
  81. -------------------------
  82.  
  83. SoftLinks only works with files, you cannot link directories. If you absolutely
  84. want to provide a "linked" directory or application, you can create the
  85. directory somewhere else and create links to all the files in the source
  86. directory inside the destination directory. This, however, is a quite tiring
  87. job. The SoftLinks front-end could automate this task easily, but it has been
  88. left out deliberately in order to prevent the user from thinking that SoftLinks
  89. does provide linked directories (after all, this is only a workaround as new
  90. files which are created in the source directory do not by magic appear as a new
  91. link in the destination directory). Using the documented SWIs it should be very
  92. easy to write a little program to create "mirror" directories full of links in
  93. case you should need it. You might also try using the *CreateLink command in
  94. conjunction with one of these utilitites that allow you to apply *commands to
  95. each object in a directory (e.g. FilerAct).
  96.  
  97. The SoftLinks module
  98. --------------------
  99.  
  100. The software consists of two parts, the !SoftLinks application and the
  101. SoftLinks module. Note that in order to make links work, only the SoftLinks
  102. module (which is inside the !SoftLinks application) needs to be loaded.
  103. This can be done in the !Boot file. The !SoftLinks application is only a
  104. front-end to create links.
  105.  
  106.  
  107. The !SoftLinks application
  108. --------------------------
  109.  
  110. To create a link install the !SoftLinks application and drag a file to the
  111. icon on the icon bar (or open the window by clicking on the icon and drag
  112. the file onto the window). This file is called the source file.
  113.   If the source file is already a link the words 'Source file is a link to'
  114. in the bottom left of the window and the file name of the source file of the
  115. link is displayed.
  116.   The radio buttons can be used to specify the desired access level of the
  117. link. The default is 'read/write/overwrite'.
  118.   Drag the file icon to a directory display or fill in a file name and press
  119. on the Create link button in order to create a link to the source file. Note
  120. that you can create several links to one file.
  121.  
  122.  
  123. SoftLinks and LinkFS
  124. --------------------
  125.  
  126. There is another piece of software offering links: LinkFS (written by
  127. Tom Hughes).
  128.  
  129. It uses an image filing system (RISC OS 3 only) to provide linked directories.
  130. However, it does not provide file links.
  131.   SoftLinks does it the other way round, i.e. it provides file links only but
  132. not linked directories. So depending on what you want to use the links for,
  133. you may as well have a look at LinkFS. SoftLinks and LinkFS are mutually
  134. compatible, so you may use them simultaneously.
  135.  
  136. (Since this manual was written, some more similar pieces of software have
  137. emerged, and I will not comment on these).
  138.  
  139. Access control
  140. --------------
  141.  
  142. There are three different access levels of file links:
  143.   
  144. 1) read-only links
  145.  
  146.    Only reading operations are carried out on the source file. An error is
  147.    reported if an attempt is made to overwrite the link or to open it
  148.    with write access.
  149.    
  150. 2) read/write links
  151.  
  152.    All reading operations and opening the file for read/write access are
  153.    carried out on the source file. An error is reported if an attempt is
  154.    made to overwrite the link or to create a new file in its place.
  155.  
  156. 3) read/write/overwrite links
  157.  
  158.    The most powerful (and most dangerous) kind of file link:
  159.    All reading, writing and overwriting operations are carried out on the
  160.    source file.
  161.    This means that the file can be edited and saved back and the source
  162.    file is affected instead! Thus, the base file and the link are on the
  163.    same level. If you alter one of them, the changes are reflected in both
  164.    files.
  165.  
  166. These access levels are independent of the access attributes of the source
  167. file. Of course, the access restrictions of the source file apply, too. This
  168. means that you cannot write to the link if the source file is locked or does
  169. not have write access.
  170.  
  171. Note that it is not possible to change the access level of a link. Changing
  172. the file attributes of the link (e.g. using the Filer menu entry 'Access'
  173. does not affect the access level of the link).
  174.  
  175.  
  176. Deleting links:
  177. ---------------
  178.  
  179. As a link is only a special file you can delete it as any other file.
  180.  
  181. Note that deleting the link *never* affects the source file !
  182.  
  183. If you delete a link, the link only is deleted and its source file remains
  184. intact. If you delete the source file while there are any links to it, the
  185. result is that you get an error ('file xxx not found') if you try to
  186. access the link. In this case the only thing you can do is to delete the
  187. link (or to re-create the base file).
  188.  
  189. However, using the Filer to delete a link which has no existing associated
  190. source file fails because RISC OS is clever and checks whether the file is
  191. there in the first place. Of course, as the file is a symbolic link,
  192. what RISC OS sees is that the source file is *not* there, so an error is
  193. reported. The only way to delete the link in this case is to use the
  194. *remove command as this does *not* check whether the file to be deleted
  195. exists.
  196.  
  197.  
  198. Other points:
  199. -------------
  200.  
  201. Changing the directory information (e.g. file type, date stamp) is always
  202. allowed. So changing the file type of either the source file or of the link
  203. is reflected in both files even if the link is read-only.
  204.  
  205. Of course you may have as many links to a file as you want. It is however
  206. not allowed to have a link to a link. The !SoftLinks application simply
  207. creates another link to the source file if you try to create a link to a
  208. link. The SWI SoftLinks_Create and the command *CreateLink return an
  209. error in this case.
  210.  
  211.  
  212. Copying:
  213. --------
  214.  
  215. When copying a file link using the RISC OS2 non-interactive copy or when
  216. using the *Copy command, the link itself is copied, i.e. copying a link
  217. simply creates a new link to the source file.
  218.  
  219. When using the RISC OS3 interactive copy in the desktop (with FilerAction),
  220. the source file is copied, so what you get is not another link, but a copy
  221. of the source file.
  222.  
  223.  
  224. *-commands provided by the SoftLinks module:
  225. --------------------------------------------
  226.  
  227. Since version 1.23, the SoftLinks module provides the following *-commands:
  228.  
  229. --------------------------------------------
  230. *LinksOff
  231.  
  232. Switch symbolic linking off temporarily. To re-enable the linking mechanism,
  233. each execution of *LinksOff must be matched by one execution of *LinksOn.
  234. See SWI SoftLinks_LinksOff.
  235.  
  236. --------------------------------------------
  237. *LinksOn
  238.  
  239. Re-enable symbolic linking. See SWI SoftLinks_LinksOn.
  240.  
  241. --------------------------------------------
  242. *LinksStatus
  243.  
  244. Displays whether symbolic linking is enabled or not. The number displayed is
  245. the on returned by the SWI SoftLinks_LinksStatus.
  246.  
  247. --------------------------------------------
  248. *CreateLink <source spec> <destionation spec> [<option>]
  249.  
  250. Creates a new symbolic link at the destination which refers to the source
  251. file. The source file must exist and there must not be a file already at
  252. the destination location.
  253.  
  254. You are strongly advised to give a full path name as the source spec. The name
  255. is interpreted each time the link is accessed so specifying a leaf name only
  256. may lead to unpredictable results. Note that the source spec is OS_GSTrans'ed
  257. so you might include system variables. Future versions of SoftLinks might
  258. canoniclise the source spec.
  259.  
  260. The option, if present must be one of the following characters (if no option
  261. is present, r is the default):
  262. r      read-only link
  263. w      read-write link
  264. o      link with read-write-overwrite access
  265.  
  266. *CheckLink <file>
  267.  
  268. Checks whether a file is a normal file or a link.
  269.  
  270.  
  271. SWIs provided by the SoftLinks module:
  272. --------------------------------------
  273.  
  274. SWI SoftLinks_FollowLink (&46A40)
  275.  
  276. check whether a file is a link or a normal file
  277.  
  278. in : R1 = path name of file to be checked
  279.  
  280. out: R0 = 0 if file is no link
  281.           1 if file is a link
  282.      R1 = path name of source file which is referred to by link (if R0=1)
  283.  
  284.  
  285. Since version 1.22, SoftLinks provides the following additional SWIs:
  286.  
  287. --------------------------------------
  288. SWI SoftLinks_CreateLink (&46A41)
  289.  
  290. create a new symbolic link
  291.  
  292. in : R0 = 0 for a read-only link
  293.           1 for a read-write link
  294.           2 for a read-write-overwrite link
  295.      R1 = filename of source file (i.e. of the source file the link is
  296.                                    supposed to refer to)
  297.      R2 = filename of destination file (i.e. of the link to be created)
  298.  
  299. out: all registers preserved
  300.  
  301. Errors: Source file does not exist
  302.         Destination file exists
  303.         Source file is a link
  304.         
  305. The SWI fails if the source file does not exist or if the source file
  306. exists, but it is a link. In order to prevent the user from accidentially
  307. overwriting the source file by specifying the files in the wrong order,
  308. the SWI does not overwrite files, i.e. if the destination file exists
  309. already, it returns an error.
  310.  
  311. You are strongly advised to give a full path name as the destination file
  312. name. The name is interpreted each time the link is accessed so specifying
  313. a leaf name only may lead to unpredictable results. Note that in contrast to
  314. *CreateLink, the source name is not GSTrans'ed so if you include system
  315. variables in the source filename, the variable is evaluated every time the
  316. link is accessed. Future versions of SoftLinks might canoniclise the source
  317. filename.
  318.  
  319. --------------------------------------
  320. The following SWIs work similar to the Hourglass_On and Hourglass_Off
  321. calls. While the status is > 0, linking is switched off. Each call to
  322. SoftLinks_LinksOff increases the status, each call to SoftLinks_LinksOn
  323. decreases it (if the status is 0 already, calls to SoftLinks_LinksOn
  324. are ignored). SoftLinks_LinksStatus returns the status.
  325.  
  326. SWI SoftLinks_LinksOff (&46A42)
  327.  
  328. switch linking mechanism off
  329.  
  330. in : -
  331. out: R0 = number of times SoftLinks_LinksOn has to be called until the
  332.           linking mechanism is on again
  333.  
  334. --------------------------------------
  335. SWI SoftLinks_LinksOn (&46A42)
  336.  
  337. switch linking mechanism on again (if SoftLinks_LinksOff has been
  338. called several times you have to call SoftLinks_LinksOn the same
  339. number of times in order to enable linking)
  340.  
  341. in : -
  342. out: R0 = number of times SoftLinks_LinksOn has to be called until the
  343.           linking mechanism is on again
  344.  
  345. --------------------------------------
  346. SWI SoftLinks_LinksStatus (&46A42)
  347.  
  348. in : -
  349. out: R0 = number of times SoftLinks_LinksOn has to be called until the
  350.           linking mechanism is on again
  351.  
  352.  
  353. Technical information:
  354. ----------------------
  355.  
  356. Links are implemented as untyped files with special load and execution
  357. addresses: load address &400, execution address &400,&401 or &402
  358. respectively for read-only, read/write, read/write/overwrite links.
  359. (It is very unlikely that this clashes with other files as the load and
  360. execution addresses are too low to be sensible).
  361. Additionally, they contain the word SOFTLINK and the version number
  362. (currently 100) at the beginning of the file. In the current version
  363. the link simply contains the path name (null-terminated) of the source
  364. file that is referenced by it at offset 11 of the file (i.e. after the
  365. identification "SOFTLINK100" at the beginning).
  366.  
  367. The SoftLinks module claims the OS_File, OS_GBPB, OS_FSControl and the
  368. OS_Find vector and checks whether the file which is to be accessed is a
  369. normal file or a link. If it is a link, the path name of the source file
  370. is substituted, the vector is called, and the original name is restored
  371. before passing control back to the caller of the vector.
  372. All relevant operations of RISC OS 2 and RISC OS 3 (namely most of the
  373. OS_File, OS_Find and OS_GBPB calls and one OS_FSControl call) are monitored
  374. by the SoftLinks module.
  375.  
  376. Not all calls are supported by the SoftLinks module. So when using
  377. *EX or *FileInfo, you can see the real nature of the file link: An
  378. unstamped file with load/execution address. However, this is no problem,
  379. as all SWIs that can be used by applications to read information about
  380. the file or to read the file itself are supported.
  381.  
  382. Operations that access the link itself instead of the source file are:
  383.   all OS_FSControl calls, exception: 4 (RUN a file)
  384.   among their corresponding *commands are: *Copy, *Wipe, *Fileinfo, *Ex
  385.   
  386. As OS_Find which is used to open/close files is among the calls that are
  387. intercepted by the SoftLinks module, opening a link always opens the
  388. source file. Therefore, all calls which operate on open files work.
  389.  
  390.  
  391. Problems:
  392. ---------
  393.  
  394. Until now I found only one application that refused to work together with
  395. SoftLinks, and this is DDT.
  396.   If a C source file is a file link, compilation works well, but if you try
  397. to debug the application using DDT, it complains that it cannot find the
  398. source file. This is because DDT removes all vector claimants and gains
  399. control of the vectors itself. So while DDT is running to debug a program,
  400. symbolic linking does not take place (at least not for files which are
  401. accessed by DDT itself).
  402.  
  403. An interesting point is that SoftLinks works well with Compression
  404. (Computer Concepts), i.e. the source file may be compressed, or the link,
  405. or both, it simply works!
  406.  
  407.  
  408. History:
  409. --------
  410.  
  411. Version 1.00 (22-Apr-1993)
  412.  
  413. Version 1.01 (05-May-1993):
  414.   bug removed: the system crashed if a directory was deleted that had a
  415.                filer directory viewer open on it
  416.  
  417. Version 1.10 (25-Jun-1993):
  418.   bug removed: Frontend application did not run under RISC OS 2
  419.  
  420. Version 1.11 (20-Jul-1993):
  421.   small modification: the 'Create link' icon is shaded until a file is
  422.                       dragged onto the window
  423.  
  424. Version 1.20 (13-Oct-1993):
  425.   now copies over command line parameters when running a file link
  426.  
  427. Version 1.21 (18-May-1996):
  428.   removed all length checks for links; there is no more a fixed length
  429.   of link files
  430.  
  431. Version 1.30 (22-Aug-1996):
  432.   new SWIs:
  433.   SoftLinks_CreateLink
  434.   SoftLinks_LinksOff, SoftLinks_LinksOn, SoftLinks_LinksStatus
  435.   new *-commands:
  436.   *LinksOff, *LinksOn, *LinksStatus, *CreateLink, *CheckLink
  437.   improved user interface
  438.   code checked and modified for StrongARM compatibility
  439.  
  440. Version 1.31 (17-Sep-1996):
  441.   bug introduced with 1.30 removed (*RUNning a link did no longer work)
  442.  
  443. Copyright notes:
  444. ----------------
  445.  
  446. This application and the SoftLinks module are FREEWARE, this means it may
  447. be copied freely provided that no part is modified and that all files
  448. are distributed together.
  449.  
  450. I retain the copyright of all files.
  451.  
  452. Martin Wuerthner
  453. Jahnstrasse 18
  454. 71116 Gaertringen
  455. Germany
  456.  
  457. e-mail: wuerthne@minnie.informatik.uni-stuttgart.de
  458.  
  459. Phone: +049-7034-928986
  460. Fax:   +049-7034-928988
  461.