MEM

Overview

Provides structures and functions for performing memory operations, including memory mapping, remapping, allocation, and release.

Since:

1.0

Version:

1.0

Summary

Files

File Name	Description
malloc.h	Declares APIs for allocating and releasing memory.
mman.h	Declares structures and functions for performing memory operations, including memory mapping, remapping, unmapping, and attribute setting.
shm.h	Declares APIs for creating, mapping, deleting, and controlling shared memory.

Data Structures

Data Structure Name	Description
shmid_ds	Stores information about a shared memory segment.
shminfo	Describes limitations and attributes of system-level shared memory.
shm_info	Describes system resource information about the shared memory.

Macros

Macro Name and Value	Description
MAP_FAILED ((void *) -1)	Indicates the return value of functions such as mmap() when the operation fails.
MAP_SHARED 0x01	Indicates the mapping attribute that the updates to the mapping are visible to other processes mapping the same file and are carried through to the underlying file. This macro is used as an input parameter passed to functions such as mmap().
MAP_PRIVATE 0x02	Indicates the mapping attribute that the updates to the mapping are not visible to other mapping processes and are not carried through to the underlying file. This macro is used as an input parameter passed to functions such as mmap().
MAP_FIXED 0x10	Indicates the mapping attribute that specifies the mapping as fixed mapping. This macro is used as an input parameter passed to functions such as mmap().
MAP_ANON 0x20	Indicates the mapping attribute that specifies the mapping as anonymous mapping without a specified file or device. This macro is used as an input parameter passed to functions such as mmap().
MAP_ANONYMOUS MAP_ANON	Indicates the mapping attribute that specifies the mapping as anonymous mapping without a specified file or device. This macro is the synonym for MAP_ANON and is used as an input parameter passed to functions such as mmap().
PROT_NONE 0	Indicates that no permission is granted to the current process for accessing the mapping area. This macro is used as an input parameter passed to functions such as mmap().
PROT_READ 1	Indicates that the current process is granted the read permission on the mapping area. This macro is used as an input parameter passed to functions such as mmap().
PROT_WRITE 2	Indicates that the current process is granted the write permission on the mapping area. This macro is used as an input parameter passed to functions such as mmap().
PROT_EXEC 4	Indicates that the current process is granted the execute permission on the mapping area. This macro is used as an input parameter passed to functions such as mmap().
MREMAP_MAYMOVE 1	Indicates the remapping attribute that allows the mapping to be relocated to a new address. This macro is used as an input parameter passed to functions such as mremap().
MREMAP_FIXED 2	Indicates the remapping attribute that specifies the mapping as fixed mapping. This macro is used as an input parameter passed to functions such as mremap().
SHMLBA 4096	Aligns the shared memory address.
SHM_R 0400	Indicates that the shared memory segment is readable. This macro is used for setting the shmflg parameter passed to functions such as shmget().
SHM_W 0200	Indicates that the shared memory segment is writable. This macro is used for setting the shmflg parameter passed to functions such as shmget().
SHM_RDONLY 010000	Indicates that the attached shared memory segment is read-only. This macro is used for setting the shmflg parameter passed to functions such as shmat().
SHM_RND 020000	Indicates that the shared memory address can be rounded to a value meeting the requirement (SHMLBA). This macro is used for setting the shmflg parameter passed to functions such as shmat().
SHM_REMAP 040000	Indicates that the memory segment can be remapped. This macro is used for setting the shmflg parameter passed to functions such as shmat().
SHM_EXEC 0100000	Indicates that the attached shared memory segment is executable. This macro is used for setting the shmflg parameter passed to functions such as shmat().
SHM_LOCK 11	Locks the shared memory segment in memory so that it cannot be swapped to the swap partition. This macro is used for setting the shmflg parameter passed to functions such as shmget().
SHM_UNLOCK 12	Unlocks the shared memory segment. This macro is used for setting the shmflg parameter passed to functions such as shmget().
SHM_STAT (13 \| (IPC_STAT & 0x100))	Obtains a shmid_ds data structure. This macro is used for setting the cmd parameter passed to shmctl().
SHM_INFO 14	Obtains a shm_info data structure that includes system resource information about this shared memory segment. This macro is used for setting the cmd parameter passed to shmctl().
SHM_STAT_ANY (15 \| (IPC_STAT & 0x100))	Obtains a shmid_ds data structure without permission check. This macro is used for setting the cmd parameter passed to shmctl().

Functions

Function Name	Description
malloc (size_t size)	void Dynamically allocates a block of uninitialized memory with the specified size.
calloc (size_t nmemb, size_t size)	void Dynamically allocates multiple blocks of memory with the specified size.
realloc (void ptr, size_t size)	void Changes the size of a previously allocated memory block pointed to by ptr to the specified size.
free (void ptr)	void Frees the memory space pointed to by ptr.
memalign (size_t alignment, size_t size)	void Allocates a block of memory with the specified size based on the given alignment mode.
malloc_usable_size (void ptr)	size_t Obtains the size of the memory block pointed to by ptr.
mmap (void addr, size_t length, int prot, int flags, int fd, off_t offset)	void Creates a mapping between the virtual address space of the calling process and a file or device.
munmap (void addr, size_t length)	int Removes all mappings for the specified virtual address space.
mprotect (void addr, size_t len, int prot)	int Sets protection attributes for the memory pages contained in the memory region starting from addr with the specified length.
mremap (void old_address, size_t old_size, size_t new_size, int flags,…)	void Remaps a virtual memory region.
shmat (int shmid, const void shmaddr, int shmflg)	void Attaches the shared memory segment identified by shmid* to the address space of the current process.*
shmctl (int shmid, int cmd, struct shmid_ds buf)	int Performs a control operation specified by the cmd parameter on the shared memory segment identified by shmid.
shmdt (const void *shmaddr)	int Detaches the shared memory segment attached to the address pointed to by shmaddr from the address space of the calling process.
shmget (key_t key, size_t size, int shmflg)	int Obtains or creates a shared memory segment with the specified size based on the ID specified by key.

Details

Function Documentation

calloc()

void* calloc (size_t nmemb, size_t size )

Description:

Dynamically allocates multiple blocks of memory with the specified size.

Parameters:

Name	Description
nmemb	Indicates the number of memory blocks to allocate.
size	Indicates the size of the memory block to allocate, in bytes.

Returns:

Returns the pointer to the allocated memory block if the operation is successful; returns NULL and sets errno to a value in the following table if the operation fails or nmemb or size is set to 0.

errno	Description
ENOMEM	Insufficient memory.

free()

void free (void * ptr)

Description:

Frees the memory space pointed to by ptr.

Parameters:

Name	Description
ptr	Indicates the pointer to a memory block previously allocated with malloc, calloc or realloc.

malloc()

void* malloc (size_t size)

Description:

Dynamically allocates a block of uninitialized memory with the specified size.

The allocated memory can be initialized by calling memset().

Parameters:

Name	Description
size	Indicates the size of the memory block to allocate, in bytes.

Returns:

Returns the pointer to the allocated memory block if the operation is successful; returns NULL and sets errno to a value in the following table if the operation fails or size is set to 0.

errno	Description
ENOMEM	Insufficient memory.

malloc_usable_size()

size_t malloc_usable_size (void * ptr)

Description:

Obtains the size of the memory block pointed to by ptr.

Parameters:

Name	Description
ptr	Indicates the pointer to a block of memory previously allocated by functions such as malloc().

Returns:

Returns the number of usable bytes in the block of allocated memory pointed to by ptr; returns 0 if ptr is NULL.

See also:

malloc() | calloc() | realloc()

memalign()

void* memalign (size_t alignment, size_t size )

Description:

Allocates a block of memory with the specified size based on the given alignment mode.

The value of alignment must be a power of two.

Parameters:

Name	Description
alignment	Indicates the alignment size of the allocated memory.
size	Indicates the size of the memory block to allocate, in bytes.

Returns:

Returns the pointer to the allocated memory block if the operation is successful; returns NULL and sets errno to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid alignment value (not a power of two).
ENOMEM	Insufficient memory.

mmap()

void* mmap (void * addr, size_t length, int prot, int flags, int fd, off_t offset )

Description:

Creates a mapping between the virtual address space of the calling process and a file or device.

The start address for the mapping is specified by addr, and the length to map is specified by length. The contents of the mapping are initialized starting at offset with the specified length in the file referred to by the file descriptor fd.

Parameters:

Name	Description
addr	Indicates the pointer to the start address of the mapping. If this parameter is NULL, the kernel determines the address to start.
length	Indicates the length of the mapping, in bytes.
prot	Indicates the permission to be granted on the mapping area. The permission to grant must not conflict with the open mode of the file. The value of this parameter is the bitwise OR combination of one or more of the following constants:
flags	Specifies whether updates are visible to other processes mapping the same segment, and whether updates are carried through to the underlying file. The following table describes available values.
fd	Indicates the file or device to map.
offset	Indicates the offset into the file where the mapping will start.

prot	Description
PROT_EXEC	Executable
PROT_READ	Readable
PROT_WRITE	Writable

Attention:

If the file mapping is successful, fd cannot be closed before the mapping is deleted. (This rule does not conform to the Portable Operating System Interface (POSIX) standard. You should pay special attention to this rule.)

Returns:

Returns the pointer to the address where the mapping is placed if the operation is successful; returns MAP_FAILED and sets errno to a value in the following table if the operation fails.

errno	Description
EACCES	The file descriptor specified by fd refers to a non-regular file. The file descriptor specified by fd is invalid. MAP_SHARED and PROT_WRITE are specified, but the file identified by fd is not opened in O_RDWR mode. PROT_WRITE is specified, but the file is append-only.
EBADF	The file descriptor specified by fd is invalid, and MAP_ANONYMOUS is not specified in flags.
EINVAL	The length and offset are too large, addr is not page-aligned, or the length is 0. Neither MAP_SHARED nor MAP_ANONYMOUS is specified in flags, or both are specified.
EAGAIN	The file identified by fd has been locked.
ENFILE	The total number of open files exceeds the system limit.
ENODEV	The file identified by fd does not support memory mapping.
ENOMEM	Insufficient memory.
EPERM	PROT_EXEC is specified in prot, but the mapped area belongs to a file on a file system that was mounted non-executable, or the file seal does not allow this operation.

mprotect()

int mprotect (void * addr, size_t len, int prot )

Description:

Sets protection attributes for the memory pages contained in the memory region starting from addr with the specified length.

The address specified by addr must be page-aligned. If the process attempts to access memory in a manner that violates the protection attributes, an access exception will occur, and the process will be terminated.

Parameters:

Name	Description
addr	Indicates the pointer to the start address of the memory region to modify, which must be a multiple of the page size.
len	Indicates the length of the memory region to modify, in bytes.
prot	Indicates the permission of the memory region to modify, which can be a bitwise OR combination of one or more of the constants listed in prot.

prot	Description
PROT_EXEC	Executable
PROT_READ	Readable
PROT_WRITE	Writable
PROT_NONE	Not accessible

Returns:

Returns 0 if the operation is successful; returns -1 and sets errno to a value in the following table if the operation fails.

errno	Description
EACCES	The memory region cannot be granted the specified permission. This error can occur, for example, when you use mmap to map a file with prot set to PROT_READ and then use this function to set prot to PROT_WRITE.
EINVAL	addr is an invalid pointer or it points to an address that is not a multiple of the page size.
ENOMEM	Internal kernel structures cannot be allocated due to insufficient memory, or addresses in the specified range are invalid for the address space of the process. The total number of mappings with different attributes exceeds the maximum number allowed by the system if the protection attribute of the memory region is changed.

mremap()

void* mremap (void * old_address, size_t old_size, size_t new_size, int flags,  ... )

Description:

Remaps a virtual memory region.

This function expands or shrinks an existing memory mapping, and may also move the mapping at the same time depending on the settings of flags and the available virtual address space.

Parameters:

Name	Description
old_address	Indicates the old address of the virtual memory region to expand or shrink.
old_size	Indicates the old size of the virtual memory region.
new_size	Indicates the requested size of the virtual memory region after the expansion or shrinking.
flags	Specifies whether the existing memory can be mapped to a new or specified address.
new_address	Indicates the new address of the virtual memory region. This parameter is optional and is used when MREMAP_FIXED is specified in flags.

flags	Description
MREMAP_MAYMOVE	By default, if no enough space is available to expand a mapping at its current location, the operation fails. If this flag is specified, the kernel is allowed to relocate the mapping to a new virtual address when necessary.
MREMAP_FIXED	If this flag is specified, the new_address parameter is enabled in this function and the memory is mapped to a new address. This flag must be used together with MREMAP_MAYMOVE.

Returns:

Returns the pointer to the new mapping address if the operation is successful; returns MAP_FAILED and sets errno to a value in the following table if the operation fails.

errno	Description
EAGAIN	The memory segment to expand is locked.
EFAULT	Some memory addresses in the range from old_address to old_address+old_size are invalid for this process.
EINVAL	old_address is not a multiple of the page size, or a value other than MREMAP_MAYMOVE and MREMAP_FIXED is specified in flags. new_size is 0, new_size or new_address is invalid, or MREMAP_FIXED is specified in flags without also specifying MREMAP_MAYMOVE. old_size is 0 but old_address does not point to a shared memory mapping; old_size is 0 but MREMAP_MAYMOVE is not specified in flags; or the new memory address range specified by new_address and new_size overlaps the old memory address range specified by old_address and old_size.
ENOMEM	Insufficient memory.

munmap()

int munmap (void * addr, size_t length )

Description:

Removes all mappings for the specified virtual address space.

After all mappings are removed, any references to addresses within the specified range will generate invalid memory references. The memory region will also be automatically unmapped when the process is terminated. Closing the file descriptor does not remove mappings from the region.

Parameters:

Name	Description
addr	Indicates the pointer to the start address of the memory region to unmap, which is the return value of mmap().
length	Indicates the length of the address range to unmap, which should be the length specified in mmap().

Returns:

Returns 0 if the operation is successful; returns -1 and sets errno to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input parameters.

realloc()

void* realloc (void * ptr, size_t size )

Description:

Changes the size of a previously allocated memory block pointed to by ptr to the specified size.

The contents of the memory block will be retained from the beginning of the memory pointed to by ptr to the lesser of the old and new sizes. If the new size is larger than the old size, the added memory portion will not be initialized. The behavior of this function varies depending on the input parameters:

Parameters:

Name	Description
ptr	Indicates the pointer to a memory block previously allocated with malloc, calloc or realloc.
size	Indicates the new size for the memory block, in bytes.

Returns:

Returns the pointer to the new memory block if the operation is successful; returns NULL and sets errno to a value in the following table if the operation fails.

errno	Description
ENOMEM	Insufficient memory.

shmat()

void* shmat (int shmid, const void * shmaddr, int shmflg )

Description:

Attaches the shared memory segment identified by shmid to the address space of the current process.

Parameters:

Name	Description
shmid	Identifies the shared memory segment to attach, which is obtained by shmget().
shmaddr	Indicates the space address of the current process to attach. If this parameter is NULL, the system chooses an unused address to attach.
shmflg	Indicates the attribute of the shared memory segment to attach, which is the bitwise OR combination of one or more of the following flags:

shmflg	Description
SHM_RND	Round the attached address. If shmaddr is not NULL and SHM_RND is specified in shmflg, the address is rounded down to the nearest multiple of SHMLBA.
SHM_EXEC	Allow the contents of the attached shared memory segment to be executable.
SHM_RDONLY	Set the contents of the attached shared memory segment to be read-only.
SHM_REMAP	Replace any existing mapping in the address range starting at shmaddr and continuing for the size of the segment during the current memory mapping. When SHM_REMAP is not specified, an EINVAL error will be returned if a mapping exists in the address range.

Returns:

Returns the pointer to the address of the attached shared memory segment if the operation is successful; returns (void *)-1 and sets errno to a value in the following table if the operation fails.

errno	Description
EACCES	The current process does not have the required permission on the requested mapping type.
EIDRM	The shared memory segment specified by shmid has been removed.
EINVAL	The value of shmid is invalid. shmaddr is not aligned (not page-aligned and SHM_RND is not specified) or its value is invalid. SHM_REMAP is specified, but shmaddr is NULL.
ENOMEM	No page tables can be allocated.

shmctl()

int shmctl (int shmid, int cmd, struct [shmid_ds]($api-api-SmartVision-Devices-shmid_ds.md) * buf )

Description:

Performs a control operation specified by the cmd parameter on the shared memory segment identified by shmid.

Parameters:

Name	Description
shmid	Identifies the shared memory segment to attach, which is obtained by shmget().
cmd	Indicates the control operation to perform. The following table describes available values.
buf	Indicates the pointer to the buffer for storing the information to set or obtain.

cmd	Description
IPC_STAT	Copy information from the kernel data structure associated with the shared memory segment identified by shmid into the shmid_ds structure pointed to by buf.
SHM_STAT	Return a shmid_ds data structure. When SHM_STAT is specified, shmid does not identify a shared memory segment. Instead, it indicates the index to the kernel’s internal array that maintains information about all shared memory segments.
IPC_SET	Write the values of some fields in the shmid_ds data structure pointed to by buf to the kernel data structure associated with the specified shared memory segment, updating also its shm_ctimemember. The following fields can be modified: shm_perm.uid, shm_perm.gid, and shm_perm.mode.
IPC_RMID	Mark the shared memory segment to be destroyed.
IPC_INFO	Return information about system-wide shared memory limits and parameters in the structure pointed to by buf. The returned structure is of the shminfo type, and a cast is required.
SHM_INFO	Return a shm_info structure that contains information about system resources consumed by the specified shared memory segment.

Returns:

Returns 0 if the operation is successful; returns -1 and sets errno to a value in the following table if the operation fails.

errno	Description
EACCES	IPC_STAT or SHM_STAT is specified in cmb, but the mode field in shm_perm does not allow any read operation on the shared memory segment identified by shmid.
EFAULT	SHM_STAT or IPC_STAT is specified in cmd, but the address pointed to by buf is not accessible.
EIDRM	shmid points to a removed shared memory segment.
EINVAL	The value of shmid or cmd is invalid. When SHM_STAT is specified in cmd, the value is considered invalid if the index specified by shmid refers to an unused array slot.
ENOMEM	No page tables can be allocated.
EPERM	IPC_SET or IPC_RMID is attempted, but the effective user ID of the calling process is not that of the creator or the owner, and the process is not privileged.

shmdt()

int shmdt (const void * shmaddr)

Description:

Detaches the shared memory segment attached to the address pointed to by shmaddr from the address space of the calling process.

Parameters:

Name	Description
shmaddr	Indicates the pointer to the address of the shared memory segment to detach. The value of this parameter should be the pointer previously returned by shmat().

Returns:

Returns 0 if the operation is successful; returns -1 and sets errno to a value in the following table if the operation fails.

errno	Description
EINVAL	No shared memory segment is attached to shmaddr, or shmaddr is not aligned.

shmget()

int shmget (key_t key, size_t size, int shmflg )

Description:

Obtains or creates a shared memory segment with the specified size based on the ID specified by key.

If the shared memory segment associated with key does not exist and IPC_CREAT is specified in shmflg or if key has the value IPC_PRIVATE, this function creates a shared memory segment with the size equal to the value of size rounded up to a multiple of PAGE_SIZE.

Parameters:

Name	Description
key	Indicates the key of the shared memory segment.
size	Indicates the size of the shared memory segment to create. The actual size is rounded up to a multiple of PAGE_SIZE.
shmflg	Indicates the attribute of the shared memory segment, which is the bitwise OR combination of one or more of the following flags:

shmflg	Description
IPC_CREAT	Create a new shared memory segment. If this flag is not specified, this function will find the segment with the specified key and check to see whether the user has permission to access the segment.
IPC_EXCL	Used together with IPC_CREAT to ensure that this function is called to create a shared memory segment. The calling fails if the segment already exists.

Returns:

Returns the ID of the shared memory segment if the operation is successful; returns -1 and sets errno to a value in the following table if the operation fails.

errno	Description
EACCES	The current process does not have the permission to obtain the specified shared memory segment.
EEXIST	IPC_EXCL and IPC_CREAT are specified, but the shared memory segment associated with key already exists.
EINVAL	The size specified for the shared memory segment to create is less than the value of shmmin in shminfo or greater than the value of shmmax. The shared memory segment associated with key already exists, but the value of size is greater than the size of the segment.
ENOENT	No segment exists for the given key, and IPC_CREAT is not specified.
ENOMEM	Insufficient memory.
ENOSPC	Allocating a segment of the requested size would cause the system to exceed the system-wide limit on shared memory (shmall in shminfo).