Copyright 1997-2004 © J.D. “Illiad” Frazer

Used with permission. http://www.userfriendly.org

We start the discussion by defining some terms.

Partition

Filesystem

Inode

Device

Directory

Conceptually, each disk block contains either some number of inodes, or file data. The inode, in turn, contains pointers to the blocks that contain the file’s data. See Figure 5.1.

Figure 5.1. Conceptual view of inode and data blocks

The figure shows all the inode blocks at the front of the partition and the data blocks after them. Early Unix filesystems were indeed organized this way. However, while all modern systems still have inodes and data blocks, the organization has changed for improved efficiency and robustness. The details vary from system to system, and even within GNU/Linux systems there are multiple kinds of filesystems, but the concepts are the same.

Directories make the connection between a filename and an inode. Directory entries contain an inode number and a filename. They also contain additional bookkeeping information that is not of interest to us here. See Figure 5.2.

Figure 5.2. Conceptual directory contents

Early Unix systems had two-byte inode numbers and up to 14-byte filenames. Here is the entire content of the V7 /usr/include/sys/dir.h:

#ifndef DIRSIZ
#define DIRSIZ 14
#endif
struct  direct
{
        ino_t  d_ino;
        char   d_name[DIRSIZ];
};

An ino_t is defined in the V7 <sys/types.h> as ’typedef unsigned int ino_t;’. Since a PDP-11 int is 16 bits, so too is the ino_t. This organization made it easy to read directories directly; since the size of an entry was fixed, the code was simple. (The only thing to watch out for was that a full 14-character d_name was not NUL-terminated.)

Directory content management was also easy for the system. When a file was removed from a directory, the system replaced the inode number with a binary zero, signifying that the “slot” in the directory was unused. New files could then reuse the empty slot. This helped keep the size of directory files themselves reasonable. (By convention, inode number 1 is unused; inode number 2 is always the first usable inode. More details are provided in Section 8.1, “Mounting and Unmounting Filesystems,” page 228.)

Modern systems provide long filenames. Each directory entry is of variable length, with a common limit of 255 bytes for the filename component of the directory. Later on, we show how to read a directory’s contents on a modern system. Modern systems also provide 32-bit (or even 64-bit!) inode numbers.

When a file is created with open() or creat(), the system finds an unused inode and assigns it to the new file. It creates the directory entry for the file, with the file’s name and inode number in it. The -i option to ls shows the inode number:

$ echo hello, world > message                      Create new file
$ ls -il message                                   Show inode number too
 228786 -rw-r--r--    1 arnold  devel    13 May  4 15:43 message

Since directory entries associate filenames with inodes, it is possible for one file to have multiple names. Each directory entry referring to the same inode is called a link, or hard link, to the file. Links are created with the ln command. The usage is ’ln oldfile newfile’:

$ ln message msg                                   Create a link
$ cat msg                                          Show contents of new name
hello, world
$ ls -il msg message                               Show inode numbers
 228786 -rw-r--r--    2 arnold   devel   13 May  4 15:43 message
 228786 -rw-r--r--    2 arnold   devel   13 May  4 15:43 msg

The output shows that the inode numbers of the two files are the same, and the third field in the long output is now 2. This field is the link count, which reports how many links (directory entries referring to the inode) the file has.

It cannot be emphasized enough: Hard links all refer to the same file. If you change one, you have changed the others:

$ echo "Hi, how ya doin' ?" > msg                   Change file by new name
$ cat message                                       Show contents by old name
Hi, how ya doin' ?
$ ls -il message msg                                Show info. Size changed
 228786 -rw-r--r--    2 arnold   devel    19 May  4 15:51 message
 228786 -rw-r--r--    2 arnold   devel    19 May  4 15:51 msg

Although we’ve created two links to the same file in a single directory, hard links are not restricted to being in the same directory; they can be in any other directory on the same filesystem. (This is discussed a bit more in Section 5.1.6, “Symbolic Links,” page 128.)

Additionally, you can create a link to a file you don’t own as long as you have write permission in the directory in which you’re creating the link. (Such a file retains all the attributes of the original file: the owner, permissions, and so on. This is because it is the original file; it has only acquired an additional name.) User-level code cannot create a hard link to a directory.

Once a link is removed, creating a new file by the same name as the original file creates a new file:

$ rm message                                        Remove old name
$ echo "What's happenin?" > message                 Reuse the name
$ ls -il msg message                                Show information
228794 -rw-r--r--     1 arnold   devel    17 May  4 15:58 message
228786 -rw-r--r--     1 arnold   devel    19 May  4 15:51 msg

Notice that the link counts for both files are now equal to 1.

At the C level, links are created with the link() system call:

#include <unistd.h>                                             POSIX

int link(const char *oldpath, const char *newpath);

The return value is 0 if the link was created successfully, or -1 otherwise, in which case errno reflects the error. An important failure case is one in which newpath already exists. The system won’t remove it for you, since attempting to do so can cause inconsistencies in the filesystem.

 20  /* Implementation overview:
 21
 22     Simply call the system 'link' function */
 23
     ...#include statements omitted for brevity...
 34
 35  /* The official name of this program (e.g., no 'g' prefix). */
 36  #define PROGRAM_NAME "link"
 37
 38  #define AUTHORS "Michael Stone"
 39
 40  /* Name this program was run with. */
 41  char *program_name;
 42
 43  void
 44  usage (int status)
 45  {
     ...omitted for brevity...
 62  }
 63
 64  int
 65  main (int argc, char **argv)
 66  {
 67    program_name = argv[0];
 68    setlocale (LC_ALL, "");
 69    bindtextdomain (PACKAGE, LOCALEDIR);
 70    textdomain (PACKAGE);
 71
 72    atexit (close_stdout);
 73
 74    parse_long_options (argc, argv, PROGRAM_NAME, GNU_PACKAGE, VERSION,
 75                        AUTHORS, usage);
 76
 77    /* The above handles --help and --version.
 78       Since there is no other invocation of getopt, handle '--' here. */
 79    if (1 < argc && STREQ (argv[1], "--"))
 80      {
 81       --argc;
 82       ++argv;
 83      }
 84
 85    if (argc < 3)
 86      {
 87        error (0, 0, _("too few arguments"));
 88        usage (EXIT_FAILURE);
 89      }
 90
 91    if (3 < argc)
 92      {
 93        error (0, 0, _("too many arguments"));
 94        usage (EXIT_FAILURE);
 95      }
 96
 97    if (link (argv[1], argv[2]) != 0)
 98      error (EXIT_FAILURE, errno, _("cannot create link %s to %s"),
 99             quote_n (0, argv[2]), quote_n (1, argv[1]));
100
101    exit (EXIT_SUCCESS);
102  }

$ pwd                                           Show current directory
/tmp
$ ls -ldi /tmp                                  Show its inode number
 225345 drwxrwxrwt   14 root     root     4096 May  4 16:15 /tmp
$ mkdir x                                       Create a new directory
$ ls -ldi x                                     And show its inode number
  52794 drwxr-xr-x    2 arnold   devel    4096 May  4 16:27 x
$ ls -ldi x/. x/..                              Show. and.. inode numbers
  52794 drwxr-xr-x    2 arnold   devel    4096 May  4 16:27 x/.
 225345 drwxrwxrwt   15 root     root     4096 May  4 16:27 x/..

Given the way in which directory entries map names to inode numbers, renaming a file is conceptually quite easy:

Early versions of the mv command did work this way. However, when done this way, file renaming is not atomic; that is, it doesn’t happen in one uninterruptible operation. And, on a heavily loaded system, a malicious user could take advantage of race conditions,^[1] subverting the rename operation and substituting a different file for the original one.

For this reason, 4.2 BSD introduced the rename() system call:

#include <stdio.h>                                           ISO C

int rename(const char *oldpath, const char *newpath);

On Linux systems, the renaming operation is atomic; the manpage states:

As with other system calls, a 0 return indicates success, and a return value of -1 indicates an error.

Removing a file means removing the file’s entry in the directory and decrementing the file’s link count (maintained in the inode). The contents of the file, and the disk blocks holding them, are not freed until the link count reaches zero.

The system call is named unlink():

#include <unistd.h>                                      POSIX

int unlink(const char *pathname);

Given our discussion of file links, the name makes sense; this call removes the given link (directory entry) for the file. It returns 0 on success and -1 on error.

The ability to remove a file requires write permission only for the directory and not for the file itself. This fact can be confusing, particularly for new Linux/Unix users. However, since the operation is one on the directory, this makes sense; it is the directory contents that are being modified, not the file’s contents.^[2]

/* Obtaining private temporary storage, error checking omitted for brevity */
int fd;
mode_t mode = O_CREAT|O_EXCL|O_TRUNC|O_RDWR;

fd = open("/tmp/myfile", mode, 0000);           Open the file
unlink("/tmp/myfile");                          Remove it

...continue to use file...
close(fd);                                      Close file, free storage

#include <stdio.h>                                      ISO C

int remove(const char *pathname);

We started the chapter with a discussion of partitions, filesystems, and inodes. We also saw that directory entries associate names with inode numbers. Because directory entries contain no other information, hard links are restricted to files within the same filesystem. This has to be; there is no way to distinguish inode 2341 on one filesystem from inode 2341 on another filesystem. Here is what happens when we try:

$ mount                                 Show filesystems in use
/dev/hda2 on / type ext3 (rw)
/dev/hda5 on /d type ext3 (rw)
...
$ ls -li /tmp/message                   Earlier example was on filesystem for /
 228786 -rw-r--r--    2 arnold   devel        19 May 4 15:51 /tmp/message
$ cat /tmp/message
Hi, how ya doin' ?
$ /bin/pwd                              Current directory is on a different filesystem
/d/home/arnold
$ ln /tmp/message .                     Attempt the link
ln: creating hard link `./message' to `/tmp/message': Invalid cross-device link

Large systems often have many partitions, both on physically attached local disks and on remotely mounted network filesystems. The hard-link restriction to the same filesystem is inconvenient, for example, if some files or directories must be moved to a new location, but old software uses a hard-coded filename for the old location.

To get around this restriction, 4.2 BSD introduced symbolic links. A symbolic link (also referred to as a soft link) is a special kind of file (just as a directory is a special kind of file). The contents of the file are the pathname of the file being “pointed to.” All modern Unix systems, including Linux, provide symbolic links; indeed they are now part of POSIX.

Symbolic links may refer to any file anywhere on the system. They may also refer to directories. This makes it easy to move directories from place to place, with a symbolic link left behind in the original location pointing to the new location.

When processing a filename, the system notices symbolic links and instead performs the action on the pointed-to file or directory. Symbolic links are created with the -s option to ln:

$ /bin/pwd                                  Where are we
/d/home/arnold                              On a different filesystem
$ ln -s /tmp/message ./hello                Create a symbolic link
$ cat hello                                 Use it
Hi, how ya doin' ?
$ ls -l hello                               Show information about it
lrwxrwxrwx    1 arnold   devel     12 May  4 16:41 hello -> /tmp/message

The file pointed to by the link need not exist. The system detects this at runtime and acts appropriately:

$ rm /tmp/message                            Remove pointed-to file
$ cat ./hello                                Attempt to use it by the soft link
cat: ./hello: No such file or directory
$ echo hi again > hello                      Create new file contents
$ ls -l /tmp/message                         Show pointed-to file info ...
-rw-r--r--    1 arnold   devel       9 May  4 16:45 /tmp/message
$ cat /tmp/message                           ... and contents
hi again

Symbolic links are created with the symlink() system call:

#include <unistd.h>                                             POSIX

int symlink(const char *oldpath, const char *newpath);

The oldpath argument names the pointed-to file or directory, and newpath is the name of the symbolic link to be created. The return value is 0 on success and -1 on error; see your symlink(2) manpage for the possible errno values.

Symbolic links have their disadvantages:

Directory entries are represented by a struct dirent (not the same as the V7 struct direct!):

struct dirent {
    ...
    ino_t d_ino;            /* XSI extension --- see text */
    char  d_name[...];      /* See text on the size of this array */
...
};

For portability, POSIX specifies only the d_name field, which is a zero-terminated array of bytes representing the filename part of the directory entry. The size of d_name is not specified by the standard, other than to say that there may be at most NAME_MAX bytes before the terminating zero. (NAME_MAX is defined in <limits.h>.) The XSI extension to POSIX provides for the d_ino inode number field.

In practice, since filenames can be of variable length and NAME_MAX is usually fairly large (like 255), the struct dirent contains additional members that aid in the bookkeeping of variable-length directory entries on disk. These additional members are not relevant for everyday code.

The following functions provide the directory-reading interface:

#include <sys/types.h>                                                   POSIX
#include <dirent.h>

DIR *opendir(const char *name);       Open a directory for reading
struct dirent *readdir(DIR *dir);     Return one struct dirent at a time
int closedir(DIR *dir);               Close an open directory
void rewinddir(DIR *dirp);            Return to the front of a directory

The DIR type is analogous to the FILE type in <stdio.h>. It is an opaque type, meaning that application code is not supposed to know what’s inside it; its contents are for use by the other directory routines. If opendir() returns NULL, the named directory could not be opened for reading and errno is set to indicate the error.

Once you have an open DIR * variable, it can be used to retrieve a pointer to a struct dirent representing the next directory entry. readdir() returns NULL upon end-of-file or error.

Finally, closedir() is analogous to the fclose() function in <stdio.h>; it closes the open DIR * variable. The rewinddir() function can be used to start over at the beginning of a directory.

With these routines in hand (or at least in the C library), we can write a simple catdir program that “cats” the contents of a directory. Such a program is presented in ch05-catdir.c:

 1  /* ch05-catdir.c --- Demonstrate opendir(), readdir(), closedir(). */
 2
 3  #include <stdio.h>      /* for printf() etc. */
 4  #include <errno.h>      /* for errno */
 5  #include <sys/types.h>  /* for system types */
 6  #include <dirent.h>     /* for directory functions */
 7
 8  char *myname;
 9  int process(char *dir);
10
11  /* main --- loop over directory arguments */
12
13  int main(int argc, char **argv)
14  {
15      int i;
16      int errs = 0;
17
18      myname = argv[0];
19
20      if (argc == 1)
21          errs = process(".");    /* default to current directory */
22      else
23          for (i = 1; i < argc; i++)
24              errs += process(argv[i]);
25
26      return (errs != 0);
27  }

This program is quite similar to ch04-cat.c (see Section 4.2, “Presenting a Basic Program Structure,” page 84); the main() function is almost identical. The primary difference is that it defaults to using the current directory if there are no arguments (lines 20–21).

29  /*
30   * process --- do something with the directory, in this case,
31   *             print inode/name pairs on standard output.
32   *             Returns 0 if all ok, 1 otherwise.
33   */
34
35  int
36  process(char *dir)
37  {
38      DIR *dp;
39      struct dirent *ent;
40
41      if ((dp = opendir(dir)) == NULL) {
42          fprintf(stderr, "%s: %s: cannot open for reading: %s
",
43                  myname, dir, strerror(errno));
44          return 1;
45      }
46
47      errno = 0;
48      while ((ent = readdir(dp)) != NULL)
49          printf("%8ld %s
", ent->d_ino, ent->d_name);
50
51      if (errno != 0) {
52          fprintf(stderr, "%s: %s: reading directory entries: %s
",
53                  myname, dir, strerror(errno));
54          return 1;
55      }
56
57      if (closedir(dp) != 0) {
58          fprintf(stderr, "%s: %s: closedir: %s
",
59                  myname, dir, strerror(errno));
60          return 1;
61      }
62
63      return 0;
64  }

The process() function does all the work, and the majority of it is error-checking code. The heart of the function is lines 48 and 49:

while ((ent = readdir(dp)) != NULL)
    printf("%8ld %s
", ent->d_ino, ent->d_name);

This loop reads directory entries, one at a time, until readdir() returns NULL. The loop body prints the inode number and filename of each entry. Here’s what happens when the program is run:

$ ch05-catdir                Default to current directory
  639063 .
  639062 ..
  639064 proposal.txt
  639012 lightsabers.url
  688470 code
  638976 progex.texi
  639305 texinfo.tex
  639007 15-processes.texi
  639011 00-preface.texi
  639020 18-tty.texi
  638980 Makefile
  639239 19-i18n.texi
...

The output is not sorted in any way; it represents the linear contents of the directory. (We describe how to sort the directory contents in Section 6.2, “Sorting and Searching Functions,” page 181.)

NAME
    getdents - get directory entries
SYNOPSIS
    #include <unistd.h>
    #include <linux/types.h>
    #include <linux/dirent.h>
    #include <linux/unistd.h>

    _syscall3(int, getdents, uint, fd, struct dirent *, dirp,
 uint, count);

    int getdents(unsigned int fd, struct dirent *dirp, unsigned
 int count);

struct dirent {
    ...
    ino_t d_ino;              /* As before */
    char  d_name[...];        /* As before */
    unsigned char d_type;     /* Linux and modern BSD */
    ...
};

Occasionally, it’s useful to mark the current position in a directory in order to be able to return to it later. For example, you might be writing code that traverses a directory tree and wish to recursively enter each subdirectory as you come across it. (How to distinguish files from directories is discussed in the next section.) For this reason, the original BSD interface included two additional routines:

#include <dirent.h>                                              XSI

/* Caveat Emptor: POSIX XSI uses long, not off_t, for both functions */
off_t telldir(DIR *dir);                     Return current position
void seekdir(DIR *dir, off_t offset);        Move to given position

These routines are similar to the ftell() and fseek() functions in <stdio.h>. They return the current position in a directory and set the current position to a previously retrieved value, respectively.

These routines are included in the XSI part of the POSIX standard, since they make sense only for directories that are implemented with linear storage of directory entries.

Besides the assumptions made about the underlying directory structure, these routines are riskier to use than the simple directory-reading routines. This is because the contents of a directory might be changing dynamically: As files are added to or removed from a directory, the operating system adjusts the contents of the directory. Since directory entries are of variable length, it may be that the absolute offset saved at an earlier time no longer represents the start of a directory entry! Thus, we don’t recommend that you use these functions unless you have to.

Linux (and Unix) supports the following different kinds of file types:

Regular files

Directories

Symbolic links

Devices

Named pipes

Sockets

Three system calls return information about files:

#include <sys/types.h>                                        POSIX
#include <sys/stat.h>
#include <unistd.h>

int stat(const char *file_name, struct stat *buf);
int fstat(int filedes, struct stat *buf);
int lstat(const char *file_name, struct stat *buf);

The stat() function accepts a pathname and returns information about the given file. It follows symbolic links; that is, when applied to a symbolic link, stat() returns information about the pointed-to file, not about the link itself. For those times when you want to know if a file is a symbolic link, use the lstat() function instead; it does not follow symbolic links.

The fstat() function retrieves information about an already open file. It is particularly useful for file descriptors 0, 1, and 2, (standard input, output, and error) which are already open when a process starts up. However, it can be applied to any open file. (An open file descriptor will never relate to a symbolic link; make sure you understand why.)

The value passed in as the second parameter should be the address of a struct stat, declared in <sys/stat.h>. As with the struct dirent, the struct stat contains at least the following members:

struct stat {
    ...
    dev_t      st_dev;      /* device */
    ino_t      st_ino;      /* inode */
    mode_t     st_mode;     /* type and protection */
    nlink_t    st_nlink;    /* number of hard links */
    uid_t      st_uid;      /* user ID of owner */
    gid_t      st_gid;      /* group ID of owner */
    dev_t      st_rdev;     /* device type (block or character device) */
    off_t      st_size;     /* total size, in bytes */
    blksize_t  st_blksize;  /* blocksize for filesystem I/O */
    blkcnt_t   st_blocks;   /* number of blocks allocated */
    time_t     st_atime;    /* time of last access */
    time_t     st_mtime;    /* time of last modification */
    time_t     st_ctime;    /* time of last inode change */
    ...
};

(The layout may be different on different architectures.) This structure uses a number of typedef ’d types. Although they are all (typically) integer types, the use of specially defined types allows them to have different sizes on different systems. This keeps user-level code that uses them portable. Here is a fuller description of each field.

st_dev

st_ino

st_mode

st_nlink

st_uid

st_gid

st_rdev

st_size

st_blksize

st_blocks

st_atime

st_mtime

st_ctime

The time_t type used for the st_atime, st_mtime, and st_ctime fields represents dates and times. These time-related values are sometimes termed timestamps. Discussion of how to use a time_t value is delayed until Section 6.1, “Times and Dates,” page 166. Similarly, the uid_t and gid_t types represent user and group ID numbers, which are discussed in Section 6.3, “User and Group Names,” page 195. Most of the other types are not of general interest.

The 2.6 and later Linux kernel supplies three additional fields in the struct stat. These provide nanosecond resolution on the file times:

Some other systems also provide such high-resolution time fields, but the member names for the struct stat are not standardized, making it difficult to write portable code that uses these times. (See Section 14.3.2, “Microsecond File Times: utimes(),” page 545, for a related advanced system call.)

Recall that the st_mode field encodes both the file’s type and its permissions. <sys/stat.h> defines a number of macros that determine the file’s type. In particular, these macros return true or false when applied to the st_mode field. The macros correspond to each of the file types described earlier. Assume that the following code has been executed:

struct stat stbuf;
char filename[PATH_MAX];    /* PATH_MAX is from <limits.h> */

...fill in filename with a file name...
if (stat(filename, & stbuf) < 0) {
    /* handle error */
}

Once stbuf has been filled in by the system, the following macros can be called, being passed stbuf.st_mode as the argument:

S_ISREG(stbuf. st_mode)

S_ISDIR(stbuf.st_mode)

S_ISCHR(stbuf.st_mode)

S_ISBLK(stbuf.st_mode)

S_ISFIFO(stbuf.st_mode)

S_ISLNK(stbuf.st_mode)

S_ISSOCK(stbuf.st_mode)

if (S_ISREG(stbuf.st_mode)) ...            Correct

if (S_ISREG(stbuf.st_mode) == 1) ...       Incorrect

Along with the macros, <sys/stat.h> provides two sets of bitmasks. One set is for testing permission, and the other set is for testing the type of a file. We saw the permission masks in Section 4.6, “Creating Files,” page 106, when we discussed the mode_t type and values for open() and creat(). The bitmasks, their values for GNU/Linux, and their meanings are described in Table 5.2.

Several of these masks serve to isolate the different sets of bits encoded in the st_mode field:

The permission and file type bits are depicted graphically in Figure 5.3.

Figure 5.3. Permission and file-type bits

The file-type masks are standardized primarily for compatibility with older code; they should not be used directly, because such code is less readable than the corresponding macros. It happens that the macros are implemented, logically enough, with the masks, but that’s irrelevant for user-level code.

The POSIX standard explicitly states that no new bitmasks will be standardized in the future and that tests for any additional kinds of file types that may be added will be available only as S_ISxxx() macros.

$ ls -l /dev/hda /dev/hda?          Show numbers for first hard disk
brw-rw----    1 root     disk    3,   0 Aug 31  2002 /dev/hda
brw-rw----    1 root     disk    3,   1 Aug 31  2002 /dev/hda1
brw-rw----    1 root     disk    3,   2 Aug 31  2002 /dev/hda2
brw-rw----    1 root     disk    3,   3 Aug 31  2002 /dev/hda3
brw-rw----    1 root     disk    3,   4 Aug 31  2002 /dev/hda4
brw-rw----    1 root     disk    3,   5 Aug 31  2002 /dev/hda5
brw-rw----    1 root     disk    3,   6 Aug 31  2002 /dev/hda6
brw-rw----    1 root     disk    3,   7 Aug 31  2002 /dev/hda7
brw-rw----    1 root     disk    3,   8 Aug 31  2002 /dev/hda8
brw-rw----    1 root     disk    3,   9 Aug 31  2002 /dev/hda9

$ ls -l /dev/null                   Show info for /dev/null, too
crw-rw-rw-    1 root     root    1,   3 Aug 31  2002 /dev/null

#include <sys/types.h>                                               Common
#include <sys/sysmacros.h>

int major(dev_t dev);                           Major device number
int minor(dev_t dev);                           Minor device number
dev_t makedev(int major, int minor);            Create a dev_t value

/* ch05-devnum.c --- Demonstrate stat(), major(), minor(). */

#include <stdio.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/sysmacros.h>

int main(int argc, char **argv)
{
    struct stat sbuf;
    char *devtype;
  
    if (argc != 2) {
        fprintf(stderr, "usage: %s path
", argv[0]);
        exit(1);
    }

    if (stat(argv[1], & sbuf) < 0) {
        fprintf(stderr, "%s: stat: %s
", argv[1], strerror(errno));
        exit(1);
    }

    if (S_ISCHR(sbuf.st_mode))
        devtype = "char";
    else if (S_ISBLK(sbuf.st_mode))
        devtype = "block";
    else {
        fprintf(stderr, "%s is not a block or character device
", argv[1]);
        exit(1);
    }

    printf("%s: major: %d, minor: %d
", devtype,
            major(sbuf.st_rdev), minor(sbuf.st_rdev));

    exit(0);
}

$ ch05-devnum /tmp                          Try a nondevice
/tmp is not a block or character device
$ ch05-devnum /dev/null                     Character device
char: major: 1, minor: 3
$ ch05-devnum /dev/hda2                     Block device
block: major: 3, minor: 2

31     fstat(fileno(stdout), &statb);
32     statb.st_mode &= S_IFMT;
33     if (statb.st_mode!=S_IFCHR && statb.st_mode!=S_IFBLK) {
34         dev = statb.st_dev;
35         ino = statb.st_ino;
36     }

50         fstat(fileno(fi), &statb);
51         if (statb.st_dev==dev && statb.st_ino==ino) {
52             fprintf(stderr, "cat: input %s is output
",
53                fflg?"-": *argv);
54             fclose(fi);
55             continue;
56         }

17    int dev, ino = -1;

$ tty                                 Print current terminal device name
/dev/pts/3
$ cat /dev/pts/3 > /dev/pts/3         Copy keyboard input to screen
this is a line of text                Type in a line
this is a line of text                cat repeats it

In general, symbolic links act like hard links; file operations such as open() and stat() apply to the pointed-to file instead of to the symbolic link itself. However, there are times when it really is necessary to work with the symbolic link instead of with the file the link points to.

For this reason, the lstat() system call exists. It behaves exactly like stat(), but if the file being checked happens to be a symbolic link, then the information returned applies to the symbolic link, and not to the pointed-to file. Specifically:

We already saw that the symlink() system call creates a symbolic link. But given an existing symbolic link, how can we retrieve the name of the file it points to? (ls obviously can, so we ought to be able to also.)

Opening the link with open() in order to read it with read() won’t work; open() follows the link to the pointed-to file. Symbolic links thus necessitate an additional system call, named readlink():

#include <unistd.h>                                       POSIX

int readlink(const char *path, char *buf, size_t bufsiz);

readlink() places the contents of the symbolic link named by path into the buffer pointed to by buf. No more than bufsiz characters are copied. The return value is the number of characters placed in buf or -l if an error occurred. readlink() does not supply the trailing zero byte.

Note that if the buffer passed in to readlink() is too small, you will lose information; the full name of the pointed-to file won’t be available. To properly use readlink(), your code should do the following:

Code to do all that would look something like this:

/* Error checking omitted for brevity */
int count;
char linkfile[PATH_MAX], realfile[PATH_MAX];  /* PATH_MAX is in <limits.h> */
strut stat sbuf;

... fill in linkfile with path to symbolic link of interest...
lstat(linkfile, & sbuf);                            Get stat information
if (! S_ISLNK(sbuf.st_mode))                        Check that it's a symlink
    /* not a symbolic link, handle it */
if (sbuf.st_size + 1 > PATH_MAX)                    Check buffer size
    /* handle buffer size problems */

count = readlink(linkfile, realfile, PATH_MAX);     Read the link
if (count != sbuf.st_size)
    /* something weird going on, handle it */

realfile[count] = '';                             Make it into a C string

This example uses fixed-size buffers for simplicity of presentation. Real code would use malloc() to allocate a buffer of the correct size since the fixed-size arrays might be too small. The file lib/xreadlink.c in the GNU Coreutils does just this. It reads the contents of a symbolic link into storage allocated by malloc(). We show here just the function; most of the file is boilerplate definitions. Line numbers are relative to the start of the file:

55  /* Call readlink to get the symbolic link value of FILENAME.
56     Return a pointer to that NUL-terminated string in malloc'd storage.
57     If readlink fails, return NULL (caller may use errno to diagnose).
58     If realloc fails, or if the link value is longer than SIZE_MAX :-),
59     give a diagnostic and exit. */
60
61  char *
62  xreadlink (char const *filename)
63  {
64    /* The initial buffer size for the link value. A power of 2
65       detects arithmetic overflow earlier, but is not required. */
66    size_t buf_size = 128;
67
68    while (1)
69      {
70        char *buffer = xmalloc (buf_size);
71        ssize_t link_length = readlink (filename, buffer, buf_size);
72
73        if (link_length < 0)
74          {
75             int saved_errno = errno;
76             free (buffer);
77             errno = saved_errno;
78             return NULL;
79          }
80
81        if ((size_t) link_length < buf_size)
82          {
83             buffer[link_length] = 0;
84             return buffer;
85          }
86
87        free (buffer);
88        buf_size *= 2;
89        if (SSIZE_MAX < buf_size || (SIZE_MAX / 2 < SSIZE_MAX && buf_size == 0))
90          xalloc_die ();
91      }
92  }

The function body consists of an infinite loop (lines 68–91), broken at line 84 which returns the allocated buffer. The loop starts by allocating an initial buffer (line 70) and reading the link (line 71). Lines 73–79 handle the error case, saving and restoring errno so that it can be used correctly by the calling code.

Lines 81–85 handle the “success” case, in which the link’s contents’ length is smaller than the buffer size. In this case, the terminating zero is supplied (line 83) and then the buffer returned (line 84), breaking the infinite loop. This ensures that the entire link contents have been placed into the buffer, since readlink() has no way to indicate “insufficient space in buffer.”

Lines 87–88 free the buffer and double the buffer size for the next try at the top of the loop. Lines 89–90 handle the case in which the link’s size is too big: buf_size is greater than SSIZE_MAX, or SSIZE_MAX is larger than the value that can be represented in a signed integer of the same size as used to hold SIZE_MAX and buf_size has wrapped around to zero. (These are unlikely conditions, but strange things do happen.) If either condition is true, the program dies with an error message. Otherwise, the function continues around to the top of the loop to make another try at allocating a buffer and reading the link.

Some further explanation: The ’SIZE_MAX / 2 < SSIZE_MAX’ condition is true only on systems on which ’SIZE_MAX < 2 * SSIZE_MAX’; we don’t know of any, but only on such a system can buf_size wrap around to zero. Since in practice this condition can’t be true, the compiler can optimize away the whole expression, including the following ’buf_size == 0’ test. After reading this code, you might ask, “Why not use lstat() to retrieve the size of the symbolic link, allocate a buffer of the right size with malloc(), and be done?” Well, there are a number of reasons.^[9]

Finally, when the buffer isn’t big enough, xreadlink() uses free() and malloc() with a bigger size, instead of realloc(), to avoid the useless copying that realloc() does. (The comment on line 58 is thus out of date since realloc() isn’t being used; this is fixed in the post-5.0 version of the Coreutils.)

File ownership and group are changed with three similar system calls:

#include <sys/types.h>                                     POSIX
#include <unistd.h>

int chown(const char *path, uid_t owner, gid_t group);
int fchown(int fd, uid_t owner, gid_t group);
int lchown(const char *path, uid_t owner, gid_t group);

chown() works on a pathname argument, fchown() works on an open file, and lchown() works on symbolic links instead of on the files pointed to by symbolic links. In all other respects, the three calls work identically, returning 0 on success and -1 on error.

It is noteworthy that one system call changes both the owner and group of a file. To change only the owner or only the group, pass in a value of -1 for the ID number that is to be left unchanged.

While you might think that you could pass in the corresponding value from a previously retrieved struct stat for the file or file descriptor, that method is more error prone. There’s a race condition: The owner or group could have changed between the call to stat() and the call to chown().

You might wonder, “Why be able to change ownership of a symbolic link? The permissions and ownership on them don’t matter.” But what happens if a user leaves, but all his files are still needed? It’s necessary to be able to change the ownership on all the person’s files to someone else, including symbolic links.

GNU/Linux systems normally do not permit ordinary (non-root) users to change the ownership of (“give away”) their files. Changing the group to one of the user’s groups is allowed, of course. The restriction on changing owners follows BSD systems, which also have this prohibition. The primary reason is that allowing users to give away files can defeat disk accounting. Consider a scenario like this:

$ mkdir mywork                         Make a directory
$ chmod go-rwx mywork                  Set permissions to draw------
$ cd mywork                            Go there
$ myprogram > large_data_file          Create a large file
$ chmod ugo+rw large_data_file         Set permissions to -rw-rw-rw-
$ chown otherguy large_data_file       Give file away to otherguy

In this example, large_data_file now belongs to user otherguy. The original user can continue to read and write the file, because of the permissions. But otherguy will be charged for the disk space it occupies. However, since it’s in a directory that belongs to the original user, which cannot be accessed by otherguy, there is no way for otherguy to remove the file.

Some System V systems do allow users to give away files. (Setuid and setgid files have the corresponding bit removed when the owner is changed.) This can be a particular problem when files are extracted from a .tar or .cpio archive; the extracted files end up belonging to the UID or GID encoded in the archive. On such systems, the tar and cpio programs have options that prevent this, but it’s important to know that chown()’s behavior does vary across systems.

We will see in Section 6.3, “User and Group Names,” page 195, how to relate user and group names to their corresponding numeric values.

After all the discussion in Chapter 4, “Files and File I/O,” page 83, and in this chapter, changing permissions is almost anticlimatic. It’s done with one of two system calls, chmod() and fchmod():

#include <sys/types.h>                                           POSIX
#include <sys/stat.h>

int chmod(const char *path, mode_t mode);
int fchmod(int fildes, mode_t mode);

chmod() works on a pathname argument, and fchmod() works on an open file. (There is no lchmod() call in POSIX, since the system ignores the permission settings on symbolic links. Some systems do have such a call, though.) As with most other system calls, these return 0 on success and -1 on failure. Only the file’s owner or root can change a file’s permissions.

The mode value is created in the same way as for open() and creat(), as discussed in Section 4.6, “Creating Files,” page 106. See also Table 5.2, which lists the permission constants.

The system will not allow setting the setgid bit (S_ISGID) if the group of the file does not match the effective group ID of the process or one of its supplementary groups. (We have not yet discussed these issues in detail; see Section 11.1.1, “Real and Effective IDs,” page 405.) Of course, this check does not apply to root or to code running as root.

The struct stat structure contains three fields of type time_t:

A time_t value represents time in “seconds since the Epoch.” The Epoch is the Beginning of Time for computer systems. GNU/Linux and Unix use Midnight, January 1, 1970 UTC^[10] as the Epoch. Microsoft Windows systems use Midnight January 1, 1980 (local time, apparently) as the Epoch.

time_t values are sometimes referred to as timestamps. In Section 6.1, “Times and Dates,” page 166, we look at how these values are obtained and at how they’re used. For now, it’s enough to know what a time_t value is and that it represents seconds since the Epoch.

The utime() system call allows you to change a file’s access and modification timestamps:

#include <sys/types.h>                                       POSIX
#include <utime.h>

int utime(const char *filename, struct utimbuf *buf);

A struct utimbuf looks like this:

struct utimbuf {
    time_t actime;  /* access time */
    time_t modtime; /* modification time */
};

If the call is successful, it returns 0; otherwise, it returns -1. If buf is NULL, then the system sets both the access time and the modification time to the current time.

To change one time but not the other, use the original value from the struct stat. For example:

/* Error checking omitted for brevity */
struct stat sbuf;
struct utimbuf ut;
time_t now;

time(& now);                              Get current time of day, see next chapter
stat("/some/file", & sbuf);               Fill in sbuf
ut.actime = sbuf.st_atime;                Access time unchanged

ut.modtime = now - (24 * 60 * 60);        Set modtime to 24 hours ago

utime("/some/file", & ut);                Set the values

About now, you may be asking yourself, “Why would anyone want to change a file’s access and modification times?” Good question.

To answer it, consider the case of a program that creates backup archives, such as tar or cpio. These programs have to read the contents of a file in order to archive them. Reading the file, of course, changes the file’s access time.

However, that file might not have been read by a human in 10 years. Someone doing an ’ls -lu’, which displays the access time (instead of the default modification time), should see that the last time the file was read was 10 years ago. Thus, the backup program should save the original access and modification times, read the file in order to archive it, and then restore the original times with utime().

Similarly, consider the case of an archiving program restoring a file from an archive. The archive stores the file’s original access and modification times. However, when a file is extracted from an archive to a newly created copy on disk, the new file has the current date and time of day for its access and modification times.

However, it’s more useful if the newly created file looks as if it’s the same age as the original file in the archive. Thus, the archiver needs to be able to set the access and modification times to those stored in the archive.

24  #include <sys/types.h>
25
26  #ifdef HAVE_UTIME_H
27  # include <utime.h>
28  #endif
29
30  #include "full-write.h"
31  #include "safe-read.h"
32
33  /* Some systems (even some that do have <utime.h>) don't declare this
34     structure anywhere. */
35  #ifndef HAVE_STRUCT_UTIMBUF
36  struct utimbuf
37  {
38    long actime;
39    long modtime;
40  };
41  #endif
42
43  /* Emulate utime (file, NULL) for systems (like 4.3BSD) that do not
44     interpret it to set the access and modification times of FILE to
45     the current time. Return 0 if successful, -1 if not. */
46
47  static int
48  utime_null (const char *file)
49  {
50  #if HAVE_UTIMES_NULL
51    return utimes (file, 0);
52  #else
53    int fd;
54    char c;
55    int status = 0;
56    struct stat sb;
57
58    fd = open (file, O_RDWR);
59    if (fd < 0
60        || fstat (fd, &sb) < 0
61        || safe_read (fd, &c, sizeof c) == SAFE_READ_ERROR
62        || lseek (fd, (off_t) 0, SEEK_SET) < 0
63        || full_write (fd, &c, sizeof c) != sizeof c
64        /* Maybe do this -- it's necessary on SunOS4.1.3 with some combination
65           of patches, but that system doesn't use this code: it has utimes.
66           || fsync (fd) < 0
67        */
68        || (st.st_size == 0 && ftruncate (fd, st.st_size) < 0)
69        || close (fd) < 0)
70      status = -1;
71    return status;
72  #endif
73  }
74
75  int
76  rpl_utime (const char *file, const struct utimbuf *times)
77  {
78    if (times)
79      return utime (file, times);
80
81    return utime_null (file);
82  }

The original Unix systems had only chown() and chmod() system calls. However, on heavily loaded systems, these system calls are subject to race conditions, by which an attacker could arrange to replace with a different file the file whose ownership or permissions were being changed.

However, once a file is opened, race conditions aren’t an issue anymore. A program can use stat() on a pathname to obtain information about the file. If the information is what’s expected, then after the file is opened, fstat() can verify that the file is the same (by comparing the st_dev and st_ino fields of the “before” and “after” struct stat structures).

Once the program knows that the files are the same, the ownership or permissions can then be changed with fchown() or fchmod().

These system calls, as well as lchown(), are of relatively recent vintage;^[11] older Unix systems won’t have them, although modern, POSIX-compliant systems do.

There are no corresponding futime() or lutime() functions. In the case of futime(), this is (apparently) because the file timestamps are not critical to system security in the same way that ownership and permissions are. There is no lutime(), since the timestamps are irrelevant for symbolic links.