The memset() function copies the value val (treated as an unsigned char) into the first count bytes of buf. It is particularly useful for zeroing out blocks of dynamic memory:

void *p = malloc(count);
if (p != NULL)
    memset(p, 0, count);

However, memset() can be used on any kind of memory, not just dynamic memory. The return value is the first argument: buf.

Three functions copy one block of memory to another. The first two differ in their handling of overlapping memory areas; the third copies memory but stops upon seeing a particular value.

void *memcpy(void *dest, const void *src, size_t count)

void *memmove(void *dest, const void *src, size_t count)

void *memccpy(void *dest, const void *src, int val, size_t count)

Now, what’s the issue with overlapping memory? Consider Figure 12.1.

Figure 12.1. Overlapping copies

The goal is to copy the four instances of struct xyz in data[0] through data[3] into data[3] through data[6].data[3] is the problem here; a byte-by-byte copy moving forward in memory from data[0] will clobber data[3] before it can be safely copied into data[6]! (It’s also possible to come up with a scenario where a backwards copy through memory destroys overlapping data.)

The memcpy() function was the original System V API for copying blocks of memory; its behavior for overlapping blocks of memory wasn’t particularly defined one way or the other. For the 1989 C standard, the committee felt that this lack of defined behavior was a problem; thus they invented memmove(). For historical compatibility, memcpy() was left alone, with the behavior for overlapping memory specifically stated as undefined, and memmove() was invented to provide a routine that would correctly deal with problem cases.

Which one should you use in your own code? For a library function that has no knowledge of the memory areas being passed into it, you should use memmove(). That way, you’re guaranteed that there won’t be any problems with overlapping areas. For application-level code that “knows” that two areas don’t overlap, it’s safe to use memcpy().

For both memcpy() and memmove() (as for strcpy()), the destination buffer is the first argument and the source is the second one. To remember this, note that the order is the same as for an assignment statement:

dest = src;

(Many systems have manpages that don’t help, providing the prototype as ’void *memcpy(void *buf1, void *buf2, size_t n)’ and relying on the prose to explain which is which. Fortunately, the GNU/Linux manpage uses better names.)

The memcmp() function compares count bytes from two arbitrary buffers of data. Its return value is like strcmp(): negative, zero, or positive if the first buffer is less than, equal to, or greater than the second one.

You may be wondering “Why not use strcmp() for such comparisons?” The difference between the two functions is that memcmp() doesn’t care about zero bytes (the ’’ string terminator). Thus, memcmp() is the function to use when you need to compare arbitrary binary data.

Another advantage to memcmp() is that it’s faster than the typical C implementation:

/* memcmp --- example C implementation, NOT for real use */

int memcmp(const void *buf1, const void *buf2, size_t count)
{
    const unsigned char *cp1 = (const unsigned char *) buf1;
    const unsigned char *cp2 = (const unsigned char *) buf2;
    int diff;

    while (count-- != 0) {
        diff = *cp1++ - *cp2++;
        if (diff != 0)
            return diff;
    }
    return 0;
}

The speed can be due to special “block memory compare” instructions that many architectures support or to comparisons in units larger than bytes. (This latter operation is tricky and is best left to the library’s author.)

For these reasons, you should always use your library’s version of memcmp() instead of rolling your own. Chances are excellent that the library author knows the machine better than you do.

The memchr() function is similar to the strchr() function: It returns the location of a particular value within an arbitrary buffer. As for memcmp() vs. strcmp(), the principal reason to use memchr() is that you have arbitrary binary data.

GNU wc uses memchr() when counting only lines and bytes,^[4] and this allows wc to be quite fast. From wc.c in the GNU Coreutils:

257  else if (!count_chars && !count_complicated)
258    {
259      /* Use a separate loop when counting only lines or lines and bytes --
260         but not chars or words. */
261      while ((bytes_read = safe_read (fd, buf, BUFFER_SIZE)) > 0)
262        {
263          register char *p = buf;
264 
265          if (bytes_read == SAFE_READ_ERROR)
266            {
267              error (0, errno, "%s", file);
268              exit_status = 1;
269              break;
270            }
271
272          while ((p = memchr (p, '
', (buf + bytes_read) - p)))
273            {
274              ++p;
275              ++lines;
276            }
277          bytes += bytes_read;
278        }
279    }

The outer loop (lines 261–278) reads data blocks from the input file. The inner loop (lines 272–276) uses memchr() to find and count newline characters. The complicated expression ’(buf + bytes_read) - p’ resolves to the number of bytes left between the current value of p and the end of the buffer.

The comment on lines 259–260 needs some explanation. Briefly, modern systems can use characters that occupy more than one byte in memory and on disk. (This is discussed in a little more detail in Section 13.4, “Can You Spell That for Me, Please?,” page 521.) Thus, wc has to use different code if it’s distinguishing characters from bytes: This code deals with the counting-bytes case.

There are three functions whose purpose is to create the name of a unique, nonexistent file. Once you have such a filename, you can use it to create a temporary file. Since the name is unique, you’re “guaranteed” exclusive use of the file. Here are the function declarations:

#include <stdio.h>

char *tmpnam(char *s);                                   ISO C
char *tempnam(const char *dir, const char *pfx);         XSI
char *mktemp(char *template);                            ISO C

The functions all provide different variations of the same theme: They fill in or create a buffer with the path of a unique temporary filename. The file is unique in that the created name doesn’t exist as of the time the functions create the name and return it. The functions work as follows:

char *tmpnam(char *s)

char *tempnam(const char *dir, const char *pfx)

char *mktemp(char *template)

/* Old-style code: don't do this. */
char *tfile = mktemp("/tmp/myprogXXXXXX");
... use tfile ...

Using these functions is quite straightforward. The file ch12-mktemp.c demonstrates mktemp(); changes to use the other functions are not difficult:

 1  /* ch12-mktemp.c --- demonstrate naive use of mktemp().
 2                       Error checking omitted for brevity */
 3
 4  #include <stdio.h>
 5  #include <fcntl.h>    /* for open flags */
 6  #include <limits.h>   /* for PATH_MAX */
 7
 8  int main(void)
 9  {
10      static char template[] = "/tmp/myfileXXXXXX";
11      char fname[PATH_MAX];
12      static char mesg[] =
13          "Here's lookin' at you, kid!
";   /* beats "hello, world" */
14      int fd;
15
16      strcpy(fname, template);
17      mktemp(fname);
18
19      /* RACE CONDITION WINDOW OPENS */
20
21      printf("Filename is %s
", fname);
22
23      /* RACE CONDITION WINDOW LASTS TO HERE */
24
25      fd = open(fname, O_CREAT|o_RDWR|O_TRUNC, 0600);
26      write(fd, mesg, strlen(mesg));
27      close(fd);
28
29      /* unlink(fname); */
30
31      return 0;
32  }

The template variable (line 10) defines the filename template; the ’XXXXXX’ will be replaced with a unique value. Line 16 copies the template into fname, which isn’t const: It can be modified. Line 18 calls mktemp() to generate the filename, and line 21 prints it so we can see what it is. (We explain the comments on lines 19 and 23 shortly.)

Line 25 opens the file, creating it if necessary. Line 26 writes the message in mesg, and line 27 closes the file. In a program in which the file should be removed when we’re done with it, line 29 would not be commented out. (Sometimes, a temporary file should not be unlinked; for example, if the file will be renamed once it’s completely written.) We’ve commented it out so that we can run this program and look at the file afterwards. Here’s what happens when the program runs:

$ ch12-mktemp                              Run the program
Filename is /tmp/myfileQES4WA              Filename printed
$ cat /tmp/myfileQES4WA
Here's lookin' at you, kid!                Contents are what we expect
$ ls -l /tmp/myfileQES4WA                  So are owner and permissions
-rw-------    1 arnold   devel          28 Sep 18 09:27 /tmp/myfileQES4WA
$ rm /tmp/myfileQES4WA                     Remove it
$ ch12-mktemp                              Is same filename reused?
Filename is /tmp/myfileic7xCy              No. That's good
$ cat /tmp/myfileic7xCy                    Check contents again
Here's lookin' at you, kid!
$ ls -l /tmp/myfileic7xCy                  Check owner and permissions again
-rw-------    1 arnold   devel          28 Sep 18 09:28 /tmp/myfileic7xCy

Everything seems to be working fine. mktemp() gives back a unique name, ch12-mktemp creates the file with the right permissions, and the contents are what’s expected. So what’s the problem with all of these functions?

Historically, mktemp() used a simple, predictable algorithm to generate the replacement characters for the ’XXXXXX’ in the template. Furthermore, the interval between the time the filename is generated and the time the file itself is created creates a race condition.

How? Well, Linux and Unix systems use time slicing, a technique that shares the processor among all the executing processes. This means that, although a program appears to be running all the time, in actuality, there are times when processes are sleeping, that is, waiting to run on the processor.

Now, consider a professor’s program for tracking student grades. Both the professor and a malicious student are using a heavily loaded, multiuser system at the same time.

The professor’s program uses mktemp() to create temporary files, and the student, having in the past watched the grading program create and remove temporary files, has figured out the algorithm that mktemp() uses. (The GLIBC version doesn’t have this problem, but not all systems use GLIBC!) Figure 12.2 illustrates the race condition and how the student takes advantage of it.

Figure 12.2. Race condition with mktemp()

Here’s what happened.

Our example is simplistic; besides just stealing the grade data, a clever (if immoral) student might be able to change the data in place. If the professor doesn’t double-check his program’s results, no one would be the wiser.

For the reasons given, and others, all three functions described in this section should never be used. They exist in POSIX and in GLIBC only to support old programs that were written before the dangers of these routines were understood. To this end, GNU/Linux systems generate a warning at link time:

$ cc ch12-mktemp.c -o ch12-mktemp          Compile the program
/tmp/cc1XCvD9.o(.text+0x35) : In function 'main':
: the use of 'mktemp' is dangerous, better use 'mkstemp'

(We cover mkstemp() in the next subsection.)

Should your system not have mkstemp(), think about how you might use these interfaces to simulate it. (See also “Exercises” for Chapter 12, page 482, at the end of the chapter.)

There are two functions that don’t have race condition problems. One is intended for use with the <stdio.h> library:

#include <stdio.h>                       ISO C

FILE *tmpfile(void);

The second function is for use with the file-descriptor-based system calls:

#include <stdlib.h>                       XSI

int mkstemp(char *template);

tmpfile() returns a FILE * value representing a unique, open temporary file. The file is opened in "w+b" mode. The w+ means “open for reading and writing, truncate the file first,” and the b means binary mode, not text mode. (There’s no difference on a GNU/Linux or Unix system, but there is on other systems.) The file is automatically deleted when the file pointer is closed; there is no way to get to the file’s name to save its contents. The program in ch12-tmpfile.c demonstrates tmpfile():

/* ch12-tmpfile.c --- demonstrate tmpfile().
                      Error checking omitted for brevity */

#include <stdio.h>

int main(void)
{
    static char mesg[] =
        "Here's lookin' at you, kid!"; /* beats "hello, world" */
    FILE *fp;
    char buf[BUFSIZ];

    fp = tmpfile();                    /* Get temp file */
    fprintf(fp, "%s", mesg);           /* Write to it */
    fflush(fp);                        /* Force it out */

    rewind(fp);                        /* Move to front */
    fgets(buf, sizeof buf, fp);        /* Read contents */
 
    printf("Got back <%s>
", buf);     /* Print retrieved data */

    fclose(fp);                        /* Close file, goes away */
    return 0;                          /* All done */
}

The returned FILE * value is no different from any other FILE * returned by fopen(). When run, the results are what’s expected:

$ ch12-tmpfile
Got back <Here's lookin' at you, kid!>

We saw earlier that the GLIBC authors recommend the use of mkstemp() function:

$ cc ch12-mktemp.c -o ch12-mktemp      Compile the program
/tmp/cc1XCvD9.o(.text+0x35): In function 'main':
: the use of 'mktemp' is dangerous, better use 'mkstemp'

This function is similar to mktemp() in that it takes a filename ending in ’XXXXXX’ and replaces those characters with a unique suffix to create a unique filename. However, it goes one step further. It creates and opens the file. The file is created with mode 0600 (that is, -rw-------). Thus, only the user running the program can access the file.

Furthermore, and this is what makes mkstemp() more secure, the file is created using the O_EXCL flag, which guarantees that the file doesn’t exist and keeps anyone else from opening the file.

The return value is an open file descriptor that can be used for reading and writing. The pathname now stored in the buffer passed to mkstemp() should be used to remove the file when you’re done. This is all demonstrated in ch12-mkstemp.c, which is a straightforward modification of ch12-tmpfile.c:

/* ch12-mkstemp.c --- demonstrate mkstemp().
                      Error checking omitted for brevity */

#include <stdio.h>
#include <fcntl.h>  /* for open flags */
#include <limits.h> /* for PATH_MAX */

int main(void)
{
    static char template[] = "/tmp/myfileXXXXXX";
    char fname[PATH_MAX];
    static char mesg[] =
        "Here's lookin' at you, kid!
"; /* beats "hello, world" */
    int fd;
    char buf[BUFSIZ];
    int n;

    strcpy(fname, template);            /* Copy template */
    fd = mkstemp(fname);                /* Create and open temp file */
    printf("Filename is %s
", fname);  /* Print it for information */

    write(fd, mesg, strlen(mesg));      /* Write something to file */

    lseek(fd, 0L, SEEK_SET);            /* Rewind to front */
    n = read(fd, buf, sizeof(buf));     /* Read data back; NOT '' terminated! */
    printf("Got back: %.*s", n, buf);   /* Print it out for verification */

    close(fd);                          /* Close file */
    unlink(fname);                      /* Remove it */

    return 0;
}

When run, the results are as expected:

$ ch12-mkstemp
Filename is /tmp/myfileuXFW1N
Got back: Here's lookin' at you, kid!

Many standard utilities pay attention to the TMPDIR environment variable, using the directory it names as the place in which to put their temporary files. If TMPDIR isn’t set, then the default directory for temporary files is usually /tmp, although most modern systems have a /var/tmp directory as well. /tmp is usually cleared of all files and directories by administrative shell scripts at system startup.

Many GNU/Linux systems provide a directory /dev/shm that uses the tmpfs filesystem type:

$ df
Filesystem       1K-blocks      Used Available Use% Mounted on
/dev/hda2          6198436   5136020    747544  88% /
/dev/hda5         61431520  27720248  30590648  48% /d
none                256616         0    256616   0% /dev/shm

The tmpfs filesystem type provides a RAM disk: a portion of memory used as if it were a disk. Furthermore, the tmpfs filesystem uses the Linux kernel’s virtual memory mechanisms to allow it to grow beyond a fixed size limit. If you have lots of RAM in your system, this approach can provide a noticeable speedup. To test performance we started with the /usr/share/dict/linux.words file, which is a sorted list of correctly spelled words, one per line. We then randomized this file so that it was no longer sorted and created a larger file containing 500 copies of the random version of the file:

$ ls -l /tmp/randwords.big                                     Show size
-rw-r--r--    1 arnold   devel   204652500 Sep 18 16:02 /tmp/randwords.big
$ wc -l  /tmp/randwords.big                                    How many words?
22713500 /tmp/randwords.big                                    Over 22 million!

We then sorted the file, first using the default /tmp directory, and then with TMPDIR set to /dev/shm:^[5]

$ time sort /tmp/randwords.big > /dev/null                     Use real files

real    1m32.566s
user    1m23.137s
sys     0m1.740s
$ time TMPDIR=/dev/shm sort /tmp/randwords.big > /dev/null     Use RAM disk

real    1m28.257s
user    1m18.469s
sys     0m1.602s

Interestingly, using the RAM disk was only marginally faster than using regular files. (On some further tests, it was actually slower!) We conjecture that the kernel’s buffer cache (see Section 4.6.2, “Creating Files with creat(),” page 109) comes into the picture, quite effectively speeding up file I/O.^[6]

The RAM disk has a significant disadvantage: It is limited by the amount of swap space configured on your system.^[7] When we tried to sort a file containing 1,000 copies of the randomized words file, the RAM disk ran out of room, whereas the regular sort finished successfully.

Using TMPDIR for your own programs is straightforward. We offer the following outline:

const char template[] = "myprog.XXXXXX";
char *tmpdir, *tfile;
size_t count;
int fd;

if ((tmpdir = getenv("TMPDIR")) == NULL)              Use TMPDIR value if there
    tmpdir = "/tmp";                                  Otherwise, default to /tmp

count = strlen(tmpdir) + strlen(template) + 2;        Compute size of filename
tfile = (char *) malloc(count);                       Allocate space for it
if (tfile == NULL)                                    Check for error
    /* recover */

sprintf(tfile, "%s/%s", tmpdir, template);            Create final template
fd = mkstemp(tfile);                                  Create and open file
... use tempfile via fd ...
close(fd);                                            Clean up
unlink(tfile);
free(tfile);

Depending on your application’s needs, you may wish to unlink the file immediately after opening it instead of doing so as part of the cleanup.

Nonlocal gotos are accomplished with the setjmp() and longjmp() functions. These functions come in two flavors. The traditional routines are defined by the ISO C standard:

#include <setjmp.h>                               ISO C

int setjmp(jmp_buf env);
void longjmp(jmp_buf env, int val);

The jmp_buf type is typedef’d in <setjmp.h>. setjmp() saves the current “environment” in env. env is typically a global or file-level static variable so that it can be used from a called function. This environment includes whatever information is necessary for jumping to the location at which setjmp() is called. The contents of a jmp_buf are by nature machine dependent; thus, jmp_buf is an opaque type: something you use without knowing what’s inside it.

setjmp() returns 0 when it is called to save the current environment in a jmp_buf. It returns nonzero when a nonlocal jump is made using the environment:

jmp_buf command_loop;                 At global level
...then in main()...
if (setjmp (command_loop) == 0)       State saved OK, proceed on
    ;
else                                  We get here via nonlocal goto
    printf("?
");                    ed's famous message
...now start command loop...

longjmp() makes the jump. The first parameter is a jmp_buf that must have been initialized by setjmp(). The second is an integer nonzero value that setjmp() returns in the original environment. This is so that code such as that just shown can distinguish between setting the environment and arriving by way of a nonlocal jump.

The C standard states that even if longjmp() is called with a second argument of 0, setjmp() still returns nonzero. In such a case, it instead returns 1.

The ability to pass an integer value and have that come back from the return of setjmp() is useful; it lets user-level code distinguish the reason for the jump. For instance, gawk uses this capability to handle the break and continue statements inside loops. (The awk language is deliberately similar to C in its syntax for loops, with while, do-while, and for loops, and break and continue.) The use of setjmp() looks like this (from eval.c in the gawk 3.1.3 distribution):

507  case Node_K_while:
508      PUSH_BINDING(loop_tag_stack, loop_tag, loop_tag_valid);
509
510      stable_tree = tree;
511      while (eval_condition(stable_tree->lnode)) {
512          INCREMENT(stable_tree->exec_count);
513          switch (setjmp(loop_tag)) {
514          case 0: /* normal non-jump */
515              (void) interpret (stable_tree->rnode);
516              break;
517          case TAG_CONTINUE:   /* continue statement */
518              break;
519          case TAG_BREAK:      /* break statement */
520              RESTORE_BINDING(loop_tag_stack, loop_tag, loop_tag_valid);
521              return 1;
522          default:
523              cant_happen();
524          }
525      }
526      RESTORE_BINDING(loop_tag_stack, loop_tag, loop_tag_valid);
527      break;

This code fragment represents a while loop. Line 508 manages nested loops by means of a stack of saved jmp_buf variables. Lines 511–524 run the while loop (using a C while loop!). Line 511 tests the loop’s condition. If it’s true, line 513 does a switch on the setjmp() return value. If it’s 0 (lines 514–516), then line 515 runs the statement’s body. However, when setjmp() returns either TAG_BREAK or TAG_CONTINUE, the switch statement handles them appropriately (lines 517–518 and 519–521, respectively).

An awk-level break statement passes TAG_BREAK to longjmp(), and the awk-level continue passes TAG_CONTINUE. Again, from eval.c, with some irrelevant details omitted:

657  case Node_K_break:
658      INCREMENT(tree->exec_count);
             ...
675          longjmp(loop_tag, TAG_BREAK);
676      break;
677
678  case Node_K_continue:
679      INCREMENT(tree->exec_count);
             ...
696          longjmp(loop_tag, TAG_CONTINUE);
697      break;

You can think of setjmp() as placing the label, and longjmp() as the goto, with the extra advantage of being able to tell where the code “came from” (by the return value).

For historical reasons that would most likely bore you to tears, the 1999 C standard is silent about the effect of setjmp() and longjmp() on the state of a process’s signals, and POSIX states explicitly that their effect on the process signal mask (see Section 10.6, “POSIX Signals,” page 367) is undefined.

In other words, if a program changes its process signal mask between the first call to setjmp() and a call to longjmp(), what is the state of the process signal mask after the longjmp()? Is it the mask in effect when setjmp() was first called? Or is it the current mask? POSIX says explicitly “there’s no way to know.”

To make handling of the process signal mask explicit, POSIX introduced two additional functions and one typedef:

#include <setjmp.h>                                                      POSIX

int sigsetjmp(sigjmp_buf env, int savesigs);     Note: sigjmp_buf, not jmp_buf!
void siglongjmp(sigjmp_buf env, int val); 

The main difference is the savesigs argument to sigsetjmp(). If nonzero, then the current set of blocked signals is saved in env, along with the rest of the environment that would be saved by setjmp(). A siglongjmp() with an env where savesigs was true restores the saved process signal mask.

There are several technical caveats to be aware of:

First, because the environment saving and restoring can be messy, machine-dependent tasks, setjmp() and longjmp() are allowed to be macros.

Second, the C standard limits the use of setjmp() to the following situations:

Third, if you wish to change a local variable in the function that calls setjmp(), after the call, and you want that variable to maintain its most recently assigned value after a longjmp(), you must declare the variable to be volatile. Otherwise, any non-volatile local variables changed after setjmp() was initially called have indeterminate values. (Note that the jmp_buf variable itself need not be declared volatile.) For example:

 1  /* ch12-setjmp.c --- demonstrate setjmp()/longjmp() and volatile. */
 2
 3  #include <stdio.h>
 4  #include <setjmp.h>
 5
 6  jmp_buf env;
 7
 8  /* comeback --- do a longjmp */
 9
10  void comeback(void)
11  {
12      longjmp(env, 1);
13      printf("This line is never printed
");
14  }
15
16  /* main --- call setjmp, fiddle with vars, print values */
17
18  int main(void)
19  {
20      int i = 5;
21      volatile int j = 6;
22
23      if (setjmp(env) == 0) {     /* first time */
24          i++;
25          j++;
26          printf("first time: i = %d, j = %d
", i, j);
27          comeback();
28      } else         /* second time */
29          printf("second time: i = %d, j = %d
", i, j);
30
31      return 0;
32  }

In this example, only j (line 21) is guaranteed to maintain its value for the second call to printf(). The value of i (line 20), according to the 1999 C standard, is indeterminate. It may be 6, it may be 5, or it may even be something else!

Fourth, as described in Section 12.5.2, “Handling Signal Masks: sigsetjmp() and siglongjmp(),” page 449, the 1999 C standard makes no statement about the effect, if any, of setjmp() and longjmp() on the state of the program’s signals. If that’s important, you have to use sigsetjmp() and siglongjmp() instead.

Fifth, these routines provide amazing potential for memory leaks! Consider a program in which main() calls setjmp() and then calls several nested functions, each of which allocates dynamic memory with malloc(). If the most deeply nested function does a longjmp() back into main(), the pointers to the dynamic memory are lost. Consider ch12-memleak.c:

 1  /* ch12-memleak.c --- demonstrate memory leaks with setjmp()/longjmp(). */
 2
 3  #include <stdio.h>
 4  #include <malloc.h>     /* for definition of ptrdiff_t on GLIBC */
 5  #include <setjmp.h>
 6  #include <unistd.h>
 7
 8  jmp_buf env;
 9
10  void f1(void), f2(void);
11
12  /* main --- leak memory with setjmp() and longjmp() */
13
14  int main(void)
15  {
16      char *start_break;
17      char *current_break;
18      ptrdiff_t diff;
19
20      start_break = sbrk((ptrdiff_t) 0);
21
22      if (setjmp(env) == 0)       /* first time */
23          printf("setjmp called
");
24
25      current_break = sbrk((ptrdiff_t) 0);
26
27      diff = current_break - start_break;
28      printf("memsize = %ld
", (long) diff);
29
30      f1();
31
32      return 0;
33  }
34
35  /* f1 --- allocate some memory, make a nested call */
36
37  void f1(void)
38  {
39      char *p = malloc(1024);
40
41      f2();
42  }
43
44  /* f2 --- allocate some memory, make longjmp */
45
46  void f2(void)
47  {
48      char *p = malloc(1024);
49
50      longjmp(env, 1);
51  }

This program sets up an infinite loop, using setjmp() and longjmp(). Line 20 uses sbrk() (see Section 3.2.3, “System Calls: brk() and sbrk(),” page 75) to find the current start of the heap, and then line 22 calls setjmp(). Line 25 gets the current start of the heap; this location changes each time through since the code is entered repeatedly by longjmp(). Lines 27–28 compute how much memory has been allocated and print the amount. Here’s what happens when it runs:

$ ch12-memleak                Run the program
setjmp called
memsize = 0
memsize = 6372
memsize = 6372
memsize = 6372
memsize = 10468
memsize = 10468
memsize = 14564
memsize = 14564
memsize = 18660
memsize = 18660
...

The program leaks memory like a sieve. It runs until interrupted from the keyboard or until it runs out of memory (at which point it produces a massive core dump).

Functions f1() and f2() each allocate memory, and f2() does the longjmp() back to main() (line 51). Once that happens, the local pointers (lines 41 and 49) to the allocated memory are gone! Such memory leaks can be difficult to track down because they are often for small amounts of memory, and as such, they can go unnoticed literally for years.^[8]

This code is clearly pathological, but it’s intended to illustrate our point: setjmp() and longjmp() can lead to hard-to-find memory leaks. Suppose that f1() called free() correctly. It would then be far from obvious that the memory would never be freed. In a larger, more realistic program, in which longjmp() might be called only by an if, such a leak becomes even harder to find.

In the presence of setjmp() and longjmp(), dynamic memory must thus be managed by global variables, and you must have code that detects entry with longjmp() (by checking the setjmp() return value). Such code should then clean up any dynamically allocated memory that’s no longer needed.

Sixth, longjmp() and siglongjmp() should not be used from any functions registered with atexit() (see Section 9.1.5.3, “Exiting Functions,” page 302).

Seventh, setjmp() and longjmp() can be costly operations on machines with lots of registers.

Given all of these issues, you should take a hard look at your program’s design. If you don’t need to use setjmp() and longjmp(), then you’re probably better off not doing so. However, if their use is the best way to structure your program, then go ahead and use them, but do so carefully.

Standard C defines two related functions for pseudorandom numbers:

#include <stdlib.h>                                 ISO C

int rand(void);
void srand(unsigned int seed);

rand() returns a pseudorandom number between 0 and RAND_MAX (inclusive, as far as we can tell from the C99 standard) each time it’s called. The constant RAND_MAX must be at least 32,767; it can be larger.

srand() seeds the random number generator with seed. If srand() is never called by the application, rand() behaves as if the initial seed were 1.

The following program, ch12-rand.c, uses rand() to print die faces.

 1  /* ch12-rand.c --- generate die rolls, using rand(). */
 2
 3  #include <stdio.h>
 4  #include <stdlib.h>
 5
 6  char *die_faces[] = {    /* ASCII graphics rule! */
 7      "       ",
 8      "   *   ",  /* 1 */
 9      "       ",
10
11      "       ",
12      " *   * ",  /* 2 */
13      "       ",
14
15      "       ",
16      " * * * ",  /* 3 */
17      "       ",
18
19      " *    * ",
20      "        ", /* 4 */
21      " *    * ",
22
23      " *    * ",
24      "   *    ", /* 5 */
25      " *    * ",
26
27      " * * *  ",
28      "        ", /* 6 */
29      " * * *  ",
30 };
31
32  /* main --- print N different die faces */
33
34  int main(int argc, char **argv)
35  {
36      int nfaces;
37      int i, j, k;
38
39      if (argc != 2) {
40          fprintf(stderr, "usage: %s number-die-faces
", argv[0]);
41          exit(1);
42      }
43
44      nfaces = atoi(argv[1]);
45
46      if (nfaces <= 0) {
47          fprintf(stderr, "usage: %s number-die-faces
", argv[0]);
48          fprintf(stderr, "	Use a positive number!
");
49          exit(1);
50      }
51
52      for (i = 1; i <= nfaces; i++) {
53          j = rand() % 6;    /* force to range 0 <= j <= 5 */
54          printf("+-------+
");
55          for (k = 0; k < 3; k++)
56              printf("|%s|
", die_faces[(j * 3) + k]);
57          printf("+-------+

");
58      }
59
60      return 0;
61 }

This program uses simple ASCII graphics to print out the semblance of a die face. You call it with the number of die faces to print. This is computed on line 44 with atoi(). (In general, atoi() should be avoided for production code since it does no error or overflow checking nor does it do any input validation.)

The key line is line 53, which converts the rand() return value into a number between zero and five, using the remainder operator, %. The value `j * 3’ acts a starting index into the die_faces array for the three strings that make up each die’s face. Lines 54 and 57 print out surrounding top and bottom lines, and the loop on lines 55 and 56 prints the face itself. When run, it produces output like the following:

$ ch12-rand 2          Print two dice
+-------+
|       |
| *   * |
|       |
+-------+

+-------+
| *   * |
|   *   |
| *   * |
+-------+

The rand() interface dates back to V7 and the PDP-11. In particular, on many systems the result is only a 16-bit number, which severely limits the range of numbers that can be returned. Furthermore, the algorithm it used is considered “weak” by modern standards. (The GLIBC version of rand() doesn’t have these problems, but portable code needs to be written with the awareness that rand() isn’t the best API to use.)

ch12-rand.c uses a simple technique to obtain a value within a certain range: the % operator. This technique uses the low bits of the returned value (just as in decimal division, where the remainder of dividing by 10 or 100 uses the lowest one or two decimal digits). It turns out that the historical rand() generator did a better job of producing random values in the middle and higher-order bits than in the lower bits. Thus, if you must use rand(), try to avoid the lower bits. The GNU/Linux rand(3) manpage cites Numerical Recipes in C,^[9] which recommends this technique:

j = 1+(int) (10.0*rand()/(RAND_MAX+1.0)); /* for a number between 1 and 10 */

4.3 BSD introduced random() and its partner functions. These functions use a much better random number generator, which returns a 31-bit value. They are now an XSI extension standardized by POSIX:

#include <stdlib.h>                                          XSI

long random(void);
void srandom(unsigned int seed);
char *initstate(unsigned int seed, char *state, size_t n);
char *setstate(char *state);

The first two functions correspond closely to rand() and srand() and can be used similarly. However, instead of a single seed value that produces the sequence of pseudorandom numbers, these functions use a seed value along with a state array: an array of bytes that holds state information for calculating the pseudorandom numbers. The last two functions let you manage the state array.

long random(void);

void srandom(unsigned int seed);

char *initstate(unsigned int seed, char *state, size_t n);

char *setstate(char *state);

If initstate() and setstate() are never called, random() uses an internal state array of size 128.

The state array is opaque; you initialize it with initstate() and pass it to the random() function with setstate(), but you don’t otherwise need to look inside it. If you use initstate() and setstate(), you don’t have to also call srandom(), since the seed is included in the state information. ch12-random.c uses these routines instead of rand(). It also uses a common technique, which is to seed the random number generator with the time of day, added to the PID.

 1  /* ch12-random.c --- generate die rolls, using random(). */
 2
 3  #include <stdio.h>
 4  #include <stdlib.h>
 5  #include <sys/types.h>
 6  #include <unistd.h>
 7
 8  char *die_faces[] = { /* ASCII graphics rule! */
       ... as before ...
32  };
33
34  /* main --- print N different die faces */
35
36  int main(int argc, char **argv)
37  {
38      int nfaces;
39      int i, j, k;
40      char state[256];
41      time_t now;
42
       ... check args, compute nfaces, as before ...
55
56      (void) time(& now); /* seed with time of day and PID */
57      (void) initstate((unsigned int) (now + getpid()), state, sizeof state);
58      (void) setstate(state);
59
60      for (i = 1; i <= nfaces; i++) {
61          j = random() % 6;       /* force to range 0 <= j <= 5 */
62          printf("+-------+
");
63          for (k = 0; k < 3; k++)
64              printf("|%s|
", die_faces[(j * 3) + k]);
65          printf("+-------+

");
66      }
67
68      return 0;
69  }

Including the PID as part of the seed value guarantees that you’ll get different results, even when two programs are started within the same second.

Because it produces a higher-quality sequence of random numbers, random() is preferred over rand(), and GNU/Linux and all modern Unix systems support it.

Both rand() and srandom() are pseudorandom number generators. Their output, for the same seed, is a reproducible sequence of numbers. Some applications, like cryptography, require their random numbers to be (more) truly random. To this end, the Linux kernel, as well as various BSD and commercial Unix systems, provide special device files that provide access to an “entropy pool” of random bits that the kernel collects from physical devices and other sources. From the random(4) manpage:

/dev/random

/dev/urandom

For most applications, reading from /dev/urandom should be good enough. If you’re going to be writing high-quality cryptographic algorithms, you should read up on cryptography and randomness first; don’t rely on the cursory presentation here! Here’s our die rolling program, once more, using /dev/urandom:

 1  /* ch12-devrandom.c --- generate die rolls, using /dev/urandom. */
 2
 3  #include <stdio.h>
 4  #include <fcntl.h>
 5  #include <stdlib.h>
 6
 7  char *die_faces[] = {   /* ASCII graphics rule! */
       ... as before ...
31  };
32
33  /* myrandom --- return data from /dev/urandom as unsigned long */
34
35  unsigned long myrandom(void)
36  {
37      static int fd = -1;
38      unsigned long data;
39
40      if (fd == -1)
41          fd = open("/dev/urandom", O_RDONLY);
42
43      if (fd == -1 || read(fd, & data, sizeof data) <= 0)
44          return random();    /* fall back */
45
46      return data;
47  }
48
49  /* main --- print N different die faces */
50
51  int main(int argc, char **argv)
52  {
53      int nfaces;
54      int i, j, k;
55
        ... check args, compute nfaces, as before ...
68
69      for (i = 1; i <= nfaces; i++) {
70          j = myrandom() % 6;     /* force to range 0 <= j <= 5 */
71          printf("+-------+
");
72          for (k = 0; k < 3; k++)
73              printf("|%s|
", die_faces[(j * 3) + k]);
74          printf("+-------+
");
75          putchar('
'),
76      }
77
78      return 0;
79  }

Lines 35–47 provide a function-call interface to /dev/urandom, reading an unsigned long’s worth of data each time. The cost is one file descriptor that remains open throughout the program’s life.

We start with the fnmatch() (“filename match”) function:

#include <fnmatch.h>                                             POSIX

int fnmatch(const char *pattern, const char *string, int flags);

This function matches string against pattern, which is a regular shell wildcard pattern. The flags value (described shortly) modifies the function’s behavior. The return value is 0 if string matches pattern, FNM_NOMATCH if it doesn’t, and a nonzero value if an error occurred. Unfortunately, POSIX doesn’t define any specific errors; thus, you can only tell that something went wrong, but not what.

The flags variable is the bitwise-OR of one or more of the flags listed in Table 12.1.

fnmatch() works with strings from any source; strings to be matched need not be actual filenames. In practice though, you would use fnmatch() from code that reads a directory with readdir() (see Section 5.3.1, “Basic Directory Reading,” page 133):

struct dirent dp;
DIR *dir;
char pattern[100];
... fill pattern, open directory, check for errors ...
while ((dp = readdir(dir)) != NULL) {
    if (fnmatch(pattern, dir->d_name, FNM_PERIOD) == 0)
        /* filename matches pattern */
    else
        continue;    /* doesn't match */
}

GNU ls uses fnmatch() to implement its --ignore option. You can provide multiple patterns to ignore (with multiple options). ls tests each filename against all the patterns. It does this with the file_interesting() function in ls.c:

2269  /* Return nonzero if the file in `next' should be listed. */
2270
2271  static int
2272  file_interesting (const struct dirent *next)
2273  {
2274    register struct ignore_pattern *ignore;
2275
2276    for (ignore = ignore_patterns; ignore; ignore = ignore->next)
2277      if (fnmatch (ignore->pattern, next->d_name, FNM_PERIOD) == 0)
2278        return 0;
2279
2280    if (really_all_files
2281        || next->d_name[0] != `.'
2282        || (all_files
2283            && next->d_name[1] != `'
2284            && (next->d_name[1] != `.' || next->d_name[2] != `')))
2285     return 1;
2286
2287    return 0;
2288  }

The loop on lines 2276–2278 tests the filename against the list of patterns for files to ignore. If any of the patterns matches, the file is not interesting and file_interesting() returns false (that is, 0).

The all_files variable corresponds to the -A option, which shows files whose names begin with a period but that aren’t `.’ and `..’. The really_all_files variable corresponds to the -a option, which implies -A, and also shows `.’ and `..’. Given this information, the condition on lines 2280–2284 can be represented with the following pseudocode:

if (   show every file, no matter what its name (-a)
    OR the first character of the name isn't a period
    OR (    show dot files (-A)
        AND there are multiple characters in the filename
        AND (   the second character isn't a period
             OR the third character doesn't end the name)))
                 return TRUE;

The glob() and globfree() functions are more elaborate than fnmatch():

#include <glob.h>                                         POSIX

int glob(const char *pattern, int flags,
         int (*errfunc) (const char *epath, int eerrno),
         glob_t *pglob);
void globfree(glob_t *pglob);

The glob() function does directory scanning and wildcard matching, returning a list of all pathnames that match the pattern. Wildcards can be included at multiple points in the pathame, not just for the last component (for example, `/usr/*/*.so’). The arguments are as follows:

const char *pattern

int flags

int (*errfunc) (const char *epath, int eerrno)

glob_t *pglob

The glob_t structure holds the list of pathnames that glob() produces:

typedef struct {                                                    POSIX
    size_t gl_pathc;         Count of paths matched so far
    char **gl_pathv;         List of matched pathnames
    size_t gl_offs;          Slots to reserve in gl_pathv
} glob_t;

size_t gl_pathc

char **gl_pathv

size_t gl_offs

Table 12.2 lists the standard flags for glob().

The GLIBC version of the glob_t structure contains additional members:

typedef struct {                                                         GLIBC
/* POSIX components: */
    size_t gl_pathc;                                     Count of paths matched so far
    char **gl_pathv;                                     List of matched pathnames
    size_t gl_offs;                                      Slots to reserve in gl_pathv
/* GLIBC components: */
    int gl_flags;                                        Copy of flags, additional GLIBC flags
    void (*gl_closedir) (DIR *);                         Private version of closedir()
    struct dirent *(*gl_readdir) (DIR *);                Private version of readdir()
    DIR *(*gl_opendir) (const char *);                   Private version of opendir()
    int (*gl_lstat) (const char *, struct stat *);       Private version of lstat()
    int (*gl_stat) (const char *, struct stat *);        Private version of stat()
} glob_t;

The members are as follows:

int gl_flags

void (*gl_closedir) (DIR *)

struct dirent *(*gl_readdir) (DIR *)

DIR *(*gl_opendir) (const char *)

int (*gl_lstat) (const char *, struct stat *)

int (*gl_stat) (const char *, struct stat *)

The pointers to private versions of the standard functions are mainly for use in implementing GLIBC; it is highly unlikely that you will ever need to use them. Because GLIBC provides the gl_flags field and additional flag values, the manpage and Info manual document the rest of the GLIBC glob_t structure. Table 12.3 lists the additional flags.

The GLOB_ONLYDIR flag functions as a hint to the implementation that the caller is only interested in directories. Its primary use is by other functions within GLIBC, and a caller still has to be prepared to handle nondirectory files. You should not use it in your programs.

glob() can be called more than once: The first call should not have the GLOB_APPEND flag set, and all subsequent calls must have it set. You cannot change gl_offs between calls, and if you modify any values in gl_pathv or gl_pathc, you must restore them before making a subsequent call to glob().

The ability to call glob() multiple times allows you to build up the results in a single list. This is quite useful; it approaches the power of the shell’s wildcard expansion facility, but at the C programming level.

glob() returns 0 if there were no problems or one of the values in Table 12.4 if there were.

globfree() releases all the memory that glob() dynamically allocated. The following program, ch12-glob.c, demonstrates glob():

 1  /* ch12-glob.c --- demonstrate glob(). */
 2
 3  #include <stdio.h>
 4  #include <errno.h>
 5  #include <glob.h>
 6
 7  char *myname;
 8
 9  /* globerr --- print error message for glob() */
10
11  int globerr (const char *path, int eerrno)
12  {
13      fprintf(stderr, "%s: %s: %s
", myname, path, strerror(eerrno));
14      return 0;   /* let glob() keep going */
15  }
16
17  /* main() --- expand command-line wildcards and print results */
18
19  int main(int argc, char **argv)
20  {
21      int i;
22      int flags = 0;
23      glob_t results;
24      int ret;
25
26      if (argc == 1) {
27          fprintf(stderr, "usage: %s wildcard ...
", argv[0]);
28          exit(1);
29      }
30
31      myname = argv[0];    /* for globerr() */
32
33      for (i = 1; i < argc; i++) {
34          flags |= (i > 1 ? GLOB_APPEND : 0);
35          ret = glob(argv[i], flags, globerr, & results);
36          if (ret != 0) {
37              fprintf(stderr, "%s: problem with %s (%s), stopping early
",
38                  myname, argv[i],
39      /* ugly: */ (ret == GLOB_ABORTED ? "filesystem problem" :
40                   ret == GLOB_NOMATCH ? "no match of pattern" :
41                   ret == GLOB_NOSPACE ? "no dynamic memory" :
42                   "unknown problem"));
43              break;
44          }
45      }
46
47      for (i = 0; i < results.gl_pathc; i++)
48          printf("%s
", results.gl_pathv[i]);
49
50      globfree(& results);
51      return 0;
52  }

Line 7 defines myname, which points to the program’s name; this variable is for error messages from globerr(), defined on lines 11–15.

Lines 33–45 are the heart of the program. They loop over the patterns given on the command line, calling glob() on each one to append its results to the list. Most of the loop is error handling (lines 36–44). Lines 47–48 print the resulting list, and lines 50–51 clean up and return.

Lines 39–41 aren’t pretty; a separate function that converts the integer constant to a string should be used; we’ve done it this way primarily to save space. Code like this is tolerable in a small program, but a larger program should use a function.

If you think about all the work going on under the hood (opening and reading directories, matching patterns, dynamic allocation to grow the list, sorting the list), you can start to appreciate how much glob() does for you! Here are some results:

$ ch12-glob `/usr/lib/x*.so' `../../*.texi'
/usr/lib/xchat-autob5.so
/usr/lib/xchat-autogb.so
../../00-preface.texi
../../01-intro.texi
../../02-cmdline.texi
../../03-memory.texi
...

Note that we have to quote the arguments to keep the shell from doing the expansion!

Many members of the POSIX committee felt that glob() didn’t do enough: They wanted a library routine capable of doing everything the shell can do: tilde expansion (`echo ~arnold’), shell variable expansion (`echo $HOME’), and command substitution (`echo $(cd ; pwd)’). Many others felt that glob() wasn’t the right function for this purpose. To “satisfy” everyone, POSIX supplies an additional two functions that do everything:

#include <wordexp.h>                                                 POSIX

int wordexp(const char *words, wordexp_t *pwordexp, int flags);
void wordfree(wordexp_t *wordexp);

These functions work similarly to glob() and globfree(), but on a wordexp_t structure:

typedef struct {
    size_t we_wordc;          Count of words matched
    char **we_wordv;          List of expanded words
    size_t we_offs;           Slots to reserve in we_wordv
} wordexp_t;

The members are completely analogous to those of the glob_t described earlier; we won't repeat the whole description here.

As with glob(), several flags control wordexp()'s behavior. The flags are listed in Table 12.5.

The return value is 0 if everything went well or one of the values in Table 12.6 if not.

We leave it to you as an exercise (see later) to modify ch12-glob.c to use wordexp() and wordfree(). Here’s our version in action:

$ ch12-wordexp `echo $HOME'                  Shell variable expansion
echo
/home/arnold
$ ch12-wordexp `echo $HOME/*.gz'             Variables and wildcards
echo
/home/arnold/48000.wav.gz
/home/arnold/ipmasq-HOWTO.tar.gz
/home/arnold/rc.firewall-examples.tar.gz
$ ch12-wordexp `echo ~arnold'                Tilde expansion
echo
/home/arnold
$ ch12-wordexp `echo ~arnold/.p*'            Tilde and wildcards
echo
/home/arnold/.postitnotes
/home/arnold/.procmailrc
/home/arnold/.profile
$ ch12-wordexp "echo `~arnold/.p*'"          Quoting works
echo
~arnold/.p*