Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::malloc(3)		      C++ Standard Libary		std::malloc(3)

NAME
       std::malloc - std::malloc

Synopsis
	  Defined in header <cstdlib>
	  void*	malloc(	std::size_t size );

	  Allocates size bytes of uninitialized	storage.

	  If allocation	succeeds, returns a pointer to the lowest (first) byte
       in the
	  allocated  memory block that is suitably aligned for any scalar type
       (at least as
	  strictly as std::max_align_t).

	  If size is  zero,  the  behavior  is	implementation	defined	 (null
       pointer may be
	  returned,  or	 some non-null pointer may be returned that may	not be
       used to access
	  storage, but has to be passed	to std::free)

	  The following	functions are required to be thread-safe:

	    * The library versions of operator new and operator	delete
	    * User replacement versions	of global operator new and operator
	      delete
	    *	      std::calloc,	   std::malloc,		 std::realloc,
       (since C++11)
	      std::aligned_alloc
	      (since C++17), std::free

	  Calls	 to  these  functions that allocate or deallocate a particular
       unit
	  of storage occur in a	single total order, and	each such deallocation
	  call happens-before the next allocation (if any) in this order.

Parameters
	  size - number	of bytes to allocate

Return value
	  On success, returns the pointer to the beginning of newly  allocated
       memory. To avoid
	  a  memory  leak,  the	 returned  pointer  must  be  deallocated with
       std::free() or
	  std::realloc().

	  On failure, returns a	null pointer.

Notes
	  This function	does not call constructors or initialize memory	in any
       way. There are
	  no ready-to-use smart	pointers that could guarantee that the	match-
       ing deallocation
	  function is called. The preferred method of memory allocation	in C++
       is using
	  RAII-ready  functions	 std::make_unique, std::make_shared, container
       constructors,
	  etc, and, in low-level library code, new-expression.

	  For loading a	large file, file mapping  via  OS-specific  functions,
       e.g. mmap on POSIX
	  or  CreateFileMapping(A/W)  along  with MapViewOfFile	on Windows, is
       preferable to
	  allocating a buffer for file reading.

Example
       // Run this code

	#include <iostream>
	#include <cstdlib>
	#include <string>
	#include <memory>

	int main()
	{
	    constexpr std::size_t size = 4;
	    if (auto ptr = reinterpret_cast<std::string*>(
		    std::malloc(size * sizeof(std::string))))
	    {	try
		{   for	(std::size_t i = 0; i <	size; ++i)
			std::construct_at(ptr +	i, 5, 'a' + i);
		    for	(std::size_t i = 0; i <	size; ++i)
			std::cout << "ptr[" << i << "] == " << ptr[i] << '\n';
		    std::destroy_n(ptr,	size);
		}
		catch(...) {}
		std::free(ptr);
	    }
	}

Output:
	p[0] ==	aaaaa
	p[1] ==	bbbbb
	p[2] ==	ccccc
	p[3] ==	ddddd

See also
	  operator new		allocation functions
	  operator new[]	(function)
	  get_temporary_buffer	obtains	uninitialized storage
	  (deprecated in C++17)	(function template)
	  (removed in C++20)

http://cppreference.com		  2022.07.31			std::malloc(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::malloc&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help