From owner-svn-doc-head@freebsd.org Sat Jun 27 00:25:35 2015 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id B94BC98D807; Sat, 27 Jun 2015 00:25:35 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 9319C1684; Sat, 27 Jun 2015 00:25:35 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t5R0PZeX073014; Sat, 27 Jun 2015 00:25:35 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t5R0PY7s073007; Sat, 27 Jun 2015 00:25:34 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201506270025.t5R0PY7s073007@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Sat, 27 Jun 2015 00:25:34 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r46873 - in head: en_US.ISO8859-1/articles en_US.ISO8859-1/articles/leap-seconds en_US.ISO8859-1/htdocs/docs share/xml X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 27 Jun 2015 00:25:35 -0000 Author: wblock Date: Sat Jun 27 00:25:33 2015 New Revision: 46873 URL: https://svnweb.freebsd.org/changeset/doc/46873 Log: Add a short article on how FreeBSD handles leap seconds. Thanks for contributions from Peter Jeremy, Poul-Henning Kamp, Ian Lepore, Xin LI, and Warner Losh. Requested by Bartek Rutkowski. Added: head/en_US.ISO8859-1/articles/leap-seconds/ head/en_US.ISO8859-1/articles/leap-seconds/Makefile (contents, props changed) head/en_US.ISO8859-1/articles/leap-seconds/article.xml (contents, props changed) Modified: head/en_US.ISO8859-1/articles/Makefile head/en_US.ISO8859-1/htdocs/docs/books.xml head/share/xml/urls.ent Modified: head/en_US.ISO8859-1/articles/Makefile ============================================================================== --- head/en_US.ISO8859-1/articles/Makefile Fri Jun 26 23:03:20 2015 (r46872) +++ head/en_US.ISO8859-1/articles/Makefile Sat Jun 27 00:25:33 2015 (r46873) @@ -17,6 +17,7 @@ SUBDIR+= gjournal-desktop SUBDIR+= hubs SUBDIR+= ipsec-must SUBDIR+= ldap-auth +SUBDIR+= leap-seconds SUBDIR+= linux-emulation SUBDIR+= linux-users SUBDIR+= mailing-list-faq Added: head/en_US.ISO8859-1/articles/leap-seconds/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/articles/leap-seconds/Makefile Sat Jun 27 00:25:33 2015 (r46873) @@ -0,0 +1,19 @@ +# +# $FreeBSD$ +# +# Article: Leap Seconds + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.xml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/en_US.ISO8859-1/articles/leap-seconds/article.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/articles/leap-seconds/article.xml Sat Jun 27 00:25:33 2015 (r46873) @@ -0,0 +1,118 @@ + + + +
+ + + &os; Support for Leap Seconds + + $FreeBSD$ + + + + Introduction + + A leap second is an ad-hoc one-second + correction to synchronize atomic timescales with Earth rotation. + This article describes how &os; interacts with leap + seconds. + + As of this writing, the next leap second will occur at + 2015-Jun-30 23:59:60. This particular leap second is unusual, + being in the middle of a business day for North and South + America and the Asia/Pacific region. + + Leap seconds are announced by IERS + on Bulletin + C. + + Standard leap second behavior is described in RFC + 7164. Also see &man.time2posix.3;. + + + + Default Leap Second Handling on &os; + + The easiest way to handle leap seconds is with the + POSIX time rules &os; uses by default, + combined with NTP. + When &man.ntpd.8; is running and the time is synchronized with + upstream NTP servers that handle leap seconds + correctly, the leap second will cause the system time to + automatically repeat the last second of the day. No other + adjustments are necessary. + + If the upstream NTP servers do not handle + leap seconds correctly, &man.ntpd.8; will step the time by one + second after the errant upstream server has noticed and stepped + itself. + + If NTP is not being used, manual + adjustment of the system clock will be required after the leap + second has passed. + + + + Cautions + + Leap seconds are inserted at the same instant all over the + world: UTC midnight. In Japan that is + mid-morning, in the Pacific mid-day, in the Americas late + afternoon, and in Europe at night. + + We believe and expect that &os;, if provided correct and + stable NTP service, will work as designed + during this leap second, as it did during the previous + ones. + + However, we caution that practically no applications have + ever asked the kernel about leap seconds. Our experience is + that, as designed, leap seconds are essentially a replay of the + second before the leap second, and this is a surprise to most + application programmers. + + Other operating systems and other computers may or may not + handle the leap-second the same way as &os;, and systems without + correct and stable NTP service will not know + anything about leap seconds at all. + + It is not unheard of for computers to crash because of + leap seconds, and experience has shown that a large fraction + of all public NTP servers might handle and + announce the leap second incorrectly. + + Please try to make sure nothing horrible happens because of + the leap second. + + + + Testing + + It is possible to test whether a leap second will be used. + Due to the nature of NTP, the test might work + up to 24 hours before the leap second. Some major reference + clock sources only announce leap seconds one hour ahead of the + event. Query the NTP daemon: + + &prompt.user; ntpq -c 'rv 0 leap' + + Output that includes leap_add_sec + indicates proper support of the leap second. Before the 24 hour + period before the leap second, or after the leap second has + passed, leap_none will be reported. + + + + Conclusion + + We hope this discussion of leap seconds on &os; has been of + use. Now let us never speak of it again. + +
Modified: head/en_US.ISO8859-1/htdocs/docs/books.xml ============================================================================== --- head/en_US.ISO8859-1/htdocs/docs/books.xml Fri Jun 26 23:03:20 2015 (r46872) +++ head/en_US.ISO8859-1/htdocs/docs/books.xml Sat Jun 27 00:25:33 2015 (r46873) @@ -170,6 +170,10 @@ A practical guide about setting up an LDAP server on &os; and how to use it for authenticating users.

+

&os; Support + for Leap Seconds (leap-seconds)
+ A short description of how leap seconds are handled on &os;.

+

Linux emulation in &os; (linux-emulation)
A technical description about the internals of the Linux Modified: head/share/xml/urls.ent ============================================================================== --- head/share/xml/urls.ent Fri Jun 26 23:03:20 2015 (r46872) +++ head/share/xml/urls.ent Sat Jun 27 00:25:33 2015 (r46873) @@ -75,6 +75,8 @@ + +