umem_zalloc man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

umem_alloc(3MALLOC)   Memory Allocation Library Functions  umem_alloc(3MALLOC)

NAME
       umem_alloc,  umem_zalloc, umem_free, umem_nofail_callback - fast, scal‐
       able memory allocation

SYNOPSIS
       cc [ flag ... ] file... -lumem [ library ... ]
       #include <umem.h>

       void *umem_alloc(size_t size, int  flags);

       void *umem_zalloc(size_t size, int  flags);

       void umem_free(void *buf, size_t size);

       void umem_nofail_callback((int (*callback)(void));

       void *malloc(size_t size);

       void *calloc(size_t nelem, size_t elsize);

       void free(void *ptr);

       void *memalign(size_t alignment, size_t size);

       void *realloc(void *ptr, size_t size);

       void *valloc(size_t size);

DESCRIPTION
       The umem_alloc() function returns a pointer to a block  of  size	 bytes
       suitably	 aligned for any variable type. The initial contents of memory
       allocated using umem_alloc() is undefined. The  flags  argument	deter‐
       mines  the  behavior  of	 umem_alloc()  if  it is unable to fulfill the
       request. The flags argument can take the following values:

       UMEM_DEFAULT    Return NULL on failure.

       UMEM_NOFAIL     Call an optional callback (set  with  umem_nofail_call‐
		       back()) on failure. The callback takes no arguments and
		       can finish by:

			 ·  returning UMEM_CALLBACK_RETRY, in which  case  the
			    allocation	will  be  retried.   If the allocation
			    fails, the callback will be invoked again.

			 ·  returning  UMEM_CALLBACK_EXIT(status),  in	 which
			    case  exit(2)  is invoked with status as its argu‐
			    ment. The exit() function is called only once.  If
			    multiple threads return from the UMEM_NOFAIL call‐
			    back  with	UMEM_CALLBACK_EXIT(status),  one  will
			    call  exit()  while	 the other blocks until exit()
			    terminates the program.

			 ·  invoking  a	 context-changing  function   (setcon‐
			    text(2))  or a non-local jump (longjmp(3C) or sig‐
			    longjmp(3C), or ending the current thread of  con‐
			    trol (thr_exit(3C) or pthread_exit(3C). The appli‐
			    cation is responsible for any  necessary  cleanup.
			    The state of libumem remains consistent.

		       If  no  callback	 has been set or the callback has been
		       set to NULL, umem_alloc(...,  UMEM_NOFAIL)  behaves  as
		       though the callback returned UMEM_CALLBACK_EXIT(255).

		       The  libumem  library can call callbacks from any place
		       that a UMEM_NOFAIL  allocation  is  issued.  In	multi‐
		       threaded	 applications,	callbacks are expected to per‐
		       form their own concurrency management.

       The function call umem_alloc(0, flag) always returns NULL. The function
       call umem_free(NULL, 0) is allowed.

       The  umem_zalloc() function has the same semantics as umem_alloc(), but
       the block of memory is initialized to zeros before it is returned.

       The  umem_free()	 function  frees  blocks  previously  allocated	 using
       umem_alloc()  and  umem_zalloc().  The  buffer  address	and  size must
       exactly match the original allocation.  Memory  must  not  be  returned
       piecemeal.

       The  umem_nofail_callback()  function sets the process-wide UMEM_NOFAIL
       callback. See the description of UMEM_NOFAIL for more information.

       The malloc(), calloc(), free(),	memalign(),  realloc(),	 and  valloc()
       functions  are are as described in malloc(3C). The libumem library pro‐
       vides these functions for  backwards-compatibility  with	 the  standard
       functions.

ENVIRONMENT VARIABLES
       See  umem_debug(3MALLOC)	 for  environment  variables  that  effect the
       debugging features of the libumem library.

       UMEM_OPTIONS    Contains a list of comma-separated  options.   Unrecog‐
		       nized  options  are  ignored. The options that are sup‐
		       ported are:

		       backend=sbrk    Set the	underlying  function  used  to
		       backend=mmap    allocate memory. This option can be set
				       to   sbrk   (the	  default)   for    an
				       sbrk(2)-based  source  or  mmap	for an
				       mmap(2)-based source. If set to a value
				       that  is	 not  supported,  sbrk will be
				       used.

EXAMPLES
       Example 1: Using the umem_alloc() function.

       #include <stdio.h>
       #include <umem.h>
       ...
       char *buf = umem_alloc(1024, UMEM_DEFAULT);

       if (buf == NULL) {
	    fprintf(stderr, "out of memory\n");
		 return (1);
       }
       /* cannot assume anything about buf's contents */
       ...
       umem_free(buf, 1024);
       ...

       Example 2: Using the umem_zalloc() function

       #include <stdio.h>
       #include <umem.h>
       ...
       char *buf = umem_zalloc(1024, UMEM_DEFAULT);

       if (buf == NULL) {
	   fprintf(stderr, "out of memory\n");
		return (1);
       }
       /* buf contains zeros */
       ...
       umem_free(buf, 1024);
       ...

       Example 3: Using UMEM_NOFAIL

       #include <stdlib.h>
       #include <stdio.h>
       #include <umem.h>

       /*
	* Note that the allocation code below does not have to
	* check for umem_alloc() returning NULL
	*/
       int
       my_failure_handler(void)
       {
		(void) fprintf(stderr, "out of memory\n");
		return (UMEM_CALLBACK_EXIT(255));
       }
       ...
       umem_nofail_callback(my_failure_handler);
       ...
       int i;
       char *buf[100];

       for (i = 0; i < 100; i++)
		buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
       ...
       for (i = 0; i < 100; i++)
	   umem_free(buf[i], 1024 * 1024);
       ...

       Example 4: Using UMEM_NOFAIL in a multithreaded application

       #define _REENTRANT
       #include <thread.h>
       #include <stdio.h>
       #include <umem.h>

       void *
       start_func(void *the_arg)
       {
		 int *info = (int *)the_arg;
		 char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);

		 /* does not need to check for buf == NULL */
		 buf[0] = 0;
		 ...
		 /*
		  * if there were other UMEM_NOFAIL allocations,
		  * we would need to arrange for buf to be
		  * umem_free()ed upon failure.
		  */
		 ...
		 umem_free(buf, 1024 * 1024);
		 return (the_arg);
       }
       ...
       int
       my_failure_handler(void)
       {
		/* terminate the current thread with status NULL */
		thr_exit(NULL);
       }
       ...
       umem_nofail_callback(my_failure_handler);
       ...
       int my_arg;

       thread_t tid;
       void *status;

       (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
	   NULL);
       ...
       while (thr_join(0, &tid, &status) != 0)
		 ;

       if (status == NULL) {
	   (void) fprintf(stderr, "thread %d ran out of memory\n",
		    tid);
       }
       ...

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │See below.		   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

       The malloc(), calloc(), free(), realloc(), and valloc()	functions  are
       Standard.   The	 memalign()  function  is  Stable.  The	 umem_alloc(),
       umem_zalloc(), umem_free(), and	umem_nofail_callback()	functions  are
       Evolving.

SEE ALSO
       exit(2),	   mmap(2),    sbrk(2),	  bsdmalloc(3MALLOC),	libumem(3LIB),
       longjmp(3C),    malloc(3C),    malloc(3MALLOC),	   mapmalloc(3MALLOC),
       pthread_exit(3C),       thr_exit(3C),	   umem_cache_create(3MALLOC),
       umem_debug(3MALLOC), watchmalloc(3MALLOC), attributes(5), standards(5)

       Solaris Modular Debugger Guide

WARNINGS
       Any of the following can cause undefined results:

	 ·  Passing a pointer returned from umem_alloc() or  umem_zalloc()  to
	    free() or realloc().

	 ·  Passing  a	pointer	 returned  from	 malloc(), calloc(), valloc(),
	    memalign(), or realloc() to umem_free().

	 ·  Writing past the end of a buffer allocated using  umem_alloc()  or
	    umem_zalloc()

	 ·  Performing UMEM_NOFAIL allocations from an atexit(3C) handler.

       If  the UMEM_NOFAIL callback performs UMEM_NOFAIL allocations, infinite
       recursion can occur.

NOTES
       The following list compares the features	 of  the  malloc(3C),  bsdmal‐
       loc(3MALLOC),  malloc(3MALLOC),	mtmalloc(3MALLOC)  ,  and  the libumem
       functions.

	 ·  The malloc(3C), bsdmalloc(3MALLOC), and malloc(3MALLOC)  functions
	    have no support for concurrency. The libumem and mtmalloc(3MALLOC)
	    functions support concurrent allocations.

	 ·  The bsdmalloc(3MALLOC) functions afford better performance but are
	    space-inefficient.

	 ·  The	 malloc(3MALLOC) functions are space-efficient but have slower
	    performance.

	 ·  The standard,  fully  SCD-compliant	 malloc(3C)  functions	are  a
	    trade-off between performance and space-efficiency.

	 ·  The	 mtmalloc(3MALLOC) functions provide fast, concurrent malloc()
	    implementations that are not space-efficient.

	 ·  The libumem functions provide a fast, concurrent allocation imple‐
	    mentation  that  in most cases is more space-efficient than mtmal‐
	    loc(3MALLOC).

SunOS 5.10			  26 Aug 2002		   umem_alloc(3MALLOC)
[top]

List of man pages available for SunOS

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