Main Menu ¶

1.2.2.1 POSIX Safety Concepts ¶

This manual documents various safety properties of GNU C Library functions, in lines that follow their prototypes and look like:

Preliminary: | MT-Safe | AS-Safe | AC-Safe |

The properties are assessed according to the criteria set forth in the POSIX standard for such safety contexts as Thread-, Async-Signal- and Async-Cancel- -Safety. Intuitive definitions of these properties, attempting to capture the meaning of the standard definitions, follow.

• MT-Safe or Thread-Safe functions are safe to call in the presence of other threads. MT, in MT-Safe, stands for Multi Thread.

  Being MT-Safe does not imply a function is atomic, nor that it uses any of the memory synchronization mechanisms POSIX exposes to users. It is even possible that calling MT-Safe functions in sequence does not yield an MT-Safe combination. For example, having a thread call two MT-Safe functions one right after the other does not guarantee behavior equivalent to atomic execution of a combination of both functions, since concurrent calls in other threads may interfere in a destructive way.

  Whole-program optimizations that could inline functions across library interfaces may expose unsafe reordering, and so performing inlining across the GNU C Library interface is not recommended. The documented MT-Safety status is not guaranteed under whole-program optimization. However, functions defined in user-visible headers are designed to be safe for inlining.

• AS-Safe or Async-Signal-Safe functions are safe to call from asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous Signal.

  Many functions that are AS-Safe may set errno, or modify the floating-point environment, because their doing so does not make them unsuitable for use in signal handlers. However, programs could misbehave should asynchronous signal handlers modify this thread-local state, and the signal handling machinery cannot be counted on to preserve it. Therefore, signal handlers that call functions that may set errno or modify the floating-point environment must save their original values, and restore them before returning.

• AC-Safe or Async-Cancel-Safe functions are safe to call when asynchronous cancellation is enabled. AC in AC-Safe stands for Asynchronous Cancellation.

  The POSIX standard defines only three functions to be AC-Safe, namely pthread_cancel, pthread_setcancelstate, and pthread_setcanceltype. At present the GNU C Library provides no guarantees beyond these three functions, but does document which functions are presently AC-Safe. This documentation is provided for use by the GNU C Library developers.

  Just like signal handlers, cancellation cleanup routines must configure the floating point environment they require. The routines cannot assume a floating point environment, particularly when asynchronous cancellation is enabled. If the configuration of the floating point environment cannot be performed atomically then it is also possible that the environment encountered is internally inconsistent.

• MT-Unsafe, AS-Unsafe, AC-Unsafe functions are not safe to call within the safety contexts described above. Calling them within such contexts invokes undefined behavior.

  Functions not explicitly documented as safe in a safety context should be regarded as Unsafe.

• Preliminary safety properties are documented, indicating these properties may not be counted on in future releases of the GNU C Library.

  Such preliminary properties are the result of an assessment of the properties of our current implementation, rather than of what is mandated and permitted by current and future standards.

  Although we strive to abide by the standards, in some cases our implementation is safe even when the standard does not demand safety, and in other cases our implementation does not meet the standard safety requirements. The latter are most likely bugs; the former, when marked as Preliminary, should not be counted on: future standards may require changes that are not compatible with the additional safety properties afforded by the current implementation.

  Furthermore, the POSIX standard does not offer a detailed definition of safety. We assume that, by “safe to call”, POSIX means that, as long as the program does not invoke undefined behavior, the “safe to call” function behaves as specified, and does not cause other functions to deviate from their specified behavior. We have chosen to use its loose definitions of safety, not because they are the best definitions to use, but because choosing them harmonizes this manual with POSIX.

  Please keep in mind that these are preliminary definitions and annotations, and certain aspects of the definitions are still under discussion and might be subject to clarification or change.

  Over time, we envision evolving the preliminary safety notes into stable commitments, as stable as those of our interfaces. As we do, we will remove the Preliminary keyword from safety notes. As long as the keyword remains, however, they are not to be regarded as a promise of future behavior.

Other keywords that appear in safety notes are defined in subsequent sections.

1.2.2.2 Unsafe Features ¶

Functions that are unsafe to call in certain contexts are annotated with keywords that document their features that make them unsafe to call. AS-Unsafe features in this section indicate the functions are never safe to call when asynchronous signals are enabled. AC-Unsafe features indicate they are never safe to call when asynchronous cancellation is enabled. There are no MT-Unsafe marks in this section.

• lock

  Functions marked with lock as an AS-Unsafe feature may be interrupted by a signal while holding a non-recursive lock. If the signal handler calls another such function that takes the same lock, the result is a deadlock.

  Functions annotated with lock as an AC-Unsafe feature may, if cancelled asynchronously, fail to release a lock that would have been released if their execution had not been interrupted by asynchronous thread cancellation. Once a lock is left taken, attempts to take that lock will block indefinitely.

• corrupt

  Functions marked with corrupt as an AS-Unsafe feature may corrupt data structures and misbehave when they interrupt, or are interrupted by, another such function. Unlike functions marked with lock, these take recursive locks to avoid MT-Safety problems, but this is not enough to stop a signal handler from observing a partially-updated data structure. Further corruption may arise from the interrupted function’s failure to notice updates made by signal handlers.

  Functions marked with corrupt as an AC-Unsafe feature may leave data structures in a corrupt, partially updated state. Subsequent uses of the data structure may misbehave.

• heap

  Functions marked with heap may call heap memory management functions from the malloc/free family of functions and are only as safe as those functions. This note is thus equivalent to:

  | AS-Unsafe lock | AC-Unsafe lock fd mem |

• dlopen

  Functions marked with dlopen use the dynamic loader to load shared libraries into the current execution image. This involves opening files, mapping them into memory, allocating additional memory, resolving symbols, applying relocations and more, all of this while holding internal dynamic loader locks.

  The locks are enough for these functions to be AS- and AC-Unsafe, but other issues may arise. At present this is a placeholder for all potential safety issues raised by dlopen.

• plugin

  Functions annotated with plugin may run code from plugins that may be external to the GNU C Library. Such plugin functions are assumed to be MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stack unwinding libraries, name service switch (NSS) and character set conversion (iconv) back-ends.

  Although the plugins mentioned as examples are all brought in by means of dlopen, the plugin keyword does not imply any direct involvement of the dynamic loader or the libdl interfaces, those are covered by dlopen. For example, if one function loads a module and finds the addresses of some of its functions, while another just calls those already-resolved functions, the former will be marked with dlopen, whereas the latter will get the plugin. When a single function takes all of these actions, then it gets both marks.

• i18n

  Functions marked with i18n may call internationalization functions of the gettext family and will be only as safe as those functions. This note is thus equivalent to:

  | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt |

• timer

  Functions marked with timer use the alarm function or similar to set a time-out for a system call or a long-running operation. In a multi-threaded program, there is a risk that the time-out signal will be delivered to a different thread, thus failing to interrupt the intended thread. Besides being MT-Unsafe, such functions are always AS-Unsafe, because calling them in signal handlers may interfere with timers set in the interrupted code, and AC-Unsafe, because there is no safe way to guarantee an earlier timer will be reset in case of asynchronous cancellation.

1.2.2.3 Conditionally Safe Features ¶

For some features that make functions unsafe to call in certain contexts, there are known ways to avoid the safety problem other than refraining from calling the function altogether. The keywords that follow refer to such features, and each of their definitions indicate how the whole program needs to be constrained in order to remove the safety problem indicated by the keyword. Only when all the reasons that make a function unsafe are observed and addressed, by applying the documented constraints, does the function become safe to call in a context.

• init

  Functions marked with init as an MT-Unsafe feature perform MT-Unsafe initialization when they are first called.

  Calling such a function at least once in single-threaded mode removes this specific cause for the function to be regarded as MT-Unsafe. If no other cause for that remains, the function can then be safely called after other threads are started.

  Functions marked with init as an AS- or AC-Unsafe feature use the internal libc_once machinery or similar to initialize internal data structures.

  If a signal handler interrupts such an initializer, and calls any function that also performs libc_once initialization, it will deadlock if the thread library has been loaded.

  Furthermore, if an initializer is partially complete before it is canceled or interrupted by a signal whose handler requires the same initialization, some or all of the initialization may be performed more than once, leaking resources or even resulting in corrupt internal data.

  Applications that need to call functions marked with init as an AS- or AC-Unsafe feature should ensure the initialization is performed before configuring signal handlers or enabling cancellation, so that the AS- and AC-Safety issues related with libc_once do not arise.

• race

  Functions annotated with race as an MT-Safety issue operate on objects in ways that may cause data races or similar forms of destructive interference out of concurrent execution. In some cases, the objects are passed to the functions by users; in others, they are used by the functions to return values to users; in others, they are not even exposed to users.

  We consider access to objects passed as (indirect) arguments to functions to be data race free. The assurance of data race free objects is the caller’s responsibility. We will not mark a function as MT-Unsafe or AS-Unsafe if it misbehaves when users fail to take the measures required by POSIX to avoid data races when dealing with such objects. As a general rule, if a function is documented as reading from an object passed (by reference) to it, or modifying it, users ought to use memory synchronization primitives to avoid data races just as they would should they perform the accesses themselves rather than by calling the library function. FILE streams are the exception to the general rule, in that POSIX mandates the library to guard against data races in many functions that manipulate objects of this specific opaque type. We regard this as a convenience provided to users, rather than as a general requirement whose expectations should extend to other types.

  In order to remind users that guarding certain arguments is their responsibility, we will annotate functions that take objects of certain types as arguments. We draw the line for objects passed by users as follows: objects whose types are exposed to users, and that users are expected to access directly, such as memory buffers, strings, and various user-visible struct types, do not give reason for functions to be annotated with race. It would be noisy and redundant with the general requirement, and not many would be surprised by the library’s lack of internal guards when accessing objects that can be accessed directly by users.

  As for objects that are opaque or opaque-like, in that they are to be manipulated only by passing them to library functions (e.g., FILE, DIR, obstack, iconv_t), there might be additional expectations as to internal coordination of access by the library. We will annotate, with race followed by a colon and the argument name, functions that take such objects but that do not take care of synchronizing access to them by default. For example, FILE stream unlocked functions will be annotated, but those that perform implicit locking on FILE streams by default will not, even though the implicit locking may be disabled on a per-stream basis.

  In either case, we will not regard as MT-Unsafe functions that may access user-supplied objects in unsafe ways should users fail to ensure the accesses are well defined. The notion prevails that users are expected to safeguard against data races any user-supplied objects that the library accesses on their behalf.

  This user responsibility does not apply, however, to objects controlled by the library itself, such as internal objects and static buffers used to return values from certain calls. When the library doesn’t guard them against concurrent uses, these cases are regarded as MT-Unsafe and AS-Unsafe (although the race mark under AS-Unsafe will be omitted as redundant with the one under MT-Unsafe). As in the case of user-exposed objects, the mark may be followed by a colon and an identifier. The identifier groups all functions that operate on a certain unguarded object; users may avoid the MT-Safety issues related with unguarded concurrent access to such internal objects by creating a non-recursive mutex related with the identifier, and always holding the mutex when calling any function marked as racy on that identifier, as they would have to should the identifier be an object under user control. The non-recursive mutex avoids the MT-Safety issue, but it trades one AS-Safety issue for another, so use in asynchronous signals remains undefined.

  When the identifier relates to a static buffer used to hold return values, the mutex must be held for as long as the buffer remains in use by the caller. Many functions that return pointers to static buffers offer reentrant variants that store return values in caller-supplied buffers instead. In some cases, such as tmpname, the variant is chosen not by calling an alternate entry point, but by passing a non-NULL pointer to the buffer in which the returned values are to be stored. These variants are generally preferable in multi-threaded programs, although some of them are not MT-Safe because of other internal buffers, also documented with race notes.

• const

  Functions marked with const as an MT-Safety issue non-atomically modify internal objects that are better regarded as constant, because a substantial portion of the GNU C Library accesses them without synchronization. Unlike race, that causes both readers and writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe, this mark is applied to writers only. Writers remain equally MT- and AS-Unsafe to call, but the then-mandatory constness of objects they modify enables readers to be regarded as MT-Safe and AS-Safe (as long as no other reasons for them to be unsafe remain), since the lack of synchronization is not a problem when the objects are effectively constant.

  The identifier that follows the const mark will appear by itself as a safety note in readers. Programs that wish to work around this safety issue, so as to call writers, may use a non-recursve rwlock associated with the identifier, and guard all calls to functions marked with const followed by the identifier with a write lock, and all calls to functions marked with the identifier by itself with a read lock. The non-recursive locking removes the MT-Safety problem, but it trades one AS-Safety problem for another, so use in asynchronous signals remains undefined.

• sig

  Functions marked with sig as a MT-Safety issue (that implies an identical AS-Safety issue, omitted for brevity) may temporarily install a signal handler for internal purposes, which may interfere with other uses of the signal, identified after a colon.

  This safety problem can be worked around by ensuring that no other uses of the signal will take place for the duration of the call. Holding a non-recursive mutex while calling all functions that use the same temporary signal; blocking that signal before the call and resetting its handler afterwards is recommended.

  There is no safe way to guarantee the original signal handler is restored in case of asynchronous cancellation, therefore so-marked functions are also AC-Unsafe.

  Besides the measures recommended to work around the MT- and AS-Safety problem, in order to avert the cancellation problem, disabling asynchronous cancellation and installing a cleanup handler to restore the signal to the desired state and to release the mutex are recommended.

• term

  Functions marked with term as an MT-Safety issue may change the terminal settings in the recommended way, namely: call tcgetattr, modify some flags, and then call tcsetattr; this creates a window in which changes made by other threads are lost. Thus, functions marked with term are MT-Unsafe. The same window enables changes made by asynchronous signals to be lost. These functions are also AS-Unsafe, but the corresponding mark is omitted as redundant.

  It is thus advisable for applications using the terminal to avoid concurrent and reentrant interactions with it, by not using it in signal handlers or blocking signals that might use it, and holding a lock while calling these functions and interacting with the terminal. This lock should also be used for mutual exclusion with functions marked with race:tcattr(fd), where fd is a file descriptor for the controlling terminal. The caller may use a single mutex for simplicity, or use one mutex per terminal, even if referenced by different file descriptors.

  Functions marked with term as an AC-Safety issue are supposed to restore terminal settings to their original state, after temporarily changing them, but they may fail to do so if cancelled.

  Besides the measures recommended to work around the MT- and AS-Safety problem, in order to avert the cancellation problem, disabling asynchronous cancellation and installing a cleanup handler to restore the terminal settings to the original state and to release the mutex are recommended.

1.2.2.4 Other Safety Remarks ¶

Additional keywords may be attached to functions, indicating features that do not make a function unsafe to call, but that may need to be taken into account in certain classes of programs:

• locale

  Functions annotated with locale as an MT-Safety issue read from the locale object without any form of synchronization. Functions annotated with locale called concurrently with locale changes may behave in ways that do not correspond to any of the locales active during their execution, but an unpredictable mix thereof.

  We do not mark these functions as MT- or AS-Unsafe, however, because functions that modify the locale object are marked with const:locale and regarded as unsafe. Being unsafe, the latter are not to be called when multiple threads are running or asynchronous signals are enabled, and so the locale can be considered effectively constant in these contexts, which makes the former safe.

• env

  Functions marked with env as an MT-Safety issue access the environment with getenv or similar, without any guards to ensure safety in the presence of concurrent modifications.

  We do not mark these functions as MT- or AS-Unsafe, however, because functions that modify the environment are all marked with const:env and regarded as unsafe. Being unsafe, the latter are not to be called when multiple threads are running or asynchronous signals are enabled, and so the environment can be considered effectively constant in these contexts, which makes the former safe.

• hostid

  The function marked with hostid as an MT-Safety issue reads from the system-wide data structures that hold the “host ID” of the machine. These data structures cannot generally be modified atomically. Since it is expected that the “host ID” will not normally change, the function that reads from it (gethostid) is regarded as safe, whereas the function that modifies it (sethostid) is marked with const:hostid, indicating it may require special care if it is to be called. In this specific case, the special care amounts to system-wide (not merely intra-process) coordination.

• sigintr

  Functions marked with sigintr as an MT-Safety issue access the _sigintr internal data structure without any guards to ensure safety in the presence of concurrent modifications.

  We do not mark these functions as MT- or AS-Unsafe, however, because functions that modify the this data structure are all marked with const:sigintr and regarded as unsafe. Being unsafe, the latter are not to be called when multiple threads are running or asynchronous signals are enabled, and so the data structure can be considered effectively constant in these contexts, which makes the former safe.

• fd

  Functions annotated with fd as an AC-Safety issue may leak file descriptors if asynchronous thread cancellation interrupts their execution.

  Functions that allocate or deallocate file descriptors will generally be marked as such. Even if they attempted to protect the file descriptor allocation and deallocation with cleanup regions, allocating a new descriptor and storing its number where the cleanup region could release it cannot be performed as a single atomic operation. Similarly, releasing the descriptor and taking it out of the data structure normally responsible for releasing it cannot be performed atomically. There will always be a window in which the descriptor cannot be released because it was not stored in the cleanup handler argument yet, or it was already taken out before releasing it. It cannot be taken out after release: an open descriptor could mean either that the descriptor still has to be closed, or that it already did so but the descriptor was reallocated by another thread or signal handler.

  Such leaks could be internally avoided, with some performance penalty, by temporarily disabling asynchronous thread cancellation. However, since callers of allocation or deallocation functions would have to do this themselves, to avoid the same sort of leak in their own layer, it makes more sense for the library to assume they are taking care of it than to impose a performance penalty that is redundant when the problem is solved in upper layers, and insufficient when it is not.

  This remark by itself does not cause a function to be regarded as AC-Unsafe. However, cumulative effects of such leaks may pose a problem for some programs. If this is the case, suspending asynchronous cancellation for the duration of calls to such functions is recommended.

• mem

  Functions annotated with mem as an AC-Safety issue may leak memory if asynchronous thread cancellation interrupts their execution.

  The problem is similar to that of file descriptors: there is no atomic interface to allocate memory and store its address in the argument to a cleanup handler, or to release it and remove its address from that argument, without at least temporarily disabling asynchronous cancellation, which these functions do not do.

  This remark does not by itself cause a function to be regarded as generally AC-Unsafe. However, cumulative effects of such leaks may be severe enough for some programs that disabling asynchronous cancellation for the duration of calls to such functions may be required.

• cwd

  Functions marked with cwd as an MT-Safety issue may temporarily change the current working directory during their execution, which may cause relative pathnames to be resolved in unexpected ways in other threads or within asynchronous signal or cancellation handlers.

  This is not enough of a reason to mark so-marked functions as MT- or AS-Unsafe, but when this behavior is optional (e.g., nftw with FTW_CHDIR), avoiding the option may be a good alternative to using full pathnames or file descriptor-relative (e.g. openat) system calls.

• !posix

  This remark, as an MT-, AS- or AC-Safety note to a function, indicates the safety status of the function is known to differ from the specified status in the POSIX standard. For example, POSIX does not require a function to be Safe, but our implementation is, or vice-versa.

  For the time being, the absence of this remark does not imply the safety properties we documented are identical to those mandated by POSIX for the corresponding functions.

• :identifier

  Annotations may sometimes be followed by identifiers, intended to group several functions that e.g. access the data structures in an unsafe way, as in race and const, or to provide more specific information, such as naming a signal in a function marked with sig. It is envisioned that it may be applied to lock and corrupt as well in the future.

  In most cases, the identifier will name a set of functions, but it may name global objects or function arguments, or identifiable properties or logical components associated with them, with a notation such as e.g. :buf(arg) to denote a buffer associated with the argument arg, or :tcattr(fd) to denote the terminal attributes of a file descriptor fd.

  The most common use for identifiers is to provide logical groups of functions and arguments that need to be protected by the same synchronization primitive in order to ensure safe operation in a given context.

• /condition

  Some safety annotations may be conditional, in that they only apply if a boolean expression involving arguments, global variables or even the underlying kernel evaluates to true. Such conditions as /hurd or /!linux!bsd indicate the preceding marker only applies when the underlying kernel is the HURD, or when it is neither Linux nor a BSD kernel, respectively. /!ps and /one_per_line indicate the preceding marker only applies when argument ps is NULL, or global variable one_per_line is nonzero.

  When all marks that render a function unsafe are adorned with such conditions, and none of the named conditions hold, then the function can be regarded as safe.

3.2.1.1 Dynamic Memory Allocation ¶

Dynamic memory allocation is a technique in which programs determine as they are running where to store some information. You need dynamic allocation when the amount of memory you need, or how long you continue to need it, depends on factors that are not known before the program runs.

For example, you may need a block to store a line read from an input file; since there is no limit to how long a line can be, you must allocate the memory dynamically and make it dynamically larger as you read more of the line.

Or, you may need a block for each record or each definition in the input data; since you can’t know in advance how many there will be, you must allocate a new block for each record or definition as you read it.

When you use dynamic allocation, the allocation of a block of memory is an action that the program requests explicitly. You call a function or macro when you want to allocate space, and specify the size with an argument. If you want to free the space, you do so by calling another function or macro. You can do these things whenever you want, as often as you want.

Dynamic allocation is not supported by C variables; there is no storage class “dynamic”, and there can never be a C variable whose value is stored in dynamically allocated space. The only way to get dynamically allocated memory is via a system call (which is generally via a GNU C Library function call), and the only way to refer to dynamically allocated space is through a pointer. Because it is less convenient, and because the actual process of dynamic allocation requires more computation time, programmers generally use dynamic allocation only when neither static nor automatic allocation will serve.

For example, if you want to allocate dynamically some space to hold a struct foobar, you cannot declare a variable of type struct foobar whose contents are the dynamically allocated space. But you can declare a variable of pointer type struct foobar * and assign it the address of the space. Then you can use the operators ‘*’ and ‘->’ on this pointer variable to refer to the contents of the space:

{
  struct foobar *ptr = malloc (sizeof *ptr);
  ptr->name = x;
  ptr->next = current_foobar;
  current_foobar = ptr;
}

3.2.3.1 Basic Memory Allocation ¶

To allocate a block of memory, call malloc. The prototype for this function is in stdlib.h.

Function: void * malloc (size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

This function returns a pointer to a newly allocated block size bytes long, or a null pointer (setting errno) if the block could not be allocated.

The contents of the block are undefined; you must initialize it yourself (or use calloc instead; see Allocating Cleared Space). Normally you would convert the value to a pointer to the kind of object that you want to store in the block. Here we show an example of doing so, and of initializing the space with zeros using the library function memset (see Copying Strings and Arrays):

struct foo *ptr = malloc (sizeof *ptr);
if (ptr == 0) abort ();
memset (ptr, 0, sizeof (struct foo));

You can store the result of malloc into any pointer variable without a cast, because ISO C automatically converts the type void * to another type of pointer when necessary. However, a cast is necessary if the type is needed but not specified by context.

Remember that when allocating space for a string, the argument to malloc must be one plus the length of the string. This is because a string is terminated with a null character that doesn’t count in the “length” of the string but does need space. For example:

char *ptr = malloc (length + 1);

See Representation of Strings, for more information about this.

3.2.3.2 Examples of malloc ¶

If no more space is available, malloc returns a null pointer. You should check the value of every call to malloc. It is useful to write a subroutine that calls malloc and reports an error if the value is a null pointer, returning only if the value is nonzero. This function is conventionally called xmalloc. Here it is:

void *
xmalloc (size_t size)
{
  void *value = malloc (size);
  if (value == 0)
    fatal ("virtual memory exhausted");
  return value;
}

Here is a real example of using malloc (by way of xmalloc). The function savestring will copy a sequence of characters into a newly allocated null-terminated string:

char *
savestring (const char *ptr, size_t len)
{
  char *value = xmalloc (len + 1);
  value[len] = '\0';
  return memcpy (value, ptr, len);
}

The block that malloc gives you is guaranteed to be aligned so that it can hold any type of data. On GNU systems, the address is always a multiple of eight on 32-bit systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page boundary) necessary; for those cases, use aligned_alloc or posix_memalign (see Allocating Aligned Memory Blocks).

Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another call to malloc. If you attempt to treat the block as longer than you asked for it to be, you are liable to destroy the data that malloc uses to keep track of its blocks, or you may destroy the contents of another block. If you have already allocated a block and discover you want it to be bigger, use realloc (see Changing the Size of a Block).

Portability Notes:

• In the GNU C Library, a successful malloc (0) returns a non-null pointer to a newly allocated size-zero block; other implementations may return NULL instead. POSIX and the ISO C standard allow both behaviors.
• In the GNU C Library, a failed malloc call sets errno, but ISO C does not require this and non-POSIX implementations need not set errno when failing.
• In the GNU C Library, malloc always fails when size exceeds PTRDIFF_MAX, to avoid problems with programs that subtract pointers or use signed indexes. Other implementations may succeed in this case, leading to undefined behavior later.

3.2.3.3 Freeing Memory Allocated with malloc ¶

When you no longer need a block that you got with malloc, use the function free to make the block available to be allocated again. The prototype for this function is in stdlib.h.

Function: void free (void *ptr) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The free function deallocates the block of memory pointed at by ptr.

Freeing a block alters the contents of the block. Do not expect to find any data (such as a pointer to the next block in a chain of blocks) in the block after freeing it. Copy whatever you need out of the block before freeing it! Here is an example of the proper way to free all the blocks in a chain, and the strings that they point to:

struct chain
  {
    struct chain *next;
    char *name;
  }

void
free_chain (struct chain *chain)
{
  while (chain != 0)
    {
      struct chain *next = chain->next;
      free (chain->name);
      free (chain);
      chain = next;
    }
}

Occasionally, free can actually return memory to the operating system and make the process smaller. Usually, all it can do is allow a later call to malloc to reuse the space. In the meantime, the space remains in your program as part of a free-list used internally by malloc.

The free function preserves the value of errno, so that cleanup code need not worry about saving and restoring errno around a call to free. Although neither ISO C nor POSIX.1-2017 requires free to preserve errno, a future version of POSIX is planned to require it.

There is no point in freeing blocks at the end of a program, because all of the program’s space is given back to the system when the process terminates.

3.2.3.4 Changing the Size of a Block ¶

Often you do not know for certain how big a block you will ultimately need at the time you must begin to use the block. For example, the block might be a buffer that you use to hold a line being read from a file; no matter how long you make the buffer initially, you may encounter a line that is longer.

You can make the block longer by calling realloc or reallocarray. These functions are declared in stdlib.h.

Function: void * realloc (void *ptr, size_t newsize) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The realloc function changes the size of the block whose address is ptr to be newsize.

Since the space after the end of the block may be in use, realloc may find it necessary to copy the block to a new address where more free space is available. The value of realloc is the new address of the block. If the block needs to be moved, realloc copies the old contents.

If you pass a null pointer for ptr, realloc behaves just like ‘malloc (newsize)’. Otherwise, if newsize is zero realloc frees the block and returns NULL. Otherwise, if realloc cannot reallocate the requested size it returns NULL and sets errno; the original block is left undisturbed.

Function: void * reallocarray (void *ptr, size_t nmemb, size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The reallocarray function changes the size of the block whose address is ptr to be long enough to contain a vector of nmemb elements, each of size size. It is equivalent to ‘realloc (ptr, nmemb * size)’, except that reallocarray fails safely if the multiplication overflows, by setting errno to ENOMEM, returning a null pointer, and leaving the original block unchanged.

reallocarray should be used instead of realloc when the new size of the allocated block is the result of a multiplication that might overflow.

Portability Note: This function is not part of any standard. It was first introduced in OpenBSD 5.6.

Like malloc, realloc and reallocarray may return a null pointer if no memory space is available to make the block bigger. When this happens, the original block is untouched; it has not been modified or relocated.

In most cases it makes no difference what happens to the original block when realloc fails, because the application program cannot continue when it is out of memory, and the only thing to do is to give a fatal error message. Often it is convenient to write and use subroutines, conventionally called xrealloc and xreallocarray, that take care of the error message as xmalloc does for malloc:

void *
xreallocarray (void *ptr, size_t nmemb, size_t size)
{
  void *value = reallocarray (ptr, nmemb, size);
  if (value == 0)
    fatal ("Virtual memory exhausted");
  return value;
}

void *
xrealloc (void *ptr, size_t size)
{
  return xreallocarray (ptr, 1, size);
}

You can also use realloc or reallocarray to make a block smaller. The reason you would do this is to avoid tying up a lot of memory space when only a little is needed. In several allocation implementations, making a block smaller sometimes necessitates copying it, so it can fail if no other space is available.

Portability Notes:

• Portable programs should not attempt to reallocate blocks to be size zero. On other implementations if ptr is non-null, realloc (ptr, 0) might free the block and return a non-null pointer to a size-zero object, or it might fail and return NULL without freeing the block. The ISO C17 standard allows these variations.
• In the GNU C Library, reallocation fails if the resulting block would exceed PTRDIFF_MAX in size, to avoid problems with programs that subtract pointers or use signed indexes. Other implementations may succeed, leading to undefined behavior later.
• In the GNU C Library, if the new size is the same as the old, realloc and reallocarray are guaranteed to change nothing and return the same address that you gave. However, POSIX and ISO C allow the functions to relocate the object or fail in this situation.

3.2.3.5 Allocating Cleared Space ¶

The function calloc allocates memory and clears it to zero. It is declared in stdlib.h.

Function: void * calloc (size_t count, size_t eltsize) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

This function allocates a block long enough to contain a vector of count elements, each of size eltsize. Its contents are cleared to zero before calloc returns.

You could define calloc as follows:

void *
calloc (size_t count, size_t eltsize)
{
  void *value = reallocarray (0, count, eltsize);
  if (value != 0)
    memset (value, 0, count * eltsize);
  return value;
}

But in general, it is not guaranteed that calloc calls reallocarray and memset internally. For example, if the calloc implementation knows for other reasons that the new memory block is zero, it need not zero out the block again with memset. Also, if an application provides its own reallocarray outside the C library, calloc might not use that redefinition. See Replacing malloc.

3.2.3.6 Allocating Aligned Memory Blocks ¶

The address of a block returned by malloc or realloc in GNU systems is always a multiple of eight (or sixteen on 64-bit systems). If you need a block whose address is a multiple of a higher power of two than that, use aligned_alloc or posix_memalign. aligned_alloc and posix_memalign are declared in stdlib.h.

Function: void * aligned_alloc (size_t alignment, size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The aligned_alloc function allocates a block of size bytes whose address is a multiple of alignment. The alignment must be a power of two.

The aligned_alloc function returns a null pointer on error and sets errno to one of the following values:

ENOMEM

There was insufficient memory available to satisfy the request.

EINVAL

alignment is not a power of two.

This function was introduced in ISO C11 and hence may have better portability to modern non-POSIX systems than posix_memalign.

Function: void * memalign (size_t boundary, size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The memalign function allocates a block of size bytes whose address is a multiple of boundary. The boundary must be a power of two! The function memalign works by allocating a somewhat larger block, and then returning an address within the block that is on the specified boundary.

The memalign function returns a null pointer on error and sets errno to one of the following values:

ENOMEM

There was insufficient memory available to satisfy the request.

EINVAL

boundary is not a power of two.

The memalign function is obsolete and aligned_alloc or posix_memalign should be used instead.

Function: int posix_memalign (void **memptr, size_t alignment, size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | See POSIX Safety Concepts.

The posix_memalign function is similar to the memalign function in that it returns a buffer of size bytes aligned to a multiple of alignment. But it adds one requirement to the parameter alignment: the value must be a power of two multiple of sizeof (void *).

If the function succeeds in allocation memory a pointer to the allocated memory is returned in *memptr and the return value is zero. Otherwise the function returns an error value indicating the problem. The possible error values returned are:

ENOMEM

There was insufficient memory available to satisfy the request.

EINVAL

alignment is not a power of two multiple of sizeof (void *).

This function was introduced in POSIX 1003.1d. Although this function is superseded by aligned_alloc, it is more portable to older POSIX systems that do not support ISO C11.

Function: void * valloc (size_t size) ¶

Preliminary: | MT-Unsafe init | AS-Unsafe init lock | AC-Unsafe init lock fd mem | See POSIX Safety Concepts.

Using valloc is like using memalign and passing the page size as the value of the first argument. It is implemented like this:

void *
valloc (size_t size)
{
  return memalign (getpagesize (), size);
}

How to get information about the memory subsystem? for more information about the memory subsystem.

The valloc function is obsolete and aligned_alloc or posix_memalign should be used instead.

3.2.3.7 Malloc Tunable Parameters ¶

You can adjust some parameters for dynamic memory allocation with the mallopt function. This function is the general SVID/XPG interface, defined in malloc.h.

Function: int mallopt (int param, int value) ¶

Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock | AC-Unsafe init lock | See POSIX Safety Concepts.

When calling mallopt, the param argument specifies the parameter to be set, and value the new value to be set. Possible choices for param, as defined in malloc.h, are:

M_MMAP_MAX ¶

The maximum number of chunks to allocate with mmap. Setting this to zero disables all use of mmap.

The default value of this parameter is 65536.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_MMAP_MAX_ to the desired value.

M_MMAP_THRESHOLD ¶

All chunks larger than this value are allocated outside the normal heap, using the mmap system call. This way it is guaranteed that the memory for these chunks can be returned to the system on free. Note that requests smaller than this threshold might still be allocated via mmap.

If this parameter is not set, the default value is set as 128 KiB and the threshold is adjusted dynamically to suit the allocation patterns of the program. If the parameter is set, the dynamic adjustment is disabled and the value is set statically to the input value.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_MMAP_THRESHOLD_ to the desired value.

M_PERTURB ¶

If non-zero, memory blocks are filled with values depending on some low order bits of this parameter when they are allocated (except when allocated by calloc) and freed. This can be used to debug the use of uninitialized or freed heap memory. Note that this option does not guarantee that the freed block will have any specific values. It only guarantees that the content the block had before it was freed will be overwritten.

The default value of this parameter is 0.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_PERTURB_ to the desired value.

M_TOP_PAD ¶

This parameter determines the amount of extra memory to obtain from the system when an arena needs to be extended. It also specifies the number of bytes to retain when shrinking an arena. This provides the necessary hysteresis in heap size such that excessive amounts of system calls can be avoided.

The default value of this parameter is 0.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_TOP_PAD_ to the desired value.

M_TRIM_THRESHOLD ¶

This is the minimum size (in bytes) of the top-most, releasable chunk that will trigger a system call in order to return memory to the system.

If this parameter is not set, the default value is set as 128 KiB and the threshold is adjusted dynamically to suit the allocation patterns of the program. If the parameter is set, the dynamic adjustment is disabled and the value is set statically to the provided input.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_TRIM_THRESHOLD_ to the desired value.

M_ARENA_TEST ¶

This parameter specifies the number of arenas that can be created before the test on the limit to the number of arenas is conducted. The value is ignored if M_ARENA_MAX is set.

The default value of this parameter is 2 on 32-bit systems and 8 on 64-bit systems.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_ARENA_TEST to the desired value.

M_ARENA_MAX ¶

This parameter sets the number of arenas to use regardless of the number of cores in the system.

The default value of this tunable is 0, meaning that the limit on the number of arenas is determined by the number of CPU cores online. For 32-bit systems the limit is twice the number of cores online and on 64-bit systems, it is eight times the number of cores online. Note that the default value is not derived from the default value of M_ARENA_TEST and is computed independently.

This parameter can also be set for the process at startup by setting the environment variable MALLOC_ARENA_MAX to the desired value.

3.2.3.8 Heap Consistency Checking ¶

You can ask malloc to check the consistency of dynamic memory by using the mcheck function and preloading the malloc debug library libc_malloc_debug using the LD_PRELOAD environment variable. This function is a GNU extension, declared in mcheck.h.

Function: int mcheck (void (*abortfn) (enum mcheck_status status)) ¶

Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

Calling mcheck tells malloc to perform occasional consistency checks. These will catch things such as writing past the end of a block that was allocated with malloc.

The abortfn argument is the function to call when an inconsistency is found. If you supply a null pointer, then mcheck uses a default function which prints a message and calls abort (see Aborting a Program). The function you supply is called with one argument, which says what sort of inconsistency was detected; its type is described below.

It is too late to begin allocation checking once you have allocated anything with malloc. So mcheck does nothing in that case. The function returns -1 if you call it too late, and 0 otherwise (when it is successful).

The easiest way to arrange to call mcheck early enough is to use the option ‘-lmcheck’ when you link your program; then you don’t need to modify your program source at all. Alternatively you might use a debugger to insert a call to mcheck whenever the program is started, for example these gdb commands will automatically call mcheck whenever the program starts:

(gdb) break main
Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
(gdb) command 1
Type commands for when breakpoint 1 is hit, one per line.
End with a line saying just "end".
>call mcheck(0)
>continue
>end
(gdb) ...

This will however only work if no initialization function of any object involved calls any of the malloc functions since mcheck must be called before the first such function.

Function: enum mcheck_status mprobe (void *pointer) ¶

Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

The mprobe function lets you explicitly check for inconsistencies in a particular allocated block. You must have already called mcheck at the beginning of the program, to do its occasional checks; calling mprobe requests an additional consistency check to be done at the time of the call.

The argument pointer must be a pointer returned by malloc or realloc. mprobe returns a value that says what inconsistency, if any, was found. The values are described below.

Data Type: enum mcheck_status ¶

This enumerated type describes what kind of inconsistency was detected in an allocated block, if any. Here are the possible values:

MCHECK_DISABLED

mcheck was not called before the first allocation. No consistency checking can be done.

MCHECK_OK

No inconsistency detected.

MCHECK_HEAD

The data immediately before the block was modified. This commonly happens when an array index or pointer is decremented too far.

MCHECK_TAIL

The data immediately after the block was modified. This commonly happens when an array index or pointer is incremented too far.

MCHECK_FREE

The block was already freed.

Another possibility to check for and guard against bugs in the use of malloc, realloc and free is to set the environment variable MALLOC_CHECK_. When MALLOC_CHECK_ is set to a non-zero value less than 4, a special (less efficient) implementation is used which is designed to be tolerant against simple errors, such as double calls of free with the same argument, or overruns of a single byte (off-by-one bugs). Not all such errors can be protected against, however, and memory leaks can result. Like in the case of mcheck, one would need to preload the libc_malloc_debug library to enable MALLOC_CHECK_ functionality. Without this preloaded library, setting MALLOC_CHECK_ will have no effect.

Any detected heap corruption results in immediate termination of the process.

There is one problem with MALLOC_CHECK_: in SUID or SGID binaries it could possibly be exploited since diverging from the normal programs behavior it now writes something to the standard error descriptor. Therefore the use of MALLOC_CHECK_ is disabled by default for SUID and SGID binaries.

So, what’s the difference between using MALLOC_CHECK_ and linking with ‘-lmcheck’? MALLOC_CHECK_ is orthogonal with respect to ‘-lmcheck’. ‘-lmcheck’ has been added for backward compatibility. Both MALLOC_CHECK_ and ‘-lmcheck’ should uncover the same bugs - but using MALLOC_CHECK_ you don’t need to recompile your application.

3.2.3.9 Statistics for Memory Allocation with malloc ¶

You can get information about dynamic memory allocation by calling the mallinfo2 function. This function and its associated data type are declared in malloc.h; they are an extension of the standard SVID/XPG version.

Data Type: struct mallinfo2 ¶

This structure type is used to return information about the dynamic memory allocator. It contains the following members:

size_t arena

This is the total size of memory allocated with sbrk by malloc, in bytes.

size_t ordblks

This is the number of chunks not in use. (The memory allocator size_ternally gets chunks of memory from the operating system, and then carves them up to satisfy individual malloc requests; see The GNU Allocator.)

size_t smblks

This field is unused.

size_t hblks

This is the total number of chunks allocated with mmap.

size_t hblkhd

This is the total size of memory allocated with mmap, in bytes.

size_t usmblks

This field is unused and always 0.

size_t fsmblks

This field is unused.

size_t uordblks

This is the total size of memory occupied by chunks handed out by malloc.

size_t fordblks

This is the total size of memory occupied by free (not in use) chunks.

size_t keepcost

This is the size of the top-most releasable chunk that normally borders the end of the heap (i.e., the high end of the virtual address space’s data segment).

Function: struct mallinfo2 mallinfo2 (void) ¶

Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock | AC-Unsafe init lock | See POSIX Safety Concepts.

This function returns information about the current dynamic memory usage in a structure of type struct mallinfo2.

3.2.3.10 Summary of malloc-Related Functions ¶

Here is a summary of the functions that work with malloc:

void *malloc (size_t size)

Allocate a block of size bytes. See Basic Memory Allocation.

void free (void *addr)

Free a block previously allocated by malloc. See Freeing Memory Allocated with malloc.

void *realloc (void *addr, size_t size)

Make a block previously allocated by malloc larger or smaller, possibly by copying it to a new location. See Changing the Size of a Block.

void *reallocarray (void *ptr, size_t nmemb, size_t size)

Change the size of a block previously allocated by malloc to nmemb * size bytes as with realloc. See Changing the Size of a Block.

void *calloc (size_t count, size_t eltsize)

Allocate a block of count * eltsize bytes using malloc, and set its contents to zero. See Allocating Cleared Space.

void *valloc (size_t size)

Allocate a block of size bytes, starting on a page boundary. See Allocating Aligned Memory Blocks.

void *aligned_alloc (size_t alignment, size_t size)

Allocate a block of size bytes, starting on an address that is a multiple of alignment. See Allocating Aligned Memory Blocks.

int posix_memalign (void **memptr, size_t alignment, size_t size)

Allocate a block of size bytes, starting on an address that is a multiple of alignment. See Allocating Aligned Memory Blocks.

void *memalign (size_t boundary, size_t size)

Allocate a block of size bytes, starting on an address that is a multiple of boundary. See Allocating Aligned Memory Blocks.

int mallopt (int param, int value)

Adjust a tunable parameter. See Malloc Tunable Parameters.

int mcheck (void (*abortfn) (void))

Tell malloc to perform occasional consistency checks on dynamically allocated memory, and to call abortfn when an inconsistency is found. See Heap Consistency Checking.

struct mallinfo2 mallinfo2 (void)

Return information about the current dynamic memory usage. See Statistics for Memory Allocation with malloc.

3.2.4.1 How to install the tracing functionality ¶

Function: void mtrace (void) ¶

Preliminary: | MT-Unsafe env race:mtrace init | AS-Unsafe init heap corrupt lock | AC-Unsafe init corrupt lock fd mem | See POSIX Safety Concepts.

The mtrace function provides a way to trace memory allocation events in the program that calls it. It is disabled by default in the library and can be enabled by preloading the debugging library libc_malloc_debug using the LD_PRELOAD environment variable.

When the mtrace function is called it looks for an environment variable named MALLOC_TRACE. This variable is supposed to contain a valid file name. The user must have write access. If the file already exists it is truncated. If the environment variable is not set or it does not name a valid file which can be opened for writing nothing is done. The behavior of malloc etc. is not changed. For obvious reasons this also happens if the application is installed with the SUID or SGID bit set.

If the named file is successfully opened, mtrace installs special handlers for the functions malloc, realloc, and free. From then on, all uses of these functions are traced and protocolled into the file. There is now of course a speed penalty for all calls to the traced functions so tracing should not be enabled during normal use.

This function is a GNU extension and generally not available on other systems. The prototype can be found in mcheck.h.

Function: void muntrace (void) ¶

Preliminary: | MT-Unsafe race:mtrace locale | AS-Unsafe corrupt heap | AC-Unsafe corrupt mem lock fd | See POSIX Safety Concepts.

The muntrace function can be called after mtrace was used to enable tracing the malloc calls. If no (successful) call of mtrace was made muntrace does nothing.

Otherwise it deinstalls the handlers for malloc, realloc, and free and then closes the protocol file. No calls are protocolled anymore and the program runs again at full speed.

This function is a GNU extension and generally not available on other systems. The prototype can be found in mcheck.h.

3.2.4.2 Example program excerpts ¶

Even though the tracing functionality does not influence the runtime behavior of the program it is not a good idea to call mtrace in all programs. Just imagine that you debug a program using mtrace and all other programs used in the debugging session also trace their malloc calls. The output file would be the same for all programs and thus is unusable. Therefore one should call mtrace only if compiled for debugging. A program could therefore start like this:

#include <mcheck.h>

int
main (int argc, char *argv[])
{
#ifdef DEBUGGING
  mtrace ();
#endif
  ...
}

This is all that is needed if you want to trace the calls during the whole runtime of the program. Alternatively you can stop the tracing at any time with a call to muntrace. It is even possible to restart the tracing again with a new call to mtrace. But this can cause unreliable results since there may be calls of the functions which are not called. Please note that not only the application uses the traced functions, also libraries (including the C library itself) use these functions.

This last point is also why it is not a good idea to call muntrace before the program terminates. The libraries are informed about the termination of the program only after the program returns from main or calls exit and so cannot free the memory they use before this time.

So the best thing one can do is to call mtrace as the very first function in the program and never call muntrace. So the program traces almost all uses of the malloc functions (except those calls which are executed by constructors of the program or used libraries).

3.2.4.3 Some more or less clever ideas ¶

You know the situation. The program is prepared for debugging and in all debugging sessions it runs well. But once it is started without debugging the error shows up. A typical example is a memory leak that becomes visible only when we turn off the debugging. If you foresee such situations you can still win. Simply use something equivalent to the following little program:

#include <mcheck.h>
#include <signal.h>

static void
enable (int sig)
{
  mtrace ();
  signal (SIGUSR1, enable);
}

static void
disable (int sig)
{
  muntrace ();
  signal (SIGUSR2, disable);
}

int
main (int argc, char *argv[])
{
  ...

  signal (SIGUSR1, enable);
  signal (SIGUSR2, disable);

  ...
}

I.e., the user can start the memory debugger any time s/he wants if the program was started with MALLOC_TRACE set in the environment. The output will of course not show the allocations which happened before the first signal but if there is a memory leak this will show up nevertheless.

3.2.4.4 Interpreting the traces ¶

If you take a look at the output it will look similar to this:

= Start
 [0x8048209] - 0x8064cc8
 [0x8048209] - 0x8064ce0
 [0x8048209] - 0x8064cf8
 [0x80481eb] + 0x8064c48 0x14
 [0x80481eb] + 0x8064c60 0x14
 [0x80481eb] + 0x8064c78 0x14
 [0x80481eb] + 0x8064c90 0x14
= End

What this all means is not really important since the trace file is not meant to be read by a human. Therefore no attention is given to readability. Instead there is a program which comes with the GNU C Library which interprets the traces and outputs a summary in an user-friendly way. The program is called mtrace (it is in fact a Perl script) and it takes one or two arguments. In any case the name of the file with the trace output must be specified. If an optional argument precedes the name of the trace file this must be the name of the program which generated the trace.

drepper$ mtrace tst-mtrace log
No memory leaks.

In this case the program tst-mtrace was run and it produced a trace file log. The message printed by mtrace shows there are no problems with the code, all allocated memory was freed afterwards.

If we call mtrace on the example trace given above we would get a different output:

drepper$ mtrace errlog
- 0x08064cc8 Free 2 was never alloc'd 0x8048209
- 0x08064ce0 Free 3 was never alloc'd 0x8048209
- 0x08064cf8 Free 4 was never alloc'd 0x8048209

Memory not freed:
-----------------
   Address     Size     Caller
0x08064c48     0x14  at 0x80481eb
0x08064c60     0x14  at 0x80481eb
0x08064c78     0x14  at 0x80481eb
0x08064c90     0x14  at 0x80481eb

We have called mtrace with only one argument and so the script has no chance to find out what is meant with the addresses given in the trace. We can do better:

drepper$ mtrace tst errlog
- 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
- 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
- 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39

Memory not freed:
-----------------
   Address     Size     Caller
0x08064c48     0x14  at /home/drepper/tst.c:33
0x08064c60     0x14  at /home/drepper/tst.c:33
0x08064c78     0x14  at /home/drepper/tst.c:33
0x08064c90     0x14  at /home/drepper/tst.c:33

Suddenly the output makes much more sense and the user can see immediately where the function calls causing the trouble can be found.

Interpreting this output is not complicated. There are at most two different situations being detected. First, free was called for pointers which were never returned by one of the allocation functions. This is usually a very bad problem and what this looks like is shown in the first three lines of the output. Situations like this are quite rare and if they appear they show up very drastically: the program normally crashes.

The other situation which is much harder to detect are memory leaks. As you can see in the output the mtrace function collects all this information and so can say that the program calls an allocation function from line 33 in the source file /home/drepper/tst-mtrace.c four times without freeing this memory before the program terminates. Whether this is a real problem remains to be investigated.

3.2.6.1 Creating Obstacks ¶

The utilities for manipulating obstacks are declared in the header file obstack.h.

Data Type: struct obstack ¶

An obstack is represented by a data structure of type struct obstack. This structure has a small fixed size; it records the status of the obstack and how to find the space in which objects are allocated. It does not contain any of the objects themselves. You should not try to access the contents of the structure directly; use only the functions described in this chapter.

You can declare variables of type struct obstack and use them as obstacks, or you can allocate obstacks dynamically like any other kind of object. Dynamic allocation of obstacks allows your program to have a variable number of different stacks. (You can even allocate an obstack structure in another obstack, but this is rarely useful.)

All the functions that work with obstacks require you to specify which obstack to use. You do this with a pointer of type struct obstack *. In the following, we often say “an obstack” when strictly speaking the object at hand is such a pointer.

The objects in the obstack are packed into large blocks called chunks. The struct obstack structure points to a chain of the chunks currently in use.

The obstack library obtains a new chunk whenever you allocate an object that won’t fit in the previous chunk. Since the obstack library manages chunks automatically, you don’t need to pay much attention to them, but you do need to supply a function which the obstack library should use to get a chunk. Usually you supply a function which uses malloc directly or indirectly. You must also supply a function to free a chunk. These matters are described in the following section.

3.2.6.2 Preparing for Using Obstacks ¶

Each source file in which you plan to use the obstack functions must include the header file obstack.h, like this:

#include <obstack.h>

Also, if the source file uses the macro obstack_init, it must declare or define two functions or macros that will be called by the obstack library. One, obstack_chunk_alloc, is used to allocate the chunks of memory into which objects are packed. The other, obstack_chunk_free, is used to return chunks when the objects in them are freed. These macros should appear before any use of obstacks in the source file.

Usually these are defined to use malloc via the intermediary xmalloc (see Unconstrained Allocation). This is done with the following pair of macro definitions:

#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free

Though the memory you get using obstacks really comes from malloc, using obstacks is faster because malloc is called less often, for larger blocks of memory. See Obstack Chunks, for full details.

At run time, before the program can use a struct obstack object as an obstack, it must initialize the obstack by calling obstack_init.

Function: int obstack_init (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe mem | See POSIX Safety Concepts.

Initialize obstack obstack-ptr for allocation of objects. This function calls the obstack’s obstack_chunk_alloc function. If allocation of memory fails, the function pointed to by obstack_alloc_failed_handler is called. The obstack_init function always returns 1 (Compatibility notice: Former versions of obstack returned 0 if allocation failed).

Here are two examples of how to allocate the space for an obstack and initialize it. First, an obstack that is a static variable:

static struct obstack myobstack;
...
obstack_init (&myobstack);

Second, an obstack that is itself dynamically allocated:

struct obstack *myobstack_ptr
  = (struct obstack *) xmalloc (sizeof (struct obstack));

obstack_init (myobstack_ptr);

Variable: obstack_alloc_failed_handler ¶

The value of this variable is a pointer to a function that obstack uses when obstack_chunk_alloc fails to allocate memory. The default action is to print a message and abort. You should supply a function that either calls exit (see Program Termination) or longjmp (see Non-Local Exits) and doesn’t return.

void my_obstack_alloc_failed (void)
...
obstack_alloc_failed_handler = &my_obstack_alloc_failed;

3.2.6.3 Allocation in an Obstack ¶

The most direct way to allocate an object in an obstack is with obstack_alloc, which is invoked almost like malloc.

Function: void * obstack_alloc (struct obstack *obstack-ptr, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

This allocates an uninitialized block of size bytes in an obstack and returns its address. Here obstack-ptr specifies which obstack to allocate the block in; it is the address of the struct obstack object which represents the obstack. Each obstack function or macro requires you to specify an obstack-ptr as the first argument.

This function calls the obstack’s obstack_chunk_alloc function if it needs to allocate a new chunk of memory; it calls obstack_alloc_failed_handler if allocation of memory by obstack_chunk_alloc failed.

For example, here is a function that allocates a copy of a string str in a specific obstack, which is in the variable string_obstack:

struct obstack string_obstack;

char *
copystring (char *string)
{
  size_t len = strlen (string) + 1;
  char *s = (char *) obstack_alloc (&string_obstack, len);
  memcpy (s, string, len);
  return s;
}

To allocate a block with specified contents, use the function obstack_copy, declared like this:

Function: void * obstack_copy (struct obstack *obstack-ptr, void *address, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

This allocates a block and initializes it by copying size bytes of data starting at address. It calls obstack_alloc_failed_handler if allocation of memory by obstack_chunk_alloc failed.

Function: void * obstack_copy0 (struct obstack *obstack-ptr, void *address, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

Like obstack_copy, but appends an extra byte containing a null character. This extra byte is not counted in the argument size.

The obstack_copy0 function is convenient for copying a sequence of characters into an obstack as a null-terminated string. Here is an example of its use:

char *
obstack_savestring (char *addr, int size)
{
  return obstack_copy0 (&myobstack, addr, size);
}

Contrast this with the previous example of savestring using malloc (see Basic Memory Allocation).

3.2.6.4 Freeing Objects in an Obstack ¶

To free an object allocated in an obstack, use the function obstack_free. Since the obstack is a stack of objects, freeing one object automatically frees all other objects allocated more recently in the same obstack.

Function: void obstack_free (struct obstack *obstack-ptr, void *object) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt | See POSIX Safety Concepts.

If object is a null pointer, everything allocated in the obstack is freed. Otherwise, object must be the address of an object allocated in the obstack. Then object is freed, along with everything allocated in obstack-ptr since object.

Note that if object is a null pointer, the result is an uninitialized obstack. To free all memory in an obstack but leave it valid for further allocation, call obstack_free with the address of the first object allocated on the obstack:

obstack_free (obstack_ptr, first_object_allocated_ptr);

Recall that the objects in an obstack are grouped into chunks. When all the objects in a chunk become free, the obstack library automatically frees the chunk (see Preparing for Using Obstacks). Then other obstacks, or non-obstack allocation, can reuse the space of the chunk.

3.2.6.5 Obstack Functions and Macros ¶

The interfaces for using obstacks may be defined either as functions or as macros, depending on the compiler. The obstack facility works with all C compilers, including both ISO C and traditional C, but there are precautions you must take if you plan to use compilers other than GNU C.

If you are using an old-fashioned non-ISO C compiler, all the obstack “functions” are actually defined only as macros. You can call these macros like functions, but you cannot use them in any other way (for example, you cannot take their address).

Calling the macros requires a special precaution: namely, the first operand (the obstack pointer) may not contain any side effects, because it may be computed more than once. For example, if you write this:

obstack_alloc (get_obstack (), 4);

you will find that get_obstack may be called several times. If you use *obstack_list_ptr++ as the obstack pointer argument, you will get very strange results since the incrementation may occur several times.

In ISO C, each function has both a macro definition and a function definition. The function definition is used if you take the address of the function without calling it. An ordinary call uses the macro definition by default, but you can request the function definition instead by writing the function name in parentheses, as shown here:

char *x;
void *(*funcp) ();
/* Use the macro.  */
x = (char *) obstack_alloc (obptr, size);
/* Call the function.  */
x = (char *) (obstack_alloc) (obptr, size);
/* Take the address of the function.  */
funcp = obstack_alloc;

This is the same situation that exists in ISO C for the standard library functions. See Macro Definitions of Functions.

Warning: When you do use the macros, you must observe the precaution of avoiding side effects in the first operand, even in ISO C.

If you use the GNU C compiler, this precaution is not necessary, because various language extensions in GNU C permit defining the macros so as to compute each argument only once.

3.2.6.6 Growing Objects ¶

Because memory in obstack chunks is used sequentially, it is possible to build up an object step by step, adding one or more bytes at a time to the end of the object. With this technique, you do not need to know how much data you will put in the object until you come to the end of it. We call this the technique of growing objects. The special functions for adding data to the growing object are described in this section.

You don’t need to do anything special when you start to grow an object. Using one of the functions to add data to the object automatically starts it. However, it is necessary to say explicitly when the object is finished. This is done with the function obstack_finish.

The actual address of the object thus built up is not known until the object is finished. Until then, it always remains possible that you will add so much data that the object must be copied into a new chunk.

While the obstack is in use for a growing object, you cannot use it for ordinary allocation of another object. If you try to do so, the space already added to the growing object will become part of the other object.

Function: void obstack_blank (struct obstack *obstack-ptr, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

The most basic function for adding to a growing object is obstack_blank, which adds space without initializing it.

Function: void obstack_grow (struct obstack *obstack-ptr, void *data, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

To add a block of initialized space, use obstack_grow, which is the growing-object analogue of obstack_copy. It adds size bytes of data to the growing object, copying the contents from data.

Function: void obstack_grow0 (struct obstack *obstack-ptr, void *data, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

This is the growing-object analogue of obstack_copy0. It adds size bytes copied from data, followed by an additional null character.

Function: void obstack_1grow (struct obstack *obstack-ptr, char c) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

To add one character at a time, use the function obstack_1grow. It adds a single byte containing c to the growing object.

Function: void obstack_ptr_grow (struct obstack *obstack-ptr, void *data) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

Adding the value of a pointer one can use the function obstack_ptr_grow. It adds sizeof (void *) bytes containing the value of data.

Function: void obstack_int_grow (struct obstack *obstack-ptr, int data) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

A single value of type int can be added by using the obstack_int_grow function. It adds sizeof (int) bytes to the growing object and initializes them with the value of data.

Function: void * obstack_finish (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt | See POSIX Safety Concepts.

When you are finished growing the object, use the function obstack_finish to close it off and return its final address.

Once you have finished the object, the obstack is available for ordinary allocation or for growing another object.

This function can return a null pointer under the same conditions as obstack_alloc (see Allocation in an Obstack).

When you build an object by growing it, you will probably need to know afterward how long it became. You need not keep track of this as you grow the object, because you can find out the length from the obstack just before finishing the object with the function obstack_object_size, declared as follows:

Function: int obstack_object_size (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the current size of the growing object, in bytes. Remember to call this function before finishing the object. After it is finished, obstack_object_size will return zero.

If you have started growing an object and wish to cancel it, you should finish it and then free it, like this:

obstack_free (obstack_ptr, obstack_finish (obstack_ptr));

This has no effect if no object was growing.

You can use obstack_blank with a negative size argument to make the current object smaller. Just don’t try to shrink it beyond zero length—there’s no telling what will happen if you do that.

3.2.6.7 Extra Fast Growing Objects ¶

The usual functions for growing objects incur overhead for checking whether there is room for the new growth in the current chunk. If you are frequently constructing objects in small steps of growth, this overhead can be significant.

You can reduce the overhead by using special “fast growth” functions that grow the object without checking. In order to have a robust program, you must do the checking yourself. If you do this checking in the simplest way each time you are about to add data to the object, you have not saved anything, because that is what the ordinary growth functions do. But if you can arrange to check less often, or check more efficiently, then you make the program faster.

The function obstack_room returns the amount of room available in the current chunk. It is declared as follows:

Function: int obstack_room (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This returns the number of bytes that can be added safely to the current growing object (or to an object about to be started) in obstack obstack-ptr using the fast growth functions.

While you know there is room, you can use these fast growth functions for adding data to a growing object:

Function: void obstack_1grow_fast (struct obstack *obstack-ptr, char c) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe corrupt mem | See POSIX Safety Concepts.

The function obstack_1grow_fast adds one byte containing the character c to the growing object in obstack obstack-ptr.

Function: void obstack_ptr_grow_fast (struct obstack *obstack-ptr, void *data) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The function obstack_ptr_grow_fast adds sizeof (void *) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_int_grow_fast (struct obstack *obstack-ptr, int data) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The function obstack_int_grow_fast adds sizeof (int) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_blank_fast (struct obstack *obstack-ptr, int size) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The function obstack_blank_fast adds size bytes to the growing object in obstack obstack-ptr without initializing them.

When you check for space using obstack_room and there is not enough room for what you want to add, the fast growth functions are not safe. In this case, simply use the corresponding ordinary growth function instead. Very soon this will copy the object to a new chunk; then there will be lots of room available again.

So, each time you use an ordinary growth function, check afterward for sufficient space using obstack_room. Once the object is copied to a new chunk, there will be plenty of space again, so the program will start using the fast growth functions again.

Here is an example:

void
add_string (struct obstack *obstack, const char *ptr, int len)
{
  while (len > 0)
    {
      int room = obstack_room (obstack);
      if (room == 0)
        {
          /* Not enough room.  Add one character slowly,
             which may copy to a new chunk and make room.  */
          obstack_1grow (obstack, *ptr++);
          len--;
        }
      else
        {
          if (room > len)
            room = len;
          /* Add fast as much as we have room for. */
          len -= room;
          while (room-- > 0)
            obstack_1grow_fast (obstack, *ptr++);
        }
    }
}

3.2.6.8 Status of an Obstack ¶

Here are functions that provide information on the current status of allocation in an obstack. You can use them to learn about an object while still growing it.

Function: void * obstack_base (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | See POSIX Safety Concepts.

This function returns the tentative address of the beginning of the currently growing object in obstack-ptr. If you finish the object immediately, it will have that address. If you make it larger first, it may outgrow the current chunk—then its address will change!

If no object is growing, this value says where the next object you allocate will start (once again assuming it fits in the current chunk).

Function: void * obstack_next_free (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | See POSIX Safety Concepts.

This function returns the address of the first free byte in the current chunk of obstack obstack-ptr. This is the end of the currently growing object. If no object is growing, obstack_next_free returns the same value as obstack_base.

Function: int obstack_object_size (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function returns the size in bytes of the currently growing object. This is equivalent to

obstack_next_free (obstack-ptr) - obstack_base (obstack-ptr)

3.2.6.9 Alignment of Data in Obstacks ¶

Each obstack has an alignment boundary; each object allocated in the obstack automatically starts on an address that is a multiple of the specified boundary. By default, this boundary is aligned so that the object can hold any type of data.

To access an obstack’s alignment boundary, use the macro obstack_alignment_mask, whose function prototype looks like this:

Macro: int obstack_alignment_mask (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The value is a bit mask; a bit that is 1 indicates that the corresponding bit in the address of an object should be 0. The mask value should be one less than a power of 2; the effect is that all object addresses are multiples of that power of 2. The default value of the mask is a value that allows aligned objects to hold any type of data: for example, if its value is 3, any type of data can be stored at locations whose addresses are multiples of 4. A mask value of 0 means an object can start on any multiple of 1 (that is, no alignment is required).

The expansion of the macro obstack_alignment_mask is an lvalue, so you can alter the mask by assignment. For example, this statement:

obstack_alignment_mask (obstack_ptr) = 0;

has the effect of turning off alignment processing in the specified obstack.

Note that a change in alignment mask does not take effect until after the next time an object is allocated or finished in the obstack. If you are not growing an object, you can make the new alignment mask take effect immediately by calling obstack_finish. This will finish a zero-length object and then do proper alignment for the next object.

3.2.6.10 Obstack Chunks ¶

Obstacks work by allocating space for themselves in large chunks, and then parceling out space in the chunks to satisfy your requests. Chunks are normally 4096 bytes long unless you specify a different chunk size. The chunk size includes 8 bytes of overhead that are not actually used for storing objects. Regardless of the specified size, longer chunks will be allocated when necessary for long objects.

The obstack library allocates chunks by calling the function obstack_chunk_alloc, which you must define. When a chunk is no longer needed because you have freed all the objects in it, the obstack library frees the chunk by calling obstack_chunk_free, which you must also define.

These two must be defined (as macros) or declared (as functions) in each source file that uses obstack_init (see Creating Obstacks). Most often they are defined as macros like this:

#define obstack_chunk_alloc malloc
#define obstack_chunk_free free

Note that these are simple macros (no arguments). Macro definitions with arguments will not work! It is necessary that obstack_chunk_alloc or obstack_chunk_free, alone, expand into a function name if it is not itself a function name.

If you allocate chunks with malloc, the chunk size should be a power of 2. The default chunk size, 4096, was chosen because it is long enough to satisfy many typical requests on the obstack yet short enough not to waste too much memory in the portion of the last chunk not yet used.

Macro: int obstack_chunk_size (struct obstack *obstack-ptr) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This returns the chunk size of the given obstack.

Since this macro expands to an lvalue, you can specify a new chunk size by assigning it a new value. Doing so does not affect the chunks already allocated, but will change the size of chunks allocated for that particular obstack in the future. It is unlikely to be useful to make the chunk size smaller, but making it larger might improve efficiency if you are allocating many objects whose size is comparable to the chunk size. Here is how to do so cleanly:

if (obstack_chunk_size (obstack_ptr) < new-chunk-size)
  obstack_chunk_size (obstack_ptr) = new-chunk-size;

3.2.6.11 Summary of Obstack Functions ¶

Here is a summary of all the functions associated with obstacks. Each takes the address of an obstack (struct obstack *) as its first argument.

void obstack_init (struct obstack *obstack-ptr)

Initialize use of an obstack. See Creating Obstacks.

void *obstack_alloc (struct obstack *obstack-ptr, int size)

Allocate an object of size uninitialized bytes. See Allocation in an Obstack.

void *obstack_copy (struct obstack *obstack-ptr, void *address, int size)

Allocate an object of size bytes, with contents copied from address. See Allocation in an Obstack.

void *obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)

Allocate an object of size+1 bytes, with size of them copied from address, followed by a null character at the end. See Allocation in an Obstack.

void obstack_free (struct obstack *obstack-ptr, void *object)

Free object (and everything allocated in the specified obstack more recently than object). See Freeing Objects in an Obstack.

void obstack_blank (struct obstack *obstack-ptr, int size)

Add size uninitialized bytes to a growing object. See Growing Objects.

void obstack_grow (struct obstack *obstack-ptr, void *address, int size)

Add size bytes, copied from address, to a growing object. See Growing Objects.

void obstack_grow0 (struct obstack *obstack-ptr, void *address, int size)

Add size bytes, copied from address, to a growing object, and then add another byte containing a null character. See Growing Objects.

void obstack_1grow (struct obstack *obstack-ptr, char data-char)

Add one byte containing data-char to a growing object. See Growing Objects.

void *obstack_finish (struct obstack *obstack-ptr)

Finalize the object that is growing and return its permanent address. See Growing Objects.

int obstack_object_size (struct obstack *obstack-ptr)

Get the current size of the currently growing object. See Growing Objects.

void obstack_blank_fast (struct obstack *obstack-ptr, int size)

Add size uninitialized bytes to a growing object without checking that there is enough room. See Extra Fast Growing Objects.

void obstack_1grow_fast (struct obstack *obstack-ptr, char data-char)

Add one byte containing data-char to a growing object without checking that there is enough room. See Extra Fast Growing Objects.

int obstack_room (struct obstack *obstack-ptr)

Get the amount of room now available for growing the current object. See Extra Fast Growing Objects.

int obstack_alignment_mask (struct obstack *obstack-ptr)

The mask used for aligning the beginning of an object. This is an lvalue. See Alignment of Data in Obstacks.

int obstack_chunk_size (struct obstack *obstack-ptr)

The size for allocating chunks. This is an lvalue. See Obstack Chunks.

void *obstack_base (struct obstack *obstack-ptr)

Tentative starting address of the currently growing object. See Status of an Obstack.

void *obstack_next_free (struct obstack *obstack-ptr)

Address just after the end of the currently growing object. See Status of an Obstack.

3.2.7.1 alloca Example ¶

As an example of the use of alloca, here is a function that opens a file name made from concatenating two argument strings, and returns a file descriptor or minus one signifying failure:

int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  stpcpy (stpcpy (name, str1), str2);
  return open (name, flags, mode);
}

Here is how you would get the same results with malloc and free:

int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = malloc (strlen (str1) + strlen (str2) + 1);
  int desc;
  if (name == 0)
    fatal ("virtual memory exceeded");
  stpcpy (stpcpy (name, str1), str2);
  desc = open (name, flags, mode);
  free (name);
  return desc;
}

As you can see, it is simpler with alloca. But alloca has other, more important advantages, and some disadvantages.

3.2.7.2 Advantages of alloca ¶

Here are the reasons why alloca may be preferable to malloc:

• Using alloca wastes very little space and is very fast. (It is open-coded by the GNU C compiler.)
• Since alloca does not have separate pools for different sizes of blocks, space used for any size block can be reused for any other size. alloca does not cause memory fragmentation.
• Nonlocal exits done with longjmp (see Non-Local Exits) automatically free the space allocated with alloca when they exit through the function that called alloca. This is the most important reason to use alloca.

  To illustrate this, suppose you have a function open_or_report_error which returns a descriptor, like open, if it succeeds, but does not return to its caller if it fails. If the file cannot be opened, it prints an error message and jumps out to the command level of your program using longjmp. Let’s change open2 (see alloca Example) to use this subroutine:

  int
  open2 (char *str1, char *str2, int flags, int mode)
  {
    char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
    stpcpy (stpcpy (name, str1), str2);
    return open_or_report_error (name, flags, mode);
  }
  

  Because of the way alloca works, the memory it allocates is freed even when an error occurs, with no special effort required.

  By contrast, the previous definition of open2 (which uses malloc and free) would develop a memory leak if it were changed in this way. Even if you are willing to make more changes to fix it, there is no easy way to do so.

3.2.7.3 Disadvantages of alloca ¶

These are the disadvantages of alloca in comparison with malloc:

• If you try to allocate more memory than the machine can provide, you don’t get a clean error message. Instead you get a fatal signal like the one you would get from an infinite recursion; probably a segmentation violation (see Program Error Signals).
• Some non-GNU systems fail to support alloca, so it is less portable. However, a slower emulation of alloca written in C is available for use on systems with this deficiency.

3.2.7.4 GNU C Variable-Size Arrays ¶

In GNU C, you can replace most uses of alloca with an array of variable size. Here is how open2 would look then:

int open2 (char *str1, char *str2, int flags, int mode)
{
  char name[strlen (str1) + strlen (str2) + 1];
  stpcpy (stpcpy (name, str1), str2);
  return open (name, flags, mode);
}

But alloca is not always equivalent to a variable-sized array, for several reasons:

• A variable size array’s space is freed at the end of the scope of the name of the array. The space allocated with alloca remains until the end of the function.
• It is possible to use alloca within a loop, allocating an additional block on each iteration. This is impossible with variable-sized arrays.

NB: If you mix use of alloca and variable-sized arrays within one function, exiting a scope in which a variable-sized array was declared frees all blocks allocated with alloca during the execution of that scope.