malloc.md

description	title	ms.date	api_name	api_location	api_type	topic_type	f1_keywords	helpviewer_keywords	ms.assetid
Learn more about: malloc	malloc	4/2/2020	malloc _o_malloc	msvcrt.dll msvcr80.dll msvcr90.dll msvcr100.dll msvcr100_clr0400.dll msvcr110.dll msvcr110_clr0400.dll msvcr120.dll msvcr120_clr0400.dll ucrtbase.dll api-ms-win-crt-heap-l1-1-0.dll	DLLExport	apiref	malloc	malloc function memory allocation	144fcee2-be34-4a03-bb7e-ed6d4b99eea0

malloc

Allocates memory blocks.

Syntax

void *malloc(
   size_t size
);

Parameters

size
Bytes to allocate.

Return value

malloc returns a void pointer to the allocated space, or NULL if there's insufficient memory available. To return a pointer to a type other than void, use a type cast on the return value. The storage space pointed to by the return value is suitably aligned for storage of any type of object that has an alignment requirement less than or equal to that of the fundamental alignment. (In Visual C++, the fundamental alignment is the alignment that's required for a double, or 8 bytes. In code that targets 64-bit platforms, it's 16 bytes.) Use _aligned_malloc to allocate storage for objects that have a larger alignment requirement—for example, the SSE types __m128 and __m256, and types that are declared by using __declspec(align( n )) where n is greater than 8. If size is 0, malloc allocates a zero-length item in the heap and returns a valid pointer to that item. Always check the return from malloc, even if the amount of memory requested is small.

Remarks

The malloc function allocates a memory block of at least size bytes. The block may be larger than size bytes because of the space that's required for alignment and maintenance information.

malloc sets errno to ENOMEM if a memory allocation fails or if the amount of memory requested exceeds _HEAP_MAXREQ. For information about this and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

The startup code uses malloc to allocate storage for the _environ, envp, and argv variables. The following functions and their wide-character counterparts also call malloc.

:::row::: :::column span=""::: calloc
_exec functions
fgetc
_fgetchar
fgets
fprintf
fputc
_fputchar
fputs
fread :::column-end::: :::column span=""::: fscanf
fseek
fsetpos
_fullpath
fwrite
getc
getchar
_getcwd
_getdcwd
gets :::column-end::: :::column span=""::: _getw
_popen
printf
putc
putchar
_putenv
puts
_putw
scanf :::column-end::: :::column span=""::: _searchenv
setvbuf
_spawn functions
_strdup
system
_tempnam
ungetc
vfprintf
vprintf :::column-end::: :::row-end:::

The C++ _set_new_mode function sets the new handler mode for malloc. The new handler mode indicates whether, on failure, malloc is to call the new handler routine as set by _set_new_handler. By default, malloc doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when malloc fails to allocate memory, malloc calls the new handler routine in the same way that the new operator does when it fails for the same reason. To override the default, call _set_new_mode(1) early in your program, or link with NEWMODE.OBJ (see Link options).

When the application is linked with a debug version of the C run-time libraries, malloc resolves to _malloc_dbg. For more information about how the heap is managed during the debugging process, see CRT debug heap details.

malloc is marked __declspec(noalias) and __declspec(restrict). These attributes mean that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see noalias and restrict.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Requirements

Routine	Required header
malloc	<stdlib.h> and <malloc.h>

For more compatibility information, see Compatibility.

Libraries

All versions of the C run-time libraries.

Example

// crt_malloc.c
// This program allocates memory with
// malloc, then frees the memory with free.

#include <stdlib.h>   // For _MAX_PATH definition
#include <stdio.h>
#include <malloc.h>

int main( void )
{
   char *string;

   // Allocate space for a path name
   string = malloc( _MAX_PATH );

   // In a C++ file, explicitly cast malloc's return.  For example,
   // string = (char *)malloc( _MAX_PATH );

   if( string == NULL )
      printf( "Insufficient memory available\n" );
   else
   {
      printf( "Memory space allocated for path name\n" );
      free( string );
      printf( "Memory freed\n" );
   }
}

Memory space allocated for path name
Memory freed

See also

Memory allocation
calloc
free
realloc
_aligned_malloc