1DATE(1P) POSIX Programmer's Manual DATE(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 date — write the date and time
13
15 date [-u] [+format]
16 date [-u] mmddhhmm[[cc]yy]
18
20 The date utility shall write the date and time to standard output or
21 attempt to set the system date and time. By default, the current date
22 and time shall be written. If an operand beginning with '+' is speci‐
23 fied, the output format of date shall be controlled by the conversion
24 specifications and other text in the operand.
25
27 The date utility shall conform to the Base Definitions volume of
28 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
29 The following option shall be supported:
31 -u Perform operations as if the TZ environment variable was set
33 to the string "UTC0", or its equivalent historical value of
34 "GMT0". Otherwise, date shall use the timezone indicated by
35 the TZ environment variable or the system default if that
36 variable is unset or null.
37
39 The following operands shall be supported:
40 +format When the format is specified, each conversion specifier shall
42 be replaced in the standard output by its corresponding
43 value. All other characters shall be copied to the output
44 without change. The output shall always be terminated with a
45 <newline>.
46 Conversion Specifications
48 %a Locale's abbreviated weekday name.
49 %A Locale's full weekday name.
51 %b Locale's abbreviated month name.
53 %B Locale's full month name.
55 %c Locale's appropriate date and time representation.
57 %C Century (a year divided by 100 and truncated to an
59 integer) as a decimal number [00,99].
60 %d Day of the month as a decimal number [01,31].
62 %D Date in the format mm/dd/yy.
64 %e Day of the month as a decimal number [1,31] in a two-
66 digit field with leading <space> character fill.
67 %h A synonym for %b.
69 %H Hour (24-hour clock) as a decimal number [00,23].
71 %I Hour (12-hour clock) as a decimal number [01,12].
73 %j Day of the year as a decimal number [001,366].
75 %m Month as a decimal number [01,12].
77 %M Minute as a decimal number [00,59].
79 %n A <newline>.
81 %p Locale's equivalent of either AM or PM.
83 %r 12-hour clock time [01,12] using the AM/PM notation;
85 in the POSIX locale, this shall be equivalent to
86 %I:%M:%S %p.
87 %S Seconds as a decimal number [00,60].
89 %t A <tab>.
91 %T 24-hour clock time [00,23] in the format HH:MM:SS.
93 %u Weekday as a decimal number [1,7] (1=Monday).
95 %U Week of the year (Sunday as the first day of the
97 week) as a decimal number [00,53]. All days in a new
98 year preceding the first Sunday shall be considered
99 to be in week 0.
100 %V Week of the year (Monday as the first day of the
102 week) as a decimal number [01,53]. If the week con‐
103 taining January 1 has four or more days in the new
104 year, then it shall be considered week 1; otherwise,
105 it shall be the last week of the previous year, and
106 the next week shall be week 1.
107 %w Weekday as a decimal number [0,6] (0=Sunday).
109 %W Week of the year (Monday as the first day of the
111 week) as a decimal number [00,53]. All days in a new
112 year preceding the first Monday shall be considered
113 to be in week 0.
114 %x Locale's appropriate date representation.
116 %X Locale's appropriate time representation.
118 %y Year within century [00,99].
120 %Y Year with century as a decimal number.
122 %Z Timezone name, or no characters if no timezone is
124 determinable.
125 %% A <percent-sign> character.
127 See the Base Definitions volume of POSIX.1‐2017, Section
129 7.3.5, LC_TIME for the conversion specifier values in the
130 POSIX locale.
131 Modified Conversion Specifications
133 Some conversion specifiers can be modified by the E and O modifier
134 characters to indicate a different format or specification as specified
135 in the LC_TIME locale description (see the Base Definitions volume of
136 POSIX.1‐2017, Section 7.3.5, LC_TIME). If the corresponding keyword
137 (see era, era_year, era_d_fmt, and alt_digits in the Base Definitions
138 volume of POSIX.1‐2017, Section 7.3.5, LC_TIME) is not specified or not
139 supported for the current locale, the unmodified conversion specifier
140 value shall be used.
141 %Ec Locale's alternative appropriate date and time representation.
143 %EC The name of the base year (period) in the locale's alternative
145 representation.
146 %Ex Locale's alternative date representation.
148 %EX Locale's alternative time representation.
150 %Ey Offset from %EC (year only) in the locale's alternative repre‐
152 sentation.
153 %EY Full alternative year representation.
155 %Od Day of month using the locale's alternative numeric symbols.
157 %Oe Day of month using the locale's alternative numeric symbols.
159 %OH Hour (24-hour clock) using the locale's alternative numeric
161 symbols.
162 %OI Hour (12-hour clock) using the locale's alternative numeric
164 symbols.
165 %Om Month using the locale's alternative numeric symbols.
167 %OM Minutes using the locale's alternative numeric symbols.
169 %OS Seconds using the locale's alternative numeric symbols.
171 %Ou Weekday as a number in the locale's alternative representation
173 (Monday = 1).
174 %OU Week number of the year (Sunday as the first day of the week)
176 using the locale's alternative numeric symbols.
177 %OV Week number of the year (Monday as the first day of the week,
179 rules corresponding to %V), using the locale's alternative
180 numeric symbols.
181 %Ow Weekday as a number in the locale's alternative representation
183 (Sunday = 0).
184 %OW Week number of the year (Monday as the first day of the week)
186 using the locale's alternative numeric symbols.
187 %Oy Year (offset from %C) in alternative representation.
189 mmddhhmm[[cc]yy]
191 Attempt to set the system date and time from the value given
192 in the operand. This is only possible if the user has appro‐
193 priate privileges and the system permits the setting of the
194 system date and time. The first mm is the month (number); dd
195 is the day (number); hh is the hour (number, 24-hour system);
196 the second mm is the minute (number); cc is the century and
197 is the first two digits of the year (this is optional); yy is
198 the last two digits of the year and is optional. If century
199 is not specified, then values in the range [69,99] shall
200 refer to years 1969 to 1999 inclusive, and values in the
201 range [00,68] shall refer to years 2000 to 2068 inclusive.
202 The current year is the default if yy is omitted.
203 Note: It is expected that in a future version of this
205 standard the default century inferred from a
206 2-digit year will change. (This would apply to all
207 commands accepting a 2-digit year as input.)
208
210 Not used.
211
213 None.
214
216 The following environment variables shall affect the execution of date:
217 LANG Provide a default value for the internationalization vari‐
219 ables that are unset or null. (See the Base Definitions vol‐
220 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
221 ables for the precedence of internationalization variables
222 used to determine the values of locale categories.)
223 LC_ALL If set to a non-empty string value, override the values of
225 all the other internationalization variables.
226 LC_CTYPE Determine the locale for the interpretation of sequences of
228 bytes of text data as characters (for example, single-byte as
229 opposed to multi-byte characters in arguments).
230 LC_MESSAGES
232 Determine the locale that should be used to affect the format
233 and contents of diagnostic messages written to standard
234 error.
235 LC_TIME Determine the format and contents of date and time strings
237 written by date.
238 NLSPATH Determine the location of message catalogs for the processing
240 of LC_MESSAGES.
241 TZ Determine the timezone in which the time and date are writ‐
243 ten, unless the -u option is specified. If the TZ variable is
244 unset or null and -u is not specified, an unspecified system
245 default timezone is used.
246
248 Default.
249
251 When no formatting operand is specified, the output in the POSIX locale
252 shall be equivalent to specifying:
253 date "+%a %b %e %H:%M:%S %Z %Y"
256
258 The standard error shall be used only for diagnostic messages.
259
261 None.
262
264 None.
265
267 The following exit values shall be returned:
268 0 The date was written successfully.
270 >0 An error occurred.
272
274 Default.
275 The following sections are informative.
277
279 Conversion specifiers are of unspecified format when not in the POSIX
280 locale. Some of them can contain <newline> characters in some locales,
281 so it may be difficult to use the format shown in standard output for
282 parsing the output of date in those locales.
283 The range of values for %S extends from 0 to 60 seconds to accommodate
285 the occasional leap second.
286 Although certain of the conversion specifiers in the POSIX locale (such
288 as the name of the month) are shown with initial capital letters, this
289 need not be the case in other locales. Programs using these fields may
290 need to adjust the capitalization if the output is going to be used at
291 the beginning of a sentence.
292 The date string formatting capabilities are intended for use in Grego‐
294 rian-style calendars, possibly with a different starting year (or
295 years). The %x and %c conversion specifications, however, are intended
296 for local representation; these may be based on a different, non-Grego‐
297 rian calendar.
298 The %C conversion specification was introduced to allow a fallback for
300 the %EC (alternative year format base year); it can be viewed as the
301 base of the current subdivision in the Gregorian calendar. The century
302 number is calculated as the year divided by 100 and truncated to an
303 integer; it should not be confused with the use of ordinal numbers for
304 centuries (for example, ``twenty-first century''.) Both the %Ey and %y
305 can then be viewed as the offset from %EC and %C, respectively.
306 The E and O modifiers modify the traditional conversion specifiers, so
308 that they can always be used, even if the implementation (or the cur‐
309 rent locale) does not support the modifier.
310 The E modifier supports alternative date formats, such as the Japanese
312 Emperor's Era, as long as these are based on the Gregorian calendar
313 system. Extending the E modifiers to other date elements may provide an
314 implementation-defined extension capable of supporting other calendar
315 systems, especially in combination with the O modifier.
316 The O modifier supports time and date formats using the locale's alter‐
318 native numerical symbols, such as Kanji or Hindi digits or ordinal num‐
319 ber representation.
320 Non-European locales, whether they use Latin digits in computational
322 items or not, often have local forms of the digits for use in date for‐
323 mats. This is not totally unknown even in Europe; a variant of dates
324 uses Roman numerals for the months: the third day of September 1991
325 would be written as 3.IX.1991. In Japan, Kanji digits are regularly
326 used for dates; in Arabic-speaking countries, Hindi digits are used.
327 The %d, %e, %H, %I, %m, %S, %U, %w, %W, and %y conversion specifica‐
328 tions always return the date and time field in Latin digits (that is, 0
329 to 9). The %O modifier was introduced to support the use for display
330 purposes of non-Latin digits. In the LC_TIME category in localedef, the
331 optional alt_digits keyword is intended for this purpose. As an exam‐
332 ple, assume the following (partial) localedef source:
333 alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
336 "IX";"X";"XI";"XII"
337 d_fmt "%e.%Om.%Y"
338 With the above date, the command:
340 date "+%x"
343 would yield 3.IX.1991. With the same d_fmt, but without the alt_digits,
345 the command would yield 3.9.1991.
346
348 1. The following are input/output examples of date used at arbitrary
349 times in the POSIX locale:
350 $ date
353 Tue Jun 26 09:58:10 PDT 1990
354 $ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
356 DATE: 11/02/91
357 TIME: 13:36:16
358 $ date "+TIME: %r"
360 TIME: 01:36:32 PM
361 2. Examples for Denmark, where the default date and time format is %a
363 %d %b %Y %T %Z:
364 $ LANG=da_DK.iso_8859-1 date
367 ons 02 okt 1991 15:03:32 CET
368 $ LANG=da_DK.iso_8859-1 \
370 date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
371 DATO: onsdag den 2. oktober 1991
372 KLOKKEN: 15:03:56
373 3. Examples for Germany, where the default date and time format is %a
375 %d.%h.%Y, %T %Z:
376 $ LANG=De_DE.88591 date
379 Mi 02.Okt.1991, 15:01:21 MEZ
380 $ LANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
382 DATUM: Mittwoch, 02. Oktober 1991
383 ZEIT: 15:02:02
384 4. Examples for France, where the default date and time format is %a
386 %d %h %Y %Z %T:
387 $ LANG=Fr_FR.88591 date
390 Mer 02 oct 1991 MET 15:03:32
391 $ LANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
393 JOUR: Mercredi 02 octobre 1991
394 HEURE: 15:03:56
395
397 Some of the new options for formatting are from the ISO C standard. The
398 -u option was introduced to allow portable access to Coordinated Uni‐
399 versal Time (UTC). The string "GMT0" is allowed as an equivalent TZ
400 value to be compatible with all of the systems using the BSD implemen‐
401 tation, where this option originated.
402 The %e format conversion specification (adopted from System V) was
404 added because the ISO C standard conversion specifications did not pro‐
405 vide any way to produce the historical default date output during the
406 first nine days of any month.
407 There are two varieties of day and week numbering supported (in addi‐
409 tion to any others created with the locale-dependent %E and %O modifier
410 characters):
411 * The historical variety in which Sunday is the first day of the week
413 and the weekdays preceding the first Sunday of the year are consid‐
414 ered week 0. These are represented by %w and %U. A variant of this
415 is %W, using Monday as the first day of the week, but still refer‐
416 ring to week 0. This view of the calendar was retained because so
417 many historical applications depend on it and the ISO C standard
418 strftime() function, on which many date implementations are based,
419 was defined in this way.
420 * The international standard, based on the ISO 8601:2004 standard
422 where Monday is the first weekday and the algorithm for the first
423 week number is more complex: If the week (Monday to Sunday) con‐
424 taining January 1 has four or more days in the new year, then it is
425 week 1; otherwise, it is week 53 of the previous year, and the next
426 week is week 1. These are represented by the new conversion speci‐
427 fications %u and %V, added as a result of international comments.
428
430 None.
431
433 The Base Definitions volume of POSIX.1‐2017, Section 7.3.5, LC_TIME,
434 Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guide‐
435 lines
436 The System Interfaces volume of POSIX.1‐2017, fprintf(), strftime()
438
440 Portions of this text are reprinted and reproduced in electronic form
441 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
442 table Operating System Interface (POSIX), The Open Group Base Specifi‐
443 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
444 Electrical and Electronics Engineers, Inc and The Open Group. In the
445 event of any discrepancy between this version and the original IEEE and
446 The Open Group Standard, the original IEEE and The Open Group Standard
447 is the referee document. The original Standard can be obtained online
448 at http://www.opengroup.org/unix/online.html .
449 Any typographical or formatting errors that appear in this page are
451 most likely to have been introduced during the conversion of the source
452 files to man page format. To report such errors, see https://www.ker‐
453 nel.org/doc/man-pages/reporting_bugs.html .
454IEEE/The Open Group 2017 DATE(1P)