diff --git a/bin/date/date.1 b/bin/date/date.1 index d53f0bdbb5fa..8cb5aad52311 100644 --- a/bin/date/date.1 +++ b/bin/date/date.1 @@ -61,23 +61,26 @@ .Oc .Op Cm + Ns Ar format .Sh DESCRIPTION -.Nm Date -displays the current date and time when invoked without arguments. -Providing arguments will format the date and time in a user-defined -way or set the date. +When invoked without arguments, the +.Nm +utility displays the current date and time. +Otherwise, depending on the options specified, +.Nm +will set the date and time or print it in a user-defined way. +.Pp Only the superuser may set the date. .Pp The options are as follows: .Bl -tag -width Ds -.It Fl d -Set the kernel's value for daylight savings time. +.It Fl d Ar dst +Set the system's value for daylight saving time. If .Ar dst is non-zero, future calls to .Xr gettimeofday 2 -will return a non-zero -.Ql tz_dsttime . +will return a non-zero value for +.Fa tz_dsttime . .It Fl f Use .Ar fmt @@ -89,30 +92,29 @@ the default .Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns .Oc .No "\&MM" Ns Op "\&.ss" Xc -format. Parsing is done using +format. +Parsing is done using .Xr strptime 3 . .It Fl j -Do not try to set the date. This allows you to use the +Do not try to set the date. +This allows you to use the .Fl f flag in addition to the .Cm + option to convert one date format to another. .It Fl n -The utility +By default, +if the .Xr timed 8 -is used to synchronize the clocks on groups of machines. -By default, if -.Xr timed -is running, +daemon is running, .Nm -will set the time on all of the machines in the local group. +sets the time on all of the machines in the local group. The .Fl n -option stops -.Nm -from setting the time for other than the current machine. -.It Fl r -Print out the date and time that is +option suppresses this behavior and causes the time to be set only on the +current machine. +.It Fl r Ar seconds +Print out (in specified format) the date and time represented by .Ar seconds from the Epoch .Po @@ -120,19 +122,18 @@ from the Epoch see .Xr time 3 .Pc . -.It Fl t -Set the kernel's value for minutes west of +.It Fl t Ar minutes_west +Set the system's value for minutes west of .Tn GMT . -.Ar Minutes_west +.Ar minutes_west specifies the number of minutes returned in -.Ql tz_minuteswest +.Fa tz_minuteswest by future calls to .Xr gettimeofday 2 . .It Fl u Display or set the date in .Tn UTC -.Pq universal -time. +(Coordinated Universal) time. .It Fl v Adjust the second, minute, hour, month day, week day, month or year according to .Ar val . @@ -140,8 +141,9 @@ If .Ar val is preceded with a plus or minus sign, the date is adjusted forwards or backwards according to the remaining string, otherwise the relevant -part of the date is set. The date can be adjusted as many times as -required using these flags. Flags are processed in the order given. +part of the date is set. +The date can be adjusted as many times as required using these flags. +Flags are processed in the order given. .Pp When setting values .Pq rather than adjusting them , @@ -167,18 +169,20 @@ or must be used to specify which part of the date is to be adjusted. .Pp The week day or month may be specified using a name rather than a -number. If a name is used with the plus +number. +If a name is used with the plus .Pq or minus sign, the date will be put forwards .Pq or backwards to the next .Pq previous -date that matches the given week day or month. This will not adjust the date +date that matches the given week day or month. +This will not adjust the date if the given week day or month is the same as the current one. .Pp When a date is adjusted to a specific value or in units greater than hours, -daylight savings time considerations are ignored. -Adjustments in units of hours or less honour daylight savings time. +daylight saving time considerations are ignored. +Adjustments in units of hours or less honor daylight saving time. So, assuming the current date is March 26, 0:30 and that the DST adjustment means that the clock goes forward at 01:00 to 02:00, using .Fl v No +1H @@ -200,14 +204,17 @@ the two times. Refer to the examples below for further details. .El .Pp -An operand with a leading plus -.Pq Dq \&+ -sign signals a user-defined format string which specifies the format in -which to display the date and time. The format string may contain any of -the conversion specifications described in the +An operand with a leading plus sign +.Pq Sq + +signals a user-defined format +string which specifies the format in which to display the date and time. +The format string may contain any of the conversion specifications described +in the .Xr strftime 3 manual page, as well as any arbitrary text. -A character is always output after the characters specified by +A newline +.Pq Ql \en +character is always output after the characters specified by the format string. The format string for the default display is .Dq +%+ . @@ -225,23 +232,22 @@ prepended to the abbreviated year. Year in abbreviated form .Pq e.g. 89 for 1989, 06 for 2006 . .It Ar mm -Numeric month. -A number from 1 to 12. +Numeric month, a number from 1 to 12. .It Ar dd Day, a number from 1 to 31. .It Ar HH Hour, a number from 0 to 23. .It Ar MM Minutes, a number from 0 to 59. -.It Ar .ss +.It Ar ss Seconds, a number from 0 to 61 .Pq 59 plus a maximum of two leap seconds . .El .Pp Everything but the minutes is optional. .Pp -Time changes for Daylight Saving and Standard time and leap seconds -and years are handled automatically. +Time changes for Daylight Saving Time, standard time, leap seconds, +and leap years are handled automatically. .Sh EXAMPLES The command: .Bd -literal -offset indent @@ -305,9 +311,8 @@ sets the time to .Li "2:32 PM" , without modifying the date. .Sh ENVIRONMENT -The execution of -.Nm -is affected by the following environment variables: +The following environment variables affect the execution of +.Nm date : .Bl -tag -width Ds .It Ev TZ The timezone to use when displaying dates. @@ -323,9 +328,9 @@ for more information. .Sh FILES .Bl -tag -width /var/log/messages -compact .It Pa /var/log/wtmp -a record of date resets and time changes +record of date resets and time changes .It Pa /var/log/messages -a record of the user setting the time +record of the user setting the time .El .Sh SEE ALSO .Xr gettimeofday 2 , @@ -339,31 +344,29 @@ a record of the user setting the time .%A S. Zatti .Re .Sh DIAGNOSTICS -The -.Nm -utility exits 0 on success, 1 if unable to set the date, and 2 +Exit status is 0 on success, 1 if unable to set the date, and 2 if able to set the local date, but unable to set it globally. .Pp Occasionally, when -.Xr timed +.Xr timed 8 synchronizes the time on many hosts, the setting of a new time value may require more than a few seconds. On these occasions, .Nm prints: -.Ql Network time being set . +.Dq Network time being set . The message -.Ql Communication error with timed +.Dq Communication error with timed occurs when the communication between .Nm and -.Xr timed +.Xr timed 8 fails. .Sh STANDARDS The .Nm -command is expected to be compatible with +utility is expected to be compatible with .St -p1003.2 . .Sh HISTORY A