alloca man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

malloc(3C)							    malloc(3C)

NAME
       malloc(),  alloca(),  calloc(),	free(),	 mallinfo(),  mallopt(), memo‐
       rymap(), realloc(), valloc() - main memory allocator

SYNOPSIS
   alloca()
   System V Synopsis
   Remarks
       The functionality in the old package has	 been  incorporated  into  The
       library	corresponding  to the linker option is now an empty library on
       PA-RISC based systems only; it does not exist on Makefiles that	refer‐
       ence  this  library on PA-RISC based systems will continue to work, but
       they will not work on

   Obsolescent Interfaces
       has been deprecated at HP-UX 11i Version 1 and is  now  obsolete.   The
       function is more useful for statistics.

DESCRIPTION
       The  functions  described here provide a simple, general purpose memory
       allocation package:

	      Allocates space for a block of at least
			     size bytes, but does not initialize the space.

	      Allocates space for an array of
			     nelem elements, each of size  elsize  bytes,  and
			     initializes the space to zeros.  Actual amount of
			     space allocated will be at least nelem  *	elsize
			     bytes.

	      Changes the size of the block pointed to by
			     ptr  to  size  bytes and returns a pointer to the
			     (possibly moved) block.   Existing	 contents  are
			     unchanged	up  to	the  lesser of the new and old
			     sizes.  If ptr is a NULL  pointer,	 behaves  like
			     for  the specified size.  If size is zero and ptr
			     is not a NULL pointer, the object it points to is
			     freed  and NULL is returned.  of blocks with spe‐
			     cial alignments, such as those created by is  not
			     supported.

	      Allocates space for a block of at least
			     size  bytes  starting  on a boundary aligned to a
			     multiple of the  value  returned  by  (__SC_PAGE‐
			     SIZE).  This space is uninitialized.

	      Deallocates the space pointed to by
			     ptr (a pointer to a block previously allocated by
			     or and makes  the	space  available  for  further
			     allocation.   If ptr is a NULL pointer, no action
			     occurs.

	      Provides for control over the allocation algorithm
			     and other options in the package.	The  available
			     values for cmd are:

			     Set	    maxfast  to	 value.	 The algorithm
					    allocates  all  blocks  below  the
					    size  of  maxfast in large groups,
					    then doles them out very  quickly.
					    The	 default  value for maxfast is
					    zero.

			     Set	    numlblks to value.	The above men‐
					    tioned  ``large groups'' each con‐
					    tain  numlblks  blocks.   numlblks
					    must   be  greater	than  1.   The
					    default value for numlblks is

			     Set	    grain to value.  The sizes of  all
					    blocks  smaller  than  maxfast are
					    considered to be rounded up to the
					    nearest  multiple of grain.	 grain
					    must be greater  than  zero.   The
					    default  value  of	grain  is  the
					    smallest number of bytes that  can
					    accommodate	 alignment of any data
					    type.  value is rounded  up	 to  a
					    multiple of the default when grain
					    is set.

			     Block all blockable signals in
					    and This option  is	 provided  for
					    those  who	need  to  write signal
					    handlers  that  allocate   memory.
					    When  set,	the  routines  can  be
					    called from within signal handlers
					    (they become re-entrant).  Default
					    action is to block	all  blockable
					    signals.

					    NOTE:   performance	  of  will  be
					    impacted  considerably  when   the
					    option is set.

			     Do not block all blockable signals in
					    and	 This  option  cancels	signal
					    blocking initiated by the option.

			     Enable the feature of
					    This option is provided for 32-bit
					    applications   with	  one	arena.
					    Release of last block happens only
					    when  size	of  the	 free block is
					    greater than the threshold.

					    The threshold value is defined  as
					    The	 feature  is  disabled	if the
					    value is greater than or equal  to
					    threshold  value.	Default action
					    is not to release last block.

			     These values are defined in the header file.

			     can be called  repeatedly;	 but  once  the	 first
			     small  block  is allocated, it is not possible to
			     change the and values.

	      Provides instrumentation describing space usage,
			     but cannot be called until the first small	 block
			     is allocated.  It returns the structure

			     The structure is defined in the header file.

       Each  of	 the  allocation  routines returns a pointer to space suitably
       aligned (after possible pointer coercion) for storage of	 any  type  of
       object.

	      Displays the contents of the memory allocator
			     for  HP-UX 32-bit operating systems only.	A list
			     of addresses and block  descriptions  is  written
			     (using  to	 standard output.  If the value of the
			     show_stats parameter is 1, statistics  concerning
			     number  of	 blocks	 and  sizes  used will also be
			     written.  If the value is zero, only  the	memory
			     map will be written.

			     The addresses and sizes displayed by may not cor‐
			     respond to those  requested  by  an  application.
			     The  size of a block (as viewed by the allocator)
			     includes header information and padding to	 prop‐
			     erly align the block.  The address is also offset
			     by a certain amount  to  accommodate  the	header
			     information.

			     has been deprecated at HP-UX 11i Version 1 and is
			     now obsolete.

	      Allocates space from the stack of the caller
			     for a block of at least size bytes, but does  not
			     initialize the space.  The space is automatically
			     freed when the calling routine exits.

			     Memory returned by is not related to memory allo‐
			     cated   by	 other	memory	allocation  functions.
			     Behavior of addresses returned by	as  parameters
			     to other memory functions is undefined.

			     The  implementation  of  this  routine  is system
			     dependent and its use is discouraged.

RETURN VALUE
       Upon successful completion, and return  a  pointer  to  space  suitably
       aligned	(after	possible  pointer coercion) for storage of any type of
       object.	Otherwise, they return a NULL  pointer.	  If  returns  a  NULL
       pointer, the memory pointed to by the original pointer is left intact.

       returns zero for success and nonzero for failure.

DIAGNOSTICS
       and  return  a  NULL pointer if there is no available memory, or if the
       memory managed by has  been  detectably	corrupted.   This  memory  may
       become corrupted if data is stored outside the bounds of a block, or if
       an invalid pointer (a pointer not generated by or is passed as an argu‐
       ment to or

       If  is  called after any allocation of a small block and cmd is not set
       to or or if cmd or value is invalid, nonzero is	returned.   Otherwise,
       it returns zero.

ERRORS
       and	    set	 to  and  return  a NULL pointer when an out-of-memory
		    condition arises.

       and	    set to and return a NULL pointer  when  the	 memory	 being
		    managed by has been detectably corrupted.

EXTERNAL INFLUENCES
       For PA-RISC based systems, the performance of the family of APIs can be
       tuned via the environment variables and

       For systems, in addition to and three global variables can be used  for
       performance tuning: and

       For  threaded applications, uses multiple arenas.  Memory requests from
       different threads are handled by different  arenas.   can  be  used  to
       adjust  the  number  of	arenas	and  how many pages each time an arena
       expands itself (the expansion factor), assuming that the page  size  is
       4096  bytes.   In general, the more threads in an application, the more
       arenas should be used for better performance.  The number of arenas can
       be from 1 to 64 for threaded applications.

       For non-threaded applications, only one arena is used.  If the environ‐
       ment variable is not set, or the number of arenas is set to be  out  of
       the  range, the default number of 8 will be used.  The expansion factor
       is from 1 to 4096, default value is 32.	Again, if the factor is out of
       the range, the default value will be used.

       Here is an example of how to use

       This  means  that the number of arenas is 16, and the expansion size is
       8*4096 bytes.  In general, the more arenas you  use,  the  smaller  the
       expansion factor should be, and vice versa.

       is  used to turn on the small block allocator, and to set up parameters
       for the small block allocator, namely, maxfast,	grain,	and  numlblks.
       Applications  with  small  block allocator turned on usually run faster
       than with it turned off.	  Small	 block	allocator  can	be  turned  on
       through however, it is not early enough for C++/Java applications.  The
       environment variable turns it on before the  application	 starts.   The
       call  can  still	 be used the same way.	If the environment variable is
       set, and no small block allocator has been used, the  subsequent	 calls
       can still overwrite whatever is set through If the environment variable
       is set, and small block allocator has been  used,  then	will  have  no
       effect.

       To use this environment variable,

       This  means that the maxfast size is 512, the number of small blocks is
       100, and the grain size is 16.  You have to supply all 3 values, and in
       that order.  If not, the default values will be used instead.

       Three  new  global variables, and are introduced for Itanium-based sys‐
       tems to over-ride the environment option.  When these  three  variables
       are  initialized	 within	 an  application,  has no effect.  This way, a
       finely tuned application can lock in performance across different  user
       environments.   However,	 as  a	subsequent call to before any block of
       memory was allocated will change the behavior.  By default, these three
       variables  will	be initialized to zero at start up.  It is the same as
       setting them to

       By default, SBA (Small Block Allocation) is turned on for Itanium-based
       systems.	  This	may  contribute	 to better application performance.  A
       user can set

       This will turn off SBA.

       For all other possible values, please refer to

       is used to turn on the thread local cache.  Turning this option on sets
       up  a private cache for each thread to which access is effectively non-
       threaded, so there is less contention on the arenas.  For  some	multi-
       threaded	 applications this can give a significant performance improve‐
       ment.

       The thread local cache saves blocks of sizes that have previously  been
       used,  and  thus may be requested again.	 The size of the cache is con‐
       figurable.  The cache is organized in buckets of sizes that are	powers
       of  two;	 that  is,  there is a bucket for all blocks in the size range
       64-127 bytes, another for 128-255 bytes, and so on.

       Thread Local Cache can be tuned by setting the environment variable  as
       follows:

       The  values  must  be supplied in the exact order indicated.  The first
       three parameters are mandatory, and the last two are optional.

       denotes the number of pointers cached per bucket.  If is 0, then thread
       local cache is disabled.	 The maximum value for is 32768.

       is an indication of the number of buckets.  The maximum block size that
       will be cached is can range between 8 and 32.

       is an indication in minutes of after how long blocks in an unused cache
       will  be	 released  to the arena.  is only a hint, so caches may or may
       not be retired after the specified time period.	If is 0, retirement is
       disabled.  The maximum value for is 1440 (that is, 24 hours).

       enables	cached	blocks	to  be exchanged among threads.	 A thread that
       heavily allocates blocks of a certain size is soon bound to run out  of
       blocks  in its private cache.  The exchange allows the thread to borrow
       blocks from a global pool if available.	This  may  be  more  efficient
       than going back to the arena.  is a hint to the caching algorithm indi‐
       cating a particular number of cache misses after which it  will	search
       the  global  pool  for  appropriate  sized  blocks.  The algorithm also
       releases unused cache blocks to the global pool.	 If is 0 or  not  set,
       cache exchange is turned off.

       is  an indication of the size of the global cache pool.	This parameter
       is valid only if is turned on.  The default value for is 8.

       The maximum number of blocks that will be cached for each thread is

       Here are examples of how to use

       This means that is 1024, is 32, is 20 minutes, is 4, and is 8.

       This is a valid configuration where the global pool is not activated.

       and have no effect on non-threaded applications, while has.

       NOTE:  Modifying these variables increases  the	chances	 of  surfacing
       existing user memory defects such as buffer overrun.

WARNINGS
       functions  use  and  (see  brk(2))  to  increase the address space of a
       process.	 Therefore, an application program that uses or must  not  use
       them  to	 decrease  the	address space, because this confuses the func‐
       tions.

       and do not check their pointer argument for validity.

       The following actions are  considered  bad  programming	practices  and
       should  not  be done.  The results are unpredictable, probably undesir‐
       able and not supported.	Examples of undesirable results	 are  loss  of
       data, memory fault, bus error or infinite loop.

	      ·	 Attempting  to	 or a pointer not generated as the result of a
		 call to or

	      ·	 Reading or writing data outside the boundaries	 of  an	 allo‐
		 cated block.

	      ·	 Attempting to an aligned block such as the result of

       The  following  actions are strongly discouraged and may be unsupported
       in a future version of

	      ·	 Attempting to the same block twice.

	      ·	 Depending on unmodified contents of a block after it has been
		 freed.

	      ·	 Attempting to a block after it is freed.

       Undocumented features of earlier memory allocators have not been dupli‐
       cated.  Applications which used any of the above bad programming	 prac‐
       tices or discouraged practices are not guaranteed to continue function‐
       ing at future releases.

   Compatibility
       The only external difference between the old allocator and the  alloca‐
       tor is that the old allocator would return a NULL pointer for a request
       of zero bytes.  The allocator returns a valid memory address.  This  is
       not a concern for most applications.

       By default, SBA (Small Block Allocation) is turned on for Itanium-based
       systems and is turned off for PA-RISC systems.  This was due to perfor‐
       mance  concerns.	  Please  refer	 to  the  section  of this manpage for
       details.

SEE ALSO
       brk(2), errno(2), thread_safety(5).

STANDARDS CONFORMANCE

								    malloc(3C)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net