8. Stored Filesystems

Stored filesystems allow users to save and load persistent data from any random-access storage media, such as hard disks, floppy diskettes, and CD-ROMs. Stored filesystems are required for bootstrapping standalone workstations, as well.

8.1 Repairing Filesystems

FIXME: finish

8.2 Linux Extended 2 FS

FIXME: finish

8.3 BSD Unix FS

FIXME: finish

8.4 ISO-9660 CD-ROM FS

FIXME: finish

8.5 Diskfs Library

The diskfs library is declared in <hurd/diskfs.h>, and does a lot of the work of implementing stored filesystems. libdiskfs requires the threads, ports, iohelp, fshelp, and store libraries. You should understand all these libraries before you attempt to use diskfs, and you should also be familiar with the pager library (see section 4.2 Pager Library).

For historical reasons, the library for implementing stored filesystems is called libdiskfs instead of libstorefs. Keep in mind, however, that diskfs is useful for filesystems which are implemented on any block-addressed storage device, since it uses the store library to do I/O.

Note that stored filesystems can be tricky to implement, since the diskfs callback interfaces are not trivial. It really is best if you examine the source code of a similar existing filesystem server, and follow its example rather than trying to write your own from scratch.

8.5.1 Diskfs Startup

This subsection gives an outline of the general steps involved in implementing a filesystem server, to help refresh your memory and to offer explanations rather than to serve as a tutorial.

The first thing a filesystem server should do is parse its command-line arguments (see section 8.5.2 Diskfs Arguments). Then, the standard output and error streams should be redirected to the console, so that error messages are not lost if this is the bootstrap filesystem:

Function: void diskfs_console_stdio (void)

Redirect error messages to the console, so that they can be seen by users.

The following is a list of the relevant functions which would be called during the rest of the server initialization. Again, you should refer to the implementation of an already-working filesystem if you have any questions about how these functions should be used:

Function: error_t diskfs_init_diskfs (void)

Call this function after arguments have been parsed to initialize the library. You must call this before calling any other diskfs functions, and after parsing diskfs options.

Function: void diskfs_spawn_first_thread (void)

Call this after all format-specific initialization is done (except for setting diskfs_root_node); at this point the pagers should be ready to go.

Function: mach_port_t diskfs_startup_diskfs (mach_port_t bootstrap, int flags)

Call this once the filesystem is fully initialized, to advertise the new filesystem control port to our parent filesystem. If bootstrap is set, diskfs will call fsys_startup on that port as appropriate and return the realnode from that call; otherwise we call diskfs_start_bootstrap and return MACH_PORT_NULL. flags specifies how to open realnode (from the O_* set).

You should not need to call the following function directly, since diskfs_startup_diskfs will do it for you, when appropriate:

Function: void diskfs_start_bootstrap (void)

Start the Hurd bootstrap sequence as if we were the bootstrap filesystem (that is, diskfs_boot_flags is nonzero). All filesystem initialization must be complete before you call this function.

8.5.2 Diskfs Arguments

The following functions implement standard diskfs command-line and runtime argument parsing, using argp (see section `Argp' in The GNU C Library Reference Manual):

Function: error_t diskfs_set_options (char *argz, size_t argz_len)

Parse and execute the runtime options specified by argz and argz_len. EINVAL is returned if some option is unrecognized. The default definition of this routine will parse them using diskfs_runtime_argp.

Function: error_t diskfs_append_args (char **argz, unsigned *argz_len)

Append to the malloced string *argz of length *argz_len a NUL-separated list of the arguments to this translator. The default definition of this routine simply calls diskfs_append_std_options.

Function: error_t diskfs_append_std_options (char **argz, unsigned *argz_len)

Appends NUL-separated options describing the standard diskfs option state to argz and increments argz_len appropriately. Note that unlike diskfs_get_options, argz and argz_len must already have sane values.

Variable: struct argp * diskfs_runtime_argp

If this is defined or set to an argp structure, it will be used by the default diskfs_set_options to handle runtime option parsing. The default definition is initialized to a pointer to diskfs_std_runtime_argp.

Variable: const struct argp diskfs_std_runtime_argp

An argp for the standard diskfs runtime options. The default definition of diskfs_runtime_argp points to this, although the user can redefine that to chain this onto his own argp.

Variable: const struct argp diskfs_startup_argp

An argp structure for the standard diskfs command line arguments. The user may call argp_parse on this to parse the command line, chain it onto the end of his own argp structure, or ignore it completely.

Variable: const struct argp diskfs_store_startup_argp

An argp structure for the standard diskfs command line arguments plus a store specification. The address of a location in which to return the resulting struct store_parsed structure should be passed as the input argument to argp_parse; FIXME xref the declaration for STORE_ARGP.

8.5.3 Diskfs Globals

The following functions and variables control the overall behaviour of the library. Your callback functions may need to refer to these, but you should not need to modify or redefine them.

Variable: mach_port_t diskfs_default_pager

Variable: mach_port_t diskfs_exec_ctl

Variable: mach_port_t diskfs_exec

Variable: auth_t diskfs_auth_server_port

These are the respective send rights to the default pager, execserver control port, execserver itself, and authserver.

Variable: mach_port_t diskfs_fsys_identity

The io_identity identity port for the filesystem.

Variable: char ** diskfs_argv

The command line with which diskfs was started, set by the default argument parser. If you don't use it, set this yourself. This is only used for bootstrap file systems, to give the procserver.

Variable: char * diskfs_boot_flags

When this is a bootstrap filesystem, the command line options passed from the kernel. If not a bootstrap filesystem, it is zero, so it can be used to distinguish between the two cases.

Variable: struct rwlock diskfs_fsys_lock

Hold this lock while doing filesystem-level operations. Innocuous users can just hold a reader lock, but operations that might corrupt other threads should hold a writer lock.

Variable: volatile struct mapped_time_value * diskfs_mtime

The current system time, as used by the diskfs routines. This is converted into a struct timeval by the maptime_read C library function (FIXME xref).

Variable: int diskfs_synchronous

True if and only if we should do every operation synchronously. It is the format-specific code's responsibility to keep allocation information permanently in sync if this is set; the rest will be done by format-independent code.

Function: error_t diskfs_set_sync_interval (int interval)

Establish a thread to sync the filesystem every interval seconds, or never, if interval is zero. If an error occurs creating the thread, it is returned, otherwise zero. Subsequent calls will create a new thread and (eventually) get rid of the old one; the old thread won't do any more syncs, regardless.

Variable: spin_lock_t diskfs_node_refcnt_lock

Pager reference count lock.

Variable: int diskfs_readonly

Set to zero if the filesystem is currently writable.

Function: error_t diskfs_set_readonly (int readonly)

Change an active filesystem between read-only and writable modes, setting the global variable diskfs_readonly to reflect the current mode. If an error is returned, nothing will have changed. diskfs_fsys_lock should be held while calling this routine.

Function: int diskfs_check_readonly (void)

Check if the filesystem is readonly before an operation that writes it. Return nonzero if readonly, otherwise zero.

Function: error_t diskfs_remount (void)

Reread all in-core data structures from disk. This function can only be successful if diskfs_readonly is true. diskfs_fsys_lock should be held while calling this routine.

Function: error_t diskfs_shutdown (int flags)

Shutdown the filesystem; flags are as for fsys_shutdown.

8.5.4 Diskfs Node Management

Every file or directory is a diskfs node. The following functions help your diskfs callbacks manage nodes and their references:

Function: void diskfs_drop_node (struct node *np)

Node np now has no more references; clean all state. The diskfs_node_refcnt_lock must be held, and will be released upon return. np must be locked.

Function: void diskfs_node_update (struct node *np, int wait)

Set disk fields from np->dn_stat; update ctime, atime, and mtime if necessary. If wait is true, then return only after the physical media has been completely updated.

Function: void diskfs_nref (struct node *np)

Add a hard reference to node np. If there were no hard references previously, then the node cannot be locked (because you must hold a hard reference to hold the lock).

Function: void diskfs_nput (struct node *np)

Unlock node np and release a hard reference; if this is the last hard reference and there are no links to the file then request light references to be dropped.

Function: void diskfs_nrele (struct node *np)

Release a hard reference on np. If np is locked by anyone, then this cannot be the last hard reference (because you must hold a hard reference in order to hold the lock). If this is the last hard reference and there are no links, then request light references to be dropped.

Function: void diskfs_nref_light (struct node *np)

Add a light reference to a node.

Function: void diskfs_nput_light (struct node *np)

Unlock node np and release a light reference.

Function: void diskfs_nrele_light (struct node *np)

Release a light reference on np. If np is locked by anyone, then this cannot be the last reference (because you must hold a hard reference in order to hold the lock).

Function: error_t diskfs_node_rdwr (struct node *np, char *data, off_t off, size_t amt, int direction, struct protid *cred, size_t *amtread)

This is called by other filesystem routines to read or write files, and extends them automatically, if necessary. np is the node to be read or written, and must be locked. data will be written or filled. off identifies where in the file the I/O is to take place (negative values are not allowed). amt is the size of data and tells how much to copy. dir is zero for reading or nonzero for writing. cred is the user doing the access (only used to validate attempted file extension). For reads, *amtread is filled with the amount actually read.

Function: void diskfs_notice_dirchange (struct node *dp, enum dir_changed_type type, char *name)

Send notifications to users who have requested them for directory dp with dir_notice_changes. The type of modification and affected name are type and name respectively. This should be called by diskfs_direnter, diskfs_dirremove, diskfs_dirrewrite, and anything else that changes the directory, after the change is fully completed.

Function: struct node * diskfs_make_node (struct disknode *dn)

Create a new node structure with ds as its physical disknode. The new node will have one hard reference and no light references.

These next node manipulation functions are not generally useful, but may come in handy if you need to redefine any diskfs functions.

Function: error_t diskfs_create_node (struct node *dir, char *name, mode_t mode, struct node **newnode, struct protid *cred, struct dirstat *ds)

Create a new node. Give it mode: if mode includes IFDIR, also initialize `.' and `..' in the new directory. Return the node in npp. cred identifies the user responsible for the call. If name is nonzero, then link the new node into dir with name name; ds is the result of a prior diskfs_lookup for creation (and dir has been held locked since). dir must always be provided as at least a hint for disk allocation strategies.

Function: void diskfs_set_node_times (struct node *np)

If np->dn_set_ctime is set, then modify np->dn_stat.st_ctime appropriately; do the analogous operations for atime and mtime as well.

Function: struct node * diskfs_check_lookup_cache (struct node *dir, char *name)

Scan the cache looking for name inside dir. If we don't know any entries at all, then return zero. If the entry is confirmed to not exist, then return -1. Otherwise, return np for the entry, with a newly-allocated reference.

Function: error_t diskfs_cached_lookup (int cache_id, struct node **npp)

Return the node corresponding to cache_id in *npp.

Function: void diskfs_enter_lookup_cache (struct node *dir, struct node *np, char *name)

Node np has just been found in dir with name. If np is null, that means that this name has been confirmed as absent in the directory.

Function: void diskfs_purge_lookup_cache (struct node *dp, struct node *np)

Purge all references in the cache to np as a node inside directory dp.

8.5.5 Diskfs Callbacks

Like several other Hurd libraries, libdiskfs depends on you to implement application-specific callback functions. You must define the following functions and variables, but you should also look at 8.5.6 Diskfs Options, as there are several defaults which should be modified to provide good filesystem support:

Structure: struct dirstat

You must define this type, which will hold information between a call to diskfs_lookup and a call to one of diskfs_direnter, diskfs_dirremove, or diskfs_dirrewrite. It must contain enough information so that those calls work as described below.

Variable: const size_t diskfs_dirstat_size

This must be the size in bytes of a struct dirstat.

Variable: int diskfs_link_max

This is the maximum number of links to any one file, which must be a positive integer. The implementation of dir_rename does not know how to succeed if this is only one allowed link; on such formats you need to reimplement dir_rename yourself.

Variable: int diskfs_maxsymlinks

This variable is a positive integer which is the maximum number of symbolic links which can be traversed within a single call to dir_lookup. If this is exceeded, dir_lookup will return ELOOP.

Variable: struct node * diskfs_root_node

Set this to be the node of the root of the filesystem.

Variable: char * diskfs_server_name

Set this to the name of the filesystem server.

Variable: char * diskfs_server_version

Set this to be the server version string.

Variable: char * diskfs_disk_name

This should be a string that somehow identifies the particular disk this filesystem is interpreting. It is generally only used to print messages or to distinguish instances of the same filesystem type from one another. If this filesystem accesses no external media, then define this to be zero.

Function: error_t diskfs_set_statfs (fsys_statfsbuf_t *statfsbuf)

Set *statfsbuf with appropriate values to reflect the current state of the filesystem.

Function: error_t diskfs_lookup (struct node *dp, char *name, enum lookup_type type, struct node **np, struct dirstat *ds, struct protid *cred)

Function: error_t diskfs_lookup_hard (struct node *dp, char *name, enum lookup_type type, struct node **np, struct dirstat *ds, struct protid *cred)

You should not define diskfs_lookup, because it is simply a wrapper for diskfs_lookup_hard, and is already defined in libdiskfs.

Lookup in directory dp (which is locked) the name name. type will either be LOOKUP, CREATE, RENAME, or REMOVE. cred identifies the user making the call.

If the name is found, return zero, and (if np is nonzero) set *np to point to the node for it, which should be locked. If the name is not found, return ENOENT, and (if np is nonzero) set *np to zero. If np is zero, then the node found must not be locked, not even transitorily. Lookups for REMOVE and RENAME (which must often check permissions on the node being found) will always set np.

If ds is nonzero then the behaviour varies depending on the requested lookup type:

LOOKUP

Set *ds to be ignored by diskfs_drop_dirstat

CREATE

On success, set *ds to be ignored by diskfs_drop_dirstat.
On failure, set *ds for a future call to diskfs_direnter.

RENAME

On success, set *ds for a future call to diskfs_dirrewrite.
On failure, set *ds for a future call to diskfs_direnter.

REMOVE

On success, set *ds for a future call to diskfs_dirremove.
On failure, set *ds to be ignored by diskfs_drop_dirstat.

The caller of this function guarantees that if ds is nonzero, then either the appropriate call listed above or diskfs_drop_dirstat will be called with ds before the directory dp is unlocked, and guarantees that no lookup calls will be made on this directory between this lookup and the use (or destruction) of *DS.

If you use the library's versions of diskfs_rename_dir, diskfs_clear_directory, and diskfs_init_dir, then lookups for `..' might have the flag SPEC_DOTDOT ORed in. This has a special meaning depending on the requested lookup type:

LOOKUP

dp should be unlocked and its reference dropped before returning.

CREATE

Ignore this case, because SPEC_DOTDOT is guaranteed not to be given.

RENAME

REMOVE

In both of these cases, the node being found (*np) is already held locked, so don't lock it or add a reference to it.

Return ENOENT if name isn't in the directory. Return EAGAIN if name refers to the `..' of this filesystem's root. Return EIO if appropriate.

Function: error_t diskfs_direnter (struct node *dp, char *name, struct node *np, struct dirstat *ds, struct protid *cred)

Function: error_t diskfs_direnter_hard (struct node *dp, char *name, struct node *np, struct dirstat *ds, struct protid *cred)

You should not define diskfs_direnter, because it is simply a wrapper for diskfs_direnter_hard, and is already defined in libdiskfs.

Add np to directory dp under the name name. This will only be called after an unsuccessful call to diskfs_lookup of type CREATE or RENAME; dp has been locked continuously since that call and ds is as that call set it, np is locked. cred identifies the user responsible for the call (to be used only to validate directory growth).

Function: error_t diskfs_dirrewrite (struct node *dp, struct node *oldnp, struct node *np, char *name, struct dirstat *ds)

Function: error_t diskfs_dirrewrite_hard (struct node *dp, struct node *np, struct dirstat *ds)

You should not define diskfs_dirrewrite, because it is simply a wrapper for diskfs_dirrewrite_hard, and is already defined in libdiskfs.

This will only be called after a successful call to diskfs_lookup of type RENAME; this call should change the name found in directory dp to point to node np instead of its previous referent. dp has been locked continuously since the call to diskfs_lookup and ds is as that call set it; np is locked.

diskfs_dirrewrite has some additional specifications: name is the name within dp which used to correspond to the previous referent, oldnp; it is this reference which is being rewritten. diskfs_dirrewrite also calls diskfs_notice_dirchange if dp->dirmod_reqs is nonzero.

Function: error_t diskfs_dirremove (struct node *dp, struct node *np, char *name, struct dirstat *ds)

Function: error_t diskfs_dirremove_hard (struct node *dp, struct dirstat *ds)

You should not define diskfs_dirremove, because it is simply a wrapper for diskfs_dirremove_hard, and is already defined in libdiskfs.

This will only be called after a successful call to diskfs_lookup of type REMOVE; this call should remove the name found from the directory ds. dp has been locked continuously since the call to diskfs_lookup and ds is as that call set it.

diskfs_dirremove has some additional specifications: this routine should call diskfs_notice_dirchange if dp->dirmod_reqs is nonzero. The entry being removed has name name and refers to np.

Function: error_t diskfs_drop_dirstat (struct node *dp, struct dirstat *ds)

ds has been set by a previous call to diskfs_lookup on directory dp; this function is guaranteed to be called if diskfs_direnter, diskfs_dirrewrite, and diskfs_dirremove have not been called, and should free any state retained by a struct dirstat. dp has been locked continuously since the call to diskfs_lookup.

Function: void diskfs_null_dirstat (struct dirstat *ds)

Initialize ds such that diskfs_drop_dirstat will ignore it.

Function: error_t diskfs_get_directs (struct node *dp, int entry, int n, char **data, u_int *datacnt, vm_size_t bufsiz, int *amt)

Return n directory entries starting at entry from locked directory node dp. Fill *data with the entries; which currently points to *datacnt bytes. If it isn't big enough, vm_allocate into *data. Set *datacnt with the total size used. Fill amt with the number of entries copied. Regardless, never copy more than bufsiz bytes. If bufsiz is zero, then there is no limit on *datacnt; if n is -1, then there is no limit on amt.

Function: int diskfs_dirempty (struct node *dp, struct protid *cred)

Return nonzero if locked directory dp is empty. If the user has not redefined diskfs_clear_directory and diskfs_init_directory, then `empty' means `only possesses entries labelled `.' and `..'. cred identifies the user making the call... if this user cannot search the directory, then this routine should fail.

Function: error_t diskfs_get_translator (struct node *np, char **namep, u_int *namelen)

For locked node np (for which diskfs_node_translated is true) look up the name of its translator. Store the name into newly malloced storage and set *namelen to the total length.

Function: error_t diskfs_set_translator (struct node *np, char *name, u_int namelen, struct protid *cred)

For locked node np, set the name of the translating program to be name, which is namelen bytes long. cred identifies the user responsible for the call.

Function: error_t diskfs_truncate (struct node *np, off_t size)

Truncate locked node np to be size bytes long. If np is already less than or equal to size bytes long, do nothing. If this is a symlink (and diskfs_shortcut_symlink is set) then this should clear the symlink, even if diskfs_create_symlink_hook stores the link target elsewhere.

Function: error_t diskfs_grow (struct node *np, off_t size, struct protid *cred)

Grow the disk allocated to locked node np to be at least size bytes, and set np->allocsize to the actual allocated size. If the allocated size is already size bytes, do nothing. cred identifies the user responsible for the call.

Function: error_t diskfs_node_reload (struct node *node)

This function must reread all data specific to node from disk, without writing anything. It is always called with diskfs_readonly set to true.

Function: error_t diskfs_reload_global_state (void)

This function must invalidate all cached global state, and reread it as necessary from disk, without writing anything. It is always called with diskfs_readonly set to true. diskfs_node_reload is subsequently called on all active nodes, so this call doesn't need to reread any node-specific data.

Function: error_t diskfs_node_iterate (error_t (*fun) (struct node *np))

For each active node np, call fun. The node is to be locked around the call to fun. If fun returns nonzero for any node, then stop immediately, and return that value.

Function: error_t diskfs_alloc_node (struct node *dp, mode_t mode, struct node **np)

Allocate a new node to be of mode mode in locked directory dp, but don't actually set the mode or modify the directory, since that will be done by the caller. The user responsible for the request can be identified with cred. Set *np to be the newly allocated node.

Function: void diskfs_free_node (struct node *np, mode_t mode)

Free node np; the on-disk copy has already been synchronized with diskfs_node_update (where np->dn_stat.st_mode was zero). np's mode used to be mode.

Function: void diskfs_lost_hardrefs (struct node *np)

Locked node np has some light references but has just lost its last hard reference.

Function: void diskfs_new_hardrefs (struct node *np)

Locked node np has just acquired a hard reference where it had none previously. Therefore, it is okay again to have light references without real users.

Function: void diskfs_try_dropping_softrefs (struct node *np)

Node np has some light references, but has just lost its last hard references. Take steps so that if any light references can be freed, they are. Both diskfs_node_refcnt_lock and np are locked. This function will be called after diskfs_lost_hardrefs.

Function: void diskfs_node_norefs (struct node *np)

Node np has no more references; free local state, including *np if it shouldn't be retained. diskfs_node_refcnt_lock is held.

Function: error_t diskfs_set_hypermetadata (int wait, int clean)

Write any non-paged metadata from format-specific buffers to disk, asynchronously unless wait is nonzero. If clean is nonzero, then after this is written the filesystem will be absolutely clean, and it must be possible for the non-paged metadata to indicate that fact.

Function: void diskfs_write_disknode (struct node *np, int wait)

Write the information in np->dn_stat and any associated format-specific information to the disk. If wait is true, then return only after the physical media has been completely updated.

Function: void diskfs_file_update (struct node *np, int wait)

Write the contents and all associated metadata of file NP to disk. Generally, this will involve calling diskfs_node_update for much of the metadata. If wait is true, then return only after the physical media has been completely updated.

Function: mach_port_t diskfs_get_filemap (struct node *np, vm_prot_t prot)

Return a memory object port (send right) for the file contents of np. prot is the maximum allowable access. On errors, return MACH_PORT_NULL and set errno.

Function: struct pager * diskfs_get_filemap_pager_struct (struct node *np)

Return a struct pager * that refers to the pager returned by diskfs_get_filemap for locked node NP, suitable for use as an argument to pager_memcpy.

Function: vm_prot_t diskfs_max_user_pager_prot (void)

Return the bitwise OR of the maximum prot parameter (the second argument to diskfs_get_filemap) for all active user pagers.

Function: int diskfs_pager_users (void)

Return nonzero if there are pager ports exported that might be in use by users. Further pager creation should be blocked before this function returns zero.

Function: void diskfs_sync_everything (int wait)

Sync all the pagers and write any data belonging on disk except for the hypermetadata. If wait is true, then return only after the physical media has been completely updated.

Function: void diskfs_shutdown_pager (void)

Shut down all pagers. This is irreversible, and is done when the filesystem is exiting.

8.5.6 Diskfs Options

The functions and variables described in this subsection already have default definitions in libdiskfs, so you are not forced to define them; rather, they may be redefined on a case-by-case basis.

You should set the values of any option variables as soon as your program starts (before you make any calls to diskfs, such as argument parsing).

Variable: int diskfs_hard_readonly

You should set this variable to nonzero if the filesystem media can never be made writable.

Variable: char * diskfs_extra_version

Set this to be any additional version specification that should be printed for --version.

Variable: int diskfs_shortcut_symlink

This should be nonzero if and only if the filesystem format supports shortcutting symbolic link translation. The library guarantees that users will not be able to read or write the contents of the node directly, and the library will only do so if the symlink hook functions (diskfs_create_symlink_hook and diskfs_read_symlink_hook) return EINVAL or are not defined. The library knows that the dn_stat.st_size field is the length of the symlink, even if the hook functions are used.

Variable: int diskfs_shortcut_chrdev

Variable: int diskfs_shortcut_blkdev

Variable: int diskfs_shortcut_fifo

Variable: int diskfs_shortcut_ifsock

These variables should be nonzero if and only if the filesystem format supports shortcutting character device node, block device node, FIFO, or Unix-domain socket translation, respectively.

Variable: int diskfs_default_sync_interval

diskfs_set_sync_interval is called with this value when the first diskfs thread is started up (in diskfs_spawn_first_thread). This variable has a default default value of 30, which causes disk buffers to be flushed at least every 30 seconds.

Function: error_t diskfs_validate_mode_change (struct node *np, mode_t mode)

Function: error_t diskfs_validate_owner_change (struct node *np, uid_t uid)

Function: error_t diskfs_validate_group_change (struct node *np, gid_t gid)

Function: error_t diskfs_validate_author_change (struct node *np, uid_t author)

Function: error_t diskfs_validate_flags_change (struct node *np, int flags)

Function: error_t diskfs_validate_rdev_change (struct node *np, dev_t rdev)

Return zero if for the node np can be changed as requested. That is, if np's mode can be changed to mode, owner to uid, group to gid, author to author, flags to flags, or raw device number to rdev, respectively. Otherwise, return an error code.

It must always be possible to clear the mode or the flags; diskfs will not ask for permission before doing so.

Function: void diskfs_readonly_changed (int readonly)

This is called when the disk has been changed from read-only to read-write mode or vice-versa. readonly is the new state (which is also reflected in diskfs_readonly). This function is also called during initial startup if the filesystem is to be writable.

Variable: error_t (*diskfs_create_symlink_hook) (struct node *np, char *target)

If this function pointer is nonzero (and diskfs_shortcut_symlink is set) it is called to set a symlink. If it returns EINVAL or isn't set, then the normal method (writing the contents into the file data) is used. If it returns any other error, it is returned to the user.

Variable: error_t (*diskfs_read_symlink_hook) (struct node *np, char *target)

If this function pointer is nonzero (and diskfs_shortcut_symlink is set) it is called to read the contents of a symlink. If it returns EINVAL or isn't set, then the normal method (reading from the file data) is used. If it returns any other error, it is returned to the user.

Function: error_t diskfs_rename_dir (struct node *fdp, struct node *fnp, char *fromname, struct node *tdp, char *toname, struct protid *fromcred, struct protid *tocred)

Rename directory node fnp (whose parent is fdp, and which has name fromname in that directory) to have name toname inside directory tdp. None of these nodes are locked, and none should be locked upon return. This routine is serialized, so it doesn't have to be reentrant. Directories will never be renamed except by this routine. fromcred is the user responsible for fdp and fnp. tocred is the user responsible for tdp. This routine assumes the usual convention where `.' and `..' are represented by ordinary links; if that is not true for your format, you have to redefine this function.

Function: error_t diskfs_clear_directory (struct node *dp, struct node *pdp, struct protid *cred)

Clear the `.' and `..' entries from directory dp. Its parent is pdp, and the user responsible for this is identified by cred. Both directories must be locked. This routine assumes the usual convention where `.' and `..' are represented by ordinary links; if that is not true for your format, you have to redefine this function.

Function: error_t diskfs_init_dir (struct node *dp, struct node *pdp, struct protid *cred)

Locked node dp is a new directory; add whatever links are necessary to give it structure; its parent is the (locked) node pdp. This routine may not call diskfs_lookup on pdp. The new directory must be clear within the meaning of diskfs_dirempty. This routine assumes the usual convention where `.' and `..' are represented by ordinary links; if that is not true for your format, you have to redefine this function. cred identifies the user making the call.

8.5.7 Diskfs Internals

The library also exports the following functions, but they are not generally useful unless you are redefining other functions the library provides.

Function: error_t diskfs_create_protid (struct peropen *po, struct iouser *user, struct protid **cred)

Create and return a protid for an existing peropen po in cred, referring to user user. The node po->np must be locked.

Function: error_t diskfs_start_protid (struct peropen *po, struct protid **cred)

Build and return in cred a protid which has no user identification, for peropen po. The node po->np must be locked.

Function: void diskfs_finish_protid (struct protid *cred, struct iouser *user)

Finish building protid cred started with diskfs_start_protid; the user to install is user.

Function: void diskfs_protid_rele (void *arg)

Called when a protid cred has no more references. Because references to protids are maintained by the port management library, this is installed in the clean routines list. The ports library will free the structure.

Function: struct peropen * diskfs_make_peropen (struct node *np, int flags, struct peropen *context)

Create and return a new peropen structure on node np with open flags flags. The initial values for the root_parent, shadow_root, and shadow_root_parent fields are copied from context if it is nonzero, otherwise each of these values are set to zero.

Function: void diskfs_release_peropen (struct peropen *po)

Decrement the reference count on po.

Function: error_t diskfs_execboot_fsys_startup (mach_port_t port, int flags, mach_port_t ctl, mach_port_t *real, mach_msg_type_name_t *realpoly)

This function is called by S_fsys_startup for execserver bootstrap. The execserver is able to function without a real node, hence this fraud. Arguments are as for fsys_startup in <hurd/fsys.defs>.

Function: int diskfs_demuxer (mach_msg_header_t *inp, mach_msg_header_t *outp)

Demultiplex incoming libports messages on diskfs ports.

The diskfs library also provides functions to demultiplex the fs, io, fsys, interrupt, and notify interfaces. All the server routines have the prefix diskfs_S_. For those routines, in arguments of type file_t or io_t appear as struct protid * to the stub.