NetBSD-Bugs archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
kern/45277: vfsops(9) and internals guide miss several functions; XXX cleared for internals guide
>Number: 45277
>Category: kern
>Synopsis: vfsops(9) and internals guide miss several functions; XXX
>cleared for internals guide
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: kern-bug-people
>State: open
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Sat Aug 20 10:15:00 +0000 2011
>Originator: Julian Fagir
>Release: NetBSD-current
>Organization:
>Environment:
>Description:
vfsops(9)'s manpage does not mention VFS_EXTATTRCTL, VFS_FSYNC,
VFS_RENAMELOCK_ENTER, VFS_RENAMELOCK_EXIT, though they are needed for
filesystems.
Two of them were also missing in the internals guide. I did not write a
consideration of fs_extattrctl as currently this functions is rarely used
inside the kernel, and only in special cases.
Additionally, there were some XXX's in the guide that can be easily fixed (e.g.
the filesystem descriptions, see the existing definitions below the added ones).
>How-To-Repeat:
Go to http://netbsd.org/docs/internals/en/chap-file-system.html
or `man 9 vfsops`
>Fix:
--- share/man/man9/vfsops.9.orig 2011-07-19 09:57:54.000000000 +0200
+++ share/man/man9/vfsops.9 2011-08-11 22:57:48.000000000 +0200
@@ -37,13 +37,17 @@
.Nm VFS_UNMOUNT ,
.Nm VFS_ROOT ,
.Nm VFS_QUOTACTL ,
+.Nm VFS_RENAMELOCK_ENTER ,
+.Nm VFS_RENAMELOCK_EXIT ,
.Nm VFS_STATVFS ,
.Nm VFS_SYNC ,
+.Nm VFS_FSYNC ,
.Nm VFS_VGET ,
.Nm VFS_FHTOVP ,
.Nm VFS_VPTOFH ,
.Nm VFS_SNAPSHOT ,
-.Nm VFS_SUSPENDCTL
+.Nm VFS_SUSPENDCTL ,
+.Nm VFS_EXTATTRCTL
.Nd kernel file system interface
.Sh SYNOPSIS
.In sys/param.h
@@ -62,10 +66,16 @@
.Ft int
.Fn VFS_QUOTACTL "struct mount *mp" "int cmds" "uid_t uid" "void *arg"
.Ft int
+.Fn VFS_RENAMELOCK_ENTER "struct mount *mp"
+.Ft int
+.Fn VFS_RENAMELOCK_EXIT "struct mount *mp"
+.Ft int
.Fn VFS_STATVFS "struct mount *mp" "struct statvfs *sbp"
.Ft int
.Fn VFS_SYNC "struct mount *mp" "int waitfor" "kauth_cred_t cred"
.Ft int
+.Fn VFS_FSYNC "struct vnode *vp" "int flags"
+.Ft int
.Fn VFS_VGET "struct mount *mp" "ino_t ino" "struct vnode **vpp"
.Ft int
.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "struct vnode **vpp"
@@ -75,6 +85,9 @@
.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts"
.Ft int
.Fn VFS_SUSPENDCTL "struct mount *mp" "int cmd"
+.Ft int
+.Fn VFS_EXTATTRCTL "struct mount *mp" "int cmd" "struct vnode *vp" "int \
+attrnamespace" "const char *attrname"
.Sh DESCRIPTION
In a similar fashion to the
.Xr vnode 9
@@ -120,6 +133,14 @@
Ta Dv VFS_QUOTACTL \
Ta Query/modify space quotas
.\"
+.It int (*vfs_renamelock_enter)() \
+Ta Dv VFS_RENAMELOCK_ENTER \
+Ta Enter the lock for renaming files
+.\"
+.It int (*vfs_statvfs)() \
+Ta Dv VFS_RENAMELOCK_EXIT \
+Ta Exit the lock for renaming files
+.\"
.It int (*vfs_statvfs)() \
Ta Dv VFS_STATVFS \
Ta Get file system statistics
@@ -163,6 +184,10 @@
.It int (*vfs_suspendctl)() \
Ta Dv VFS_SUSPENDCTL \
Ta Suspend or resume
+.\"
+.It int (*vfs_extattrctl)() \
+Ta Dv VFS_EXTATTRCTL \
+Ta Control extended attributes
.El
.Pp
Some additional non-function members of the vfsops structure are the
@@ -269,7 +294,7 @@
The function also deallocates space associated with data structure
that were allocated for the file system when it was mounted.
.It Fn VFS_ROOT "mp" "vpp"
-Get the root vnode of the file system specified by the mount
+Get the locked root vnode of the file system specified by the mount
structure
.Fa mp .
The vnode is returned in the address given by
@@ -295,6 +320,17 @@
is the file system type specific implementation of the
.Xr quotactl 2
system call.
+.It Fn VFS_RENAMELOCK_ENTER "mp"
+Enter the rename lock of the file system specified by the mount structure
+.Fa mp .
+This is usually not called directly but rather from the system when renaming a
+file is requested.
+.It Fn VFS_RENAMELOCK_EXIT "mp"
+Exit the rename lock of the file system specified by the mount structure
+.Fa mp .
+This function is called after
+.Xr VFS_RENAMELOCK_ENTER
+when the renaming is finished.
.It Fn VFS_STATVFS "mp" "sbp"
Get file system statistics for the file system specified by the mount
structure
@@ -307,6 +343,12 @@
and
.Xr fstatvfs 2
system calls.
+.It Fn VFS_FSYNC "vp" "flags"
+Flush file system I/O buffers for a file system mounted from the device
+.Fa vp .
+This means that
+.Fa vp
+must be a node of a mounted block device.
.It Fn VFS_SYNC "mp" "waitfor" "cred"
Flush file system I/O buffers for the file system specified by the mount
structure
@@ -406,6 +448,21 @@
to resume operations.
If the file system does not support this function, it should return
.Er EOPNOTSUPP .
+.It Fn VFS_EXTATTRCTL "mp" "cmd" "vp" "attrnamespace" "attrname"
+If
+.Fa vp
+is non-NULL, it is the locked vnode of the file to apply the extattrctl to,
and
+will be unlocked on return. XXX
+When
+.Fa vp
+is NULL, then the command is either one of the commands
+.Ar EXTATTR_CMD_START
+or
+.Ar EXTATTR_CMD_STOP
+defined in
+.In sys/extattr.h
+and applied to the mount point
+.Fa mp .
.El
.Sh CODE REFERENCES
The vfs operations are implemented within the files
Index: docs/internals/en/chap-file-system.xml
===================================================================
RCS file: /cvsroot/htdocs/docs/internals/en/chap-file-system.xml,v
retrieving revision 1.3
diff -u -r1.3 chap-file-system.xml
--- docs/internals/en/chap-file-system.xml 6 Mar 2010 16:23:09 -0000
1.3
+++ docs/internals/en/chap-file-system.xml 20 Aug 2011 10:09:29 -0000
@@ -234,7 +234,7 @@
<row>
<entry><function>VOP_KQFILTER</function></entry>
- <entry>XXX</entry>
+ <entry>Register a knote with the vnode.</entry>
<!-- <entry>See <xref linkend="XXX" />.</entry> -->
</row>
@@ -697,7 +697,21 @@
<entry>Finalizes the file system driver.</entry>
<entry>Must be defined.</entry>
<entry>See <xref linkend="fs_init_and_fs_done" />.</entry>
- </row>
+ </row>
+
+ <row>
+
<entry><function>fs_renamelock_enter</function></entry>
+ <entry>Enters the lock for file renaming.</entry>
+ <entry>May be undefined (i.e., null).</entry>
+ <!-- <entry>Could be documented, but not
necessary.</entry> -->
+ </row>
+
+ <row>
+
<entry><function>fs_renamelock_enter</function></entry>
+ <entry>Exits the lock for file renaming.</entry>
+ <entry>May be undefined (i.e., null).</entry>
+ <!-- <entry>Could be documented, but not
necessary.</entry> -->
+ </row>
<row>
<entry><function>fs_mountroot</function></entry>
@@ -823,6 +837,9 @@
<sect1 id="fs_overview">
<title>File systems overview</title>
+ <para>In brackets is the name of the filesystem written as it is
+ used in NetBSD.</para>
+
<!-- ============================================================== -->
<sect2 id="fs_overview_ondisk">
@@ -831,29 +848,58 @@
<para>On-disk file systems are those that store their contents on
a physical drive.</para>
- <itemizedlist>
+ <itemizedlist>
+
<listitem>
- <para>Fast File System (ffs): XXX</para>
+ <para>Version 7 File System (v7fs): The original file system of
+ Unix Version 7.</para>
</listitem>
<listitem>
- <para>Log-structured File System (lfs): XXX</para>
+ <para>Fast File System (ffs): The lower layer of the Unix File
+ System (ufs). Designed as a successor of v7fs, it is nowadays
+ used by most unixes and is NetBSD's standard file system.
+ There also is FFSv2, mainly used by FreeBSD and also
+ implemented by NetBSD, but not used by default.</para>
</listitem>
<listitem>
- <para>Extended 2 File System (ext2fs): XXX</para>
+ <para>Log-structured File System (lfs): lfs is a file system
+ using mainly the on-disk structure of ffs but being
+ log-structured, i.e. it maintains a log of all changes to its
+ files.</para>
</listitem>
<listitem>
- <para>FAT (msdosfs): XXX</para>
+ <para>Extended 2 File System (ext2fs): The unjournaled ext2fs
+ was developed for Linux to resemble ffs. With its two
+ successors ext3 and ext4 it is the standard Linux file
+ system.</para>
</listitem>
<listitem>
- <para>ISO 9660 (cd9660): XXX</para>
+ <para>FAT (msdosfs): FAT is the file system used for floppys,
+ MSDOS, Windows (up to ME) and SD cards. Its design is open, so
+ it is implemented in nearly every OS and has become the most
+ widespread file system for interchangable disks despite its
+ severe drawbacks (limited size, limited file size).</para>
</listitem>
<listitem>
- <para>NTFS (ntfs): XXX</para>
+ <para>ISO 9660 (cd9660): ISO 9660 is the file system used for
+ CDs. It was obsoleted by UDF (which is mainly used for
+ DVDs).</para>
+ </listitem>
+
+ <listitem>
+ <para>Universal Disk format (udf): UDF is the successor of ISO
+ 9660, solving some limits of ISO 9660.</para>
+
+ <listitem>
+ <para>NTFS (ntfs): NTFS was for Microsoft the successor of FAT
+ and is used by all NT-kernels (NT, 2k, XP and later) by
+ default. Its specification is still closed, so the free
+ implementations are not 100% safe to use when writing.</para>
</listitem>
</itemizedlist>
@@ -868,7 +914,9 @@
<itemizedlist>
<listitem>
- <para>Network File System (nfs): XXX</para>
+ <para>Network File System (nfs): NFS is a filesystem
+ developed by Sun, but nowadays implemented in nearly every
+ operating system.</para>
</listitem>
<listitem>
@@ -886,7 +934,17 @@
<itemizedlist>
<listitem>
- <para>Memory File System (mfs): XXX</para>
+ <para>Memory File System (mfs): MFS is a non-persistent file
+ system that stores its information in the RAM of a
+ computer. There is <link
+
url="http://netbsd.org/docs/guide/en/chap-tuning.html#tuning-system-mfs";>chapter
+ in the guide</link> about mfs and tmpfs.</para>
+ </listitem>
+
+ <listitem>
+ <para>Temporary File System (tmpfs): tmpfs is a memory file
+ system similar to mfs, but the more modern
+ implementation.</para>
</listitem>
<listitem>
@@ -901,9 +959,6 @@
<para>Pseudo-terminal File System (ptyfs): XXX</para>
</listitem>
- <listitem>
- <para>Temporary File System (tmpfs): XXX</para>
- </listitem>
</itemizedlist>
</sect2>
@@ -917,15 +972,24 @@
<itemizedlist>
<listitem>
- <para>Null File System (nullfs): XXX</para>
+ <para>Null File System (nullfs): nullfs is a simple layered
+ file system to mount a directory onto another, overlaying it,
+ so the lower one is not accessible anymore.</para>
</listitem>
<listitem>
- <para>Union File System (unionfs): XXX</para>
+ <para>Union File System (unionfs): unionfs (and union, another
+ implementation of the same concept) is a file system that
+ overlays one directory onto another, but makes the lower layer
+ still visible. All changes are only written to the top
+ directory, the lower one stays untouched (and can thus be e.g.
+ mounted read-only).</para>
</listitem>
<listitem>
- <para>User-map File System (umapfs): XXX</para>
+ <para>User-map File System (umapfs): umapfs behaves like
+ nullfs, but remaps the UIDs and GIDs of the mounted
+ directory.</para>
</listitem>
</itemizedlist>
@@ -1112,8 +1176,21 @@
<sect2 id="fs_mount_utility">
<title>The mount utility</title>
- <para>XXX: To be written. Slightly describe how a userland mount
- utility works.</para>
+ <para>The mount utilities reside in <filename>src/sbin</filename>
+ and have the name <filename>mount_FSNAME</filename>. It is usually
+ very small and consists of a manpage (going to section 8) and a
+ little program.</para>
+
+ <para>This program must parse general mount options (such as read
+ only, noatime, etc.) with &man.getmntops.3; and parse its
+ fs-specific mount options and fill the <ulink
+ xref="fs_mount_args">fs_mount_args</ulink> of the filesystem
+ accordingly to the options you got, and then call the
+ &man.mount.2; syscall with the first argument your fs-identifier,
+ so <literal>MOUNT_EGFS</para>.
+
+ <para>Most times, this utility is called indirectly by
+ &man.mount.8;.</para>
</sect2>
Home |
Main Index |
Thread Index |
Old Index