RUMP_ETFS(3)

RUMP_ETFS(3) | Library Functions Manual | RUMP_ETFS(3)

# NAME

`rump_etfs` —
rump kernel host file system interface

# LIBRARY

rump kernel (librump, -lrump)

# SYNOPSIS

`#include <rump/rump.h>`

int
`rump_pub_etfs_register`(const char *key, const char *hostpath, enum rump_etfs_type ftype);

int
`rump_pub_etfs_register_withsize`(const char *key, const char *hostpath, enum rump_etfs_type ftype, uint64_t begin, uint64_t size);

void
`rump_boot_etfs_register`(struct rump_boot_etfs *eb);

int
`rump_pub_etfs_remove`(const char *key);

# DESCRIPTION

The rump ExtraTerrestrial File System (`rump_etfs`) is used to provide access to the host file system namespace within a rump kernel.

The operation is based on registered key values which each map to a hostpath. A key must be an absolute path (i.e. begin with “/”). Multiple leading slashes are collapsed to one (i.e. “/key” is the same as “//key”). The rest of the path, including slashes, is compared verbatim (i.e. “/key/path” does not match “/key//path”).

The hostpath is interpreted in host system context for the current working directory and can be either absolute or relative.

The key is accessible from all rump kernel clients, both local and remote. Note: the keys are not visible via readdir, so you will not see them in directory listings.

The ftype parameter specifies how the etfs file will be presented and does not have to match the host type, although some limitations apply. Possible values are:

`RUMP_ETFS_REG`
  regular file.
`RUMP_ETFS_BLK`
  block device. This is often used when mapping file system images.
`RUMP_ETFS_CHR`
  character device.
`RUMP_ETFS_DIR`
  directory. This option is valid only when hostpath is a directory. The immediate children of the host directory will be accessible inside a rump kernel.
`RUMP_ETFS_DIR_SUBDIRS`
  directory. This option is valid only when hostpath is a directory. This option recursively applies to all subdirectories, and allows a rump kernel to access an entire directory tree.

The interfaces are:

`rump_pub_etfs_register`(key, hostpath, ftype)
  Map key to a file of type ftype with the contents of hostpath.
`rump_pub_etfs_register_withsize`(key, hostpath, ftype, begin, size)
  Like the above, but map only [begin, begin+size] from hostpath. This is useful when mapping disk images where only one partition is relevant to the application. If size is given the special value `RUMP_ETFS_SIZE_ENDOFF`, the underlying file is mapped from begin to the end of the file.
`rump_boot_etfs_register`(eb)
  Unlike the above interfaces, `rump_boot_etfs_register`() can and must be called before `rump_init`(). It causes an etfs key to be available immediately when the root file system is mounted as part of `rump_init`(). The intended use is for example for firmware images to be available immediately when device driver autoconfiguration is run as part of `rump_init`().

  To use `rump_boot_etfs_register`(), the client fills out eb. The layout of eb is as follows:

      struct rump_boot_etfs {
      	/* client initializes */
      	const char *eb_key;
      	const char *eb_hostpath;
      	enum rump_etfs_type eb_type;
      	uint64_t eb_begin;
      	uint64_t eb_size;

      	/* rump kernel initializes */
      	struct rump_boot_etfs *_eb_next;
      	int eb_status;
      };

  All of the client fields must be initialized before the call. See `rump_pub_etfs_register_withsize`() for descriptions of the fields. After the function has been called, the client may not touch the structure memory or the pathname pointers. After `rump_init`() returns, the client may check the status of the registration from eb_status and free the structure. A value of -1 designates that the etfs registration was not performed, 0 designates success and a value larger than 0 designates an errno. The client must serialize calls to `rump_boot_etfs_register`().

`rump_pub_etfs_remove`(key)
  Remove etfs mapping for key. This routine may be called only if the file related to the mapping is not in use.

# RETURN VALUES

`rump_etfs` routines return 0 on success or an errno indicating the reason for failure.

# EXAMPLES

Map a host image file to a mountable /dev/harddisk path using window offsets from the disklabel.

    rump_pub_etfs_register_withsize("/dev/harddisk", "disk.img",
        RUMP_ETFS_BLK,
        pp->p_offset << DEV_BSHIFT, pp->p_size << DEV_BSHIFT);

Make the host kernel module directory hierarchy available within the rump kernel.

    rump_pub_etfs_register("/stand/i386/5.99.41",
        "/stand/i386/5.99.41", RUMP_ETFS_DIR_SUBDIRS);

# SEE ALSO

rump(3)

# HISTORY

`rump_etfs` first appeared in NetBSD 6.0.

October 27, 2014 | NetBSD 9.5