{ "mode": "info", "parameter": "time_namespaces", "section": "", "url": "https://www.chedong.com/phpMan.php/info/time_namespaces/json", "generated": "2026-08-04T19:55:23Z", "sections": { "NAME": { "content": "timenamespaces - overview of Linux time namespaces\n", "subsections": [] }, "DESCRIPTION": { "content": "Time namespaces virtualize the values of two system clocks:\n\no CLOCKMONOTONIC (and likewise CLOCKMONOTONICCOARSE and CLOCKMONO-\nTONICRAW), a nonsettable clock that represents monotonic time\nsince--as described by POSIX--\"some unspecified point in the\npast\".\n\no CLOCKBOOTTIME (and likewise CLOCKBOOTTIMEALARM), a nonsettable\nclock that is identical to CLOCKMONOTONIC, except that it also in-\ncludes any time that the system is suspended.\n\nThus, the processes in a time namespace share per-namespace values for\nthese clocks. This affects various APIs that measure against these\nclocks, including: clockgettime(2), clocknanosleep(2), nanosleep(2),\ntimersettime(2), timerfdsettime(2), and /proc/uptime.\n\nCurrently, the only way to create a time namespace is by calling un-\nshare(2) with the CLONENEWTIME flag. This call creates a new time\nnamespace but does not place the calling process in the new namespace.\nInstead, the calling process's subsequently created children are placed\nin the new namespace. This allows clock offsets (see below) for the\nnew namespace to be set before the first process is placed in the name-\nspace. The /proc/[pid]/ns/timeforchildren symbolic link shows the\ntime namespace in which the children of a process will be created. (A\nprocess can use a file descriptor opened on this symbolic link in a\ncall to setns(2) in order to move into the namespace.)\n\n/proc/PID/timensoffsets\nAssociated with each time namespace are offsets, expressed with respect\nto the initial time namespace, that define the values of the monotonic\nand boot-time clocks in that namespace. These offsets are exposed via\nthe file /proc/PID/timensoffsets. Within this file, the offsets are\nexpressed as lines consisting of three space-delimited fields:\n\n \n\nThe clock-id is a string that identifies the clock whose offsets are\nbeing shown. This field is either monotonic, for CLOCKMONOTONIC, or\nboottime, for CLOCKBOOTTIME. The remaining fields express the offset\n(seconds plus nanoseconds) for the clock in this time namespace. These\noffsets are expressed relative to the clock values in the initial time\nnamespace. The offset-secs value can be negative, subject to restric-\ntions noted below; offset-nanosecs is an unsigned value.\n\nIn the initial time namespace, the contents of the timensoffsets file\nare as follows:\n\n$ cat /proc/self/timensoffsets\nmonotonic 0 0\nboottime 0 0\n\nIn a new time namespace that has had no member processes, the clock\noffsets can be modified by writing newline-terminated records of the\nsame form to the timensoffsets file. The file can be written to mul-\ntiple times, but after the first process has been created in or has en-\ntered the namespace, write(2)s on this file fail with the error EACCES.\nIn order to write to the timensoffsets file, a process must have the\nCAPSYSTIME capability in the user namespace that owns the time name-\nspace.\n\nWrites to the timensoffsets file can fail with the following errors:\n\nEINVAL An offset-nanosecs value is greater than 999,999,999.\n\nEINVAL A clock-id value is not valid.\n\nEPERM The caller does not have the CAPSYSTIME capability.\n\nERANGE An offset-secs value is out of range. In particular;\n\no offset-secs can't be set to a value which would make the cur-\nrent time on the corresponding clock inside the namespace a\nnegative value; and\n\no offset-secs can't be set to a value such that the time on the\ncorresponding clock inside the namespace would exceed half of\nthe value of the kernel constant KTIMESECMAX (this limits\nthe clock value to a maximum of approximately 146 years).\n\nIn a new time namespace created by unshare(2), the contents of the\ntimensoffsets file are inherited from the time namespace of the creat-\ning process.\n", "subsections": [] }, "NOTES": { "content": "Use of time namespaces requires a kernel that is configured with the\nCONFIGTIMENS option.\n\nNote that time namespaces do not virtualize the CLOCKREALTIME clock.\nVirtualization of this clock was avoided for reasons of complexity and\noverhead within the kernel.\n\nFor compatibility with the initial implementation, when writing a\nclock-id to the /proc/[pid]/timensoffsets file, the numerical values\nof the IDs can be written instead of the symbolic names show above;\ni.e., 1 instead of monotonic, and 7 instead of boottime. For redabil-\nity, the use of the symbolic names over the numbers is preferred.\n\nThe motivation for adding time namespaces was to allow the monotonic\nand boot-time clocks to maintain consistent values during container mi-\ngration and checkpoint/restore.\n", "subsections": [] }, "EXAMPLES": { "content": "The following shell session demonstrates the operation of time name-\nspaces. We begin by displaying the inode number of the time namespace\nof a shell in the initial time namespace:\n\n$ readlink /proc/$$/ns/time\ntime:[4026531834]\n\nContinuing in the initial time namespace, we display the system uptime\nusing uptime(1) and use the clocktimes example program shown in\nclockgetres(2) to display the values of various clocks:\n\n$ uptime --pretty\nup 21 hours, 17 minutes\n$ ./clocktimes\nCLOCKREALTIME : 1585989401.971 (18356 days + 8h 36m 41s)\nCLOCKTAI : 1585989438.972 (18356 days + 8h 37m 18s)\nCLOCKMONOTONIC: 56338.247 (15h 38m 58s)\nCLOCKBOOTTIME : 76633.544 (21h 17m 13s)\n\nWe then use unshare(1) to create a time namespace and execute a bash(1)\nshell. From the new shell, we use the built-in echo command to write\nrecords to the timensoffsets file adjusting the offset for the\nCLOCKMONOTONIC clock forward 2 days and the offset for the CLOCKBOOT-\nTIME clock forward 7 days:\n\n$ PS1=\"ns2# \" sudo unshare -T -- bash --norc\nns2# echo \"monotonic $((2*24*60*60)) 0\" > /proc/$$/timensoffsets\nns2# echo \"boottime $((7*24*60*60)) 0\" > /proc/$$/timensoffsets\n\nAbove, we started the bash(1) shell with the --norc options so that no\nstart-up scripts were executed. This ensures that no child processes\nare created from the shell before we have a chance to update the\ntimensoffsets file.\n\nWe then use cat(1) to display the contents of the timensoffsets file.\nThe execution of cat(1) creates the first process in the new time name-\nspace, after which further attempts to update the timensoffsets file\nproduce an error.\n\nns2# cat /proc/$$/timensoffsets\nmonotonic 172800 0\nboottime 604800 0\nns2# echo \"boottime $((9*24*60*60)) 0\" > /proc/$$/timensoffsets\nbash: echo: write error: Permission denied\n\nContinuing in the new namespace, we execute uptime(1) and the\nclocktimes example program:\n\nns2# uptime --pretty\nup 1 week, 21 hours, 18 minutes\nns2# ./clocktimes\nCLOCKREALTIME : 1585989457.056 (18356 days + 8h 37m 37s)\nCLOCKTAI : 1585989494.057 (18356 days + 8h 38m 14s)\nCLOCKMONOTONIC: 229193.332 (2 days + 15h 39m 53s)\nCLOCKBOOTTIME : 681488.629 (7 days + 21h 18m 8s)\n\nFrom the above output, we can see that the monotonic and boot-time\nclocks have different values in the new time namespace.\n\nExamining the /proc/[pid]/ns/time and /proc/[pid]/ns/timeforchildren\nsymbolic links, we see that the shell is a member of the initial time\nnamespace, but its children are created in the new namespace.\n\nns2# readlink /proc/$$/ns/time\ntime:[4026531834]\nns2# readlink /proc/$$/ns/timeforchildren\ntime:[4026532900]\nns2# readlink /proc/self/ns/time # Creates a child process\ntime:[4026532900]\n\nReturning to the shell in the initial time namespace, we see that the\nmonotonic and boot-time clocks are unaffected by the timensoffsets\nchanges that were made in the other time namespace:\n\n$ uptime --pretty\nup 21 hours, 19 minutes\n$ ./clocktimes\nCLOCKREALTIME : 1585989401.971 (18356 days + 8h 38m 51s)\nCLOCKTAI : 1585989438.972 (18356 days + 8h 39m 28s)\nCLOCKMONOTONIC: 56338.247 (15h 41m 8s)\nCLOCKBOOTTIME : 76633.544 (21h 19m 23s)\n", "subsections": [] }, "SEE ALSO": { "content": "nsenter(1), unshare(1), clocksettime(2), setns(2), unshare(2), name-\nspaces(7), time(7)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A\ndescription of the project, information about reporting bugs, and the\nlatest version of this page, can be found at\nhttps://www.kernel.org/doc/man-pages/.\n\nLinux 2020-06-09 TIMENAMESPACES(7)", "subsections": [] } }, "summary": "timenamespaces - overview of Linux time namespaces", "flags": [], "examples": [ "The following shell session demonstrates the operation of time name-", "spaces. We begin by displaying the inode number of the time namespace", "of a shell in the initial time namespace:", "$ readlink /proc/$$/ns/time", "time:[4026531834]", "Continuing in the initial time namespace, we display the system uptime", "using uptime(1) and use the clocktimes example program shown in", "clockgetres(2) to display the values of various clocks:", "$ uptime --pretty", "up 21 hours, 17 minutes", "$ ./clocktimes", "CLOCKREALTIME : 1585989401.971 (18356 days + 8h 36m 41s)", "CLOCKTAI : 1585989438.972 (18356 days + 8h 37m 18s)", "CLOCKMONOTONIC: 56338.247 (15h 38m 58s)", "CLOCKBOOTTIME : 76633.544 (21h 17m 13s)", "We then use unshare(1) to create a time namespace and execute a bash(1)", "shell. From the new shell, we use the built-in echo command to write", "records to the timensoffsets file adjusting the offset for the", "CLOCKMONOTONIC clock forward 2 days and the offset for the CLOCKBOOT-", "TIME clock forward 7 days:", "$ PS1=\"ns2# \" sudo unshare -T -- bash --norc", "ns2# echo \"monotonic $((2*24*60*60)) 0\" > /proc/$$/timensoffsets", "ns2# echo \"boottime $((7*24*60*60)) 0\" > /proc/$$/timensoffsets", "Above, we started the bash(1) shell with the --norc options so that no", "start-up scripts were executed. This ensures that no child processes", "are created from the shell before we have a chance to update the", "timensoffsets file.", "We then use cat(1) to display the contents of the timensoffsets file.", "The execution of cat(1) creates the first process in the new time name-", "space, after which further attempts to update the timensoffsets file", "produce an error.", "ns2# cat /proc/$$/timensoffsets", "monotonic 172800 0", "boottime 604800 0", "ns2# echo \"boottime $((9*24*60*60)) 0\" > /proc/$$/timensoffsets", "bash: echo: write error: Permission denied", "Continuing in the new namespace, we execute uptime(1) and the", "clocktimes example program:", "ns2# uptime --pretty", "up 1 week, 21 hours, 18 minutes", "ns2# ./clocktimes", "CLOCKREALTIME : 1585989457.056 (18356 days + 8h 37m 37s)", "CLOCKTAI : 1585989494.057 (18356 days + 8h 38m 14s)", "CLOCKMONOTONIC: 229193.332 (2 days + 15h 39m 53s)", "CLOCKBOOTTIME : 681488.629 (7 days + 21h 18m 8s)", "From the above output, we can see that the monotonic and boot-time", "clocks have different values in the new time namespace.", "Examining the /proc/[pid]/ns/time and /proc/[pid]/ns/timeforchildren", "symbolic links, we see that the shell is a member of the initial time", "namespace, but its children are created in the new namespace.", "ns2# readlink /proc/$$/ns/time", "time:[4026531834]", "ns2# readlink /proc/$$/ns/timeforchildren", "time:[4026532900]", "ns2# readlink /proc/self/ns/time # Creates a child process", "time:[4026532900]", "Returning to the shell in the initial time namespace, we see that the", "monotonic and boot-time clocks are unaffected by the timensoffsets", "changes that were made in the other time namespace:", "$ uptime --pretty", "up 21 hours, 19 minutes", "$ ./clocktimes", "CLOCKREALTIME : 1585989401.971 (18356 days + 8h 38m 51s)", "CLOCKTAI : 1585989438.972 (18356 days + 8h 39m 28s)", "CLOCKMONOTONIC: 56338.247 (15h 41m 8s)", "CLOCKBOOTTIME : 76633.544 (21h 19m 23s)" ], "see_also": [ { "name": "nsenter", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/nsenter/1/json" }, { "name": "unshare", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/unshare/1/json" }, { "name": "clocksettime", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/clocksettime/2/json" }, { "name": "setns", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/setns/2/json" }, { "name": "unshare", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/unshare/2/json" }, { "name": "spaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/spaces/7/json" }, { "name": "time", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/time/7/json" } ] }