# 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\(\)](UTILS.md#gace6ee45c30e71865e6eb635200379db9). **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\(\)](MEM.md#ga7ac38fce3243a7dcf448301ee9ffd392) | [calloc\(\)](MEM.md#ga62b7798461bd461da64c5f9d35feddf7) | [realloc\(\)](MEM.md#ga1a6b5e8d2f1c37e5b43e4345586075be) ## 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](MEM.md#ga8523dcf952f6ff059a3bed717e4f1296) 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](MEM.md#ga8523dcf952f6ff059a3bed717e4f1296) 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](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](IPC.md#gace43f23fcb66ddaad964bb8ea8de6e9c) is specified in **shmflg** or if **key** has the value [IPC\_PRIVATE](IPC.md#gae2b9b856a4a657c250b0b2e1cc0835d9), this function creates a shared memory segment with the size equal to the value of **size** rounded up to a multiple of [PAGE\_SIZE](UTILS.md#ga7d467c1d283fdfa1f2081ba1e0d01b6e). **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).