1DATE(1P)                   POSIX Programmer's Manual                  DATE(1P)
2
3
4

PROLOG

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

NAME

12       date — write the date and time
13

SYNOPSIS

15       date [-u] [+format]
16
17       date [-u] mmddhhmm[[cc]yy]
18

DESCRIPTION

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

OPTIONS

27       The date utility shall  conform  to  the  Base  Definitions  volume  of
28       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
29
30       The following option shall be supported:
31
32       -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

OPERANDS

39       The following operands shall be supported:
40
41       +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
47   Conversion Specifications
48                 %a      Locale's abbreviated weekday name.
49
50                 %A      Locale's full weekday name.
51
52                 %b      Locale's abbreviated month name.
53
54                 %B      Locale's full month name.
55
56                 %c      Locale's appropriate date and time representation.
57
58                 %C      Century  (a  year  divided by 100 and truncated to an
59                         integer) as a decimal number [00,99].
60
61                 %d      Day of the month as a decimal number [01,31].
62
63                 %D      Date in the format mm/dd/yy.
64
65                 %e      Day of the month as a decimal number [1,31] in a two-
66                         digit field with leading <space> character fill.
67
68                 %h      A synonym for %b.
69
70                 %H      Hour (24-hour clock) as a decimal number [00,23].
71
72                 %I      Hour (12-hour clock) as a decimal number [01,12].
73
74                 %j      Day of the year as a decimal number [001,366].
75
76                 %m      Month as a decimal number [01,12].
77
78                 %M      Minute as a decimal number [00,59].
79
80                 %n      A <newline>.
81
82                 %p      Locale's equivalent of either AM or PM.
83
84                 %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
88                 %S      Seconds as a decimal number [00,60].
89
90                 %t      A <tab>.
91
92                 %T      24-hour clock time [00,23] in the format HH:MM:SS.
93
94                 %u      Weekday as a decimal number [1,7] (1=Monday).
95
96                 %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
101                 %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
108                 %w      Weekday as a decimal number [0,6] (0=Sunday).
109
110                 %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
115                 %x      Locale's appropriate date representation.
116
117                 %X      Locale's appropriate time representation.
118
119                 %y      Year within century [00,99].
120
121                 %Y      Year with century as a decimal number.
122
123                 %Z      Timezone name, or no characters  if  no  timezone  is
124                         determinable.
125
126                 %%      A <percent-sign> character.
127
128                 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
132   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
142       %Ec     Locale's alternative appropriate date and time representation.
143
144       %EC     The name of the base year (period) in the locale's  alternative
145               representation.
146
147       %Ex     Locale's alternative date representation.
148
149       %EX     Locale's alternative time representation.
150
151       %Ey     Offset  from %EC (year only) in the locale's alternative repre‐
152               sentation.
153
154       %EY     Full alternative year representation.
155
156       %Od     Day of month using the locale's alternative numeric symbols.
157
158       %Oe     Day of month using the locale's alternative numeric symbols.
159
160       %OH     Hour (24-hour clock) using  the  locale's  alternative  numeric
161               symbols.
162
163       %OI     Hour  (12-hour  clock)  using  the locale's alternative numeric
164               symbols.
165
166       %Om     Month using the locale's alternative numeric symbols.
167
168       %OM     Minutes using the locale's alternative numeric symbols.
169
170       %OS     Seconds using the locale's alternative numeric symbols.
171
172       %Ou     Weekday as a number in the locale's alternative  representation
173               (Monday = 1).
174
175       %OU     Week  number  of the year (Sunday as the first day of the week)
176               using the locale's alternative numeric symbols.
177
178       %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
182       %Ow     Weekday as a number in the locale's alternative  representation
183               (Sunday = 0).
184
185       %OW     Week  number  of the year (Monday as the first day of the week)
186               using the locale's alternative numeric symbols.
187
188       %Oy     Year (offset from %C) in alternative representation.
189
190       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
204                 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

STDIN

210       Not used.
211

INPUT FILES

213       None.
214

ENVIRONMENT VARIABLES

216       The following environment variables shall affect the execution of date:
217
218       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
224       LC_ALL    If set to a non-empty string value, override  the  values  of
225                 all the other internationalization variables.
226
227       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
231       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
236       LC_TIME   Determine  the  format  and contents of date and time strings
237                 written by date.
238
239       NLSPATH   Determine the location of message catalogs for the processing
240                 of LC_MESSAGES.
241
242       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

ASYNCHRONOUS EVENTS

248       Default.
249

STDOUT

251       When no formatting operand is specified, the output in the POSIX locale
252       shall be equivalent to specifying:
253
254
255           date "+%a %b %e %H:%M:%S %Z %Y"
256

STDERR

258       The standard error shall be used only for diagnostic messages.
259

OUTPUT FILES

261       None.
262

EXTENDED DESCRIPTION

264       None.
265

EXIT STATUS

267       The following exit values shall be returned:
268
269        0    The date was written successfully.
270
271       >0    An error occurred.
272

CONSEQUENCES OF ERRORS

274       Default.
275
276       The following sections are informative.
277

APPLICATION USAGE

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
284       The range of values for %S extends from 0 to 60 seconds to  accommodate
285       the occasional leap second.
286
287       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
293       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
299       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
307       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
311       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
317       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
321       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
334
335           alt_digits  "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
336                       "IX";"X";"XI";"XII"
337           d_fmt       "%e.%Om.%Y"
338
339       With the above date, the command:
340
341
342           date "+%x"
343
344       would yield 3.IX.1991. With the same d_fmt, but without the alt_digits,
345       the command would yield 3.9.1991.
346

EXAMPLES

348        1. The  following  are input/output examples of date used at arbitrary
349           times in the POSIX locale:
350
351
352               $ date
353               Tue Jun 26 09:58:10 PDT 1990
354
355               $ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
356               DATE: 11/02/91
357               TIME: 13:36:16
358
359               $ date "+TIME: %r"
360               TIME: 01:36:32 PM
361
362        2. Examples for Denmark, where the default date and time format is  %a
363           %d %b %Y %T %Z:
364
365
366               $ LANG=da_DK.iso_8859-1 date
367               ons 02 okt 1991 15:03:32 CET
368
369               $ 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
374        3. Examples  for Germany, where the default date and time format is %a
375           %d.%h.%Y, %T %Z:
376
377
378               $ LANG=De_DE.88591 date
379               Mi 02.Okt.1991, 15:01:21 MEZ
380
381               $ 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
385        4. Examples for France, where the default date and time format  is  %a
386           %d %h %Y %Z %T:
387
388
389               $ LANG=Fr_FR.88591 date
390               Mer 02 oct 1991 MET 15:03:32
391
392               $ 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

RATIONALE

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
403       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
408       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
412        *  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
421        *  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

FUTURE DIRECTIONS

430       None.
431

SEE ALSO

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
437       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
450       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 .
454
455
456
457IEEE/The Open Group                  2017                             DATE(1P)
Impressum