.\" Copyright (c) 1980, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)date.1	8.2 (Berkeley) 11/17/93
.\" %FreeBSD: src/bin/date/date.1,v 1.63 2004/04/06 22:03:38 green Exp %
.\"
.\" $FreeBSD$
.Dd November 17, 1993
.Dt DATE 1
.Os
.Sh 名称
.Nm date
.Nd 日付と時刻の表示、設定
.Sh 書式
.Nm
.Op Fl ju
.Op Fl r Ar seconds
.Oo
.Fl v
.Sm off
.Op Cm + | -
.Ar val Op Ar ymwdHMS
.Sm on
.Oc
.Ar ...
.Op Cm + Ns Ar output_fmt
.Nm
.Op Fl jnu
.Sm off
.Op Oo Oo Oo Oo Ar cc Oc Ar yy Oc Ar mm Oc Ar dd Oc Ar HH
.Ar MM Op Ar .ss
.Sm on
.Nm
.Op Fl jnu
.Fl f
.Ar input_fmt new_date
.Op Cm + Ns Ar output_fmt
.Nm
.Op Fl d Ar dst
.Op Fl t Ar minutes_west
.Sh 解説
引数なしで実行すると、
.Nm
ユーティリティは現在の日付と時刻を表示します。
引数を与えると、日時の設定、
あるいはユーザが定義したフォーマットに従った日付や時刻の表示を行います。
.Pp
.Nm
ユーティリティは、カーネルクロックから読み取った日付と時刻を表示します。
日付と時刻の設定に使用された場合、
カーネルクロックとハードウェアクロックの両方が更新されます。
.Pp
なお、日付と時刻を設定できるのはスーパユーザだけです。
システムのセキュリティレベル (
.Xr securelevel 8
を参照) が 1 より大きい場合、1 秒を越える時刻修正は許されません。
.Pp
オプション:
.Bl -tag -width Ds
.It Fl d Ar dst
夏時間用のカーネル値を設定します。もし
.Ar dst
が 0 でなければ、そのあとの
.Xr gettimeofday 2
呼び出しでは
.Ql tz_dsttime
に 0 以外の値が返ります。
.It Fl f
デフォルトの
.Ar [[[[yy]mm]dd]HH]MM[.ss]
フォーマットの代りに
.Ar fmt
を、時刻をパーズするフォーマットとして使用します。
.Xr strptime 3
を使用してパーズします。
.It Fl j
日付の設定を行いません。
本フラグを使用し、
.Fl f
フラグを
.Cm +
オプションとともに用いることで、日付の書式の変換ができます。
.It Fl n
.Xr timed
が動作している場合、デフォルトでは
.Nm
コマンドによりグループ内のすべてのマシンの時刻が変更されます。しかし、
.Fl n
オプションを指定した場合には、他のマシンの時刻は変更せず、
このマシンのみで時刻を設定します。
.It Fl r Ar seconds
基準時点
(1970 年 1 月 1 日 00:00:00;
.Xr time 3
参照)
から
.Ar seconds
秒経過した日時を表示します。
10 進数、8 進数、16 進数のいずれの指定も可能です。
.It Fl t Ar minutes_west
カーネルに
.Tn GMT
(グリニッジ標準時) からの時差を設定します。このあとに呼ばれる
.Xr gettimeofday 2
では、ここで指定された値が
.Ql tz_minuteswest
に入ります。
.It Fl u
.Tn UTC
(協定世界時) の日付を表示、設定します。
.\"	訳注(Mar.1996):UTC (Universal Time Coordinate)
.It Fl v
秒、分、時、日、曜日、月、年のいずれかを
.Ar val
にもとづき修正します
(すなわち、現在の日付を取得し、修正した結果を表示します。
日付を設定するのではありません)。
.Ar val
の前にプラスもしくはマイナスが付いている場合、
時刻はそれに従い前後に修正されます。
そうでない場合は、指定した部分が設定されます。
必要なら任意個このフラグを指定して時刻を修正することが出来ます。
フラグは指定した順序に処理されます。
.Pp
(値を修正するのではなく)
値を指定する場合、
秒の範囲は 0-59、
分の範囲は 0-59、時の範囲は 0-23、日の範囲は 1-31、曜日の範囲は 0-6
(Sun-Sat)、月の範囲は 1-12 (Jan-Dec)、
年の範囲は 80-38 もしくは 1980-2038 です。
.Pp
.Ar val
が数値の場合、
.Ar y ,
.Ar m ,
.Ar w ,
.Ar d ,
.Ar H ,
.Ar M ,
.Ar S
のいずれかを使用して、時刻のどの部分を修正するのかを指定する必要があります。
.Pp
曜日もしくは月は数値の代りに名前で指定可能です。
名前と共にプラス (もしくはマイナス) 記号を使用した場合、
日付は適合する次の (前の) 曜日もしくは月に進みます (戻ります)。
曜日もしくは月が現在のものと変らない場合、日は修正しません。
.Pp
特定の値に時刻を修正する場合や、単位が 1 時間よりも大きい場合には、
夏時間の概念は無視されます。
1 時間以下の単位での修正は、夏時間の概念を持ちます。
現在の時刻を 3 月 26 日 0:30 であり、
夏時間の修正により 01:00 から 02:00 へ進むと仮定した場合、
.Fl v No +1H
は時刻を 3 月 26 日 2:30 へ修正します。
同様に、現在の時刻が 10 月 29 日 0:30 であり、
夏時間の修正により 02:00 から 01:00 へ戻ると仮定した場合、
.Fl v No +3H
とすると時刻は 10 月 29 日 2:30 になります。
.Pp
存在しない特定の値
(例えば、ヨーロッパ/ロンドンのタイムゾーンで
2000 年 3 月 26 日 1:30 BST)
へ時刻を修正する場合、
正当な時刻になるまで、時刻は黙って 1 時間の単位で進められます。
2 回存在する特定の値
(例えば 2000 年 10 月 29 日 1:30)
へ時刻を修正する場合、最終的なタイムゾーンは、
2 回の時刻のうち早いものに適合するものとなります。
.Pp
詳細に関しては、下記の例を参照して下さい。
.El
.Pp
プラス
.Pq Sq +
で始まるオプションは、日付と時刻の表示方法を指定する
フォーマット文字列です。フォーマット文字列には、
.Xr strftime 3
で記述されているような変換文字列と、任意のテキストを含むことができます。
フォーマット文字列によって指定された文字の後には、つねに改行文字
.Pq Ql \en
が出力されます。
.Nm
のデフォルトの表示形式は、
.Bd -literal -offset indent
``+%+''
.Ed
.Pp
としたものと同じです。
.Pp
もし、引数が ``+'' 記号で始まる文字列でなければ、それはシステムに
日時を設定するための値と解釈されます。日時を設定するための正式な
表現は以下のとおりです:
.Pp
.Bl -tag -width Ds -compact -offset indent
.It Ar cc
世紀 (19 または 20 のいずれか) であり、西暦の省略表現の前に付きます。
.It Ar yy
西暦の省略表現です。西暦の 10 の位と 1 の位です
(1989 年なら 89、06 なら 2006)。
.It Ar mm
月の数字表現です。1 から 12 までの数字です。
.It Ar dd
日です。1 から 31 までの数字です。
.It Ar HH
時です。0 から 23 までの数字です。
.It Ar MM
分です。0 から 59 までの数字です。
.It Ar ss
秒です。0 から 61 までの数字です。 (59 秒 + 2 秒までのうるう秒)
.El
.Pp
分の指定以外はすべて省略可能です。
.Pp
夏時間と標準時の切り替えや、閏秒や閏年の取り扱いは自動的に行われます。
.Sh 使用例
以下のコマンド:
.Pp
.Dl "date ""+DATE: %Y-%m-%d%nTIME: %H:%M:%S"""
.Pp
は、下のような表示を行ないます。
.Bd -literal -offset indent
DATE: 1987-11-21
TIME: 13:36:16
.Ed
.Pp
ヨーロッパ/ロンドンのタイムゾーンでは、
以下のコマンド:
.Pp
.Dl "date -v1m -v+1y"
.Pp
は以下を表示します:
.Pp
.Dl "Sun Jan  4 04:15:24 GMT 1998"
.Pp
(現在 Mon Aug  4 04:15:24 BST 1997 の場合)。
.Pp
以下のコマンド:
.Pp
.Dl "date -v1d -v3m -v0y -v-1d"
.Pp
は 2000 年 2 月の最後の日を表示します:
.Pp
.Dl "Tue Feb 29 03:18:00 GMT 2000"
.Pp
以下のコマンド：
.Pp
.Dl "date -v1d -v+1m -v-1d -v-fri"
.Pp
は今月最後の金曜日を表示します:
.Pp
.Dl "Fri Aug 29 04:31:11 BST 1997"
.Pp
(現在 Mon Aug  4 04:31:11 BST 1997 の場合)。
.Pp
以下のコマンド:
.Pp
.Dl "date 8506131627"
.Pp
は、
.\" '\ ' 無しでは引数の数が限界を越えるため
.Dq Li "1985\ 年\ 6\ 月\ 13\ 日午後\ 4\ 時\ 27\ 分"
に日時を設定します。
.Dl "date ""+%Y%m%d%H%M.%S"""
.Pp
をあるマシンで使用し、別のマシンでの時刻設定に使用可能です。
(Linux では "+%m%d%H%M%Y.%S" を使うとよいでしょう)
.Pp
以下のコマンド:
.Pp
.Dl "date 1432"
.Pp
は、日を修正することなく、時だけを
.Li "午後 2 時 32 分"
に設定します。
.Sh 環境変数
.Nm
の実行は以下の環境変数の影響を受けます。
.Bl -tag -width Ds
.It Ev TZ
日時を表示する際に用いられるタイムゾーンを設定します。
通常のフォーマットは
.Pa /usr/share/zoneinfo
からの相対パス名です。例えば、コマンド
.Dq TZ=America/Los_Angeles date
はカリフォルニアの現在の時刻を表示します。
詳しいことは、
.Xr environ 7
を参照してください。
.El
.Sh 関連ファイル
.Bl -tag -width /var/log/messages -compact
.It Pa /var/log/wtmp
日付のリセットおよび時刻変更の記録がこのファイルに残されます。
.It Pa /var/log/messages
日付を変更したユーザの記録がこのファイルに残されます。
.El
.Sh 関連項目
.Xr gettimeofday 2 ,
.Xr strftime 3 ,
.Xr strptime 3 ,
.Xr utmp 5 ,
.Xr timed 8
.Rs
.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
.%A R. Gusella
.%A S. Zatti
.Re
.Sh 診断
.Nm
ユーティリティは、
成功した場合は 0 を、日時を設定できなかった場合は 1 を、
ローカルマシンの設定はできたが、グループのマシン全体の設定に失敗した
場合は 2 を返します。
.Pp
timed が多数のマシンの時計をあわせる場合には、新しい時刻のセットに
数秒かかることがあります。このとき
.Nm
は、
.Ql Network time being set
と表示します。
.Nm
と
.Xr timed 8
との間で通信に失敗した場合は、
.Ql Communication error with timed
が表示されます。
.Sh バグ
システムは
.Tn VMS
と高い互換性を持つフォーマットで日時を保持しようとしています。しかし、
.Tn VMS
は
.Tn GMT
ではなくローカルな時刻を使っており、夏時間を理解しません。そのため、
.Tn UNIX
と
.Tn VMS
を同時に使う場合は、
.Tn VMS
を
.Tn GMT
で使うべきでしょう。
.Sh 規格
.Nm
ユーティリティは
.St -p1003.2
互換であると想定しています。
.Sh 歴史
.Nm date
コマンドは
.At v1
から導入されました。