| 1 |
.\" Copyright 2003, Andries E. Brouwer <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH alloc_hugepages 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
alloc_hugepages, free_hugepages \- allocate or free huge pages |
| 9 |
.SH SYNOPSIS |
| 10 |
.nf |
| 11 |
.BR "void *syscall(" "size_t size;" |
| 12 |
.BI " SYS_alloc_hugepages, int " key , |
| 13 |
.BI " void " addr [ size "], size_t " size , |
| 14 |
.BI " int " prot ", int " flag ); |
| 15 |
.\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, |
| 16 |
.\" unsigned long size, int prot, int flag); |
| 17 |
.BI "int syscall(SYS_free_hugepages, void *" addr ); |
| 18 |
.\" asmlinkage int sys_free_hugepages(unsigned long addr); |
| 19 |
.fi |
| 20 |
.P |
| 21 |
.IR Note : |
| 22 |
glibc provides no wrappers for these system calls, |
| 23 |
necessitating the use of |
| 24 |
.BR syscall (2). |
| 25 |
.SH DESCRIPTION |
| 26 |
The system calls |
| 27 |
.BR alloc_hugepages () |
| 28 |
and |
| 29 |
.BR free_hugepages () |
| 30 |
were introduced in Linux 2.5.36 and removed again in Linux 2.5.54. |
| 31 |
They existed only on i386 and ia64 (when built with |
| 32 |
.BR CONFIG_HUGETLB_PAGE ). |
| 33 |
In Linux 2.4.20, the syscall numbers exist, |
| 34 |
but the calls fail with the error |
| 35 |
.BR ENOSYS . |
| 36 |
.P |
| 37 |
On i386 the memory management hardware knows about ordinary pages (4\ KiB) |
| 38 |
and huge pages (2 or 4\ MiB). |
| 39 |
Similarly ia64 knows about huge pages of |
| 40 |
several sizes. |
| 41 |
These system calls serve to map huge pages into the |
| 42 |
process's memory or to free them again. |
| 43 |
Huge pages are locked into memory, and are not swapped. |
| 44 |
.P |
| 45 |
The |
| 46 |
.I key |
| 47 |
argument is an identifier. |
| 48 |
When zero the pages are private, and |
| 49 |
not inherited by children. |
| 50 |
When positive the pages are shared with other applications using the same |
| 51 |
.IR key , |
| 52 |
and inherited by child processes. |
| 53 |
.P |
| 54 |
The |
| 55 |
.I addr |
| 56 |
argument of |
| 57 |
.BR free_hugepages () |
| 58 |
tells which page is being freed: it was the return value of a |
| 59 |
call to |
| 60 |
.BR alloc_hugepages (). |
| 61 |
(The memory is first actually freed when all users have released it.) |
| 62 |
The |
| 63 |
.I addr |
| 64 |
argument of |
| 65 |
.BR alloc_hugepages () |
| 66 |
is a hint, that the kernel may or may not follow. |
| 67 |
Addresses must be properly aligned. |
| 68 |
.P |
| 69 |
The |
| 70 |
.I size |
| 71 |
argument is the size of the required segment. |
| 72 |
It must be a multiple of the huge page size. |
| 73 |
.P |
| 74 |
The |
| 75 |
.I prot |
| 76 |
argument specifies the memory protection of the segment. |
| 77 |
It is one of |
| 78 |
.BR PROT_READ , |
| 79 |
.BR PROT_WRITE , |
| 80 |
.BR PROT_EXEC . |
| 81 |
.P |
| 82 |
The |
| 83 |
.I flag |
| 84 |
argument is ignored, unless |
| 85 |
.I key |
| 86 |
is positive. |
| 87 |
In that case, if |
| 88 |
.I flag |
| 89 |
is |
| 90 |
.BR IPC_CREAT , |
| 91 |
then a new huge page segment is created when none |
| 92 |
with the given key existed. |
| 93 |
If this flag is not set, then |
| 94 |
.B ENOENT |
| 95 |
is returned when no segment with the given key exists. |
| 96 |
.SH RETURN VALUE |
| 97 |
On success, |
| 98 |
.BR alloc_hugepages () |
| 99 |
returns the allocated virtual address, and |
| 100 |
.BR free_hugepages () |
| 101 |
returns zero. |
| 102 |
On error, \-1 is returned, and |
| 103 |
.I errno |
| 104 |
is set to indicate the error. |
| 105 |
.SH ERRORS |
| 106 |
.TP |
| 107 |
.B ENOSYS |
| 108 |
The system call is not supported on this kernel. |
| 109 |
.SH FILES |
| 110 |
.TP |
| 111 |
.I /proc/sys/vm/nr_hugepages |
| 112 |
Number of configured hugetlb pages. |
| 113 |
This can be read and written. |
| 114 |
.TP |
| 115 |
.I /proc/meminfo |
| 116 |
Gives info on the number of configured hugetlb pages and on their size |
| 117 |
in the three variables HugePages_Total, HugePages_Free, Hugepagesize. |
| 118 |
.SH STANDARDS |
| 119 |
Linux on Intel processors. |
| 120 |
.SH HISTORY |
| 121 |
These system calls are gone; |
| 122 |
they existed only in Linux 2.5.36 through to Linux 2.5.54. |
| 123 |
.SH NOTES |
| 124 |
Now the hugetlbfs filesystem can be used instead. |
| 125 |
Memory backed by huge pages (if the CPU supports them) is obtained by |
| 126 |
using |
| 127 |
.BR mmap (2) |
| 128 |
to map files in this virtual filesystem. |
| 129 |
.P |
| 130 |
The maximal number of huge pages can be specified using the |
| 131 |
.B hugepages= |
| 132 |
boot parameter. |
| 133 |
.\".P |
| 134 |
.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") |
| 135 |
.\" and CONFIG_HUGETLBFS (under "Filesystems"). |
| 136 |
.\" mount \-t hugetlbfs hugetlbfs /huge |
| 137 |
.\" SHM_HUGETLB |