{ "mode": "man", "parameter": "time_namespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/time_namespaces/7/json", "generated": "2026-06-16T10:09:40Z", "sections": { "NAME": { "content": "timenamespaces - overview of Linux time namespaces\n", "subsections": [] }, "DESCRIPTION": { "content": "Time namespaces virtualize the values of two system clocks:\n\n• CLOCKMONOTONIC (and likewise CLOCKMONOTONICCOARSE and CLOCKMONOTONICRAW), a nonset‐\ntable clock that represents monotonic time since—as described by POSIX—\"some unspeci‐\nfied point in the past\".\n\n• CLOCKBOOTTIME (and likewise CLOCKBOOTTIMEALARM), a nonsettable clock that is identical\nto CLOCKMONOTONIC, except that it also includes any time that the system is suspended.\n\nThus, the processes in a time namespace share per-namespace values for these clocks. This\naffects various APIs that measure against these clocks, including: clockgettime(2),\nclocknanosleep(2), nanosleep(2), timersettime(2), timerfdsettime(2), and /proc/uptime.\n\nCurrently, the only way to create a time namespace is by calling unshare(2) with the\nCLONENEWTIME flag. This call creates a new time namespace but does not place the calling\nprocess in the new namespace. Instead, the calling process's subsequently created children\nare placed in the new namespace. This allows clock offsets (see below) for the new namespace\nto be set before the first process is placed in the namespace. The\n/proc/[pid]/ns/timeforchildren symbolic link shows the time namespace in which the children\nof a process will be created. (A process can use a file descriptor opened on this symbolic\nlink in a call 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 to the initial time\nnamespace, that define the values of the monotonic and boot-time clocks in that namespace.\nThese offsets are exposed via the file /proc/PID/timensoffsets. Within this file, the off‐\nsets are expressed as lines consisting of three space-delimited fields:\n\n \n\nThe clock-id is a string that identifies the clock whose offsets are being shown. This field\nis either monotonic, for CLOCKMONOTONIC, or boottime, for CLOCKBOOTTIME. The remaining\nfields express the offset (seconds plus nanoseconds) for the clock in this time namespace.\nThese offsets are expressed relative to the clock values in the initial time namespace. The\noffset-secs value can be negative, subject to restrictions noted below; offset-nanosecs is an\nunsigned value.\n\nIn the initial time namespace, the contents of the timensoffsets file are 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 offsets can be modified\nby writing newline-terminated records of the same form to the timensoffsets file. The file\ncan be written to multiple 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. In order to write to\nthe timensoffsets file, a process must have the CAPSYSTIME capability in the user name‐\nspace that owns the time namespace.\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\n• offset-secs can't be set to a value which would make the current time on the corre‐\nsponding clock inside the namespace a negative value; and\n\n• offset-secs can't be set to a value such that the time on the corresponding clock\ninside the namespace would exceed half of the value of the kernel constant\nKTIMESECMAX (this limits the clock value to a maximum of approximately 146 years).\n\nIn a new time namespace created by unshare(2), the contents of the timensoffsets file are\ninherited from the time namespace of the creating process.\n", "subsections": [] }, "NOTES": { "content": "Use of time namespaces requires a kernel that is configured with the CONFIGTIMENS option.\n\nNote that time namespaces do not virtualize the CLOCKREALTIME clock. Virtualization of this\nclock was avoided for reasons of complexity and overhead within the kernel.\n\nFor compatibility with the initial implementation, when writing a clock-id to the\n/proc/[pid]/timensoffsets file, the numerical values of the IDs can be written instead of\nthe symbolic names show above; i.e., 1 instead of monotonic, and 7 instead of boottime. For\nredability, the use of the symbolic names over the numbers is preferred.\n\nThe motivation for adding time namespaces was to allow the monotonic and boot-time clocks to\nmaintain consistent values during container migration and checkpoint/restore.\n", "subsections": [] }, "EXAMPLES": { "content": "The following shell session demonstrates the operation of time namespaces. We begin by dis‐\nplaying the inode number of the time namespace of 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 using uptime(1) and\nuse the clocktimes example program shown in clockgetres(2) to display the values of various\nclocks:\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) shell. From the new\nshell, we use the built-in echo command to write records to the timensoffsets file adjusting\nthe offset for the CLOCKMONOTONIC clock forward 2 days and the offset for the CLOCKBOOTTIME\nclock 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 start-up scripts were\nexecuted. This ensures that no child processes are created from the shell before we have a\nchance to update the timensoffsets file.\n\nWe then use cat(1) to display the contents of the timensoffsets file. The execution of\ncat(1) creates the first process in the new time namespace, after which further attempts to\nupdate the timensoffsets file produce 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 clocktimes 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 clocks have different val‐\nues in the new time namespace.\n\nExamining the /proc/[pid]/ns/time and /proc/[pid]/ns/timeforchildren symbolic links, we see\nthat the shell is a member of the initial time namespace, but its children are created in the\nnew namespace.\n\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 monotonic and boot-time\nclocks are unaffected by the timensoffsets changes that were made in the other time name‐\nspace:\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), namespaces(7), time(7)\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 TIMENAMESPACES(7)", "subsections": [] } }, "summary": "timenamespaces - overview of Linux time namespaces", "flags": [], "examples": [ "The following shell session demonstrates the operation of time namespaces. We begin by dis‐", "playing 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 CLOCKBOOTTIME", "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 namespace, 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 val‐", "ues 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 name‐", "space:", "$ 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": "namespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/namespaces/7/json" }, { "name": "time", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/time/7/json" } ] }