1 |
.\"- |
2 |
.\" Copyright (c) 1980, 1990, 1993 |
3 |
.\" The Regents of the University of California. All rights reserved. |
4 |
.\" |
5 |
.\" This code is derived from software contributed to Berkeley by |
6 |
.\" the Institute of Electrical and Electronics Engineers, Inc. |
7 |
.\" |
8 |
.\" Redistribution and use in source and binary forms, with or without |
9 |
.\" modification, are permitted provided that the following conditions |
10 |
.\" are met: |
11 |
.\" 1. Redistributions of source code must retain the above copyright |
12 |
.\" notice, this list of conditions and the following disclaimer. |
13 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
14 |
.\" notice, this list of conditions and the following disclaimer in the |
15 |
.\" documentation and/or other materials provided with the distribution. |
16 |
.\" 4. Neither the name of the University nor the names of its contributors |
17 |
.\" may be used to endorse or promote products derived from this software |
18 |
.\" without specific prior written permission. |
19 |
.\" |
20 |
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
22 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
23 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
24 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
25 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
26 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
27 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
28 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
29 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
30 |
.\" SUCH DAMAGE. |
31 |
.\" |
32 |
.\" @(#)date.1 8.3 (Berkeley) 4/28/95 |
33 |
.\" $FreeBSD: stable/9/bin/date/date.1 208795 2010-06-04 06:56:58Z brian $ |
34 |
.\" |
35 |
.Dd June 3, 2010 |
36 |
.Dt DATE 1 |
37 |
.Os |
38 |
.Sh NAME |
39 |
.Nm date |
40 |
.Nd display or set date and time |
41 |
.Sh SYNOPSIS |
42 |
.Nm |
43 |
.Op Fl ju |
44 |
.Op Fl r Ar seconds |
45 |
.Oo |
46 |
.Fl v |
47 |
.Sm off |
48 |
.Op Cm + | - |
49 |
.Ar val Op Ar ymwdHMS |
50 |
.Sm on |
51 |
.Oc |
52 |
.Ar ... |
53 |
.Op Cm + Ns Ar output_fmt |
54 |
.Nm |
55 |
.Op Fl jnu |
56 |
.Sm off |
57 |
.Op Oo Oo Oo Oo Ar cc Oc Ar yy Oc Ar mm Oc Ar dd Oc Ar HH |
58 |
.Ar MM Op Ar .ss |
59 |
.Sm on |
60 |
.Nm |
61 |
.Op Fl jnu |
62 |
.Fl f Ar input_fmt new_date |
63 |
.Op Cm + Ns Ar output_fmt |
64 |
.Nm |
65 |
.Op Fl d Ar dst |
66 |
.Op Fl t Ar minutes_west |
67 |
.Sh DESCRIPTION |
68 |
When invoked without arguments, the |
69 |
.Nm |
70 |
utility displays the current date and time. |
71 |
Otherwise, depending on the options specified, |
72 |
.Nm |
73 |
will set the date and time or print it in a user-defined way. |
74 |
.Pp |
75 |
The |
76 |
.Nm |
77 |
utility displays the date and time read from the kernel clock. |
78 |
When used to set the date and time, |
79 |
both the kernel clock and the hardware clock are updated. |
80 |
.Pp |
81 |
Only the superuser may set the date, |
82 |
and if the system securelevel (see |
83 |
.Xr securelevel 7 ) |
84 |
is greater than 1, |
85 |
the time may not be changed by more than 1 second. |
86 |
.Pp |
87 |
The options are as follows: |
88 |
.Bl -tag -width Ds |
89 |
.It Fl d Ar dst |
90 |
Set the kernel's value for daylight saving time. |
91 |
If |
92 |
.Ar dst |
93 |
is non-zero, future calls |
94 |
to |
95 |
.Xr gettimeofday 2 |
96 |
will return a non-zero for |
97 |
.Fa tz_dsttime . |
98 |
.It Fl f |
99 |
Use |
100 |
.Ar input_fmt |
101 |
as the format string to parse the |
102 |
.Ar new_date |
103 |
provided rather than using the default |
104 |
.Sm off |
105 |
.Oo Oo Oo Oo Oo |
106 |
.Ar cc Oc |
107 |
.Ar yy Oc |
108 |
.Ar mm Oc |
109 |
.Ar dd Oc |
110 |
.Ar HH |
111 |
.Oc Ar MM Op Ar .ss |
112 |
.Sm on |
113 |
format. |
114 |
Parsing is done using |
115 |
.Xr strptime 3 . |
116 |
.It Fl j |
117 |
Do not try to set the date. |
118 |
This allows you to use the |
119 |
.Fl f |
120 |
flag in addition to the |
121 |
.Cm + |
122 |
option to convert one date format to another. |
123 |
.It Fl n |
124 |
By default, if the |
125 |
.Xr timed 8 |
126 |
daemon is running, |
127 |
.Nm |
128 |
sets the time on all of the machines in the local group. |
129 |
The |
130 |
.Fl n |
131 |
option suppresses this behavior and causes the time to be set only on the |
132 |
current machine. |
133 |
.It Fl r Ar seconds |
134 |
Print the date and time represented by |
135 |
.Ar seconds , |
136 |
where |
137 |
.Ar seconds |
138 |
is the number of seconds since the Epoch |
139 |
(00:00:00 UTC, January 1, 1970; |
140 |
see |
141 |
.Xr time 3 ) , |
142 |
and can be specified in decimal, octal, or hex. |
143 |
.It Fl t Ar minutes_west |
144 |
Set the system's value for minutes west of |
145 |
.Tn GMT . |
146 |
.Ar minutes_west |
147 |
specifies the number of minutes returned in |
148 |
.Fa tz_minuteswest |
149 |
by future calls to |
150 |
.Xr gettimeofday 2 . |
151 |
.It Fl u |
152 |
Display or set the date in |
153 |
.Tn UTC |
154 |
(Coordinated Universal) time. |
155 |
.It Fl v |
156 |
Adjust (i.e., take the current date and display the result of the |
157 |
adjustment; not actually set the date) the second, minute, hour, month |
158 |
day, week day, month or year according to |
159 |
.Ar val . |
160 |
If |
161 |
.Ar val |
162 |
is preceded with a plus or minus sign, |
163 |
the date is adjusted forwards or backwards according to the remaining string, |
164 |
otherwise the relevant part of the date is set. |
165 |
The date can be adjusted as many times as required using these flags. |
166 |
Flags are processed in the order given. |
167 |
.Pp |
168 |
When setting values |
169 |
(rather than adjusting them), |
170 |
seconds are in the range 0-59, minutes are in the range 0-59, hours are |
171 |
in the range 0-23, month days are in the range 1-31, week days are in the |
172 |
range 0-6 (Sun-Sat), |
173 |
months are in the range 1-12 (Jan-Dec) |
174 |
and years are in the range 80-38 or 1980-2038. |
175 |
.Pp |
176 |
If |
177 |
.Ar val |
178 |
is numeric, one of either |
179 |
.Ar y , |
180 |
.Ar m , |
181 |
.Ar w , |
182 |
.Ar d , |
183 |
.Ar H , |
184 |
.Ar M |
185 |
or |
186 |
.Ar S |
187 |
must be used to specify which part of the date is to be adjusted. |
188 |
.Pp |
189 |
The week day or month may be specified using a name rather than a |
190 |
number. |
191 |
If a name is used with the plus |
192 |
(or minus) |
193 |
sign, the date will be put forwards |
194 |
(or backwards) |
195 |
to the next |
196 |
(previous) |
197 |
date that matches the given week day or month. |
198 |
This will not adjust the date, |
199 |
if the given week day or month is the same as the current one. |
200 |
.Pp |
201 |
When a date is adjusted to a specific value or in units greater than hours, |
202 |
daylight savings time considerations are ignored. |
203 |
Adjustments in units of hours or less honor daylight saving time. |
204 |
So, assuming the current date is March 26, 0:30 and that the DST adjustment |
205 |
means that the clock goes forward at 01:00 to 02:00, using |
206 |
.Fl v No +1H |
207 |
will adjust the date to March 26, 2:30. |
208 |
Likewise, if the date is October 29, 0:30 and the DST adjustment means that |
209 |
the clock goes back at 02:00 to 01:00, using |
210 |
.Fl v No +3H |
211 |
will be necessary to reach October 29, 2:30. |
212 |
.Pp |
213 |
When the date is adjusted to a specific value that does not actually exist |
214 |
(for example March 26, 1:30 BST 2000 in the Europe/London timezone), |
215 |
the date will be silently adjusted forwards in units of one hour until it |
216 |
reaches a valid time. |
217 |
When the date is adjusted to a specific value that occurs twice |
218 |
(for example October 29, 1:30 2000), |
219 |
the resulting timezone will be set so that the date matches the earlier of |
220 |
the two times. |
221 |
.Pp |
222 |
It is not possible to adjust a date to an invalid absolute day, so using |
223 |
the switches |
224 |
.Fl v No 31d Fl v No 12m |
225 |
will simply fail five months of the year. |
226 |
It is therefore usual to set the month before setting the day; using |
227 |
.Fl v No 12m Fl v No 31d |
228 |
always works. |
229 |
.Pp |
230 |
Adjusting the date by months is inherently ambiguous because |
231 |
a month is a unit of variable length depending on the current date. |
232 |
This kind of date adjustment is applied in the most intuitive way. |
233 |
First of all, |
234 |
.Nm |
235 |
tries to preserve the day of the month. |
236 |
If it is impossible because the target month is shorter than the present one, |
237 |
the last day of the target month will be the result. |
238 |
For example, using |
239 |
.Fl v No +1m |
240 |
on May 31 will adjust the date to June 30, while using the same option |
241 |
on January 30 will result in the date adjusted to the last day of February. |
242 |
This approach is also believed to make the most sense for shell scripting. |
243 |
Nevertheless, be aware that going forth and back by the same number of |
244 |
months may take you to a different date. |
245 |
.Pp |
246 |
Refer to the examples below for further details. |
247 |
.El |
248 |
.Pp |
249 |
An operand with a leading plus |
250 |
.Pq Sq + |
251 |
sign signals a user-defined format string |
252 |
which specifies the format in which to display the date and time. |
253 |
The format string may contain any of the conversion specifications |
254 |
described in the |
255 |
.Xr strftime 3 |
256 |
manual page, as well as any arbitrary text. |
257 |
A newline |
258 |
.Pq Ql \en |
259 |
character is always output after the characters specified by |
260 |
the format string. |
261 |
The format string for the default display is |
262 |
.Dq +%+ . |
263 |
.Pp |
264 |
If an operand does not have a leading plus sign, it is interpreted as |
265 |
a value for setting the system's notion of the current date and time. |
266 |
The canonical representation for setting the date and time is: |
267 |
.Pp |
268 |
.Bl -tag -width Ds -compact -offset indent |
269 |
.It Ar cc |
270 |
Century |
271 |
(either 19 or 20) |
272 |
prepended to the abbreviated year. |
273 |
.It Ar yy |
274 |
Year in abbreviated form |
275 |
(e.g., 89 for 1989, 06 for 2006). |
276 |
.It Ar mm |
277 |
Numeric month, a number from 1 to 12. |
278 |
.It Ar dd |
279 |
Day, a number from 1 to 31. |
280 |
.It Ar HH |
281 |
Hour, a number from 0 to 23. |
282 |
.It Ar MM |
283 |
Minutes, a number from 0 to 59. |
284 |
.It Ar ss |
285 |
Seconds, a number from 0 to 61 |
286 |
(59 plus a maximum of two leap seconds). |
287 |
.El |
288 |
.Pp |
289 |
Everything but the minutes is optional. |
290 |
.Pp |
291 |
Time changes for Daylight Saving Time, standard time, leap seconds, |
292 |
and leap years are handled automatically. |
293 |
.Sh ENVIRONMENT |
294 |
The following environment variables affect the execution of |
295 |
.Nm : |
296 |
.Bl -tag -width Ds |
297 |
.It Ev TZ |
298 |
The timezone to use when displaying dates. |
299 |
The normal format is a pathname relative to |
300 |
.Pa /usr/share/zoneinfo . |
301 |
For example, the command |
302 |
.Dq TZ=America/Los_Angeles date |
303 |
displays the current time in California. |
304 |
See |
305 |
.Xr environ 7 |
306 |
for more information. |
307 |
.El |
308 |
.Sh FILES |
309 |
.Bl -tag -width /var/log/messages -compact |
310 |
.It Pa /var/log/utx.log |
311 |
record of date resets and time changes |
312 |
.It Pa /var/log/messages |
313 |
record of the user setting the time |
314 |
.El |
315 |
.Sh EXIT STATUS |
316 |
The |
317 |
.Nm |
318 |
utility exits 0 on success, 1 if unable to set the date, and 2 |
319 |
if able to set the local date, but unable to set it globally. |
320 |
.Sh EXAMPLES |
321 |
The command: |
322 |
.Pp |
323 |
.Dl "date ""+DATE: %Y-%m-%d%nTIME: %H:%M:%S""" |
324 |
.Pp |
325 |
will display: |
326 |
.Bd -literal -offset indent |
327 |
DATE: 1987-11-21 |
328 |
TIME: 13:36:16 |
329 |
.Ed |
330 |
.Pp |
331 |
In the Europe/London timezone, the command: |
332 |
.Pp |
333 |
.Dl "date -v1m -v+1y" |
334 |
.Pp |
335 |
will display: |
336 |
.Pp |
337 |
.Dl "Sun Jan 4 04:15:24 GMT 1998" |
338 |
.Pp |
339 |
where it is currently |
340 |
.Li "Mon Aug 4 04:15:24 BST 1997" . |
341 |
.Pp |
342 |
The command: |
343 |
.Pp |
344 |
.Dl "date -v1d -v3m -v0y -v-1d" |
345 |
.Pp |
346 |
will display the last day of February in the year 2000: |
347 |
.Pp |
348 |
.Dl "Tue Feb 29 03:18:00 GMT 2000" |
349 |
.Pp |
350 |
So will the command: |
351 |
.Pp |
352 |
.Dl "date -v3m -v30d -v0y -v-1m" |
353 |
.Pp |
354 |
because there is no such date as the 30th of February. |
355 |
.Pp |
356 |
The command: |
357 |
.Pp |
358 |
.Dl "date -v1d -v+1m -v-1d -v-fri" |
359 |
.Pp |
360 |
will display the last Friday of the month: |
361 |
.Pp |
362 |
.Dl "Fri Aug 29 04:31:11 BST 1997" |
363 |
.Pp |
364 |
where it is currently |
365 |
.Li "Mon Aug 4 04:31:11 BST 1997" . |
366 |
.Pp |
367 |
The command: |
368 |
.Pp |
369 |
.Dl "date 8506131627" |
370 |
.Pp |
371 |
sets the date to |
372 |
.Dq Li "June 13, 1985, 4:27 PM" . |
373 |
.Pp |
374 |
.Dl "date ""+%Y%m%d%H%M.%S""" |
375 |
.Pp |
376 |
may be used on one machine to print out the date |
377 |
suitable for setting on another. |
378 |
.Qq ( Li "+%m%d%H%M%Y.%S" |
379 |
for use on |
380 |
.Tn Linux . ) |
381 |
.Pp |
382 |
The command: |
383 |
.Pp |
384 |
.Dl "date 1432" |
385 |
.Pp |
386 |
sets the time to |
387 |
.Li "2:32 PM" , |
388 |
without modifying the date. |
389 |
.Pp |
390 |
Finally the command: |
391 |
.Pp |
392 |
.Dl "date -j -f ""%a %b %d %T %Z %Y"" ""`date`"" ""+%s""" |
393 |
.Pp |
394 |
can be used to parse the output from |
395 |
.Nm |
396 |
and express it in Epoch time. |
397 |
.Sh DIAGNOSTICS |
398 |
Occasionally, when |
399 |
.Xr timed 8 |
400 |
synchronizes the time on many hosts, the setting of a new time value may |
401 |
require more than a few seconds. |
402 |
On these occasions, |
403 |
.Nm |
404 |
prints: |
405 |
.Ql Network time being set . |
406 |
The message |
407 |
.Ql Communication error with timed |
408 |
occurs when the communication |
409 |
between |
410 |
.Nm |
411 |
and |
412 |
.Xr timed 8 |
413 |
fails. |
414 |
.Sh SEE ALSO |
415 |
.Xr locale 1 , |
416 |
.Xr gettimeofday 2 , |
417 |
.Xr getutxent 3 , |
418 |
.Xr strftime 3 , |
419 |
.Xr strptime 3 , |
420 |
.Xr timed 8 |
421 |
.Rs |
422 |
.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" |
423 |
.%A R. Gusella |
424 |
.%A S. Zatti |
425 |
.Re |
426 |
.Sh STANDARDS |
427 |
The |
428 |
.Nm |
429 |
utility is expected to be compatible with |
430 |
.St -p1003.2 . |
431 |
The |
432 |
.Fl d , f , j , n , r , t , |
433 |
and |
434 |
.Fl v |
435 |
options are all extensions to the standard. |
436 |
.Sh HISTORY |
437 |
A |
438 |
.Nm |
439 |
command appeared in |
440 |
.At v1 . |