1.\"	$MirOS: src/bin/date/date.1,v 1.4 2011/11/20 20:12:40 tg Exp $
2.\"	$OpenBSD: date.1,v 1.41 2004/07/21 08:59:30 jmc Exp $
3.\"	$NetBSD: date.1,v 1.12 1996/03/12 04:32:37 phil Exp $
4.\"
5.\" Copyright (c) 1980, 1990, 1993
6.\"	The Regents of the University of California.  All rights reserved.
7.\"
8.\" This code is derived from software contributed to Berkeley by
9.\" the Institute of Electrical and Electronics Engineers, Inc.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\" 1. Redistributions of source code must retain the above copyright
15.\"    notice, this list of conditions and the following disclaimer.
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in the
18.\"    documentation and/or other materials provided with the distribution.
19.\" 3. Neither the name of the University nor the names of its contributors
20.\"    may be used to endorse or promote products derived from this software
21.\"    without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\"     @(#)date.1	8.3 (Berkeley) 4/28/95
36.\"
37.Dd $Mdocdate: November 20 2011 $
38.Dt DATE 1
39.Os
40.Sh NAME
41.Nm date
42.Nd display or set date and time
43.Sh SYNOPSIS
44.Nm date
45.Op Fl anRu
46.Op Fl d Ar dst
47.Op Fl r Ar seconds
48.Op Fl t Ar minutes_west
49.Op Cm + Ns Ar format
50.Sm off
51.Oo Oo Oo Oo Oo Oo
52.Ar cc Oc
53.Ar yy Oc
54.Ar mm Oc
55.Ar dd Oc
56.Ar HH Oc
57.Ar MM Op Ar \&.SS Oc
58.Sm on
59.Sh DESCRIPTION
60When invoked without arguments, the
61.Nm
62utility displays the current date and time.
63Otherwise, depending on the options specified,
64.Nm
65will set the date and time or print it in a user-defined way.
66.Pp
67Only the superuser may set the date.
68.Pp
69The options are as follows:
70.Bl -tag -width Ds
71.It Fl a
72Use the
73.Xr adjtime 2
74call to gradually skew the local time to the
75remote time rather than just hopping.
76.It Fl d Ar dst
77Set the system's value for Daylight Saving Time.
78If
79.Ar dst
80is non-zero, future calls
81to
82.Xr gettimeofday 2
83will return a non-zero value for
84.Fa tz_dsttime .
85.It Fl n
86By default,
87if the
88.Xr timed 8
89daemon is running,
90.Nm
91sets the time on all of the machines in the local group.
92The
93.Fl n
94option suppresses this behavior and causes the time to be set only on the
95current machine.
96.It Fl R
97Select RFC 2822 format.
98.It Fl r Ar seconds
99Print out (in specified format) the date and time represented by
100.Ar seconds
101from the Epoch.
102.It Fl t Ar minutes_west
103Set the system's value for minutes west of
104.Tn GMT .
105.Ar minutes_west
106specifies the number of minutes returned in
107.Fa tz_minuteswest
108by future calls to
109.Xr gettimeofday 2 .
110.It Fl u
111Display or set the date in UTC (Coordinated Universal) time.
112.El
113.Pp
114An operand with a leading plus sign
115.Pq Sq +
116signals a user-defined format
117string which specifies the format in which to display the date and time.
118The format string may contain any of the conversion specifications described
119in the
120.Xr strftime 3
121manual page, as well as any arbitrary text.
122A newline
123.Pq Ql \en
124character is always output after the characters specified by
125the format string.
126The format string for the default display is:
127.Bd -literal -offset indent
128%a %b %e %H:%M:%S %Z %Y
129.Ed
130.Pp
131If an operand does not have a leading plus sign, it is interpreted as
132a value for setting the system's notion of the current date and time.
133The canonical representation for setting the date and time is:
134.Pp
135.Bl -tag -width Ds -compact -offset indent
136.It Ar yy
137Year in abbreviated form (for years 1969-2068).
138The format
139.Ar ccyymmddHHMM
140is also permitted, for non-ambiguous years.
141.It Ar mm
142Numeric month, a number from 1 to 12.
143.It Ar dd
144Day, a number from 1 to 31.
145.It Ar HH
146Hour, a number from 0 to 23.
147.It Ar MM
148Minute, a number from 0 to 59.
149.It Ar SS
150Second, a number from 0 to 61 (59 plus a maximum of two leap seconds).
151.El
152.Pp
153Everything but the minute is optional.
154.Pp
155Time changes for Daylight Saving Time, standard time, leap seconds,
156and leap years are handled automatically.
157.Sh ENVIRONMENT
158.Bl -tag -width Ds
159.It Ev TZ
160The timezone to use when displaying dates.
161See
162.Xr environ 7
163for more information.
164If this variable is not set, the timezone is determined based on
165.Pa /etc/localtime ,
166which the administrator adjusts using
167the
168.Fl l
169option of
170.Xr zic 8 .
171.El
172.Sh FILES
173.Bl -tag -width /var/log/messages -compact
174.It Pa /var/log/wtmp
175record of date resets and time changes
176.It Pa /var/log/messages
177record of the user setting the time
178.El
179.Sh EXAMPLES
180The following command:
181.Pp
182.Dl $ date \&"+DATE: %Y-%m-%d%nTIME: %H:%M:%S\&"
183.Pp
184displays:
185.Bd -literal -offset indent
186DATE: 1987-11-21
187TIME: 13:36:16
188.Ed
189.Pp
190Set the date to
191June 13, 1985, 4:27 PM:
192.Pp
193.Dl # date 8506131627
194.Pp
195Set the time to
1962:32 PM,
197without modifying the date:
198.Pp
199.Dl # date 1432
200.Sh DIAGNOSTICS
201Exit status is 0 on success, 1 if unable to set the date, and 2
202if able to set the local date, but unable to set it globally.
203.Pp
204Occasionally, when
205.Xr timed 8
206synchronizes the time on many hosts, the setting of a new time value may
207require more than a few seconds.
208On these occasions,
209.Nm
210prints:
211.Dq Network time being set .
212The message
213.Dq Communication error with timed
214occurs when the communication
215between
216.Nm
217and
218.Xr timed 8
219fails.
220.Sh SEE ALSO
221.Xr adjtime 2 ,
222.Xr gettimeofday 2 ,
223.Xr strftime 3 ,
224.Xr utmp 5 ,
225.Xr ntpd 8 ,
226.Xr rdate 8 ,
227.Xr timed 8
228.Rs
229.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
230.%A R. Gusella
231.%A S. Zatti
232.Re
233.Sh STANDARDS
234The
235.Nm
236utility is expected to be compatible with
237.St -p1003.2 .
238.Sh HISTORY
239A
240.Nm
241command appeared in
242.At v1 .
243.Pp
244The
245.Fl R
246option is a GNU extension and supported since
247.Mx 11 .
248