{
    "mode": "man",
    "parameter": "PKEYS",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/PKEYS/7/json",
    "generated": "2026-06-14T12:36:34Z",
    "sections": {
        "NAME": {
            "content": "pkeys - overview of Memory Protection Keys\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Memory  Protection  Keys  (pkeys) are an extension to existing page-based memory permissions.\nNormal page permissions using page tables require expensive system calls  and  TLB  invalida‐\ntions  when  changing  permissions.   Memory Protection Keys provide a mechanism for changing\nprotections without requiring modification of the page tables on every permission change.\n\nTo use pkeys, software must first \"tag\" a page in the page tables with a  pkey.   After  this\ntag is in place, an application only has to change the contents of a register in order to re‐\nmove write access, or all access to a tagged page.\n\nProtection keys work in conjunction with the existing PROTREAD/ PROTWRITE/  PROTEXEC  per‐\nmissions  passed  to  system calls such as mprotect(2) and mmap(2), but always act to further\nrestrict these traditional permission mechanisms.\n\nIf a process performs an access that violates pkey restrictions, it receives a  SIGSEGV  sig‐\nnal.  See sigaction(2) for details of the information available with that signal.\n\nTo  use the pkeys feature, the processor must support it, and the kernel must contain support\nfor the feature on a given processor.  As of early 2016 only future Intel x86 processors  are\nsupported, and this hardware supports 16 protection keys in each process.  However, pkey 0 is\nused as the default key, so a maximum of 15 are available for actual  application  use.   The\ndefault  key  is  assigned  to any memory region for which a pkey has not been explicitly as‐\nsigned via pkeymprotect(2).\n\nProtection keys have the potential to add a layer of security  and  reliability  to  applica‐\ntions.   But they have not been primarily designed as a security feature.  For instance, WRP‐\nKRU is a completely unprivileged instruction, so pkeys are useless in any case  that  an  at‐\ntacker controls the PKRU register or can execute arbitrary instructions.\n\nApplications  should  be very careful to ensure that they do not \"leak\" protection keys.  For\ninstance, before calling pkeyfree(2), the application should be sure that no memory has that\npkey  assigned.   If the application left the freed pkey assigned, a future user of that pkey\nmight inadvertently change the permissions of an unrelated data structure, which could impact\nsecurity  or stability.  The kernel currently allows in-use pkeys to have pkeyfree(2) called\non them because it would have processor or memory performance implications to perform the ad‐\nditional  checks needed to disallow it.  Implementation of the necessary checks is left up to\napplications.  Applications may implement these checks  by  searching  the  /proc/[pid]/smaps\nfile for memory regions with the pkey assigned.  Further details can be found in proc(5).\n\nAny  application  wanting  to  use protection keys needs to be able to function without them.\nThey might be unavailable because the hardware that the application runs on does not  support\nthem,  the kernel code does not contain support, the kernel support has been disabled, or be‐\ncause the keys have all been allocated, perhaps by a library the application is using.  It is\nrecommended that applications wanting to use protection keys should simply call pkeyalloc(2)\nand test whether the call succeeds, instead of attempting to detect support for  the  feature\nin any other way.\n\nAlthough  unnecessary,  hardware support for protection keys may be enumerated with the cpuid\ninstruction.  Details of how to do this can be found in the Intel Software Developers Manual.\nThe  kernel  performs this enumeration and exposes the information in /proc/cpuinfo under the\n\"flags\" field.  The string \"pku\" in this field indicates hardware support for protection keys\nand  the  string  \"ospke\"  indicates that the kernel contains and has enabled protection keys\nsupport.\n\nApplications using threads and protection keys should be especially careful.  Threads inherit\nthe  protection  key rights of the parent at the time of the clone(2), system call.  Applica‐\ntions should either ensure that their own permissions are appropriate for  child  threads  at\nthe  time  when clone(2) is called, or ensure that each child thread can perform its own ini‐\ntialization of protection key rights.\n",
            "subsections": [
                {
                    "name": "Signal Handler Behavior",
                    "content": "Each time a signal handler is invoked (including nested signals), the thread  is  temporarily\ngiven  a  new,  default set of protection key rights that override the rights from the inter‐\nrupted context.  This means that applications must re-establish their desired protection  key\nrights  upon  entering  a signal handler if the desired rights differ from the defaults.  The\nrights of any interrupted context are restored when the signal handler returns.\n\nThis signal behavior is unusual and is due to the fact that  the  x86  PKRU  register  (which\nstores protection key access rights) is managed with the same hardware mechanism (XSAVE) that\nmanages floating-point registers.  The signal behavior is the same as that of  floating-point\nregisters.\n"
                },
                {
                    "name": "Protection Keys system calls",
                    "content": "The  Linux  kernel  implements  the  following  pkey-related  system calls: pkeymprotect(2),\npkeyalloc(2), and pkeyfree(2).\n\nThe Linux pkey system calls are available only if the kernel was configured  and  built  with\nthe CONFIGX86INTELMEMORYPROTECTIONKEYS option.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "The program below allocates a page of memory with read and write permissions.  It then writes\nsome data to the memory and successfully reads it back.  After that, it attempts to  allocate\na  protection  key and disallows access to the page by using the WRPKRU instruction.  It then\ntries to access the page, which we now expect to cause a fatal signal to the application.\n\n$ ./a.out\nbuffer contains: 73\nabout to read buffer again...\nSegmentation fault (core dumped)\n",
            "subsections": [
                {
                    "name": "Program source",
                    "content": "#define GNUSOURCE\n#include <unistd.h>\n#include <sys/syscall.h>\n#include <stdio.h>\n#include <sys/mman.h>\n\nstatic inline void\nwrpkru(unsigned int pkru)\n{\nunsigned int eax = pkru;\nunsigned int ecx = 0;\nunsigned int edx = 0;\n\nasm volatile(\".byte 0x0f,0x01,0xef\\n\\t\"\n: : \"a\" (eax), \"c\" (ecx), \"d\" (edx));\n}\n\nint\npkeyset(int pkey, unsigned long rights, unsigned long flags)\n{\nunsigned int pkru = (rights << (2 * pkey));\nreturn wrpkru(pkru);\n}\n\nint\npkeymprotect(void *ptr, sizet size, unsigned long origprot,\nunsigned long pkey)\n{\nreturn syscall(SYSpkeymprotect, ptr, size, origprot, pkey);\n}\n\nint\npkeyalloc(void)\n{\nreturn syscall(SYSpkeyalloc, 0, 0);\n}\n\nint\npkeyfree(unsigned long pkey)\n{\nreturn syscall(SYSpkeyfree, pkey);\n}\n\n#define errExit(msg)    do { perror(msg); exit(EXITFAILURE); \\\n} while (0)\n\nint\nmain(void)\n{\nint status;\nint pkey;\nint *buffer;\n\n/*\n*Allocate one page of memory\n*/\nbuffer = mmap(NULL, getpagesize(), PROTREAD | PROTWRITE,\nMAPANONYMOUS | MAPPRIVATE, -1, 0);\nif (buffer == MAPFAILED)\nerrExit(\"mmap\");\n\n/*\n* Put some random data into the page (still OK to touch)\n*/\n*buffer = LINE;\nprintf(\"buffer contains: %d\\n\", *buffer);\n\n/*\n* Allocate a protection key:\n*/\npkey = pkeyalloc();\nif (pkey == -1)\nerrExit(\"pkeyalloc\");\n\n/*\n* Disable access to any memory with \"pkey\" set,\n* even though there is none right now\n*/\nstatus = pkeyset(pkey, PKEYDISABLEACCESS, 0);\nif (status)\nerrExit(\"pkeyset\");\n\n/*\n* Set the protection key on \"buffer\".\n* Note that it is still read/write as far as mprotect() is\n* concerned and the previous pkeyset() overrides it.\n*/\nstatus = pkeymprotect(buffer, getpagesize(),\nPROTREAD | PROTWRITE, pkey);\nif (status == -1)\nerrExit(\"pkeymprotect\");\n\nprintf(\"about to read buffer again...\\n\");\n\n/*\n* This will crash, because we have disallowed access\n*/\nprintf(\"buffer contains: %d\\n\", *buffer);\n\nstatus = pkeyfree(pkey);\nif (status == -1)\nerrExit(\"pkeyfree\");\n\nexit(EXITSUCCESS);\n}\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "pkeyalloc(2), pkeyfree(2), pkeymprotect(2), sigaction(2)\n",
            "subsections": []
        },
        "COLOPHON": {
            "content": "This page is part of release 5.10 of the Linux  man-pages  project.   A  description  of  the\nproject,  information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux                                        2020-06-09                                     PKEYS(7)",
            "subsections": []
        }
    },
    "summary": "pkeys - overview of Memory Protection Keys",
    "flags": [],
    "examples": [
        "The program below allocates a page of memory with read and write permissions.  It then writes",
        "some data to the memory and successfully reads it back.  After that, it attempts to  allocate",
        "a  protection  key and disallows access to the page by using the WRPKRU instruction.  It then",
        "tries to access the page, which we now expect to cause a fatal signal to the application.",
        "$ ./a.out",
        "buffer contains: 73",
        "about to read buffer again...",
        "Segmentation fault (core dumped)",
        "#define GNUSOURCE",
        "#include <unistd.h>",
        "#include <sys/syscall.h>",
        "#include <stdio.h>",
        "#include <sys/mman.h>",
        "static inline void",
        "wrpkru(unsigned int pkru)",
        "unsigned int eax = pkru;",
        "unsigned int ecx = 0;",
        "unsigned int edx = 0;",
        "asm volatile(\".byte 0x0f,0x01,0xef\\n\\t\"",
        ": : \"a\" (eax), \"c\" (ecx), \"d\" (edx));",
        "int",
        "pkeyset(int pkey, unsigned long rights, unsigned long flags)",
        "unsigned int pkru = (rights << (2 * pkey));",
        "return wrpkru(pkru);",
        "int",
        "pkeymprotect(void *ptr, sizet size, unsigned long origprot,",
        "unsigned long pkey)",
        "return syscall(SYSpkeymprotect, ptr, size, origprot, pkey);",
        "int",
        "pkeyalloc(void)",
        "return syscall(SYSpkeyalloc, 0, 0);",
        "int",
        "pkeyfree(unsigned long pkey)",
        "return syscall(SYSpkeyfree, pkey);",
        "#define errExit(msg)    do { perror(msg); exit(EXITFAILURE); \\",
        "} while (0)",
        "int",
        "main(void)",
        "int status;",
        "int pkey;",
        "int *buffer;",
        "/*",
        "*Allocate one page of memory",
        "*/",
        "buffer = mmap(NULL, getpagesize(), PROTREAD | PROTWRITE,",
        "MAPANONYMOUS | MAPPRIVATE, -1, 0);",
        "if (buffer == MAPFAILED)",
        "errExit(\"mmap\");",
        "/*",
        "* Put some random data into the page (still OK to touch)",
        "*/",
        "*buffer = LINE;",
        "printf(\"buffer contains: %d\\n\", *buffer);",
        "/*",
        "* Allocate a protection key:",
        "*/",
        "pkey = pkeyalloc();",
        "if (pkey == -1)",
        "errExit(\"pkeyalloc\");",
        "/*",
        "* Disable access to any memory with \"pkey\" set,",
        "* even though there is none right now",
        "*/",
        "status = pkeyset(pkey, PKEYDISABLEACCESS, 0);",
        "if (status)",
        "errExit(\"pkeyset\");",
        "/*",
        "* Set the protection key on \"buffer\".",
        "* Note that it is still read/write as far as mprotect() is",
        "* concerned and the previous pkeyset() overrides it.",
        "*/",
        "status = pkeymprotect(buffer, getpagesize(),",
        "PROTREAD | PROTWRITE, pkey);",
        "if (status == -1)",
        "errExit(\"pkeymprotect\");",
        "printf(\"about to read buffer again...\\n\");",
        "/*",
        "* This will crash, because we have disallowed access",
        "*/",
        "printf(\"buffer contains: %d\\n\", *buffer);",
        "status = pkeyfree(pkey);",
        "if (status == -1)",
        "errExit(\"pkeyfree\");",
        "exit(EXITSUCCESS);"
    ],
    "see_also": [
        {
            "name": "pkeyalloc",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/pkeyalloc/2/json"
        },
        {
            "name": "pkeyfree",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/pkeyfree/2/json"
        },
        {
            "name": "pkeymprotect",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/pkeymprotect/2/json"
        },
        {
            "name": "sigaction",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/sigaction/2/json"
        }
    ]
}