Chapter 5, “Directories and File Metadata,” page 117, introduced inodes for file metadata and described how directory entries link filenames to inodes. It also described partitions and filesystems, and you saw that hard links are restricted to working within a single filesystem because directories contain only inode numbers and inode numbers are not unique across the entire set of in-use filesystems.

Besides inodes and data blocks, filesystems also contain one or more copies of the superblock. This is a special disk block that describes the filesystem; its information is updated as the filesystem itself changes. For example, it contains counts of free and used inodes, free and used blocks, and other information. It also includes a magic number: a unique special value in a special location that identifies the type of the filesystem. (We’ll see how this is relevant, shortly.)

Making a partition that contains a filesystem available for use is called mounting the filesystem. Removing a filesystem from use is called, not surprisingly, unmounting the filesystem.

These two jobs are accomplished with the mount and umount [sic] programs, named for the corresponding system calls. Every Unix system’s mount() system call has a different interface. Because mounting and unmounting are considered implementation issues, POSIX purposely does not standardize these system calls.

You mount a filesystem onto a directory; such a directory is referred to as the filesystem’s mount point. By convention the directory should be empty, but nothing enforces this. However, if the mount point is not empty, all of its contents become completely inaccessible while a filesystem is mounted on it.^[1]

The kernel maintains a unique number, known as the device number, that identifies each mounted partition. For this reason, it is the (device, inode) pair that together uniquely identifies a file; when the struct stat structures for two filenames indicate that both numbers are the same, you can be sure that they do refer to the same file.

As mentioned earlier, user-level software places the inode structures and other metadata onto a disk partition, thereby creating the filesystem. This same software creates an initial root directory for the filesystem. Thus, we have to make a distinction between “the root directory named /,” which is the topmost directory in the hierarchical filename namespace, and “the root directory of a filesystem,” which is each filesystem’s individual topmost directory. The / directory is also the “root directory” of the “root filesystem.”

For reasons described in the sidebar, a filesystem’s root directory always has inode number 2 (although this is not formally standardized). Since there can be multiple filesystems, each one’s root directory has the same inode number, 2. When resolving a pathname, the kernel knows where each filesystem is mounted and arranges for the mount point’s name to refer to the root directory of the mounted filesystem. Furthermore, ’..’ in the root of a mounted filesystem is made to refer to the parent directory of the mount point.

Figure 8.1 shows two filesystems: one for the root directory, and one for /usr, before /usr is mounted. Figure 8.2 shows the situation after /usr is mounted.

Figure 8.1. Separate filesystems, before mounting

Figure 8.2. Separate filesystems, after mounting

The / directory, the root of the entire logical hierarchy, is special in an additional way: /. and /.. refer to the same directory; this is not true of any other directory on the system. (Thus, after something like ’cd /../../../..’, you’re still in /.) This behavior is implemented in a simple fashion: Both /. and /.. are hard links to the filesystem’s root directory. (You can see this in both Figure 8.1 and Figure 8.2.) Every filesystem works this way, but the kernel treats / specially and does not treat as a special case the ’..’ directory for the filesystem mounted on /.

Historically, V7 Unix supported only a single filesystem type; every partition’s metadata and directory organization were structured the same way. 4.1 BSD used a filesystem with the same structure as that of V7, but with a 1024-byte block size instead of a 512-byte one. 4.2 BSD introduced the “BSD Fast Filesystem,” which dramatically changed the layout of inodes and data on disk and enabled the use of much larger block sizes. (In general, using larger contiguous blocks of data provides better throughput, especially for file reads.)

Through 4.3 BSD and System V Release 2 in the early and mid-1980s, Unix systems continued to support just one filesystem type. To switch a computer from one filesystem to another,^[2] you had to first back up each filesystem to archival media (9-track tape), upgrade the system, and then restore the data.

In the mid-1980s, Sun Microsystems developed a kernel architecture that made it possible to use multiple filesystem architectures at the same time. This design was implemented for their SunOS operating system, primarily to support Sun’s Network File System (NFS). However, as a consequence it was also possible to support multiple on-disk architectures. System V Release 3 used a similar architecture to support the Remote File System (RFS), but it continued to support only one on-disk architecture.^[3] (RFS was never widely used and is now only a historical footnote.)

Sun’s general design became popular and widely implemented in commercial Unix systems, including System V Release 4. Linux and BSD systems use a variant of this design to support multiple on-disk filesystem formats. In particular, it’s common for all Unix variants on Intel x86 hardware to be able to mount MS-DOS/Windows FAT filesystems, including those supplying long filenames, as well as ISO 9660-formatted CD-ROMs.

Linux has several native (that is, on-disk) filesystems. The most popular are the ext2 and ext3 filesystems. Many more filesystem types are available, however. You can find information about most of them in the /usr/src/linux/Documentation/filesystems/ directory (if you have kernel source installed). Table 8.1 lists the various filesystem names, with brief descriptions of each. The abbreviation “RW” means “read/write” and “RO” means “read only.”

Not all of these filesystems are supported by the mount command; see mount(8) for the list of those that are supported.

Journaling is a technique, pioneered in database systems, for improving the performance of file updates, in such a way that filesystem recovery in the event of a crash can be done both correctly and quickly. As of this writing, several different journaling filesystems are available and competing for prominence in the GNU/Linux world. ext3 is one such; it has the advantage of being upwardly compatible with existing ext2 filesystems, and it’s easy to convert a filesystem back and forth between the two types. (See tune2fs(8).) ReiserFS and XFS also have strong followings.

The fat, msdos, umsdos, and vfat filesystems all share common code. In general, you should use vfat to mount Windows FAT-32 (or other FAT-xx) partitions, and umsdos if you wish to use a FAT partition as the root filesystem for your GNU/Linux system.

The Coherent, MINIX, original System V, and Xenix filesystems all have similar on-disk structures. The sysv filesystem type supports all of them; the four names coherent, minix, sysv, and xenix are aliases one for the other. The coherent and xenix names will eventually be removed.

The BSD Fast Filesystem has evolved somewhat over the years. The ufs filesystem supports read/write operation for the version from 4.4 BSD, which is the basis for the three widely used BSD operating systems: FreeBSD, NetBSD, and OpenBSD. It also supports read/write operation for Sun’s Solaris filesystem, for both SPARC and Intel x86 systems. The original BSD format and that from the NeXTStep operating system are supported read-only.

The “RO” designations for befs and ntfs mean that filesystems of those types can be mounted and read but files cannot be written on them or removed from them. (This may change with time; check your system’s documentation.) The cramfs, iso9660, romfs, and udf filesystems are marked “RO” because the underlying media are inherently read-only.

Two filesystem types no longer exist: ext, which was the original Extended Filesystem, and xiafs, which extended the original MINIX filesystem for longer names and larger file sizes. xiafs and ext2 came out approximately simultaneously, but ext2 eventually became the dominant filesystem.^[4]

The mount command mounts filesystems, splicing their contents into the system file hierarchy at their mount points. Under GNU/Linux, it is somewhat complicated since it has to deal with all the known filesystem types and their options. Normally, only root can run mount, although it’s possible to make exceptions for certain cases, as is discussed later in the chapter.

You specify the filesystem type with the -t option:

mount [ options ] device mount-point

For example (# is the root prompt):

# mount -t iso9660 /dev/cdrom /mnt/cdrom       Mount CD-ROM
# mount -t vfat /dev/fd0 /mnt/floppy           Mount MS-DOS floppy
# mount -t nfs files.example.com:/ /mnt/files  Mount NFS filesystem

You can use ’-t auto’ to force mount to guess the filesystem type. This usually works, although if you know for sure what kind of filesystem you have, it helps to supply the type and avoid the chance that mount will guess incorrectly. mount does this guessing by default, so ’-t auto’ isn’t strictly necessary.

GNU/Linux systems provide a special kind of mounting by means of the loopback device. In this way, a filesystem image contained in a regular file can be mounted as if it were an actual disk device. This capability is very useful, for example, with CD-ROM images. It allows you to create one and try it out, without having to burn it to a writable CD and mount the CD. The following example uses the first CD image from the Red Hat 9 distribution of GNU/Linux:

# ls -l shrike-i386-disc1.iso                                   Examine CD image file
-rw-r--r--    1 arnold devel   668991488 Apr 11 05:13 shrike-i386-discl.iso
# mount -t iso9660 -o ro, loop shrike-i386-disc1.iso /mnt/cdrom  Mount it on /mnt/cdrom
# cd /mnt/cdrom                                                 Go there
# ls                                                            Look at files
autorun              README.it              RELEASE-NOTES-fr.html
dosutils             README.ja              RELEASE-NOTES.html
EULA                 README.ko              RELEASE-NOTES-it.html
GPL                  README.pt              RELEASE-NOTES-ja.html
images               README.pt_BR           RELEASE-NOTES-ko.html
isolinux             README.zh_CN           RELEASE-NOTES-pt_BR.html
README               README.zh_TW           RELEASE-NOTES-pt.html
README-Accessibility RedHat                 RELEASE-NOTES-zh_CN.html
README.de            RELEASE-NOTES          RELEASE-NOTES-zh_TW.html
README.es            RELEASE-NOTES-de.html  RPM-GPG-KEY
README.fr            RELEASE-NOTES-es.html  TRANS.TBL
# cd                                                             Change out
# umount /mnt/cdrom                                              Unmount

Being able to mount an ISO 9660 image this way is particularly helpful when you are testing scripts that make CD images. You can create an image in a regular file, mount it, and verify that it’s arranged correctly. Then, once you’re sure it’s correct, you can copy the image to a writable CD (“burn” the CD). The loopback facility is useful for mounting floppy disk images, too.

The umount command unmounts a filesystem, removing its contents from the system file hierarchy. The usage is as follows:

umount file-or-device

The filesystem being unmounted must not be busy. This means that there aren’t any processes with open files on the filesystem and that no process has a directory on the filesystem as its current working directory:

$ mount                                                 Show what's mounted   
/dev/hda2 on / type ext3 (rw)                           / is on a real device   
none on /proc type proc (rw)
usbdevfs on /proc/bus/usb type usbdevfs (rw)
/dev/hda5 on /d type ext3 (rw)                          So is /d
none on /dev/pts type devpts (rw,gid=5,mode=620)
none on /dev/shm type tmpfs (rw)
none on /proc/sys/fs/binfmt_misc type binfmt_misc (rw)
$ su                                                    Switch to superuser
Password:                                               Password does not echo
# cd /d                                                 Make /d the current directory
# umount /d                                             Try to unmount /d
umount: /d: device is busy                              Doesn't work; it's still in use
# cd /                                                  Change out of /d
# umount /d                                             Try to unmount /d again
#                                                       Silence is golden: unmount worked

The mount command supports options that control what operations the kernel will or will not allow for the filesystem. There are a fair number of these. Only two are really useful on the command line:

ro

loop

Options are passed with the -o command-line option and can be grouped, separated by commas. For example, here is the command line used earlier:

mount -t iso9660 -o ro, loop shrike-i386-disc1.iso /mnt/cdrom

The rest of the options are intended for use in /etc/fstab (although they can also be used on the command line). The following list provides the ones we think are most important for day-to-day use.

auto, noauto

defaults

dev, nodev

exec, noexec

user, nouser

suid, nosuid

rw

The nodev, noexec, and nosuid options are particularly valuable for security on floppy-disk and CD-ROM filesystems. Consider a student environment in which students are allowed to mount their own floppies or CDs. It’s trivial to craft a filesystem with a setuid -root shell or a world-writable device file for the hard disk that could let an enterprising user change permissions on system files.

Each filesystem has additional options specific to it. One important option for ext2 and ext3 is the grpid option. We defer discussion of this option until Section 11.5.1, “Default Group for New Files and Directories,” page 412. The details for all supported filesystems can be found in the mount(8) manpage.

As a concrete example, reconsider the line for the Windows partition on our system:

# device   mount-point  type  options                                freq passno
/dev/hda1  /win         vfat  noauto, defaults, user, uid=2076, gid=10 0 0

The noauto option prevents the Windows partition from being mounted at boot time. The defaults option is the same as rw, suid, dev, exec, async. The user option allows us to mount the filesystem without being root. The uid= and gid= options force the files in /win to belong to us as a regular user so that we don’t need to be root when working on that partition.

Any of /etc/fstab, /etc/mtab, and /proc/mounts can be read programmatically with the getmntent() suite of routines:

#include <stdio.h>                                             GLIBC
#include <mntent.h>

FILE *setmntent (const char *filename, const char *type);
struct mntent *getmntent (FILE *filep);
int addmntent (FILE *filep, const struct mntent *mnt);
int endmntent (FILE *filep);
char *hasmntopt (const struct mntent *mnt, const char *opt);

setmntent() opens the file containing mount point entries. The filename argument is the file to open. The type argument is like the second argument to fopen(), indicating read, write, or read/write access. (Consider the mount command, which has to add an entry to /etc/mtab for each filesystem it mounts, and umount, which has to remove one.) The returned value of type FILE * is then used with the rest of the routines.

getmntent() reads through the file, returning a pointer to a static struct mntent, which is filled in with the appropriate values. This static storage is overwritten on each call. It returns NULL when there are no more entries. (This is similar to the routines for reading the password and group files; see Section 6.3, “User and Group Names,” page 195.)

addmntent() is called to add more information to the end of the open file; it’s intended for use by mount.

endmntent() closes the open file; call it when you’re done processing. Don’t just call fclose(); other internal data structures associated with the FILE * variable may need to be cleaned up.

hasmntopt() is a more specialized function. It scans the struct mntent passed as the first parameter for a mount option matching the second argument. If the option is found, it returns the address of the matching substring. Otherwise, it returns NULL.

The fields in the struct mntent correspond directly to the fields in the /etc/fstab file. It looks like this:

struct mntent {
   char *mnt_fsname;   /* Device or server for filesystem. */
   char *mnt_dir;      /* Directory mounted on. */
   char *mnt_type;     /* Type of filesystem: ufs, nfs, etc. */
   char *mnt_opts;     /* Comma-separated options for fs. */
   int mnt_freq;       /* Dump frequency (in days). */
   int mnt_passno;     /* Pass number for 'fsck'. */
};

The normal paradigm for working with mounted filesystems is to write an outer loop that reads /etc/mtab, processing one struct mntent at a time. Our first example, ch08-mounted.c, does exactly that:

 1  /* ch08-mounted.c --- print a list of mounted filesystems */
 2
 3  /* NOTE: GNU/Linux specific! */
 4
 5  #include <stdio.h>
 6  #include <errno.h>
 7  #include <mntent.h> /* for getmntent(), et al. */
 8  #include <unistd.h> /* for getopt() */
 9
10  void process(const char *filename);
11  void print_mount(const struct mntent *fs);
12
13  char *myname;
14
15  /* main --- process options */
16
17  int main(int argc, char **argv)
18  {
19      int c;
20      char *file = "/etc/mtab" /* default file to read */
21
22      myname = argv[0];
23      while ((c = getopt(argc, argv, "f:")) != -1) {
24          switch (c) {
25          case 'f':
26              file = optarg;
27              break;
28          default:
29              fprintf(stderr, "usage: %s [-f fstab-file]
", argv[0]);
30              exit(1);
31          }
32      }
33
34      process(file);
35      return 0;
36  }
37
38  /* process --- read struct mntent structures from file */
39
40  void process(const char *filename)
41  {
42      FILE *fp;
43      struct mntent *fs;
44
45      fp = setmntent(filename, "r"); /* read only */
46      if (fp == NULL) {
47          fprintf(stderr, "%s: %s: could not open: %s/n",
48              myname, filename, strerror(errno));
49          exit(1);
50      }
51
52      while ((fs = getmntent(fp)) != NULL)
53         print_mount(fs);
54
55      endmntent(fp);
56   }
57
58   /* print_mount --- print a single mount entry */
59
60   void print_mount(const struct mntent *fs)
61   {
62      printf("%s %s %s %s %d %d
"
63          fs->mnt_fsname,
64          fs->mnt_dir,
65          fs->mnt_type,
66          fs->mnt_opts,
67          fs->mnt_freq,
68          fs->mnt_passno);
69   }

Unlike most of the programs that we’ve seen up to now, this one is Linux specific. Many Unix systems have similar routines, but they’re not guaranteed to be identical.

By default, ch08-mounted reads /etc/mtab, printing the information about each mounted filesystem. The -f option allows you to specify a different file to read, such as /proc/mounts or even /etc/fstab.

The main() function processes the command line (lines 23–32) and calls process() on the named file. (This program follows our standard boilerplate.)

process(), in turn, opens the file (line 45), and loops over each returned filesystem (lines 52–53). When done, it closes the file (line 55).

The print_mount() function prints the information in the struct mntent. The output ends up being much the same as that of ’cat /etc/mtab’:

$ ch08-mounted                       Run the program
/dev/hda2 / ext3 rw 0 0
none /proc proc rw 0 0
usbdevfs /proc/bus/usb usbdevfs rw 0 0
/dev/hda5 /d ext3 rw 0 0
none /dev/pts devpts rw,gid=5,mode=620 0 0
none /dev/shm tmpfs rw 0 0
none /proc/sys/fs/binfmt_misc binfmt_misc rw 0 0
/dev/hda1 /win vfat rw,noexec,nosuid,nodev,uid=2076,gid=10,user=arnold 0 0

Early Unix systems had only one kind of filesystem. For them, it was sufficient if df read the superblock of each mounted filesystem, extracted the relevant statistics, and formatted them nicely for printing. (The superblock was typically the second block in the filesystem; the first was the boot block, to hold bootstrapping code.)

However, in the modern world, such an approach would be untenable. POSIX provides an XSI extension to access this information. The main function is called statvfs(). (The “vfs” part comes from the underlying SunOS technology, later used in System V Release 4, called a virtual filesystem.) There are two functions:

#include <sys/types.h>                          XSI
#include <sys/statvfs.h>

int statvfs (const char *path, struct statvfs *buf);
int fstatvfs (int fd, struct statvfs *buf);

statvfs() uses a pathname for any file; it returns information about the filesystem containing the file. fstatvfs() accepts an open file descriptor as its first argument; here too, the information returned is about the filesystem containing the open file. The struct statvfs contains the following members:

struct statvfs {
    unsigned long int f_bsize;        Block size
    unsigned long int f_frsize;       Fragment size ("fundamental block size")
    fsblkcnt_t f_blocks;              Total number of blocks
    fsblkcnt_t f_bfree;               Total number of free blocks
    fsblkcnt_t f_bavail;              Number of available blocks (≤f_bfree)
    fsfilcnt_t f_files;               Total number of inodes
    fsfilcnt_t f_ffree;               Total number of free inodes
    fsfilcnt_t f_favail;              Number of available inodes (≤f_files)
    unsigned long int f_fsid;         Filesystem ID
    unsigned long int f_flag;         Flags: ST_RDONLY and/or ST_NOSUID
    unsigned long int f_namemax;      Maximum filename length
};

The information it contains is enough to write df:

unsigned long int f_bsize

The block size is the preferred size for doing I/O. The filesystem attempts to keep at least f_bsize bytes worth of data in contiguous sectors on disk. (A sector is the smallest amount of addressable data on the disk. Typically, a disk sector is 512 bytes.)

unsigned long int f_frsize

Some filesystems (such as the BSD Fast Filesystem) distinguish between blocks and fragments of blocks. Small files whose total size is smaller than a block reside in some number of fragments. This avoids wasting disk space (at the admitted cost of more complexity in the kernel code). The fragment size is chosen at the time the filesystem is created.

fsblkcnt_t f_blocks

The total number of blocks (in units of f_bsize) in the filesystem.

fsblkcnt_t f_bfree

The total number of free blocks in the filesystem.

fsblkcnt_t f_bavail

The number of blocks that may actually be used. Some filesystems reserve a percentage of the filesystem’s blocks for use by the superuser, in case the filesystem fills up. Modern systems reserve around 5 percent, although this number can be changed by an administrator. (See tune2fs(8) on a GNU/Linux system, and tunefs(8) on Unix systems.)

fsfilcnt_t f_files

The total number of inodes (“file serial numbers”, in POSIX parlance) on the filesystem. This number is usually initialized and made permanent when the filesystem is created.

fsfilcnt_t f_ffree

The total number of free inodes.

fsfilcnt_t f_favail

The number of inodes that may actually be used. Some percentage of the inodes are reserved for the superuser, just as for blocks.

unsigned long int f_fsid

The filesystem ID. POSIX doesn’t specify what this represents, and it’s not used under Linux.

unsigned long int f_flag

Flags giving information about the filesystem. POSIX specifies two: ST_RDONLY, for a read-only filesystem (such as a CD-ROM), and ST_NOSUID, which disallows the use of the setuid and setgid permission bits on executables. GNU/Linux systems provide additional flags: They are listed in Table 8.2.

unsigned long int f_namemax

The maximum length of a filename. This refers to each individual component in a pathname; in other words, the maximum length for a directory entry.

The fsblkcnt_t and fsfilcnt_t types are defined in <sys/types.h>. They are typically unsigned long, but on modern systems, they may be even be a 64-bit type, since disks have gotten very large. The following program, ch08-statvfs.c, shows how to use statvfs():

  1  /* ch08-statvfs.c --- demonstrate statvfs */
  2
  3  /* NOTE: GNU/Linux specific! */
  4
  5  #include <stdio.h>
  6  #include <errno.h>
  7  #include <mntent.h> /* for getmntent(), et al. */
  8  #include <unistd.h> /* for getopt() */
  9  #include <sys/types.h>
 10  #include <sys/statvfs.h>
 11
 12  void process(const char *filename);
 13  void do_statvfs(const struct mntent *fs);
 14
 15  int errors = 0;
 16  char *myname;
 17
 18  /* main --- process options */
 19
 20  int main(int argc, char **argv)
 21  {
 22      int c;
 23      char *file = "/etc/mtab"; /* default file to read */
 24
 25      myname = argv[0];
 26      while ((c = getopt(argc, argv, "f:")) != -1) {
 27          switch (c) {
 28          case 'f':
 29              file = optarg;
 30              break;
 31          default:
 32              fprintf(stderr, "usage: %s [-f fstab-file]
", argv[0]);
 33              exit(1);
 34          }
 35      }
 36
 37      process(file);
 38      return(errors != 0);
 39  }
 40
 41  /* process --- read struct mntent structures from file */
 42
 43  void process(const char *filename)
 44  {
 45      FILE *fp;
 46      struct mntent *fs;
 47
 48      fp = setmntent(filename, "r"); /* read only */
 49      if (fp == NULL) {
 50          fprintf(stderr, "%s: %s: could not open: %s
",
 51              myname, filename, strerror(errno));
 52          exit(1);
 53      }
 54
 55      while ((fs = getmntent(fp)) != NULL)
 56          do_statvfs(fs);
 57
 58      endmntent(fp);
 59  }

Lines 1–59 are essentially the same as ch08-mounted.c.main() handles the command line, and process() loops over each mounted filesystem. do_statvfs() does the real work, printing the struct statvfs for each interesting filesystem.

 61  /* do_statvfs --- Use statvfs and print info */
 62
 63  void do_statvfs(const struct mntent *fs)
 64  {
 65      struct statvfs vfs;
 66
 67      if (fs->mnt_fsname[0] != '/') /* skip nonreal filesystems */
 68          return;
 69
 70      if (statvfs(fs->mnt_dir, & vfs) != 0) {
 71          fprintf(stderr, "%s: %s: statvfs failed: %s
",
 72              myname, fs->mnt_dir, strerror(errno));
 73          errors++;
 74          return;
 75      }
 76
 77      printf("%s, mounted on %s:
", fs->mnt_dir, fs->mnt_fsname);
 78      printf("	f_bsize: %ld
",  (long) vfs.f_bsize);
 79      printf("	f_frsize: %ld
", (long) vfs.f_frsize);
 80      printf("	f_blocks: %lu
", (unsigned long) vfs.f_blocks);
 81      printf("	f_bfree: %lu
",  (unsigned long) vfs.f_bfree);
 82      printf("	f_bavail: %lu
", (unsigned long) vfs.f_bavail);
 83      printf("	f_files: %lu
",  (unsigned long) vfs.f_files);
 84      printf("	f_ffree: %lu
",  (unsigned long) vfs.f_ffree);
 85      printf("	f_favail: %lu
", (unsigned long) vfs.f_favail);
 86      printf("	f_fsid: %#lx
",  (unsigned long) vfs.f_fsid);
 87
 88      printf("	f_flag: ");
 89      if (vfs.f_flag == 0)
 90          printf("(none)
");
 91      else {
 92          if ((vfs.f_flag & ST_RDONLY) != 0)
 93             printf("ST_RDONLY ");
 94          if ((vfs.f_flag & ST_NOSUID) != 0)
 95             printf("ST_NOSUID");
 96          printf("
");
 97      }
 98
 99      printf("	f_namemax: %#ld
", (long) vfs.f_namemax);
100  }

Lines 67–68 skip filesystems that are not based on a real disk device. This means that filesystems like /proc or /dev/pts are ignored. (Admittedly, this check is a heuristic, but it works: In /etc/mtab mounted devices are listed by the full device pathname: for example, /dev/hda1.) Line 70 calls statvfs() with appropriate error checking, and lines 77–99 print the information.

Lines 89–96 deal with flags: single bits of information that are or are not present. See the sidebar for a discussion of how flag bits are used in C code. Here is the output of ch08-statvfs:

$ ch08-statvfs                             Run the program
/, mounted on /dev/hda2:                   Results for ext2 filesystem
    f_bsize: 4096
    f_frsize: 4096
    f_blocks: 1549609
    f_bfree: 316663
    f_bavail: 237945
    f_files: 788704
    f_ffree: 555482
    f_favail: 555482
    f_fsid: 0
    f_flag: (none)
    f_namemax: 255
...
/win, mounted on /dev/hda1:                Results for vfat filesystem
    f_bsize: 4096
    f_frsize: 4096
    f_blocks: 2092383
    f_bfree: 1391952
    f_bavail: 1391952
    f_files: 0
    f_ffree: 0
    f_favail: 0
    f_fsid: 0
    f_flag: ST_NOSUID
    f_namemax: 260

As of this writing, for GLIBC 2.3.2 and earlier, GNU df doesn’t use statvfs(). This is because the code reads /etc/mtab, and calls stat() for each mounted filesystem, to find the one on which the device number matches that of the file (or file descriptor) argument. It needs to find the filesystem in order to read the mount options so that it can set the f_flag bits. The problem is that stat() on a remotely mounted filesystem whose server is not available can hang indefinitely, thus causing df to hang as well. This problem has since been fixed in GLIBC, but df won’t change for a while so that it can continue to work on older systems.

#define ST_RDONLY   1   /* read-only filesystem */          
 Sample definitions
#define ST_NOSUID   2   /* setuid/setgid not allowed */

int statvfs (const char *path, struct statvfs *vfs)
{
    ... fill in most of *vfs...
    vfs->f_flag = 0;                          Make sure it starts
 out as zero
    if (filesystem is read-only)
        vfs->f_flag |= ST_RDONLY;             Add the ST_RDONLY flag
    if (filesystem disallows setuid)
        vfs->f_flag | = ST_NOSUID;            Add the ST_NOSUID flag
    ...rest of routine...
}

if ((vfs.f_flag & ST_RDONLY) != 0)            True if ST_RDONLY
 flag is set

vfs.f_flag &= ~(ST_RDONLY|ST_NOSUID);         Clear both flags

The statfs() and fstatfs() system calls are Linux specific. Their declarations are as follows:

#include <sys/types.h>                               GLIBC
#include <sys/vfs.h>

int statfs(const char *path, struct statfs *buf);
int fstatfs(int fd, struct statfs *buf);

As with statvfs() and fstatvfs(), the two versions work on a filename or an open file descriptor, respectively. The struct statfs looks like this:

struct statfs {
    long    f_type;     /* type of filesystem */
    long    f_bsize;    /* optimal transfer block size */
    long    f_blocks;   /* total data blocks in filesystem */
    long    f_bfree;    /* free blocks in fs */
    long    f_bavail;   /* free blocks avail to nonsuperuser */
    long    f_files;    /* total file nodes in file system */
    long    f_ffree;    /* free file nodes in fs */
    fsid_t  f_fsid;     /* filesystem id */
    long    f_namelen;  /* maximum length of filenames */
    long    f_spare[6]; /* spare for later */
};

The fields are analogous to those in the struct statvfs. At least through GLIBC 2.3.2, the POSIX statvfs() and fstatvfs() functions are wrappers around statfs() and fstatfs(), respectively, copying the values from one kind of struct to the other.

The advantage to using statfs() or fstatfs() is that they are system calls. The kernel returns the information directly. Since there is no f_flag field with mount options, it’s not necessary to look at every mounted filesystem to find the right one. (In other words, in order to fill in the mount options, statvfs() must examine each mounted filesystem to find the one containing the file named by path or fd.statfs() doesn’t need to do that, since it doesn’t provide information about the mount options.)

There are two disadvantages to using these calls. First, they are Linux specific. Second, some of the information in the struct statvfs isn’t in the struct statfs; most noticeably, the mount flags (f_flag) and the number of available inodes (f_favail). (Thus, the Linux statvfs() has to find mount options from other sources, such as /etc/mtab, and it “fakes” the information for the struct statvfs fields for which real information isn’t available.)

One field in the struct statfs deserves special note. This is the f_type field, which indicates the type of the filesystem. The value is the filesystem’s magic number, extracted from the superblock. The statfs(2) manpage provides a list of commonly used filesystems and their magic numbers, which we use in ch08-statfs.c. (Alas, there is no separate #include file.)

  1  /* ch08-statfs.c --- demonstrate Linux statfs */
  2
  3  /* NOTE: GNU/Linux specific! */
  4
  5  #include <stdio.h>
  6  #include <errno.h>
  7  #include <mntent.h> /* for getmntent(), et al. */
  8  #include <unistd.h> /* for getopt() */
  9  #include <sys/types.h>
 10  #include <sys/vfs.h>
 11
 12  /* Defines taken from statfs(2) man page: */
 13  #define AFFS_SUPER_MAGIC      0xADFF
 14  #define EFS_SUPER_MAGIC       0x00414A53
 15  #define EXT_SUPER_MAGIC       0x137D
 16  #define EXT2_OLD_SUPER_MAGIC  0xEF51
 17  #define EXT2_SUPER_MAGIC      0xEF53
 18  #define HPFS_SUPER_MAGIC      0xF995E849
 19  #define ISOFS_SUPER_MAGIC     0x9660
 20  #define MINIX_SUPER_MAGIC     0x137F /* orig. minix */
 21  #define MINIX_SUPER_MAGIC2    0x138F /* 30-char minix */
 22  #define MINIX2_SUPER_MAGIC    0x2468 /* minix V2 */
 23  #define MINIX2_SUPER_MAGIC2   0x2478 /* minix V2, 30 char names */
 24  #define MSDOS_SUPER_MAGIC     0x4d44
 25  #define NCP_SUPER_MAGIC       0x564c
 26  #define NFS_SUPER_MAGIC       0x6969
 27  #define PROC_SUPER_MAGIC      0x9fa0
 28  #define SMB_SUPER_MAGIC       0x517B
 29  #define XENIX_SUPER_MAGIC     0x012FF7B4
 30  #define SYSV4_SUPER_MAGIC     0x012FF7B5
 31  #define SYSV2_SUPER_MAGIC     0x012FF7B6
 32  #define COH_SUPER_MAGIC       0x012FF7B7
 33  #define UFS_MAGIC             0x00011954
 34  #define XFS_SUPER_MAGIC       0x58465342
 35  #define _XIAFS_SUPER_MAGIC    0x012FD16D
 36
 37  void process (const char *filename);
 38  void do_statfs(const struct mntent *fs);
 39
 40  int errors = 0;
 41  char *myname;
 42
     ... main() is unchanged, process() is almost identical...
 85
 86  /* type2str --- convert fs type to printable string, from statfs(2) */
 87
 88  const char *type2str(long type)
 89  {
 90      static struct fsname {
 91          long type;
 92          const char *name;
 93      } table[] = {
 94          { AFFS_SUPER_MAGIC, "AFFS" },
 95          { COH_SUPER_MAGIC, "COH" },
 96          { EXT2_OLD_SUPER_MAGIC, "OLD EXT2" },
 97          { EXT2_SUPER_MAGIC, "EXT2" },
 98          { HPFS_SUPER_MAGIC, "HPFS" },
 99          { ISOFS_SUPER_MAGIC, "ISOFS" },
100          { MINIX2_SUPER_MAGIC, "MINIX V2" },
101          { MINIX2_SUPER_MAGIC2, "MINIX V2 30 char" },
102          { MINIX_SUPER_MAGIC, "MINIX" },
103          { MINIX_SUPER_MAGIC2, "MINIX 30 char" },
104          { MSDOS_SUPER_MAGIC, "MSDOS" },
105          { NCP_SUPER_MAGIC, "NCP" },
106          { NFS_SUPER_MAGIC, "NFS" },
107          { PROC_SUPER_MAGIC, "PROC" },
108          { SMB_SUPER_MAGIC, "SMB" },
109          { SYSV2_SUPER_MAGIC, "SYSV2" },
110          { SYSV4_SUPER_MAGIC, "SYSV4" },
111          { UFS_MAGIC, "UFS" },
112          { XENIX_SUPER_MAGIC, "XENIX" },
113          { _XIAFS_SUPER_MAGIC, "XIAFS" },
114          { 0, NULL },
115      };
116      static char unknown [100];
117      int i;
118
119      for (i = 0; table[i].type ! = 0; i++)
120          if (table[i].type == type)
121              return table[i].name;
122
123      sprintf (unknown, "unknown type: %#x", type);
124      return unknown;
125  }
126
127  /* do_statfs --- Use statfs and print info */
128
129  void do_statfs (const struct mntent *fs)
130  {
131     struct statfs vfs;
132
133     if (fs->mnt_fsname[0] != '/') /* skip nonreal filesystems */
134         return;
135
136     if (statfs(fs->mnt_dir, & vfs) != 0) {
137         fprintf(stderr, "%s: %s: statfs failed: %s
",
138             myname, fs->mnt_dir, strerror(errno));
139         errors++;
140         return;
141     }
142
143     printf("s, mounted on %s;/n", fs->mnt_dir, fs->mnt_fsname);
144
145     printf("	f_type: %s
", type2str(vfs.f_type));
146     printf("	f_bsize: %ld
", vfs.f_bsize);
147     printf("	f_blocks: %ld
", vfs.f_blocks);
148     printf("	f_bfree: %ld
", vfs.f_bfree);
149     printf("	f_bavail: %ld
", vfs.f_bavail);
150     printf("	f_files: %ld
", vfs.f_files);
151     printf("	f_ffree: %ld
", vfs.f_ffree);
152     printf("	f_namelen: %ld
", vfs.f_namelen);
153  }

To save space, we’ve omitted main(), which is unchanged from the other programs presented earlier, and we’ve also omitted process(), which now calls do_statfs() instead of do_statvfs().

Lines 13–35 contain the list of filesystem magic numbers from the statfs(2) manpage. Although the numbers could be retrieved from kernel source code header files, such retrieval is painful (we tried), and the presentation here is easier to follow. Lines 86–125 define type2str(), which converts the magic number to a printable string. It does a simple linear search on a table of (value, string) pairs. In the (unlikely) event that the magic number isn’t in the table, types2str() creates an “unknown type” message and returns that (lines 123–124).

do_statfs() (lines 129–153) prints the information from the struct statfs. The f_fsid member is omitted since fsid_t is an opaque type. The code is straightforward; line 145 uses type2str() to print the filesystem type. As for the similar program using statvfs(), this function ignores filesystems that aren’t on local devices (lines 133–134). Here is the output on our system:

$ ch08-statfs                        Run the Program
/, mounted on /dev/hda2:             Results for ext2 filesystem
    f_type: EXT2
    f_bsize: 4096
    f_blocks: 1549609
    f_bfree: 316664
    f_bavail: 237946
    f_files: 788704
    f_ffree: 555483
    f_namelen: 255
...
/win, mounted on /dev/hda1:          Results for vfat filesystem
    f_type: MSDOS
    f_bsize: 4096
    f_blocks: 2092383
    f_bfree: 1391952
    f_bavail: 1391952
    f_files: 0
    f_ffree: 0
    f_namelen: 260

In conclusion, whether to use statvfs() or statfs() in your own code depends on your requirements. As described in the previous section, GNU df doesn’t use statvfs() under GNU/Linux and in general tends to use each Unix system’s unique “get filesystem info” system call. Although this works, it isn’t pretty. On the other hand, sometimes you have no choice: for example, the GLIBC problems we mentioned above. In this case, there is no perfect solution.

In Section 1.2, “The Linux/Unix Process Model,” page 10, we said:

Each process has a current working directory. Each new process inherits its current directory from the process that started it (its parent). Two functions let you change to another directory:

#include <unistd.h>

int chdir (const char *path);                    POSIX
int fchdir (int fd);                             XSI

The chdir() function takes a string naming a directory, whereas fchdir() expects a file descriptor that was opened on a directory with open().^[6] Both return 0 on success and -1 on error (with errno set appropriately). Typically, if open() on a directory succeeded, then fchdir() will also succeed, unless someone changed the permissions on the directory between the calls. (fchdir() is a relatively new function; older Unix systems won’t have it.)

These functions are almost trivial to use. The following program, ch08-chdir.c, demonstrates both functions. It also demonstrates that fchdir() can fail if the permissions on the open directory don’t include search (execute) permission:

 1  /* ch08-chdir.c --- demonstrate chdir() and fchdir().
 2                      Error checking omitted for brevity */
 3
 4  #include <stdio.h>
 5  #include <fcntl.h>
 6  #include <unistd.h>
 7  #include <sys/types.h>
 8  #include <sys/stat.h>
 9
10  int main(void)
11  {
12      int fd;
13      struct stat sbuf;
14
15      fd = open(“.”, O_RDONLY);   /* open directory for reading */
16      fstat(fd, & sbuf);          /* obtain info, need original permissions */
17      chdir(“..”);                /* ’cd ..’ */
18      fchmod(fd, 0);              /* zap permissions on original directory */
19
20      if (fchdir(fd) < 0)         /* try to ’cd’ back, should fail */
21          perror(“fchdir back”);
22
23   fchmod(fd, sbuf.st_mode & 07777);   /* restore original permissions */
24   close(fd);                  /* all done */
25
26   return 0;
27 }

Line 15 opens the current directory. Line 16 calls fstat() on the open directory so that we have a copy of its permissions. Line 17 uses chdir() to move up a level in the file hierarchy. Line 18 does the dirty work, turning off all permissions on the original directory.

Lines 20–21 attempt to change back to the original directory. It is expected to fail, since the current permissions don’t allow it. Line 23 restores the original permissions. The ’sbuf.st_mode & 07777’ retrieves the low-order 12 permission bits; these are the regular 9 rwxrwxrwx bits, and the setuid, setgid, and “sticky” bits, which we discuss in Chapter 11, “Permissions and User and Group ID Numbers,” page 403. Finally, line 24 cleans up by closing the open file descriptor. Here’s what happens when the program runs:

$ ls -ld.                                               Show current permissions
drwxr-xr-x    2 arnold   devel     4096 Sep  9 16:42.
$ ch08-chdir                                            Run the program
fchdir back: Permission denied                          Fails as expected
$ ls -ld.                                               Look at permissions again
drwxr-xr-x    2 arnold   devel     4096 Sep  9 16:42.   Everything is back as it was

The aptly named getcwd() function retrieves the absolute pathname of the current working directory:

#include <unistd.h>                                       POSIX

char *getcwd(char *buf, size_t size);

The function fills in buf with the pathname; it expects buf to have size bytes. Upon success, it returns its first argument. Otherwise, if it needs more than size bytes, it returns NULL and sets errno to ERANGE. The intent is that if ERANGE happens, you should try to allocate a larger buffer (with malloc() or realloc()) and try again.

If any of the directory components leading to the current directory are not readable or searchable, then getcwd() can fail and errno will be EACCES. The following simple program demonstrates its use:

/* ch08-getcwd.c --- demonstrate getcwd().
                     Error checking omitted for brevity */

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>

int main(void)
{
    char buf[PATH_MAX];
    char *cp;

    cp = getcwd(buf, sizeof(buf));
    printf("Current dir: %s
", buf);

    printf("Changing to ..
");
    chdir("..");            /* 'cd ..' */

    cp = getcwd(buf, sizeof(buf));
    printf("Current dir is now: %s
", buf);

    return 0;
}

This simple program prints the current directory, changes to the parent directory, and then prints the new current directory. (cp isn’t really needed here, but in a real program it would be used for error checking.) When run, it produces the following output:

$ ch08-getcwd
Current dir: /home/arnold/work/prenhall/progex/code/ch08
Changing to ..
Current dir is now: /home/arnold/work/prenhall/progex/code

>Formally, if the buf argument is NULL, the behavior of getcwd() is undefined. In this case, the GLIBC version of getcwd() will call malloc() for you, allocating a buffer of size size. Going even further out of its way to be helpful, if size is 0, then the buffer it allocates will be “big enough” to hold the returned pathname. In either case, you should call free() on the returned pointer when you’re done with the buffer.

The GLIBC behavior is helpful, but it’s not portable. For code that has to work across platforms, you can write a replacement function that provides the same functionality while having your replacement function call getcwd() directly if on a GLIBC system.

GNU/Linux systems provide the file /proc/self/cwd. This file is a symbolic link to the current directory:

$ cd /tmp                         Change directory someplace
$ ls -l /proc/self/cwd            Look at the file
lrwxrwxrwx    1 arnold   devel   0 Sep 9 17:29 /proc/self/cwd -> /tmp
$ cd                              Change to home directory
$ ls -l /proc/self/cwd            Look at it again
lrwxrwxrwx   1 arnold   devel    0 Sep 9 17:30 /proc/self/cwd -> /home/arnold

This is convenient at the shell level but presents a problem at the programmatic level. In particular, the size of the file is zero! (This is because it’s a file in /proc, which the kernel fakes; it’s not a real file living on disk.)

Why is the zero size a problem? If you remember from Section 5.4.5, “Working with Symbolic Links,” page 151, lstat() on a symbolic link returns the number of characters in the name of the linked-to file in the st_size field of the struct stat. This number can then be used to allocate a buffer of the appropriate size for use with readlink(). That won’t work here, since the size is zero. You have to use (or allocate) a buffer that you guess is big enough. However, since readlink() does not fill in any more characters than you provide, you can’t tell whether or not the buffer is big enough; readlink() does not fail when there isn’t enough room. (See the Coreutils xreadlink() function in Section 5.4.5, “Working with Symbolic Links,” page 151, which solves the problem.)

In addition to getcwd(), GLIBC has several other nonportable routines. These save you the trouble of managing buffers and provide compatibility with older BSD systems. For the details, see getcwd(3).

A common programming task is to process entire directory hierarchies: doing something for every file and every directory and subdirectory in an entire tree. Consider, for example, du, which prints disk usage information, ’chown -R’, which recursively changes ownership, or the find program, which finds files matching certain criteria.

At this point, you know enough to write your own code to manually open and read directories, call stat() (or lstat()) for each entry, and recursively process subdirectories. However, such code is challenging to get right; it’s possible to run out of file descriptors if you leave parent directories open while processing subdirectories; you have to decide whether to process symbolic links as themselves or as the files they point to; you have to be able to deal with directories that aren’t readable or searchable, and so on. It’s also painful to have to write the same code over and over again if you need it for multiple applications.

#include <ftw.h>                                                  XSI

int nftw(const char *dir,                      Starting point
         int (*fn) (const char *file,          Function pointer to
                    const struct stat *sb,     function of four arguments
                    int flag, struct FTW *s),
         int depth, int flags);                Max open fds, flags

$ pwd                                   Where we are
/home/arnold/work/prenhall/progex
$ code/ch08/ch08-nftw code              Walk the 'code' directory
code (directory)                        Top-level directory
    ch02 (directory)                    Subdirectories one level indented
        ch02-printenv.c (file)          Files in subdirs two levels indented
    ch03 (directory)
        ch03-memaddr.c (file)
    ch04 (directory)
        ch04-holes.c (file)
        ch04-cat.c (file)
        ch04-maxfds.c (file)
        v7cat.c (file)
...

  1  /* ch08-nftw.c --- demonstrate nftw() */
  2
  3  #define _XOPEN_SOURCE 1              /* Required under GLIBC for nftw() */
  4  #define _XOPEN_SOURCE_EXTENDED 1     /* Same */
  5
  6  #include <stdio.h>
  7  #include <errno.h>
  8  #include <getopt.h>
  9  #include <ftw.h>       /* gets <sys/types.h> and <sys/stat.h> for us */
 10  #include <limits.h>    /* for PATH_MAX */
 11  #include <unistd.h>    /* for getdtablesize(), getcwd() declarations */
 12
 13  #define SPARE_FDS 5    /* fds for use by other functions, see text */
 14
 15  extern int process (const char *file, const struct stat *sb,
 16             int flag, struct FTW *s);
 17
 18  /* usage --- print message and die */
 19
 20  void usage (const char *name)
 21  {
 22      fprintf(stderr, "usage: %s [-c] directory ...
", name);
 23      exit(1);
 24  }
 25
 26  /* main --- call nftw() on each command-line argument */
 27
 28  int main(int argc, char **argv)
 29  {
 30      int i, c, nfds;
 31      int errors = 0;
 32      int flags = FTW_PHYS;
 33      char start[PATH_MAX], finish[PATH_MAX];
 34
 35      while ((c = getopt (argc, argv, "c")) != -1) {
 36          switch (c) {
 37          case 'c':
 38              flags |= FTW_CHDIR;
 39              break;
 40          default:
 41              usage(argv[0]);
 42              break;
 43          }
 44      }
 45
 46      if (optind == argc)
 47          usage (argv[0]);
 48
 49      getcwd(start, sizeof start);
 50
 51      nfds = getdtablesize() - SPARE_FDS; /* leave some spare descriptors */
 52      for (i = optind; i < argc; i++) {
 53          if (nftw(argv[i], process, nfds, flags) != 0) {
 54              fprintf(stderr, "%s: %s: stopped early
",
 55                  argv[0], argv[i]);
 56              errors++;
 57          }
 58      }
 59
 60      if ((flags & FTW_CHDIR) != 0) {
 61          getcwd(finish, sizeof finish);
 62          printf("Starting dir: %s
", start);
 63          printf("Finishing dir: %s
", finish);
 64      }
 65
 66      return (errors != 0);
 67  }

 69  /* process --- print out each file at the right level */
 70
 71  int process(const char *file, const struct stat *sb,
 72          int flag, struct FTW *s)
 73  {
 74      int retval = 0;
 75      const char *name = file + s->base;
 76
 77      printf("%*s", s->level * 4, "");    /* indent over */
 78
 79      switch (flag) {
 80      case FTW_F:
 81          printf("%s (file)
", name);
 82          break;
 83      case FTW_D:
 84          printf("%s (directory)
", name);
 85          break;
 86    case FTW_DNR:
 87        printf("%s (unreadable directory)
", name);
 88        break;
 89    case FTW_SL:
 90        printf("%s (symbolic link)
", name);
 91        break;
 92    case FTW_NS:
 93        printf("%s (stat failed): %s
", name, strerror(errno));
 94        break;
 95    case FTW_DP:
 96    case FTW_SLN:
 97        printf("%s: FTW_DP or FTW_SLN: can't happen!
", name);
 98        retval = 1;
 99        break;
100    default:
101        printf("%s: unknown flag %d: can't happen!
", name, flag);
102        retval = 1;
103        break;
104    }
105
106    return retval;
107  }