File ReCON - record changes to your filesystem
Contents
PAL Tutorial - Filesystem scanner
In the current release, only the PROSE Assembly Language (PAL) is available. So be aware, it's very low-level programming at this time. To learn more about the PROSE Programming Language, visit http://prose.sourceforge.net.
It is suggested you begin with the following articles before attempting this tutorial.
A full list of available tutorials for the PROSE Assembly Language can be found on the tutorials index page.
This tutorial introduces a simple filesystem management tool called File ReCON, designed to demonstate how to scan a filesystem in PAL and how to create your own fixed-width database file.
Running the program
There are a number of PAL source files that need to be compiled and executed. It is recommended you download the tutorial resource files to a new empty directory, e.g. one called frecon, and then compile and execute as follows:
$ prism -m *.pal $ prose *.pro
Overview
When run, the program will first prompt for the name of a database file that it can use (the default choice is frecon.dat) and it will create that file if it has not done so before. The database file stores the result of the last scan.
If this is a new database, you'll then be prompted for the path to scan, before being taken to the main menu:
\ ___\ \ ___\
\/ \ \/ \
| File | | ReCON |
\_____/ \_____/
Database: frecon.dat
# Records: 1
Scan Path: ./src/prose
1. Scan Filesystem 6. Newest Files
2. Biggest Files 7. Oldest Files
3. Smallest Files 8. File Changes
4. Owners Report 9. Dump Database
5. Groups Report
q. Quit
Please select (1-9, q):
Option 1 will scan the requested path, storing the results in the database file and in-memory tables. The information collected during the scan includes file permissions, ownership, size and last modified time. It may also optionally include a SHA-256 checksum calculation based on the file contents. The SHA-256 checksum will allow the "File Changes" option to report when the contents of the file have changed. The SHA-256 algorithm is implemented purely in PAL, which demonstrates the flexibility of the bytecode, however it is considerably slower than if the algorithm were implemented in pure C. To speed it up, one would implement the checksum algorithm as a virtual attribute that could be attached to a file object, or alternatively it could be implemented as a foreign function, once PROSE supports these methods in the future.
Options 2-7 will display the top 10 entries in a number of categories.
Option 8 will scan the file path again and compare against the entries in the database, reporting where changes have been encountered. This will report, for example, changes to file permissions or ownership, changes to file sizes or modification time. If the database contained SHA-256 checksums then changes to the checksum will also be reported.
Option 9 will display the contents of the database in human readable format, enumerating every record within and the data stored about each file.
How it works
Each PAL source file provides a subset of the functionality by defining one or more functions that will be used by the program.
db.pal contains the functions required for handling the database format. The database is a simple fixed width binary format and the comments inside this source file describe the byte offset positions within a record where each new field begins and how long that field is. It uses a psFile object with the psStreamSeek class to move around the file, reading bytes from computed offset positions. It also uses the psFileLock class to set an advisory lock on the database file so that you can't have two running instances of the program try to access the same database simultaneously. These classes are discussed in the ps_stream(5) man page.
The data read and write functions in db.pal also use the attr/import and attr/export instructions to read and write data in binary format to fixed width fields, see attr_import(5) and attr_export(5).
frecon.pal implements the main menu and uses a simple jump table to call the appropriate function.
pathdiff.pal reads the database records into a hierarchy in the nexus underneath .prose.db and then reads the filesystem virtual branch comparing file entries in order to produce a list of differences required by the 'File Changes' feature.
scan.pal contains the code that scans a filesystem virtual branch storing file information in the database.
sha.pal implements a SHA-256 hashing algorithm in PAL. It demonstrates many of the computational features available in PAL although it is very slow compared with a SHA-256 algorithm implemented in pure C, as discussed earlier.
stats.pal manages the tables of statistics and provides the functions required for generating the various reports available within the program.
Resources from this tutorial
Further reading
See the other tutorials available for the PROSE Assembly Language on the tutorials index page.
PROSE is released with detailed manual pages that describe how PAL operates, and how each instruction is used. These manual pages can be read using the man command, for example man pal_intro or man pal_commands, or from the Reference Manual Pages online.
