Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

ps_file - Introduction to PROSE filesystem virtual branch

CONTENTS

Description
Unix Stat Attributes
New File Entries
Deleting File Entries
See Also
Author

The filesystem virtual branch in PROSE provided by the ps_file module supports operations that appear to take place on a branch in the nexus using standard PAL instructions used for navigating and manipulating nodes on a tree, but are back-ended by a mounted filesystem in the running operating system.

The root of the filesystem is identified by an object which has had the psFileHook class associated with it, and a psFilePath attribute identifying the path to a directory underneath which the virtual branch should begin. The top of the virtual branch will also be recognised by the psVirtualBranch class, of which psFileHook is a sub-class.

In the following example, the directory /usr/local is set as the root of a new virtual filesystem branch .prose.code.default.fs_root:

.fs_top   % Set-up top of new virtual fs branch obj/def P0 class/add P0, [psFileHook] attr/add P0, [psFilePath], [/usr/local] obj/commit ![-], [fs_root], P0

Once established, nodes may be sought using normal filesystem pathname semantics underneath the virtual root but in PAL object reference notation, or by the obj/addr instruction, or a walker may be defined with reg/load to iterate the file entries that exist inside the virtual branch. See pal_indices(5), obj_addr(5) and reg_load_walker(5) respectively for further information on these concepts.

The following code examples demonstrate two different ways of addressing the file /usr/local/bin/prose, both methods will obtain a file handle to the same file.

.load_prose   % Get reference with reg/load reg/load P0, ![-fs_root.bin/prose] .addr_prose   % Get reference with obj/addr obj/addr P1, ![-fs_root], [bin], [prose]

When an object is referenced underneath a file branch, it will be a unique object with a unique name representing a handle on that file entry. The object will have the class psFile and will contain the virtual attributes psShortPath, which contains the path to the file entry relative to the virtual branch root, and psFilePath, which additionally includes the pathname prefix that was supplied with the virtual branch top-level container.

Running the above code and following with obj/dump on either P0 or P1 will yield the following output:

.prose.code.default.fs_root.bin/prose:psShortPath=[bin/prose]

The members of the stat(2) structure may be queried against any file object by assigning the psStatUnix class to the psFile object. This will make the following virtual attributes available:

statDevice
	Identifier of the device containing the file entry, or st_dev in the stat structure, represented by a psInteger type.
statInode
	The filesystem inode number uniquely identifying the entry, or st_ino in the stat structure, represented by a psInteger type.
statMode
	File type and permissions, or st_mode in the stat structure, represented by a psInteger type.
statLinks
	Number of hard links, or st_nlink in the stat structure, represented by a psInteger type.
statUid
	User ID of the file owner, or st_uid in the stat structure, represented by a psInteger type.
statUidName
	User name of the file owner, or st_uid converted to the name, represented by a psString type.
statGid
	Group ID of the owner group, or st_gid in the stat structure, represented by a psInteger type.
statGidName
	Group name of the owner group, or st_gid converted to the name, represented by a psString type.
statDeviceSpecial
	Device ID (major/minor number) of a character or block special file, or st_rdev in the stat structure, represented by a psInteger type.
statSize
	Total size of file in bytes, or st_size in the stat structure, represented by a psInteger type.
statBlockSize
	Block size for filesystem I/O, or st_blksize in the stat structure (if provided), represented by a psInteger type.
statBlocks
	Number of 512-byte blocks allocated to the file, or st_blocks in the stat structure (if provided), represented by a psInteger type.
statLastAccess
	Time of last access, or st_atim/st_atime in the stat structure, represented by a psTime type.
statLastModify
	Time of last modification, or st_mtim/st_mtime in the stat structure, represented by a psTime type.
statLastStatusChange
	Time of last status change, or st_ctim/st_ctime in the stat structure, represented by a psTime type.

Timestamps in the statLastAccess, statLastModify and statLastStatusChange attributes will be to nanosecond precision if the filesystem and operating system support it, otherwise to whatever lesser precision is available.

The stat attributes are not refreshed everytime they are queried as they are cached with the file object. If the underlying filesystem attributes have changed, the stat attributes may be refreshed with the obj/refresh instruction.

The following attributes may be modified which results in a dynamic change to the underlying file object:

o	statMode
o	statUid
o	statUidName
o	statGid
o	statGidName
o	statLastAccess
o	statLastModify
o	statSize

New file entries may be created by adding nodes to a virtual file branch. The underlying filesystem will be modified. New entries must contain the class psFile and optionally the class psStatUnix and attribute statMode indicating the file type and file permissions required, as described in stat(2). The following file types may be created in this manner:

S_IFREG (0100000)
	regular file
S_IFBLK (0060000)
	block special device
S_IFDIR (0040000)
	directory
S_IFCHR (0020000)
	character special device
S_IFIFO (0010000)
	FIFO (named pipe)

If the file mode (permissions) only are provided, and the file type is 0, this will be treated the same as a request for a regular file (S_IFREG).

Block special devices (S_IFBLK) and character special devices (S_IFCHR) additionally require the statDevice attribute which encodes the device ID (major number << 8 + minor number).

Sockets (S_IFSOCK) and symbolic links (S_IFLNK) may not be created in this way and require classes of their own.

In the following example, a directory called pidfiles will be created underneath /usr/local with access granted only to the owner:

.create_piddir   % Create ’pidfiles’ directory obj/def P0 class/add P0, [psFile], [psStatUnix] attr/add P0, [statMode], #040700 obj/commit ![-fs_root], [pidfiles], P0

Files may be deleted from a filesystem virtual branch using obj/del and tree/del. The underlying filesystem will be modified.

This mechanism only works on nodes underneath a psVirtualBranch. The psVirtualBranch container may be safely deleted without affecting the filesystem to which it refers. If any file handles are currently open, the psVirtualBranch object will have child nodes due to internal referencing and can in this case only be removed with tree/del. This is also safe, as a recursive delete that began outside of a virtual branch cannot traverse into one.

stat(2), pal_intro(5), pal_commands(5), pal_registers(5), pal_indices(5), ps_stream(5), obj_addr(5), reg_load_walker(5), obj_def(5), obj_commit(5), obj_refresh(5), obj_del(5), tree_del(5), ps_classes(5), ps_attributes(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.