Next:POSIX (The Portable Operating System Interface), Up:Standards and Portability   [Contents][Index]

Next:Berkeley Unix, Previous:ISO C, Up:Standards and Portability   [Contents][Index]

1.2.2.1 POSIX Safety Concepts ¶

This manual documents various safety properties of GNU C Libraryfunctions, 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 thePOSIX standard for such safety contexts as Thread-, Async-Signal- andAsync-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 presenceof other threads. MT, in MT-Safe, stands for Multi Thread.

  Being MT-Safe does not imply a function is atomic, nor that it uses anyof the memory synchronization mechanisms POSIX exposes to users. It iseven possible that calling MT-Safe functions in sequence does not yieldan MT-Safe combination. For example, having a thread call two MT-Safefunctions one right after the other does not guarantee behaviorequivalent to atomic execution of a combination of both functions, sinceconcurrent calls in other threads may interfere in a destructive way.

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

• AS-Safe or Async-Signal-Safe functions are safe to call fromasynchronous signal handlers. AS, in AS-Safe, stands for AsynchronousSignal.

  Many functions that are AS-Safe may seterrno, or modify thefloating-point environment, because their doing so does not make themunsuitable for use in signal handlers. However, programs couldmisbehave should asynchronous signal handlers modify this thread-localstate, and the signal handling machinery cannot be counted on topreserve it. Therefore, signal handlers that call functions that mayseterrno or modify the floating-point environmentmustsave their original values, and restore them before returning.

• AC-Safe or Async-Cancel-Safe functions are safe to call whenasynchronous cancellation is enabled. AC in AC-Safe stands forAsynchronous Cancellation.

  The POSIX standard defines only three functions to be AC-Safe, namelypthread_cancel,pthread_setcancelstate, andpthread_setcanceltype. At present the GNU C Library provides noguarantees beyond these three functions, but does document whichfunctions are presently AC-Safe. This documentation is provided for useby the GNU C Library developers.

  Just like signal handlers, cancellation cleanup routines must configurethe floating point environment they require. The routines cannot assumea floating point environment, particularly when asynchronouscancellation is enabled. If the configuration of the floating pointenvironment cannot be performed atomically then it is also possible thatthe environment encountered is internally inconsistent.

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

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

• Preliminary safety properties are documented, indicating theseproperties maynot be counted on in future releases ofthe GNU C Library.

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

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

  Furthermore, the POSIX standard does not offer a detailed definition ofsafety. We assume that, by “safe to call”, POSIX means that, as longas the program does not invoke undefined behavior, the “safe to call”function behaves as specified, and does not cause other functions todeviate from their specified behavior. We have chosen to use its loosedefinitions 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 andannotations, and certain aspects of the definitions are still underdiscussion and might be subject to clarification or change.

  Over time, we envision evolving the preliminary safety notes into stablecommitments, as stable as those of our interfaces. As we do, we willremove thePreliminary keyword from safety notes. As long as thekeyword remains, however, they are not to be regarded as a promise offuture behavior.

Other keywords that appear in safety notes are defined in subsequentsections.

1.2.2.2 Unsafe Features ¶

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

• lock

  Functions marked withlock as an AS-Unsafe feature may beinterrupted by a signal while holding a non-recursive lock. If thesignal handler calls another such function that takes the same lock, theresult is a deadlock.

  Functions annotated withlock as an AC-Unsafe feature may, ifcancelled asynchronously, fail to release a lock that would have beenreleased if their execution had not been interrupted by asynchronousthread cancellation. Once a lock is left taken, attempts to take thatlock will block indefinitely.

• corrupt

  Functions marked withcorrupt as an AS-Unsafe feature may corruptdata structures and misbehave when they interrupt, or are interruptedby, another such function. Unlike functions marked withlock,these take recursive locks to avoid MT-Safety problems, but this is notenough to stop a signal handler from observing a partially-updated datastructure. Further corruption may arise from the interrupted function’sfailure to notice updates made by signal handlers.

  Functions marked withcorrupt as an AC-Unsafe feature may leavedata structures in a corrupt, partially updated state. Subsequent usesof the data structure may misbehave.

• heap

  Functions marked withheap may call heap memory managementfunctions from themalloc/free family of functions and areonly as safe as those functions. This note is thus equivalent to:

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

• dlopen

  Functions marked withdlopen use the dynamic loader to loadshared libraries into the current execution image. This involvesopening files, mapping them into memory, allocating additional memory,resolving symbols, applying relocations and more, all of this whileholding internal dynamic loader locks.

  The locks are enough for these functions to be AS- and AC-Unsafe, butother issues may arise. At present this is a placeholder for allpotential safety issues raised bydlopen.

• plugin

  Functions annotated withplugin may run code from plugins thatmay be external to the GNU C Library. Such plugin functions are assumed to beMT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stackunwinding libraries, name service switch (NSS) and character setconversion (iconv) back-ends.

  Although the plugins mentioned as examples are all brought in by meansof dlopen, theplugin keyword does not imply any directinvolvement of the dynamic loader or thelibdl interfaces, thoseare covered bydlopen. For example, if one function loads amodule and finds the addresses of some of its functions, while anotherjust calls those already-resolved functions, the former will be markedwithdlopen, whereas the latter will get theplugin. Whena single function takes all of these actions, then it gets both marks.

• i18n

  Functions marked withi18n may call internationalizationfunctions of thegettext family and will be only as safe as thosefunctions. This note is thus equivalent to:

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

• timer

  Functions marked withtimer use thealarm function orsimilar 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 signalwill be delivered to a different thread, thus failing to interrupt theintended thread. Besides being MT-Unsafe, such functions are alwaysAS-Unsafe, because calling them in signal handlers may interfere withtimers set in the interrupted code, and AC-Unsafe, because there is nosafe way to guarantee an earlier timer will be reset in case ofasynchronous cancellation.

1.2.2.3 Conditionally Safe Features ¶

For some features that make functions unsafe to call in certaincontexts, there are known ways to avoid the safety problem other thanrefraining from calling the function altogether. The keywords thatfollow refer to such features, and each of their definitions indicatehow the whole program needs to be constrained in order to remove thesafety problem indicated by the keyword. Only when all the reasons thatmake a function unsafe are observed and addressed, by applying thedocumented constraints, does the function become safe to call in acontext.

• init

  Functions marked withinit as an MT-Unsafe feature performMT-Unsafe initialization when they are first called.

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

  Functions marked withinit as an AS- or AC-Unsafe feature use theinternallibc_once machinery or similar to initialize internaldata structures.

  If a signal handler interrupts such an initializer, and calls anyfunction that also performslibc_once initialization, it willdeadlock if the thread library has been loaded.

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

  Applications that need to call functions marked withinit as anAS- or AC-Unsafe feature should ensure the initialization is performedbefore configuring signal handlers or enabling cancellation, so that theAS- and AC-Safety issues related withlibc_once do not arise.

• race

  Functions annotated withrace as an MT-Safety issue operate onobjects in ways that may cause data races or similar forms ofdestructive interference out of concurrent execution. In some cases,the objects are passed to the functions by users; in others, they areused by the functions to return values to users; in others, they are noteven exposed to users.

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

  In order to remind users that guarding certain arguments is theirresponsibility, we will annotate functions that take objects of certaintypes as arguments. We draw the line for objects passed by users asfollows: objects whose types are exposed to users, and that users areexpected to access directly, such as memory buffers, strings, andvarious user-visiblestruct types, donot give reason forfunctions to be annotated withrace. It would be noisy andredundant with the general requirement, and not many would be surprisedby the library’s lack of internal guards when accessing objects that canbe accessed directly by users.

  As for objects that are opaque or opaque-like, in that they are to bemanipulated only by passing them to library functions (e.g.,FILE,DIR,obstack,iconv_t), there might beadditional expectations as to internal coordination of access by thelibrary. We will annotate, withrace followed by a colon and theargument name, functions that take such objects but that do not takecare of synchronizing access to them by default. For example,FILE streamunlocked functions will be annotated, butthose that perform implicit locking onFILE streams by defaultwill not, even though the implicit locking may be disabled on aper-stream basis.

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

  This user responsibility does not apply, however, to objects controlledby the library itself, such as internal objects and static buffers usedto return values from certain calls. When the library doesn’t guardthem against concurrent uses, these cases are regarded as MT-Unsafe andAS-Unsafe (although therace mark under AS-Unsafe will be omittedas redundant with the one under MT-Unsafe). As in the case ofuser-exposed objects, the mark may be followed by a colon and anidentifier. The identifier groups all functions that operate on acertain unguarded object; users may avoid the MT-Safety issues relatedwith unguarded concurrent access to such internal objects by creating anon-recursive mutex related with the identifier, and always holding themutex when calling any function marked as racy on that identifier, asthey would have to should the identifier be an object under usercontrol. The non-recursive mutex avoids the MT-Safety issue, but ittrades one AS-Safety issue for another, so use in asynchronous signalsremains undefined.

  When the identifier relates to a static buffer used to hold returnvalues, the mutex must be held for as long as the buffer remains in useby the caller. Many functions that return pointers to static buffersoffer reentrant variants that store return values in caller-suppliedbuffers instead. In some cases, such astmpname, the variant ischosen not by calling an alternate entry point, but by passing anon-NULL pointer to the buffer in which the returned values areto be stored. These variants are generally preferable in multi-threadedprograms, although some of them are not MT-Safe because of otherinternal buffers, also documented withrace notes.

• const

  Functions marked withconst as an MT-Safety issue non-atomicallymodify internal objects that are better regarded as constant, because asubstantial portion of the GNU C Library accesses them withoutsynchronization. Unlikerace, that causes both readers andwriters of internal objects to be regarded as MT-Unsafe and AS-Unsafe,this mark is applied to writers only. Writers remain equally MT- andAS-Unsafe to call, but the then-mandatory constness of objects theymodify enables readers to be regarded as MT-Safe and AS-Safe (as long asno other reasons for them to be unsafe remain), since the lack ofsynchronization is not a problem when the objects are effectivelyconstant.

  The identifier that follows theconst mark will appear by itselfas a safety note in readers. Programs that wish to work around thissafety issue, so as to call writers, may use a non-recursverwlock associated with the identifier, and guardall callsto functions marked withconst followed by the identifier with awrite lock, andall calls to functions marked with the identifierby itself with a read lock. The non-recursive locking removes theMT-Safety problem, but it trades one AS-Safety problem for another, souse in asynchronous signals remains undefined.

• sig

  Functions marked withsig as a MT-Safety issue (that implies anidentical AS-Safety issue, omitted for brevity) may temporarily installa signal handler for internal purposes, which may interfere with otheruses of the signal, identified after a colon.

  This safety problem can be worked around by ensuring that no other usesof the signal will take place for the duration of the call. Holding anon-recursive mutex while calling all functions that use the sametemporary signal; blocking that signal before the call and resetting itshandler afterwards is recommended.

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

  Besides the measures recommended to work around the MT- and AS-Safetyproblem, in order to avert the cancellation problem, disablingasynchronous cancellationand installing a cleanup handler torestore the signal to the desired state and to release the mutex arerecommended.

• term

  Functions marked withterm as an MT-Safety issue may change theterminal settings in the recommended way, namely: calltcgetattr,modify some flags, and then calltcsetattr; this creates a windowin which changes made by other threads are lost. Thus, functions markedwithterm are MT-Unsafe. The same window enables changes made byasynchronous 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 avoidconcurrent and reentrant interactions with it, by not using it in signalhandlers or blocking signals that might use it, and holding a lock whilecalling these functions and interacting with the terminal. This lockshould also be used for mutual exclusion with functions marked withrace:tcattr(fd), wherefd is a file descriptor forthe controlling terminal. The caller may use a single mutex forsimplicity, or use one mutex per terminal, even if referenced bydifferent file descriptors.

  Functions marked withterm as an AC-Safety issue are supposed torestore terminal settings to their original state, after temporarilychanging them, but they may fail to do so if cancelled.

  Besides the measures recommended to work around the MT- and AS-Safetyproblem, in order to avert the cancellation problem, disablingasynchronous cancellationand installing a cleanup handler torestore the terminal settings to the original state and to release themutex are recommended.

1.2.2.4 Other Safety Remarks ¶

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

• locale

  Functions annotated withlocale as an MT-Safety issue read fromthe locale object without any form of synchronization. Functionsannotated withlocale called concurrently with locale changes maybehave in ways that do not correspond to any of the locales activeduring their execution, but an unpredictable mix thereof.

  We do not mark these functions as MT- or AS-Unsafe, however, becausefunctions that modify the locale object are marked withconst:locale and regarded as unsafe. Being unsafe, the latterare not to be called when multiple threads are running or asynchronoussignals are enabled, and so the locale can be considered effectivelyconstant in these contexts, which makes the former safe.

• env

  Functions marked withenv as an MT-Safety issue access theenvironment withgetenv or similar, without any guards to ensuresafety in the presence of concurrent modifications.

  We do not mark these functions as MT- or AS-Unsafe, however, becausefunctions that modify the environment are all marked withconst:env and regarded as unsafe. Being unsafe, the latter arenot to be called when multiple threads are running or asynchronoussignals are enabled, and so the environment can be consideredeffectively constant in these contexts, which makes the former safe.

• hostid

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

• sigintr

  Functions marked withsigintr as an MT-Safety issue access the_sigintr internal data structure without any guards to ensuresafety in the presence of concurrent modifications.

  We do not mark these functions as MT- or AS-Unsafe, however, becausefunctions that modify the this data structure are all marked withconst:sigintr and regarded as unsafe. Being unsafe, the latterare not to be called when multiple threads are running or asynchronoussignals are enabled, and so the data structure can be consideredeffectively constant in these contexts, which makes the former safe.

• fd

  Functions annotated withfd as an AC-Safety issue may leak filedescriptors if asynchronous thread cancellation interrupts theirexecution.

  Functions that allocate or deallocate file descriptors will generally bemarked as such. Even if they attempted to protect the file descriptorallocation and deallocation with cleanup regions, allocating a newdescriptor and storing its number where the cleanup region could releaseit cannot be performed as a single atomic operation. Similarly,releasing the descriptor and taking it out of the data structurenormally responsible for releasing it cannot be performed atomically.There will always be a window in which the descriptor cannot be releasedbecause it was not stored in the cleanup handler argument yet, or it wasalready taken out before releasing it. It cannot be taken out afterrelease: an open descriptor could mean either that the descriptor stillhas to be closed, or that it already did so but the descriptor wasreallocated 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 dothis themselves, to avoid the same sort of leak in their own layer, itmakes more sense for the library to assume they are taking care of itthan to impose a performance penalty that is redundant when the problemis solved in upper layers, and insufficient when it is not.

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

• mem

  Functions annotated withmem as an AC-Safety issue may leakmemory if asynchronous thread cancellation interrupts their execution.

  The problem is similar to that of file descriptors: there is no atomicinterface to allocate memory and store its address in the argument to acleanup handler, or to release it and remove its address from thatargument, without at least temporarily disabling asynchronouscancellation, which these functions do not do.

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

• cwd

  Functions marked withcwd as an MT-Safety issue may temporarilychange the current working directory during their execution, which maycause relative pathnames to be resolved in unexpected ways in otherthreads or within asynchronous signal or cancellation handlers.

  This is not enough of a reason to mark so-marked functions as MT- orAS-Unsafe, but when this behavior is optional (e.g.,nftw withFTW_CHDIR), avoiding the option may be a good alternative tousing 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, indicatesthe safety status of the function is known to differ from the specifiedstatus in the POSIX standard. For example, POSIX does not require afunction to be Safe, but our implementation is, or vice-versa.

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

• :identifier

  Annotations may sometimes be followed by identifiers, intended to groupseveral functions that e.g. access the data structures in an unsafe way,as inrace andconst, or to provide more specificinformation, such as naming a signal in a function marked withsig. It is envisioned that it may be applied tolock andcorrupt as well in the future.

  In most cases, the identifier will name a set of functions, but it mayname global objects or function arguments, or identifiable properties orlogical components associated with them, with a notation such ase.g.:buf(arg) to denote a buffer associated with the argumentarg, or:tcattr(fd) to denote the terminal attributes of afile descriptorfd.

  The most common use for identifiers is to provide logical groups offunctions and arguments that need to be protected by the samesynchronization primitive in order to ensure safe operation in a givencontext.

• /condition

  Some safety annotations may be conditional, in that they only apply if aboolean expression involving arguments, global variables or even theunderlying kernel evaluates to true. Such conditions as/hurd or/!linux!bsd indicate the preceding marker onlyapplies when the underlying kernel is the HURD, or when it is neitherLinux nor a BSD kernel, respectively./!ps and/one_per_line indicate the preceding marker only applies whenargumentps is NULL, or global variableone_per_line isnonzero.

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

Next:SVID (The System V Interface Description), Previous:POSIX (The Portable Operating System Interface), Up:Standards and Portability   [Contents][Index]

Next:XPG (The X/Open Portability Guide), Previous:Berkeley Unix, Up:Standards and Portability   [Contents][Index]

Next:Linux (The Linux Kernel), Previous:SVID (The System V Interface Description), Up:Standards and Portability   [Contents][Index]

Previous:XPG (The X/Open Portability Guide), Up:Standards and Portability   [Contents][Index]

Next:Macro Definitions of Functions, Up:Using the Library   [Contents][Index]

#include "header"

#include <file.h>

Next:Reserved Names, Previous:Header Files, Up:Using the Library   [Contents][Index]

extern int abs (int);

#include <stdlib.h>int f (int *i) { return abs (++*i); }

#include <stdlib.h>int g (int *i) { return (abs) (++*i); }#undef absint h (int *i) { return abs (++*i); }

Next:Feature Test Macros, Previous:Macro Definitions of Functions, Up:Using the Library   [Contents][Index]

Previous:Reserved Names, Up:Using the Library   [Contents][Index]

Next:The GNU Allocator, Up:Allocating Storage For Program Data   [Contents][Index]

3.2.1.1 Dynamic Memory Allocation ¶

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

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

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

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

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

For example, if you want to allocate dynamically some space to hold astruct foobar, you cannot declare a variable of typestructfoobar whose contents are the dynamically allocated space. But you candeclare a variable of pointer typestruct foobar * and assign it theaddress 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;}

Next:Unconstrained Allocation, Previous:Memory Allocation in C Programs, Up:Allocating Storage For Program Data   [Contents][Index]

Next:Allocation Debugging, Previous:The GNU Allocator, Up:Allocating Storage For Program Data   [Contents][Index]

3.2.3.1 Basic Memory Allocation ¶

To allocate a block of memory, callmalloc. The prototype forthis function is instdlib.h.

Function:void *malloc(size_tsize) ¶

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

This function returns a pointer to a newly allocated blocksizebytes long, or a null pointer (settingerrno)if the block could not be allocated.

The contents of the block are undefined; you must initialize it yourself(or usecalloc instead; seeAllocating Cleared Space).Normally you would convert the value to a pointer to the kind of objectthat you want to store in the block. Here we show an example of doingso, and of initializing the space with zeros using the library functionmemset (seeCopying Strings and Arrays):

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

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

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

char *ptr = malloc (length + 1);

SeeRepresentation of Strings, for more information about this.

3.2.3.2 Examples ofmalloc ¶

If no more space is available,malloc returns a null pointer.You should check the value ofevery call tomalloc. It isuseful to write a subroutine that callsmalloc and reports anerror if the value is a null pointer, returning only if the value isnonzero. This function is conventionally calledxmalloc. Hereit 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 usingmalloc (by way ofxmalloc).The functionsavestring will copy a sequence of characters intoa 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 thatmalloc gives you is guaranteed to be aligned sothat it can hold any type of data. On GNU systems, the address isalways a multiple of eight on 32-bit systems, and a multiple of 16 on64-bit systems. Only rarely is any higher boundary (such as a pageboundary) necessary; for those cases, usealigned_alloc orposix_memalign (seeAllocating Aligned Memory Blocks).

Note that the memory located after the end of the block is likely to bein use for something else; perhaps a block already allocated by anothercall tomalloc. If you attempt to treat the block as longer thanyou asked for it to be, you are liable to destroy the data thatmalloc uses to keep track of its blocks, or you may destroy thecontents of another block. If you have already allocated a block anddiscover you want it to be bigger, userealloc (seeChanging the Size of a Block).

Portability Notes:

• In the GNU C Library, a successfulmalloc (0)returns a non-null pointer to a newly allocated size-zero block;other implementations may returnNULL instead.POSIX and the ISO C standard allow both behaviors.
• In the GNU C Library, a failedmalloc call setserrno,but ISO C does not require this and non-POSIX implementationsneed not seterrno when failing.
• In the GNU C Library,malloc always fails whensize exceedsPTRDIFF_MAX, to avoid problems with programs that subtractpointers or use signed indexes. Other implementations may succeed inthis case, leading to undefined behavior later.

3.2.3.3 Freeing Memory Allocated withmalloc ¶

When you no longer need a block that you got withmalloc, use thefunctionfree to make the block available to be allocated again.The prototype for this function is instdlib.h.

Function:voidfree(void *ptr) ¶

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

Thefree function deallocates the block of memory pointed atbyptr.

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

struct chain  {    struct chain *next;    char *name;  }voidfree_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 operatingsystem and make the process smaller. Usually, all it can do is allow alater call tomalloc to reuse the space. In the meantime, thespace remains in your program as part of a free-list used internally bymalloc.

Thefree function preserves the value oferrno, so thatcleanup code need not worry about saving and restoringerrnoaround a call tofree. Although neither ISO C norPOSIX.1-2017 requiresfree to preserveerrno, a futureversion of POSIX is planned to require it.

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

3.2.3.4 Changing the Size of a Block ¶

Often you do not know for certain how big a block you will ultimately needat the time you must begin to use the block. For example, the block mightbe a buffer that you use to hold a line being read from a file; no matterhow long you make the buffer initially, you may encounter a line that islonger.

You can make the block longer by callingrealloc orreallocarray. These functions are declared instdlib.h.

Function:void *realloc(void *ptr, size_tnewsize) ¶

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

Therealloc function changes the size of the block whose address isptr to benewsize.

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

If you pass a null pointer forptr,realloc behaves justlike ‘malloc (newsize)’.Otherwise, ifnewsize is zerorealloc frees the block and returnsNULL.Otherwise, ifrealloc cannot reallocate the requested sizeit returnsNULL and setserrno; the original blockis left undisturbed.

Function:void *reallocarray(void *ptr, size_tnmemb, size_tsize) ¶

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

Thereallocarray function changes the size of the block whose addressisptr to be long enough to contain a vector ofnmemb elements,each of sizesize. It is equivalent to ‘realloc (ptr,nmemb *size)’, except thatreallocarray fails safely ifthe multiplication overflows, by settingerrno toENOMEM,returning a null pointer, and leaving the original block unchanged.

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

This function was originally derived from OpenBSD 5.6, but was added inPOSIX.1-2024.

Likemalloc,realloc andreallocarray may return a nullpointer if no memory space is available to make the block bigger. When thishappens, the original block is untouched; it has not been modified orrelocated.

In most cases it makes no difference what happens to the original blockwhenrealloc fails, because the application program cannot continuewhen it is out of memory, and the only thing to do is to give a fatal errormessage. Often it is convenient to write and use subroutines,conventionally calledxrealloc andxreallocarray,that take care of the error messageasxmalloc does formalloc:

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 userealloc orreallocarray to make a blocksmaller. The reason you would do this is to avoid tying up a lot of memoryspace when only a little is needed.In several allocation implementations, making a block smaller sometimesnecessitates 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 ifptr is non-null,realloc (ptr, 0)might free the block and return a non-null pointer to a size-zeroobject, or it might fail and returnNULL without freeing the block.The ISO C17 standard allows these variations.
• In the GNU C Library, reallocation fails if the resulting blockwould exceedPTRDIFF_MAX in size, to avoid problems with programsthat subtract pointers or use signed indexes. Other implementations maysucceed, leading to undefined behavior later.
• In the GNU C Library, if the new size is the same as the old,realloc andreallocarray are guaranteed to change nothing and return the sameaddress that you gave. However, POSIX and ISO C allow the functionsto relocate the object or fail in this situation.

3.2.3.5 Allocating Cleared Space ¶

The functioncalloc allocates memory and clears it to zero. Itis declared instdlib.h.

Function:void *calloc(size_tcount, size_teltsize) ¶

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

This function allocates a block long enough to contain a vector ofcount elements, each of sizeeltsize. Its contents arecleared to zero beforecalloc returns.

You could definecalloc 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 thatcalloc callsreallocarray andmemset internally. For example, if thecalloc implementation knows for other reasons that the newmemory block is zero, it need not zero out the block again withmemset. Also, if an application provides its ownreallocarray outside the C library,calloc might not usethat redefinition. SeeReplacingmalloc.

3.2.3.6 Allocating Aligned Memory Blocks ¶

The address of a block returned bymalloc orrealloc inGNU systems is always a multiple of eight (or sixteen on 64-bitsystems). If you need a block whose address is a multiple of a higherpower of two than that, usealigned_alloc orposix_memalign.aligned_alloc andposix_memalign are declared instdlib.h.

Function:void *aligned_alloc(size_talignment, size_tsize) ¶

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

Thealigned_alloc function allocates a block ofsize bytes whoseaddress is a multiple ofalignment. Thealignment must be apower of two.

Thealigned_alloc function returns a null pointer on error and setserrno 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 betterportability to modern non-POSIX systems thanposix_memalign.

Function:void *memalign(size_tboundary, size_tsize) ¶

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

Thememalign function allocates a block ofsize bytes whoseaddress is a multiple ofboundary. Theboundary must be apower of two! The functionmemalign works by allocating asomewhat larger block, and then returning an address within the blockthat is on the specified boundary.

Thememalign function returns a null pointer on error and setserrno to one of the following values:

ENOMEM

There was insufficient memory available to satisfy the request.

EINVAL

boundary is not a power of two.

Thememalign function is obsolete andaligned_alloc orposix_memalign should be used instead.

Function:intposix_memalign(void **memptr, size_talignment, size_tsize) ¶

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

Theposix_memalign function is similar to thememalignfunction in that it returns a buffer ofsize bytes aligned to amultiple ofalignment. But it adds one requirement to theparameteralignment: the value must be a power of two multiple ofsizeof (void *).

If the function succeeds in allocation memory a pointer to the allocatedmemory 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 ofsizeof (void *).

This function was introduced in POSIX 1003.1d. Although this function issuperseded byaligned_alloc, it is more portable to older POSIXsystems that do not support ISO C11.

Function:void *valloc(size_tsize) ¶

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

Usingvalloc is like usingmemalign and passing the page sizeas 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 memorysubsystem.

Thevalloc function is obsolete andaligned_alloc orposix_memalign should be used instead.

3.2.3.7 Malloc Tunable Parameters ¶

You can adjust some parameters for dynamic memory allocation with themallopt function. This function is the general SVID/XPGinterface, defined inmalloc.h.

Function:intmallopt(intparam, intvalue) ¶

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

When callingmallopt, theparam argument specifies theparameter to be set, andvalue the new value to be set. Possiblechoices forparam, as defined inmalloc.h, are:

M_MMAP_MAX ¶

The maximum number of chunks to allocate withmmap. Setting thisto zero disables all use ofmmap.

The default value of this parameter is65536.

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_MMAP_MAX_ to the desired value.

M_MMAP_THRESHOLD ¶

All chunks larger than this value are allocated outside the normalheap, using themmap system call. This way it is guaranteedthat the memory for these chunks can be returned to the system onfree. Note that requests smaller than this threshold might stillbe allocated viammap.

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

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_MMAP_THRESHOLD_ to the desired value.

M_PERTURB ¶

If non-zero, memory blocks are filled with values depending on somelow order bits of this parameter when they are allocated (except whenallocated bycalloc) and freed. This can be used to debug theuse of uninitialized or freed heap memory. Note that this option does notguarantee that the freed block will have any specific values. It onlyguarantees that the content the block had before it was freed will beoverwritten.

The default value of this parameter is0.

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_PERTURB_ to the desired value.

M_TOP_PAD ¶

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

The default value of this parameter is0.

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_TOP_PAD_ to the desired value.

M_TRIM_THRESHOLD ¶

This is the minimum size (in bytes) of the top-most, releasable chunkthat 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 thethreshold is adjusted dynamically to suit the allocation patterns of theprogram. If the parameter is set, the dynamic adjustment is disabled and thevalue is set statically to the provided input.

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_TRIM_THRESHOLD_ to the desired value.

M_ARENA_TEST ¶

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

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

This parameter can also be set for the process at startup by setting theenvironment variableMALLOC_ARENA_TEST to the desired value.

M_ARENA_MAX ¶

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

The default value of this tunable is0, meaning that the limit on thenumber of arenas is determined by the number of CPU cores online. For 32-bitsystems the limit is twice the number of cores online and on 64-bit systems, itis eight times the number of cores online. Note that the default value is notderived 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 theenvironment variableMALLOC_ARENA_MAX to the desired value.

3.2.3.8 Heap Consistency Checking ¶

You can askmalloc to check the consistency of dynamic memory byusing themcheck function and preloading the malloc debug librarylibc_malloc_debug using theLD_PRELOAD environment variable.This function is a GNU extension, declared inmcheck.h.

Function:intmcheck(void (*abortfn) (enum mcheck_statusstatus)) ¶

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

Callingmcheck tellsmalloc to perform occasionalconsistency checks. These will catch things such as writingpast the end of a block that was allocated withmalloc.

Theabortfn argument is the function to call when an inconsistencyis found. If you supply a null pointer, thenmcheck uses adefault function which prints a message and callsabort(seeAborting a Program). The function you supply is called withone argument, which says what sort of inconsistency was detected; itstype is described below.

It is too late to begin allocation checking once you have allocatedanything withmalloc. Somcheck does nothing in thatcase. The function returns-1 if you call it too late, and0 otherwise (when it is successful).

The easiest way to arrange to callmcheck early enough is to usethe option ‘-lmcheck’ when you link your program; then you don’tneed to modify your program source at all. Alternatively you might usea debugger to insert a call tomcheck whenever the program isstarted, for example these gdb commands will automatically callmcheckwhenever the program starts:

(gdb) break mainBreakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10(gdb) command 1Type 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 objectinvolved calls any of themalloc functions sincemcheckmust be called before the first such function.

Function:enum mcheck_statusmprobe(void *pointer) ¶

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

Themprobe function lets you explicitly check for inconsistenciesin a particular allocated block. You must have already calledmcheck at the beginning of the program, to do its occasionalchecks; callingmprobe requests an additional consistency checkto be done at the time of the call.

The argumentpointer must be a pointer returned bymallocorrealloc.mprobe returns a value that says whatinconsistency, if any, was found. The values are described below.

Data Type:enum mcheck_status ¶

This enumerated type describes what kind of inconsistency was detectedin 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 pointeris decremented too far.

MCHECK_TAIL

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

MCHECK_FREE

The block was already freed.

Another possibility to check for and guard against bugs in the use ofmalloc,realloc andfree is to set the environmentvariableMALLOC_CHECK_. WhenMALLOC_CHECK_ is set to anon-zero value less than 4, a special (less efficient) implementation isused which is designed to be tolerant against simple errors, such asdouble calls offree with the same argument, or overruns of asingle byte (off-by-one bugs). Not all such errors can be protectedagainst, however, and memory leaks can result. Like in the case ofmcheck, one would need to preload thelibc_malloc_debuglibrary to enableMALLOC_CHECK_ functionality. Without thispreloaded library, settingMALLOC_CHECK_ will have no effect.

Any detected heap corruption results in immediate termination of theprocess.

There is one problem withMALLOC_CHECK_: in SUID or SGID binariesit could possibly be exploited since diverging from the normal programsbehavior it now writes something to the standard error descriptor.Therefore the use ofMALLOC_CHECK_ is disabled by default forSUID and SGID binaries.

So, what’s the difference between usingMALLOC_CHECK_ and linkingwith ‘-lmcheck’?MALLOC_CHECK_ is orthogonal with respect to‘-lmcheck’. ‘-lmcheck’ has been added for backwardcompatibility. BothMALLOC_CHECK_ and ‘-lmcheck’ shoulduncover the same bugs - but usingMALLOC_CHECK_ you don’t need torecompile your application.

3.2.3.9 Statistics for Memory Allocation withmalloc ¶

You can get information about dynamic memory allocation by calling themallinfo2 function. This function and its associated data typeare declared inmalloc.h; they are an extension of the standardSVID/XPG version.

Data Type:struct mallinfo2 ¶

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

size_t arena

This is the total size of memory allocated withsbrk bymalloc, in bytes.

size_t ordblks

This is the number of chunks not in use. (The memory allocatorinternally gets chunks of memory from the operating system, and thencarves them up to satisfy individualmalloc requests;seeThe GNU Allocator.)

size_t smblks

This field is unused.

size_t hblks

This is the total number of chunks allocated withmmap.

size_t hblkhd

This is the total size of memory allocated withmmap, 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 bymalloc.

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 normallyborders the end of the heap (i.e., the high end of the virtual addressspace’s data segment).

Function:struct mallinfo2mallinfo2(void) ¶

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

This function returns information about the current dynamic memory usagein a structure of typestruct mallinfo2.

3.2.3.10 Summary ofmalloc-Related Functions ¶

Here is a summary of the functions that work withmalloc:

void *malloc (size_tsize)

Allocate a block ofsize bytes. SeeBasic Memory Allocation.

void free (void *addr)

Free a block previously allocated bymalloc. SeeFreeing Memory Allocated withmalloc.

void *realloc (void *addr, size_tsize)

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

void *reallocarray (void *ptr, size_tnmemb, size_tsize)

Change the size of a block previously allocated bymalloc tonmemb *size bytes as withrealloc. SeeChanging the Size of a Block.

void *calloc (size_tcount, size_teltsize)

Allocate a block ofcount *eltsize bytes usingmalloc, and set its contents to zero. SeeAllocating Cleared Space.

void *valloc (size_tsize)

Allocate a block ofsize bytes, starting on a page boundary.SeeAllocating Aligned Memory Blocks.

void *aligned_alloc (size_talignment, size_tsize)

Allocate a block ofsize bytes, starting on an address that is amultiple ofalignment. SeeAllocating Aligned Memory Blocks.

int posix_memalign (void **memptr, size_talignment, size_tsize)

Allocate a block ofsize bytes, starting on an address that is amultiple ofalignment. SeeAllocating Aligned Memory Blocks.

void *memalign (size_tboundary, size_tsize)

Allocate a block ofsize bytes, starting on an address that is amultiple ofboundary. SeeAllocating Aligned Memory Blocks.

int mallopt (intparam, intvalue)

Adjust a tunable parameter. SeeMalloc Tunable Parameters.

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

Tellmalloc to perform occasional consistency checks ondynamically allocated memory, and to callabortfn when aninconsistency is found. SeeHeap Consistency Checking.

struct mallinfo2 mallinfo2 (void)

Return information about the current dynamic memory usage.SeeStatistics for Memory Allocation withmalloc.

Next:Replacingmalloc, Previous:Unconstrained Allocation, Up:Allocating Storage For Program Data   [Contents][Index]

3.2.4.1 How to install the tracing functionality ¶

Function:voidmtrace(void) ¶

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

Themtrace function provides a way to trace memory allocationevents in the program that calls it. It is disabled by default in thelibrary and can be enabled by preloading the debugging librarylibc_malloc_debug using theLD_PRELOAD environmentvariable.

When themtrace function is called it looks for an environmentvariable namedMALLOC_TRACE. This variable is supposed tocontain a valid file name. The user must have write access. If thefile already exists it is truncated. If the environment variable is notset or it does not name a valid file which can be opened for writingnothing is done. The behavior ofmalloc etc. is not changed.For obvious reasons this also happens if the application is installedwith the SUID or SGID bit set.

If the named file is successfully opened,mtrace installs specialhandlers for the functionsmalloc,realloc, andfree. From then on, all uses of these functions are traced andprotocolled into the file. There is now of course a speed penalty for allcalls to the traced functions so tracing should not be enabled during normaluse.

This function is a GNU extension and generally not available on othersystems. The prototype can be found inmcheck.h.

Function:voidmuntrace(void) ¶

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

Themuntrace function can be called aftermtrace was usedto enable tracing themalloc calls. If no (successful) call ofmtrace was mademuntrace does nothing.

Otherwise it deinstalls the handlers formalloc,realloc,andfree and then closes the protocol file. No calls areprotocolled anymore and the program runs again at full speed.

This function is a GNU extension and generally not available on othersystems. The prototype can be found inmcheck.h.

3.2.4.2 Example program excerpts ¶

Even though the tracing functionality does not influence the runtimebehavior of the program it is not a good idea to callmtrace inall programs. Just imagine that you debug a program usingmtraceand all other programs used in the debugging session also trace theirmalloc calls. The output file would be the same for all programsand thus is unusable. Therefore one should callmtrace only ifcompiled for debugging. A program could therefore start like this:

#include <mcheck.h>intmain (int argc, char *argv[]){#ifdef DEBUGGING  mtrace ();#endif  ...}

This is all that is needed if you want to trace the calls during thewhole runtime of the program. Alternatively you can stop the tracing atany time with a call tomuntrace. It is even possible to restartthe tracing again with a new call tomtrace. But this can causeunreliable results since there may be calls of the functions which arenot called. Please note that not only the application uses the tracedfunctions, also libraries (including the C library itself) use thesefunctions.

This last point is also why it is not a good idea to callmuntracebefore the program terminates. The libraries are informed about thetermination of the program only after the program returns frommain or callsexit and so cannot free the memory they usebefore this time.

So the best thing one can do is to callmtrace as the very firstfunction in the program and never callmuntrace. So the programtraces almost all uses of themalloc functions (except thosecalls which are executed by constructors of the program or usedlibraries).

3.2.4.3 Some more or less clever ideas ¶

You know the situation. The program is prepared for debugging and inall debugging sessions it runs well. But once it is started withoutdebugging the error shows up. A typical example is a memory leak thatbecomes visible only when we turn off the debugging. If you foreseesuch situations you can still win. Simply use something equivalent tothe following little program:

#include <mcheck.h>#include <signal.h>static voidenable (int sig){  mtrace ();  signal (SIGUSR1, enable);}static voiddisable (int sig){  muntrace ();  signal (SIGUSR2, disable);}intmain (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 theprogram was started withMALLOC_TRACE set in the environment.The output will of course not show the allocations which happened beforethe first signal but if there is a memory leak this will show upnevertheless.

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 notmeant to be read by a human. Therefore no attention is given toreadability. Instead there is a program which comes with the GNU C Librarywhich interprets the traces and outputs a summary in anuser-friendly way. The program is calledmtrace (it is in fact aPerl script) and it takes one or two arguments. In any case the name ofthe file with the trace output must be specified. If an optionalargument precedes the name of the trace file this must be the name ofthe program which generated the trace.

drepper$ mtrace tst-mtrace logNo memory leaks.

In this case the programtst-mtrace was run and it produced atrace filelog. The message printed bymtrace shows thereare no problems with the code, all allocated memory was freedafterwards.

If we callmtrace on the example trace given above we would get adifferent 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 0x8048209Memory not freed:-----------------   Address     Size     Caller0x08064c48     0x14  at 0x80481eb0x08064c60     0x14  at 0x80481eb0x08064c78     0x14  at 0x80481eb0x08064c90     0x14  at 0x80481eb

We have calledmtrace with only one argument and so the scripthas no chance to find out what is meant with the addresses given in thetrace. 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:39Memory not freed:-----------------   Address     Size     Caller0x08064c48     0x14  at /home/drepper/tst.c:330x08064c60     0x14  at /home/drepper/tst.c:330x08064c78     0x14  at /home/drepper/tst.c:330x08064c90     0x14  at /home/drepper/tst.c:33

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

Interpreting this output is not complicated. There are at most twodifferent situations being detected. First,free was called forpointers which were never returned by one of the allocation functions.This is usually a very bad problem and what this looks like is shown inthe first three lines of the output. Situations like this are quiterare and if they appear they show up very drastically: the programnormally crashes.

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

Next:Obstacks, Previous:Allocation Debugging, Up:Allocating Storage For Program Data   [Contents][Index]

Next:Automatic Storage with Variable Size, Previous:Replacingmalloc, Up:Allocating Storage For Program Data   [Contents][Index]

3.2.6.1 Creating Obstacks ¶

The utilities for manipulating obstacks are declared in the headerfileobstack.h.

Data Type:struct obstack ¶

An obstack is represented by a data structure of typestructobstack. This structure has a small fixed size; it records the statusof 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 tryto access the contents of the structure directly; use only the functionsdescribed in this chapter.

You can declare variables of typestruct obstack and use them asobstacks, or you can allocate obstacks dynamically like any other kindof object. Dynamic allocation of obstacks allows your program to have avariable number of different stacks. (You can even allocate anobstack structure in another obstack, but this is rarely useful.)

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

The objects in the obstack are packed into large blocks calledchunks. Thestruct obstack structure points to a chain ofthe chunks currently in use.

The obstack library obtains a new chunk whenever you allocate an objectthat won’t fit in the previous chunk. Since the obstack library manageschunks automatically, you don’t need to pay much attention to them, butyou do need to supply a function which the obstack library should use toget a chunk. Usually you supply a function which usesmallocdirectly 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 functionsmust include the header fileobstack.h, like this:

#include <obstack.h>

Also, if the source file uses the macroobstack_init, it mustdeclare or define two functions or macros that will be called by theobstack library. One,obstack_chunk_alloc, is used to allocatethe chunks of memory into which objects are packed. The other,obstack_chunk_free, is used to return chunks when the objects inthem are freed. These macros should appear before any use of obstacksin the source file.

Usually these are defined to usemalloc via the intermediaryxmalloc (seeUnconstrained Allocation). This is done withthe following pair of macro definitions:

#define obstack_chunk_alloc xmalloc#define obstack_chunk_free free

Though the memory you get using obstacks really comes frommalloc,using obstacks is faster becausemalloc is called less often, forlarger blocks of memory. SeeObstack Chunks, for full details.

At run time, before the program can use astruct obstack objectas an obstack, it must initialize the obstack by callingobstack_init.

Function:intobstack_init(struct obstack *obstack-ptr) ¶

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

Initialize obstackobstack-ptr for allocation of objects. Thisfunction calls the obstack’sobstack_chunk_alloc function. Ifallocation of memory fails, the function pointed to byobstack_alloc_failed_handler is called. Theobstack_initfunction always returns 1 (Compatibility notice: Former versions ofobstack returned 0 if allocation failed).

Here are two examples of how to allocate the space for an obstack andinitialize 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 thatobstack uses whenobstack_chunk_alloc fails to allocatememory. The default action is to print a message and abort.You should supply a function that either callsexit(seeProgram Termination) orlongjmp (seeNon-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 withobstack_alloc, which is invoked almost likemalloc.

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

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

This allocates an uninitialized block ofsize bytes in an obstackand returns its address. Hereobstack-ptr specifies which obstackto allocate the block in; it is the address of thestruct obstackobject which represents the obstack. Each obstack function or macrorequires you to specify anobstack-ptr as the first argument.

This function calls the obstack’sobstack_chunk_alloc function ifit needs to allocate a new chunk of memory; it callsobstack_alloc_failed_handler if allocation of memory byobstack_chunk_alloc failed.

For example, here is a function that allocates a copy of a stringstrin a specific obstack, which is in the variablestring_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 functionobstack_copy, declared like this:

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

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

This allocates a block and initializes it by copyingsizebytes of data starting ataddress. It callsobstack_alloc_failed_handler if allocation of memory byobstack_chunk_alloc failed.

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

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

Likeobstack_copy, but appends an extra byte containing a nullcharacter. This extra byte is not counted in the argumentsize.

Theobstack_copy0 function is convenient for copying a sequenceof characters into an obstack as a null-terminated string. Here is anexample of its use:

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

Contrast this with the previous example ofsavestring usingmalloc (seeBasic Memory Allocation).

3.2.6.4 Freeing Objects in an Obstack ¶

To free an object allocated in an obstack, use the functionobstack_free. Since the obstack is a stack of objects, freeingone object automatically frees all other objects allocated more recentlyin the same obstack.

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

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

Ifobject is a null pointer, everything allocated in the obstackis freed. Otherwise,object must be the address of an objectallocated in the obstack. Thenobject is freed, along witheverything allocated inobstack-ptr sinceobject.

Note that ifobject is a null pointer, the result is anuninitialized obstack. To free all memory in an obstack but leave itvalid for further allocation, callobstack_free with the addressof 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 allthe objects in a chunk become free, the obstack library automaticallyfrees the chunk (seePreparing for Using Obstacks). Then otherobstacks, 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 oras macros, depending on the compiler. The obstack facility works withall C compilers, including both ISO C and traditional C, but there areprecautions 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 thesemacros like functions, but you cannot use them in any other way (forexample, you cannot take their address).

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

obstack_alloc (get_obstack (), 4);

you will find thatget_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 occurseveral times.

In ISO C, each function has both a macro definition and a functiondefinition. The function definition is used if you take the address of thefunction without calling it. An ordinary call uses the macro definition bydefault, but you can request the function definition instead by writing thefunction 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 libraryfunctions. SeeMacro Definitions of Functions.

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

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

3.2.6.6 Growing Objects ¶

Because memory in obstack chunks is used sequentially, it is possible tobuild up an object step by step, adding one or more bytes at a time to theend of the object. With this technique, you do not need to know how muchdata you will put in the object until you come to the end of it. We callthis the technique ofgrowing objects. The special functionsfor 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 automaticallystarts it. However, it is necessary to say explicitly when the object isfinished. This is done with the functionobstack_finish.

The actual address of the object thus built up is not known until theobject is finished. Until then, it always remains possible that you willadd 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 forordinary allocation of another object. If you try to do so, the spacealready added to the growing object will become part of the other object.

Function:voidobstack_blank(struct obstack *obstack-ptr, intsize) ¶

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

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

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

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

To add a block of initialized space, useobstack_grow, which isthe growing-object analogue ofobstack_copy. It addssizebytes of data to the growing object, copying the contents fromdata.

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

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

This is the growing-object analogue ofobstack_copy0. It addssize bytes copied fromdata, followed by an additional nullcharacter.

Function:voidobstack_1grow(struct obstack *obstack-ptr, charc) ¶

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

To add one character at a time, use the functionobstack_1grow.It adds a single byte containingc to the growing object.

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

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

Adding the value of a pointer one can use the functionobstack_ptr_grow. It addssizeof (void *) bytescontaining the value ofdata.

Function:voidobstack_int_grow(struct obstack *obstack-ptr, intdata) ¶

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

A single value of typeint can be added by using theobstack_int_grow function. It addssizeof (int) bytes tothe growing object and initializes them with the value ofdata.

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

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

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

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

This function can return a null pointer under the same conditions asobstack_alloc (seeAllocation in an Obstack).

When you build an object by growing it, you will probably need to knowafterward how long it became. You need not keep track of this as you growthe object, because you can find out the length from the obstack justbefore finishing the object with the functionobstack_object_size,declared as follows:

Function:intobstack_object_size(struct obstack *obstack-ptr) ¶

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

This function returns the current size of the growing object, in bytes.Remember to call this functionbefore 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 shouldfinish 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 useobstack_blank with a negative size argument to makethe current object smaller. Just don’t try to shrink it beyond zerolength—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 checkingwhether there is room for the new growth in the current chunk. If youare frequently constructing objects in small steps of growth, thisoverhead can be significant.

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

The functionobstack_room returns the amount of room availablein the current chunk. It is declared as follows:

Function:intobstack_room(struct obstack *obstack-ptr) ¶

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

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

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

Function:voidobstack_1grow_fast(struct obstack *obstack-ptr, charc) ¶

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

The functionobstack_1grow_fast adds one byte containing thecharacterc to the growing object in obstackobstack-ptr.

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

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

The functionobstack_ptr_grow_fast addssizeof (void *)bytes containing the value ofdata to the growing object inobstackobstack-ptr.

Function:voidobstack_int_grow_fast(struct obstack *obstack-ptr, intdata) ¶

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

The functionobstack_int_grow_fast addssizeof (int) bytescontaining the value ofdata to the growing object in obstackobstack-ptr.

Function:voidobstack_blank_fast(struct obstack *obstack-ptr, intsize) ¶

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

The functionobstack_blank_fast addssize bytes to thegrowing object in obstackobstack-ptr without initializing them.

When you check for space usingobstack_room and there is notenough room for what you want to add, the fast growth functionsare not safe. In this case, simply use the corresponding ordinarygrowth function instead. Very soon this will copy the object to anew chunk; then there will be lots of room available again.

So, each time you use an ordinary growth function, check afterward forsufficient space usingobstack_room. Once the object is copiedto a new chunk, there will be plenty of space again, so the program willstart using the fast growth functions again.

Here is an example:

voidadd_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 ofallocation in an obstack. You can use them to learn about an object whilestill growing it.

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

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

This function returns the tentative address of the beginning of thecurrently growing object inobstack-ptr. If you finish the objectimmediately, it will have that address. If you make it larger first, itmay outgrow the current chunk—then its address will change!

If no object is growing, this value says where the next object youallocate will start (once again assuming it fits in the currentchunk).

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

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

This function returns the address of the first free byte in the currentchunk of obstackobstack-ptr. This is the end of the currentlygrowing object. If no object is growing,obstack_next_freereturns the same value asobstack_base.

Function:intobstack_object_size(struct obstack *obstack-ptr) ¶

Preliminary:| MT-Safe race:obstack-ptr| AS-Safe | AC-Safe | SeePOSIX 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 analignment boundary; each object allocated inthe obstack automatically starts on an address that is a multiple of thespecified boundary. By default, this boundary is aligned so thatthe object can hold any type of data.

To access an obstack’s alignment boundary, use the macroobstack_alignment_mask, whose function prototype looks likethis:

Macro:intobstack_alignment_mask(struct obstack *obstack-ptr) ¶

Preliminary:| MT-Safe | AS-Safe | AC-Safe | SeePOSIX Safety Concepts.

The value is a bit mask; a bit that is 1 indicates that the correspondingbit in the address of an object should be 0. The mask value should be oneless than a power of 2; the effect is that all object addresses aremultiples of that power of 2. The default value of the mask is a valuethat allows aligned objects to hold any type of data: for example, ifits value is 3, any type of data can be stored at locations whoseaddresses are multiples of 4. A mask value of 0 means an object can starton any multiple of 1 (that is, no alignment is required).

The expansion of the macroobstack_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 untilafter the next time an object is allocated or finished in theobstack. If you are not growing an object, you can make the newalignment mask take effect immediately by callingobstack_finish.This will finish a zero-length object and then do proper alignment forthe next object.

3.2.6.10 Obstack Chunks ¶

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

The obstack library allocates chunks by calling the functionobstack_chunk_alloc, which you must define. When a chunk is nolonger needed because you have freed all the objects in it, the obstacklibrary frees the chunk by callingobstack_chunk_free, which youmust also define.

These two must be defined (as macros) or declared (as functions) in eachsource file that usesobstack_init (seeCreating 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 witharguments will not work! It is necessary thatobstack_chunk_allocorobstack_chunk_free, alone, expand into a function name if it isnot itself a function name.

If you allocate chunks withmalloc, the chunk size should be apower of 2. The default chunk size, 4096, was chosen because it is longenough to satisfy many typical requests on the obstack yet short enoughnot to waste too much memory in the portion of the last chunk not yet used.

Macro:intobstack_chunk_size(struct obstack *obstack-ptr) ¶

Preliminary:| MT-Safe | AS-Safe | AC-Safe | SeePOSIX 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 byassigning it a new value. Doing so does not affect the chunks alreadyallocated, but will change the size of chunks allocated for that particularobstack in the future. It is unlikely to be useful to make the chunk sizesmaller, but making it larger might improve efficiency if you areallocating many objects whose size is comparable to the chunk size. Hereis 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. Eachtakes the address of an obstack (struct obstack *) as its firstargument.

void obstack_init (struct obstack *obstack-ptr)

Initialize use of an obstack. SeeCreating Obstacks.

void *obstack_alloc (struct obstack *obstack-ptr, intsize)

Allocate an object ofsize uninitialized bytes.SeeAllocation in an Obstack.

void *obstack_copy (struct obstack *obstack-ptr, void *address, intsize)

Allocate an object ofsize bytes, with contents copied fromaddress. SeeAllocation in an Obstack.

void *obstack_copy0 (struct obstack *obstack-ptr, void *address, intsize)

Allocate an object ofsize+1 bytes, withsize of them copiedfromaddress, followed by a null character at the end.SeeAllocation in an Obstack.

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

Freeobject (and everything allocated in the specified obstackmore recently thanobject). SeeFreeing Objects in an Obstack.

void obstack_blank (struct obstack *obstack-ptr, intsize)

Addsize uninitialized bytes to a growing object.SeeGrowing Objects.

void obstack_grow (struct obstack *obstack-ptr, void *address, intsize)

Addsize bytes, copied fromaddress, to a growing object.SeeGrowing Objects.

void obstack_grow0 (struct obstack *obstack-ptr, void *address, intsize)

Addsize bytes, copied fromaddress, to a growing object,and then add another byte containing a null character. SeeGrowing Objects.

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

Add one byte containingdata-char to a growing object.SeeGrowing Objects.

void *obstack_finish (struct obstack *obstack-ptr)

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

int obstack_object_size (struct obstack *obstack-ptr)

Get the current size of the currently growing object. SeeGrowing Objects.

void obstack_blank_fast (struct obstack *obstack-ptr, intsize)

Addsize uninitialized bytes to a growing object without checkingthat there is enough room. SeeExtra Fast Growing Objects.

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

Add one byte containingdata-char to a growing object withoutchecking that there is enough room. SeeExtra Fast Growing Objects.

int obstack_room (struct obstack *obstack-ptr)

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

int obstack_alignment_mask (struct obstack *obstack-ptr)

The mask used for aligning the beginning of an object. This is anlvalue. SeeAlignment of Data in Obstacks.

int obstack_chunk_size (struct obstack *obstack-ptr)

The size for allocating chunks. This is an lvalue. SeeObstack Chunks.

void *obstack_base (struct obstack *obstack-ptr)

Tentative starting address of the currently growing object.SeeStatus of an Obstack.

void *obstack_next_free (struct obstack *obstack-ptr)

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

Previous:Obstacks, Up:Allocating Storage For Program Data   [Contents][Index]

3.2.7.1alloca Example ¶

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

intopen2 (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 withmalloc andfree:

intopen2 (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 withalloca. Butalloca hasother, more important advantages, and some disadvantages.

3.2.7.2 Advantages ofalloca ¶

Here are the reasons whyalloca may be preferable tomalloc:

• Usingalloca wastes very little space and is very fast. (It isopen-coded by the GNU C compiler.)
• Sincealloca does not have separate pools for different sizes ofblocks, space used for any size block can be reused for any other size.alloca does not cause memory fragmentation.
• Nonlocal exits done withlongjmp (seeNon-Local Exits)automatically free the space allocated withalloca when they exitthrough the function that calledalloca. This is the mostimportant reason to usealloca.

  To illustrate this, suppose you have a functionopen_or_report_error which returns a descriptor, likeopen, if it succeeds, but does not return to its caller if itfails. If the file cannot be opened, it prints an error message andjumps out to the command level of your program usinglongjmp.Let’s changeopen2 (seealloca Example) to use thissubroutine:

  intopen2 (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 wayalloca works, the memory it allocates isfreed even when an error occurs, with no special effort required.

  By contrast, the previous definition ofopen2 (which usesmalloc andfree) would develop a memory leak if it werechanged in this way. Even if you are willing to make more changes tofix it, there is no easy way to do so.

3.2.7.3 Disadvantages ofalloca ¶

These are the disadvantages ofalloca in comparison withmalloc:

• If you try to allocate more memory than the machine can provide, youdon’t get a clean error message. Instead you get a fatal signal likethe one you would get from an infinite recursion; probably asegmentation violation (seeProgram Error Signals).
• Some non-GNU systems fail to supportalloca, so it is lessportable. However, a slower emulation ofalloca written in Cis 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 ofalloca with an array ofvariable size. Here is howopen2 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);}

Butalloca is not always equivalent to a variable-sized array, forseveral reasons:

• A variable size array’s space is freed at the end of the scope of thename of the array. The space allocated withallocaremains until the end of the function.
• It is possible to usealloca within a loop, allocating anadditional block on each iteration. This is impossible withvariable-sized arrays.

NB: If you mix use ofalloca and variable-sized arrayswithin one function, exiting a scope in which a variable-sized array wasdeclared frees all blocks allocated withalloca during theexecution of that scope.