1.\" Copyright (c) 1980, 1990, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. 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
| 1.\" Copyright (c) 1980, 1990, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. 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.\" $FreeBSD: head/bin/date/date.1 57803 2000-03-07 20:54:17Z sheldonh $
| 36.\" $FreeBSD: head/bin/date/date.1 59175 2000-04-12 13:35:17Z brian $
|
37.\"
38.Dd November 17, 1993
39.Dt DATE 1
40.Os
41.Sh NAME
42.Nm date
43.Nd display or set date and time
44.Sh SYNOPSIS
45.Nm date
46.Op Fl jnu
47.Op Fl d Ar dst
48.Op Fl r Ar seconds
49.Op Fl t Ar minutes_west
50.Oo
51.Fl v
52.Op +|- Ns
53.No val Ns Op ymwdHMS
54.Oc Ns ...
55.Oo Fl f No " "
56.Ar fmt date No |
57.Oo Oo Oo Oo Oo "\&cc" Ns
58.Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns
59.Oc
60.No "\&MM" Ns Op "\&.ss"
61.Oc
62.Op Cm + Ns Ar format
63.Sh DESCRIPTION
64.Nm Date
65displays the current date and time when invoked without arguments.
66Providing arguments will format the date and time in a user-defined
67way or set the date.
68Only the superuser may set the date.
69.Pp
70The options are as follows:
71.Bl -tag -width Ds
72.It Fl d
73Set the kernel's value for daylight savings time.
74If
75.Ar dst
76is non-zero, future calls
77to
78.Xr gettimeofday 2
79will return a non-zero
80.Ql tz_dsttime .
81.It Fl f
82Use
83.Ar fmt
84as the format string to parse the date provided rather than using
85the default
86.\" .Ar [[[[[cc]yy]mm]dd]HH]MM[.ss]
87.Xo
88.Oo Oo Oo Oo Oo "\&cc" Ns
89.Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns
90.Oc
91.No "\&MM" Ns Op "\&.ss" Xc
92format. Parsing is done using
93.Xr strptime 3 .
94.It Fl j
95Do not try to set the date. This allows you to use the
96.Fl f
97flag in addition to the
98.Cm +
99option to convert one date format to another.
100.It Fl n
101The utility
102.Xr timed 8
103is used to synchronize the clocks on groups of machines.
104By default, if
105.Xr timed
106is running,
107.Nm
108will set the time on all of the machines in the local group.
109The
110.Fl n
111option stops
112.Nm
113from setting the time for other than the current machine.
114.It Fl r
115Print out the date and time that is
116.Ar seconds
117from the Epoch
118.Po
11900:00:00 UTC, January 1, 1970;
120see
121.Xr time 3
122.Pc .
123.It Fl t
124Set the kernel's value for minutes west of
125.Tn GMT .
126.Ar Minutes_west
127specifies the number of minutes returned in
128.Ql tz_minuteswest
129by future calls to
130.Xr gettimeofday 2 .
131.It Fl u
132Display or set the date in
133.Tn UCT
134.Pq universal
135time.
136.It Fl v
137Adjust the second, minute, hour, month day, week day, month or year according to
138.Ar val .
139If
140.Ar val
141is preceded with a plus or minus sign, the date is adjusted forwards
142or backwards according to the remaining string, otherwise the relevant
143part of the date is set. The date can be adjusted as many times as
144required using these flags. Flags are processed in the order given.
145.Pp
| 37.\"
38.Dd November 17, 1993
39.Dt DATE 1
40.Os
41.Sh NAME
42.Nm date
43.Nd display or set date and time
44.Sh SYNOPSIS
45.Nm date
46.Op Fl jnu
47.Op Fl d Ar dst
48.Op Fl r Ar seconds
49.Op Fl t Ar minutes_west
50.Oo
51.Fl v
52.Op +|- Ns
53.No val Ns Op ymwdHMS
54.Oc Ns ...
55.Oo Fl f No " "
56.Ar fmt date No |
57.Oo Oo Oo Oo Oo "\&cc" Ns
58.Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns
59.Oc
60.No "\&MM" Ns Op "\&.ss"
61.Oc
62.Op Cm + Ns Ar format
63.Sh DESCRIPTION
64.Nm Date
65displays the current date and time when invoked without arguments.
66Providing arguments will format the date and time in a user-defined
67way or set the date.
68Only the superuser may set the date.
69.Pp
70The options are as follows:
71.Bl -tag -width Ds
72.It Fl d
73Set the kernel's value for daylight savings time.
74If
75.Ar dst
76is non-zero, future calls
77to
78.Xr gettimeofday 2
79will return a non-zero
80.Ql tz_dsttime .
81.It Fl f
82Use
83.Ar fmt
84as the format string to parse the date provided rather than using
85the default
86.\" .Ar [[[[[cc]yy]mm]dd]HH]MM[.ss]
87.Xo
88.Oo Oo Oo Oo Oo "\&cc" Ns
89.Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns
90.Oc
91.No "\&MM" Ns Op "\&.ss" Xc
92format. Parsing is done using
93.Xr strptime 3 .
94.It Fl j
95Do not try to set the date. This allows you to use the
96.Fl f
97flag in addition to the
98.Cm +
99option to convert one date format to another.
100.It Fl n
101The utility
102.Xr timed 8
103is used to synchronize the clocks on groups of machines.
104By default, if
105.Xr timed
106is running,
107.Nm
108will set the time on all of the machines in the local group.
109The
110.Fl n
111option stops
112.Nm
113from setting the time for other than the current machine.
114.It Fl r
115Print out the date and time that is
116.Ar seconds
117from the Epoch
118.Po
11900:00:00 UTC, January 1, 1970;
120see
121.Xr time 3
122.Pc .
123.It Fl t
124Set the kernel's value for minutes west of
125.Tn GMT .
126.Ar Minutes_west
127specifies the number of minutes returned in
128.Ql tz_minuteswest
129by future calls to
130.Xr gettimeofday 2 .
131.It Fl u
132Display or set the date in
133.Tn UCT
134.Pq universal
135time.
136.It Fl v
137Adjust the second, minute, hour, month day, week day, month or year according to
138.Ar val .
139If
140.Ar val
141is preceded with a plus or minus sign, the date is adjusted forwards
142or backwards according to the remaining string, otherwise the relevant
143part of the date is set. The date can be adjusted as many times as
144required using these flags. Flags are processed in the order given.
145.Pp
|
146Seconds are in the range 0-59, minutes are in the range 0-59, hours are
| 146When setting values
147.Pq rather than adjusting them ,
148seconds are in the range 0-59, minutes are in the range 0-59, hours are
|
147in the range 1-12, month days are in the range 1-31, week days are in the
148range 0-6
149.Pq Sun-Sat ,
150months are in the range 1-12
151.Pq Jan-Dec
152and years are in the range 80-38 or 1980-2038.
153.Pp
154If
155.Ar val
156is numeric, one of either
157.Ar y ,
158.Ar m ,
159.Ar w ,
160.Ar d ,
161.Ar H ,
162.Ar M
163or
164.Ar S
165must be used to specify which part of the date is to be adjusted.
166.Pp
167The week day or month may be specified using a name rather than a
168number. If a name is used with the plus
169.Pq or minus
170sign, the date will be put forwards
171.Pq or backwards
172to the next
173.Pq previous
174date that matches the given week day or month. This will not adjust the date
175if the given week day or month is the same as the current one.
176.Pp
| 149in the range 1-12, month days are in the range 1-31, week days are in the
150range 0-6
151.Pq Sun-Sat ,
152months are in the range 1-12
153.Pq Jan-Dec
154and years are in the range 80-38 or 1980-2038.
155.Pp
156If
157.Ar val
158is numeric, one of either
159.Ar y ,
160.Ar m ,
161.Ar w ,
162.Ar d ,
163.Ar H ,
164.Ar M
165or
166.Ar S
167must be used to specify which part of the date is to be adjusted.
168.Pp
169The week day or month may be specified using a name rather than a
170number. If a name is used with the plus
171.Pq or minus
172sign, the date will be put forwards
173.Pq or backwards
174to the next
175.Pq previous
176date that matches the given week day or month. This will not adjust the date
177if the given week day or month is the same as the current one.
178.Pp
|
| 179When a date is adjusted to a specific value or in units greater than hours,
180daylight savings time considerations are ignored.
181Adjustments in units of hours or less honour daylight savings time.
182So, assuming the current date is March 26, 0:30 and that the DST adjustment
183means that the clock goes forward at 01:00 to 02:00, using
184.Fl v No +1H
185will adjust the date to March 26, 2:30.
186Likewise, if the date is October 29, 0:30 and the DST adjustment means that
187the clock goes back at 02:00 to 01:00, using
188.Fl v No +3H
189will be necessary to reach October 20, 2:30.
190.Pp
191When the date is adjusted to a specific value that doesn't actually exist
192.Pq for example March 26, 1:30 BST 2000 ,
193the date will be silently adjusted forwards in units of one hour until it
194reaches a valid time.
195When the date is adjusted to a specific value that occurs twice
196.Pq for example October 29, 1:30 2000 ,
197the resulting timezone will be set so that the date matches the earlier of
198the two times.
199.Pp
|
177Refer to the examples below for further details.
178.El
179.Pp
180An operand with a leading plus
181.Pq Dq \&+
182sign signals a user-defined format string which specifies the format in
183which to display the date and time. The format string may contain any of
184the conversion specifications described in the
185.Xr strftime 3
186manual page, as well as any arbitrary text.
187A <newline> character is always output after the characters specified by
188the format string.
189The format string for the default display is
190.Dq +%+ .
191.Pp
192If an operand does not have a leading plus sign, it is interpreted as
193a value for setting the system's notion of the current date and time.
194The canonical representation for setting the date and time is:
195.Pp
196.Bl -tag -width Ds -compact -offset indent
197.It Ar cc
198Century
199.Pq either 19 or 20
200prepended to the abbreviated year.
201.It Ar yy
202Year in abbreviated form
203.Pq e.g. 89 for 1989, 06 for 2006 .
204.It Ar mm
205Numeric month.
206A number from 1 to 12.
207.It Ar dd
208Day, a number from 1 to 31.
209.It Ar HH
210Hour, a number from 0 to 23.
211.It Ar MM
212Minutes, a number from 0 to 59.
213.It Ar .ss
214Seconds, a number from 0 to 61
215.Pq 59 plus a maximum of two leap seconds .
216.El
217.Pp
218Everything but the minutes is optional.
219.Pp
220Time changes for Daylight Saving and Standard time and leap seconds
221and years are handled automatically.
222.Sh EXAMPLES
223The command:
224.Bd -literal -offset indent
225date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S"
226.Ed
227.Pp
228will display:
229.Bd -literal -offset indent
230DATE: 1987-11-21
231TIME: 13:36:16
232.Ed
233.Pp
234The command:
235.Bd -literal -offset indent
236date -v1m -v+1y
237.Ed
238.Pp
239will display:
240.Bd -literal -offset indent
241Sun Jan 4 03:15:24 GMT 1998
242.Ed
243.Pp
244where it is currently Mon Aug 4 04:15:24 BST 1997.
245.Pp
246The command:
247.Bd -literal -offset indent
248date -v1d -v3m -v0y -v-1d
249.Ed
250.Pp
251will display the last day of February in the year 2000:
252.Bd -literal -offset indent
253Tue Feb 29 03:18:00 GMT 2000
254.Ed
255.Pp
256The command:
257.Bd -literal -offset indent
258date -v1d -v+1m -v-1d -v-fri
259.Ed
260.Pp
261will display the last Friday of the month:
262.Bd -literal -offset indent
263Fri Aug 29 04:31:11 BST 1997
264.Ed
265.Pp
266where it is currently Mon Aug 4 04:31:11 BST 1997.
267.Pp
268The command:
269.Bd -literal -offset indent
270date 8506131627
271.Ed
272.Pp
273sets the date to
274.Dq Li "June 13, 1985, 4:27 PM" .
275.Pp
276The command:
277.Bd -literal -offset indent
278date 1432
279.Ed
280.Pp
281sets the time to
282.Li "2:32 PM" ,
283without modifying the date.
284.Sh ENVIRONMENT
285The execution of
286.Nm
287is affected by the following environment variables:
288.Bl -tag -width Ds
289.It Ev TZ
290The timezone to use when displaying dates.
291The normal format is a pathname relative to
292.Pa /usr/share/zoneinfo .
293For example, the command
294.Dq TZ=America/Los_Angeles date
295displays the current time in California.
296See
297.Xr environ 7
298for more information.
299.El
300.Sh FILES
301.Bl -tag -width /var/log/messages -compact
302.It Pa /var/log/wtmp
303a record of date resets and time changes
304.It Pa /var/log/messages
305a record of the user setting the time
306.El
307.Sh SEE ALSO
308.Xr gettimeofday 2 ,
309.Xr strftime 3 ,
310.Xr strptime 3 ,
311.Xr utmp 5 ,
312.Xr timed 8
313.Rs
314.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
315.%A R. Gusella
316.%A S. Zatti
317.Re
318.Sh DIAGNOSTICS
319The
320.Nm
321utility exits 0 on success, 1 if unable to set the date, and 2
322if able to set the local date, but unable to set it globally.
323.Pp
324Occasionally, when
325.Xr timed
326synchronizes the time on many hosts, the setting of a new time value may
327require more than a few seconds.
328On these occasions,
329.Nm
330prints:
331.Ql Network time being set .
332The message
333.Ql Communication error with timed
334occurs when the communication
335between
336.Nm
337and
338.Xr timed
339fails.
340.Sh STANDARDS
341The
342.Nm
343command is expected to be compatible with
344.St -p1003.2 .
345.Sh HISTORY
346A
347.Nm
348command appeared in
349.At v1 .
| 200Refer to the examples below for further details.
201.El
202.Pp
203An operand with a leading plus
204.Pq Dq \&+
205sign signals a user-defined format string which specifies the format in
206which to display the date and time. The format string may contain any of
207the conversion specifications described in the
208.Xr strftime 3
209manual page, as well as any arbitrary text.
210A <newline> character is always output after the characters specified by
211the format string.
212The format string for the default display is
213.Dq +%+ .
214.Pp
215If an operand does not have a leading plus sign, it is interpreted as
216a value for setting the system's notion of the current date and time.
217The canonical representation for setting the date and time is:
218.Pp
219.Bl -tag -width Ds -compact -offset indent
220.It Ar cc
221Century
222.Pq either 19 or 20
223prepended to the abbreviated year.
224.It Ar yy
225Year in abbreviated form
226.Pq e.g. 89 for 1989, 06 for 2006 .
227.It Ar mm
228Numeric month.
229A number from 1 to 12.
230.It Ar dd
231Day, a number from 1 to 31.
232.It Ar HH
233Hour, a number from 0 to 23.
234.It Ar MM
235Minutes, a number from 0 to 59.
236.It Ar .ss
237Seconds, a number from 0 to 61
238.Pq 59 plus a maximum of two leap seconds .
239.El
240.Pp
241Everything but the minutes is optional.
242.Pp
243Time changes for Daylight Saving and Standard time and leap seconds
244and years are handled automatically.
245.Sh EXAMPLES
246The command:
247.Bd -literal -offset indent
248date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S"
249.Ed
250.Pp
251will display:
252.Bd -literal -offset indent
253DATE: 1987-11-21
254TIME: 13:36:16
255.Ed
256.Pp
257The command:
258.Bd -literal -offset indent
259date -v1m -v+1y
260.Ed
261.Pp
262will display:
263.Bd -literal -offset indent
264Sun Jan 4 03:15:24 GMT 1998
265.Ed
266.Pp
267where it is currently Mon Aug 4 04:15:24 BST 1997.
268.Pp
269The command:
270.Bd -literal -offset indent
271date -v1d -v3m -v0y -v-1d
272.Ed
273.Pp
274will display the last day of February in the year 2000:
275.Bd -literal -offset indent
276Tue Feb 29 03:18:00 GMT 2000
277.Ed
278.Pp
279The command:
280.Bd -literal -offset indent
281date -v1d -v+1m -v-1d -v-fri
282.Ed
283.Pp
284will display the last Friday of the month:
285.Bd -literal -offset indent
286Fri Aug 29 04:31:11 BST 1997
287.Ed
288.Pp
289where it is currently Mon Aug 4 04:31:11 BST 1997.
290.Pp
291The command:
292.Bd -literal -offset indent
293date 8506131627
294.Ed
295.Pp
296sets the date to
297.Dq Li "June 13, 1985, 4:27 PM" .
298.Pp
299The command:
300.Bd -literal -offset indent
301date 1432
302.Ed
303.Pp
304sets the time to
305.Li "2:32 PM" ,
306without modifying the date.
307.Sh ENVIRONMENT
308The execution of
309.Nm
310is affected by the following environment variables:
311.Bl -tag -width Ds
312.It Ev TZ
313The timezone to use when displaying dates.
314The normal format is a pathname relative to
315.Pa /usr/share/zoneinfo .
316For example, the command
317.Dq TZ=America/Los_Angeles date
318displays the current time in California.
319See
320.Xr environ 7
321for more information.
322.El
323.Sh FILES
324.Bl -tag -width /var/log/messages -compact
325.It Pa /var/log/wtmp
326a record of date resets and time changes
327.It Pa /var/log/messages
328a record of the user setting the time
329.El
330.Sh SEE ALSO
331.Xr gettimeofday 2 ,
332.Xr strftime 3 ,
333.Xr strptime 3 ,
334.Xr utmp 5 ,
335.Xr timed 8
336.Rs
337.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
338.%A R. Gusella
339.%A S. Zatti
340.Re
341.Sh DIAGNOSTICS
342The
343.Nm
344utility exits 0 on success, 1 if unable to set the date, and 2
345if able to set the local date, but unable to set it globally.
346.Pp
347Occasionally, when
348.Xr timed
349synchronizes the time on many hosts, the setting of a new time value may
350require more than a few seconds.
351On these occasions,
352.Nm
353prints:
354.Ql Network time being set .
355The message
356.Ql Communication error with timed
357occurs when the communication
358between
359.Nm
360and
361.Xr timed
362fails.
363.Sh STANDARDS
364The
365.Nm
366command is expected to be compatible with
367.St -p1003.2 .
368.Sh HISTORY
369A
370.Nm
371command appeared in
372.At v1 .
|