'\" te
.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
.TH umem_alloc 3MALLOC "24 Mar 2008" "SunOS 5.11" "Memory Allocation Library Functions"
.SH NAME
umem_alloc, umem_zalloc, umem_free, umem_nofail_callback \- fast, scalable memory allocation
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ] 
#include <umem.h>

\fBvoid *\fR\fBumem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR  \fIflags\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBumem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR  \fIflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBumem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBvoid\fR \fBumem_nofail_callback\fR(\fB(int (*\fR\fIcallback\fR)(void));
.fi

.LP
.nf
\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR);
.fi

.LP
.nf
\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBumem_alloc()\fR function returns a pointer to a block of \fIsize\fR bytes suitably aligned for any variable type. The initial contents of memory allocated using \fBumem_alloc()\fR is undefined. The \fIflags\fR argument determines the behavior of \fBumem_alloc()\fR if it is unable to fulfill the request. The \fIflags\fR argument can take the following values:
.sp
.ne 2
.mk
.na
\fB\fBUMEM_DEFAULT\fR\fR
.ad
.RS 16n
.rt  
Return \fINULL\fR on failure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBUMEM_NOFAIL\fR\fR
.ad
.RS 16n
.rt  
Call an optional \fIcallback\fR (set with \fBumem_nofail_callback()\fR) on failure. The \fIcallback\fR takes no arguments and can finish by:
.RS +4
.TP
.ie t \(bu
.el o
returning \fBUMEM_CALLBACK_RETRY\fR, in which case the allocation will be retried.  If the allocation fails, the callback will be invoked again.
.RE
.RS +4
.TP
.ie t \(bu
.el o
returning \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), in which case \fBexit\fR(2) is invoked with \fIstatus\fR as its argument. The \fBexit()\fR function is called only once. If multiple threads return from the \fBUMEM_NOFAIL\fR callback with \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), one will call \fBexit()\fR while the other blocks until \fBexit()\fR terminates the program.
.RE
.RS +4
.TP
.ie t \(bu
.el o
invoking a context-changing function (\fBsetcontext\fR(2)) or a non-local jump (\fBlongjmp\fR(3C) or \fBsiglongjmp\fR(3C), or ending the current thread of control (\fBthr_exit\fR(3C) or \fBpthread_exit\fR(3C). The application is responsible for any necessary cleanup. The state of \fBlibumem\fR remains consistent.
.RE
If no callback has been set or the callback has been set to \fINULL\fR, \fBumem_alloc\fR(..., \fBUMEM_NOFAIL\fR) behaves as though the callback returned \fBUMEM_CALLBACK_EXIT\fR(255).
.sp
The \fBlibumem\fR library can call callbacks from any place that a \fBUMEM_NOFAIL\fR allocation is issued. In multithreaded applications, callbacks are expected to perform their own concurrency management.
.RE

.sp
.LP
The function call \fBumem_alloc\fR(0, \fIflag\fR) always returns \fINULL\fR. The function call \fBumem_free\fR(\fINULL\fR, 0) is allowed.
.sp
.LP
The \fBumem_zalloc()\fR function has the same semantics as \fBumem_alloc()\fR, but the block of memory is initialized to zeros before it is returned.
.sp
.LP
The \fBumem_free()\fR function frees blocks previously allocated using \fBumem_alloc()\fR and \fBumem_zalloc()\fR. The buffer address and size must exactly match the original allocation. Memory must not be returned piecemeal.
.sp
.LP
The \fBumem_nofail_callback()\fR function sets the process-wide UMEM_NOFAIL callback. See the description of UMEM_NOFAIL for more information.
.sp
.LP
The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBmemalign()\fR, \fBrealloc()\fR, and \fBvalloc()\fR functions are as described in \fBmalloc\fR(3C). The \fBlibumem\fR library provides these functions for backwards-compatibility with the standard functions.
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBumem_debug\fR(3MALLOC) for environment variables that effect the debugging features of the \fBlibumem\fR library.
.sp
.ne 2
.mk
.na
\fB\fBUMEM_OPTIONS\fR\fR
.ad
.RS 16n
.rt  
Contains a list of comma-separated options.  Unrecognized options are ignored. The options that are supported are:
.sp
.ne 2
.mk
.na
\fB\fBbackend\fR=\fBsbrk\fR\fR
.ad
.br
.na
\fB\fBbackend\fR=\fBmmap\fR\fR
.ad
.RS 16n
.rt  
Set the underlying function used to allocate memory. This option can be set to \fBsbrk\fR (the default) for an \fBsbrk\fR(2)-based source or \fBmmap\fR for an \fBmmap\fR(2)-based source. If set to a value that is not supported, \fBsbrk\fR will be used.
.RE

.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing the \fBumem_alloc()\fR function.
.sp
.in +2
.nf
#include <stdio.h>
#include <umem.h>
\&...
char *buf = umem_alloc(1024, UMEM_DEFAULT);

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

.LP
\fBExample 2 \fRUsing the \fBumem_zalloc()\fR function
.sp
.in +2
.nf
#include <stdio.h>
#include <umem.h>
\&...
char *buf = umem_zalloc(1024, UMEM_DEFAULT);

if (buf == NULL) {
    fprintf(stderr, "out of memory\en");
         return (1);
}
/* buf contains zeros */
\&...
umem_free(buf, 1024);
\&...
.fi
.in -2

.LP
\fBExample 3 \fRUsing UMEM_NOFAIL
.sp
.in +2
.nf
#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\en");
         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);
\&...
.fi
.in -2

.LP
\fBExample 4 \fRUsing UMEM_NOFAIL in a multithreaded application
.sp
.in +2
.nf
#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\en",
             tid);
}
\&...
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
_
StandardSee below.
.TE

.sp
.LP
For \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBrealloc()\fR, and \fBvalloc()\fR, see \fBstandards\fR(5).
.SH SEE ALSO
.sp
.LP
\fBexit\fR(2), \fBmmap\fR(2), \fBsbrk\fR(2), \fBbsdmalloc\fR(3MALLOC), \fBlibumem\fR(3LIB), \fBlongjmp\fR(3C), \fBmalloc\fR(3C), \fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC), \fBpthread_exit\fR(3C), \fBthr_exit\fR(3C), \fBumem_cache_create\fR(3MALLOC), \fBumem_debug\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), \fBattributes\fR(5), \fBstandards\fR(5)
.sp
.LP
\fIOracle Solaris Modular Debugger Guide\fR
.SH WARNINGS
.sp
.LP
Any of the following can cause undefined results:
.RS +4
.TP
.ie t \(bu
.el o
Passing a pointer returned from \fBumem_alloc()\fR or \fBumem_zalloc()\fR to \fBfree()\fR or \fBrealloc()\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Passing a pointer returned from \fBmalloc()\fR, \fBcalloc()\fR, \fBvalloc()\fR, \fBmemalign()\fR, or \fBrealloc()\fR to \fBumem_free()\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Writing past the end of a buffer allocated using \fBumem_alloc()\fR or \fBumem_zalloc()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
Performing \fBUMEM_NOFAIL\fR allocations from an \fBatexit\fR(3C) handler.
.RE
.sp
.LP
If the \fBUMEM_NOFAIL\fR callback performs \fBUMEM_NOFAIL\fR allocations, infinite recursion can occur.
.SH NOTES
.sp
.LP
The following list compares the features of the \fBmalloc\fR(3C), \fBbsdmalloc\fR(3MALLOC), \fBmalloc\fR(3MALLOC), \fBmtmalloc\fR(3MALLOC) , and the \fBlibumem\fR functions.
.RS +4
.TP
.ie t \(bu
.el o
The \fBmalloc\fR(3C), \fBbsdmalloc\fR(3MALLOC), and \fBmalloc\fR(3MALLOC) functions have no support for concurrency. The \fBlibumem\fR and \fBmtmalloc\fR(3MALLOC) functions support concurrent allocations.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBbsdmalloc\fR(3MALLOC) functions afford better performance but are space-inefficient.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBmalloc\fR(3MALLOC) functions are space-efficient but have slower performance.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The standard, fully SCD-compliant \fBmalloc\fR(3C) functions are a trade-off between performance and space-efficiency.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBmtmalloc\fR(3MALLOC) functions provide fast, concurrent \fBmalloc()\fR implementations that are not space-efficient.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBlibumem\fR functions provide a fast, concurrent allocation implementation that in most cases is more space-efficient than \fBmtmalloc\fR(3MALLOC).
.RE