• FsObj

FsObj interface

FsObj is Plash's object-based interface for accessing file, directory and symlink objects.

Implementations

• FsObjReal: provides access to "real" file and directory objects implemented by the Linux kernel

• FsObjReadOnly: a proxy object that allows only read access to the object being wrapped

• FsObjCopyOnWrite: layered/copy-on-write directories

• FsObjUnion: union directories

• FsObjFab: in-memory-only directories and symlinks

• FsObjMountTable: proxy object for implementing namespaces

Methods

Methods common to files, directories and symlinks:

• fsobj_type() -> int

  • Returns an integer indicating whether the object is a file, directory or symlink.
  • Unix domain sockets and other devices are classed as files.

• fsobj_stat() -> struct stat

• fsobj_utimes(struct timeval atime, struct timeval mtime)
• fsobj_chmod(int mode)

Methods for files:

• file_open(int flags) -> file_descriptor

  • Open the file, returning a file descriptor. This method does not create a new file in a directory; see dir_create_file for that.
• file_socket_connect(file_descriptor socket_fd)
  • Connect an existing socket file descriptor to an existing Unix domain socket.

Methods for directories:

• dir_traverse(string leafname) -> object

  • Get an object inside the directory by its leafname. This will only traverse one level of the directory hierarchy.

  • If the child object is a symlink, returns a symlink object. It will not follow the symlink.

• dir_list() -> list <struct dirent>

• dir_create_file(string leafname, int flags, int mode) -> file_descriptor

  • Create a file, returning a file descriptor. Fails if an object already exists under that name (i.e. adds O_EXCL).
• dir_mkdir(string leafname, int mode)
• dir_symlink(string leafname, string link_dest)
• dir_rename(string leafname, object dest_dir, string dest_leafname)
• dir_link(string leafname, object dest_dir, string dest_leafname)
• dir_unlink(string leafname)
• dir_rmdir(string leafname)
• dir_socket_bind(string leafname, file_descriptor socket_fd)
  • Create a new Unix domain socket in the filesystem, binding the given socket file descriptor to it.

Methods for symlinks:

• symlink_readlink() -> string

Discussion

This interface does not provide any equivalent to the ".." path element. There is no way to get an object's parent directory. This is an essential property for an interface that follows CapabilityDiscipline. Plash implements the ".." path element in another layer on top of this interface; see DirStacks.

dir_traverse() only traverses one level down the directory hierarchy. This is not very efficient for interprocess or distributed use; resolving a pathname will involve multiple RPCs. We may need to add another method for traversing multiple levels.

Possible future changes

The dir_link() method has an odd interface: it is invoked on the source directory, taking the destination directory as an argument. A more conventional interface would be to invoke dir_link() on the destination directory, passing the object to link, with no directory argument:

• dir_link(string leafname, object obj)

"get_child" might be a better method name than "traverse".