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
11

NAME

13       date — write the date and time
14

SYNOPSIS

16       date [−u] [+format]
17
18       date [−u] mmddhhmm[[cc]yy]
19

DESCRIPTION

21       The date utility shall write the date and time to  standard  output  or
22       attempt  to set the system date and time.  By default, the current date
23       and time shall be written. If an operand beginning with '+'  is  speci‐
24       fied,  the  output format of date shall be controlled by the conversion
25       specifications and other text in the operand.
26

OPTIONS

28       The date utility shall  conform  to  the  Base  Definitions  volume  of
29       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
30
31       The following option shall be supported:
32
33       −u        Perform  operations as if the TZ environment variable was set
34                 to the string "UTC0", or its equivalent historical  value  of
35                 "GMT0".   Otherwise, date shall use the timezone indicated by
36                 the TZ environment variable or the  system  default  if  that
37                 variable is unset or null.
38

OPERANDS

40       The following operands shall be supported:
41
42       +format   When the format is specified, each conversion specifier shall
43                 be replaced in  the  standard  output  by  its  corresponding
44                 value.  All  other  characters  shall be copied to the output
45                 without change. The output shall always be terminated with  a
46                 <newline>.
47
48   Conversion Specifications
49                 %a      Locale's abbreviated weekday name.
50
51                 %A      Locale's full weekday name.
52
53                 %b      Locale's abbreviated month name.
54
55                 %B      Locale's full month name.
56
57                 %c      Locale's appropriate date and time representation.
58
59                 %C      Century  (a  year  divided by 100 and truncated to an
60                         integer) as a decimal number [00,99].
61
62                 %d      Day of the month as a decimal number [01,31].
63
64                 %D      Date in the format mm/dd/yy.
65
66                 %e      Day of the month as a decimal number [1,31] in a two-
67                         digit field with leading <space> character fill.
68
69                 %h      A synonym for %b.
70
71                 %H      Hour (24-hour clock) as a decimal number [00,23].
72
73                 %I      Hour (12-hour clock) as a decimal number [01,12].
74
75                 %j      Day of the year as a decimal number [001,366].
76
77                 %m      Month as a decimal number [01,12].
78
79                 %M      Minute as a decimal number [00,59].
80
81                 %n      A <newline>.
82
83                 %p      Locale's equivalent of either AM or PM.
84
85                 %r      12-hour  clock time [01,12] using the AM/PM notation;
86                         in the POSIX locale,  this  shall  be  equivalent  to
87                         %I:%M:%S %p.
88
89                 %S      Seconds as a decimal number [00,60].
90
91                 %t      A <tab>.
92
93                 %T      24-hour clock time [00,23] in the format HH:MM:SS.
94
95                 %u      Weekday as a decimal number [1,7] (1=Monday).
96
97                 %U      Week  of  the  year  (Sunday  as the first day of the
98                         week) as a decimal number [00,53]. All days in a  new
99                         year  preceding  the first Sunday shall be considered
100                         to be in week 0.
101
102                 %V      Week of the year (Monday as  the  first  day  of  the
103                         week)  as  a decimal number [01,53]. If the week con‐
104                         taining January 1 has four or more days  in  the  new
105                         year,  then it shall be considered week 1; otherwise,
106                         it shall be the last week of the previous  year,  and
107                         the next week shall be week 1.
108
109                 %w      Weekday as a decimal number [0,6] (0=Sunday).
110
111                 %W      Week  of  the  year  (Monday  as the first day of the
112                         week) as a decimal number [00,53]. All days in a  new
113                         year  preceding  the first Monday shall be considered
114                         to be in week 0.
115
116                 %x      Locale's appropriate date representation.
117
118                 %X      Locale's appropriate time representation.
119
120                 %y      Year within century [00,99].
121
122                 %Y      Year with century as a decimal number.
123
124                 %Z      Timezone name, or no characters  if  no  timezone  is
125                         determinable.
126
127                 %%      A <percent-sign> character.
128
129                 See  the  Base  Definitions  volume  of POSIX.1‐2008, Section
130                 7.3.5, LC_TIME for the conversion  specifier  values  in  the
131                 POSIX locale.
132
133   Modified Conversion Specifications
134       Some  conversion  specifiers  can  be  modified by the E and O modifier
135       characters to indicate a different format or specification as specified
136       in  the  LC_TIME locale description (see the Base Definitions volume of
137       POSIX.1‐2008, Section 7.3.5, LC_TIME).  If  the  corresponding  keyword
138       (see  era,  era_year, era_d_fmt, and alt_digits in the Base Definitions
139       volume of POSIX.1‐2008, Section 7.3.5, LC_TIME) is not specified or not
140       supported  for  the current locale, the unmodified conversion specifier
141       value shall be used.
142
143       %Ec     Locale's alternative appropriate date and time representation.
144
145       %EC     The name of the base year (period) in the locale's  alternative
146               representation.
147
148       %Ex     Locale's alternative date representation.
149
150       %EX     Locale's alternative time representation.
151
152       %Ey     Offset  from %EC (year only) in the locale's alternative repre‐
153               sentation.
154
155       %EY     Full alternative year representation.
156
157       %Od     Day of month using the locale's alternative numeric symbols.
158
159       %Oe     Day of month using the locale's alternative numeric symbols.
160
161       %OH     Hour (24-hour clock) using  the  locale's  alternative  numeric
162               symbols.
163
164       %OI     Hour  (12-hour  clock)  using  the locale's alternative numeric
165               symbols.
166
167       %Om     Month using the locale's alternative numeric symbols.
168
169       %OM     Minutes using the locale's alternative numeric symbols.
170
171       %OS     Seconds using the locale's alternative numeric symbols.
172
173       %Ou     Weekday as a number in the locale's alternative  representation
174               (Monday = 1).
175
176       %OU     Week  number  of the year (Sunday as the first day of the week)
177               using the locale's alternative numeric symbols.
178
179       %OV     Week number of the year (Monday as the first day of  the  week,
180               rules  corresponding  to  %V),  using  the locale's alternative
181               numeric symbols.
182
183       %Ow     Weekday as a number in the locale's alternative  representation
184               (Sunday = 0).
185
186       %OW     Week  number  of the year (Monday as the first day of the week)
187               using the locale's alternative numeric symbols.
188
189       %Oy     Year (offset from %C) in alternative representation.
190
191       mmddhhmm[[cc]yy]
192                 Attempt to set the system date and time from the value  given
193                 in  the operand. This is only possible if the user has appro‐
194                 priate privileges and the system permits the setting  of  the
195                 system  date and time. The first mm is the month (number); dd
196                 is the day (number); hh is the hour (number, 24-hour system);
197                 the  second  mm is the minute (number); cc is the century and
198                 is the first two digits of the year (this is optional); yy is
199                 the  last  two digits of the year and is optional. If century
200                 is not specified, then values  in  the  range  [69,99]  shall
201                 refer  to  years  1969  to  1999 inclusive, and values in the
202                 range [00,68] shall refer to years 2000  to  2068  inclusive.
203                 The current year is the default if yy is omitted.
204
205                 Note:     It  is  expected  that  in a future version of this
206                           standard  the  default  century  inferred  from   a
207                           2-digit  year will change. (This would apply to all
208                           commands accepting a 2-digit year as input.)
209

STDIN

211       Not used.
212

INPUT FILES

214       None.
215

ENVIRONMENT VARIABLES

217       The following environment variables shall affect the execution of date:
218
219       LANG      Provide a default value for  the  internationalization  vari‐
220                 ables  that are unset or null. (See the Base Definitions vol‐
221                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
222                 ables  for  the  precedence of internationalization variables
223                 used to determine the values of locale categories.)
224
225       LC_ALL    If set to a non-empty string value, override  the  values  of
226                 all the other internationalization variables.
227
228       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
229                 bytes of text data as characters (for example, single-byte as
230                 opposed to multi-byte characters in arguments).
231
232       LC_MESSAGES
233                 Determine the locale that should be used to affect the format
234                 and contents  of  diagnostic  messages  written  to  standard
235                 error.
236
237       LC_TIME   Determine  the  format  and contents of date and time strings
238                 written by date.
239
240       NLSPATH   Determine the location of message catalogs for the processing
241                 of LC_MESSAGES.
242
243       TZ        Determine  the  timezone in which the time and date are writ‐
244                 ten, unless the −u option is specified. If the TZ variable is
245                 unset  or null and −u is not specified, an unspecified system
246                 default timezone is used.
247

ASYNCHRONOUS EVENTS

249       Default.
250

STDOUT

252       When no formatting operand is specified, the output in the POSIX locale
253       shall be equivalent to specifying:
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           alt_digits  "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
335                       "IX";"X";"XI";"XII"
336           d_fmt       "%e.%Om.%Y"
337
338       With the above date, the command:
339
340           date "+%x"
341
342       would yield 3.IX.1991. With the same d_fmt, but without the alt_digits,
343       the command would yield 3.9.1991.
344

EXAMPLES

346        1. The  following  are input/output examples of date used at arbitrary
347           times in the POSIX locale:
348
349               $ date
350               Tue Jun 26 09:58:10 PDT 1990
351
352               $ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
353               DATE: 11/02/91
354               TIME: 13:36:16
355
356               $ date "+TIME: %r"
357               TIME: 01:36:32 PM
358
359        2. Examples for Denmark, where the default date and time format is  %a
360           %d %b %Y %T %Z:
361
362               $ LANG=da_DK.iso_8859−1 date
363               ons 02 okt 1991 15:03:32 CET
364
365               $ LANG=da_DK.iso_8859−1 \
366                   date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
367               DATO: onsdag den 2. oktober 1991
368               KLOKKEN: 15:03:56
369
370        3. Examples  for Germany, where the default date and time format is %a
371           %d.%h.%Y, %T %Z:
372
373               $ LANG=De_DE.88591 date
374               Mi 02.Okt.1991, 15:01:21 MEZ
375
376               $ LANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
377               DATUM: Mittwoch, 02. Oktober 1991
378               ZEIT: 15:02:02
379
380        4. Examples for France, where the default date and time format  is  %a
381           %d %h %Y %Z %T:
382
383               $ LANG=Fr_FR.88591 date
384               Mer 02 oct 1991 MET 15:03:32
385
386               $ LANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
387               JOUR: Mercredi 02 octobre 1991
388               HEURE: 15:03:56
389

RATIONALE

391       Some of the new options for formatting are from the ISO C standard. The
392       −u option was introduced to allow portable access to  Coordinated  Uni‐
393       versal  Time  (UTC).   The string "GMT0" is allowed as an equivalent TZ
394       value to be compatible with all of the systems using the BSD  implemen‐
395       tation, where this option originated.
396
397       The  %e  format  conversion  specification  (adopted from System V) was
398       added because the ISO C standard conversion specifications did not pro‐
399       vide  any  way to produce the historical default date output during the
400       first nine days of any month.
401
402       There are two varieties of day and week numbering supported  (in  addi‐
403       tion to any others created with the locale-dependent %E and %O modifier
404       characters):
405
406        *  The historical variety in which Sunday is the first day of the week
407           and the weekdays preceding the first Sunday of the year are consid‐
408           ered week 0. These are represented by %w and %U.  A variant of this
409           is  %W, using Monday as the first day of the week, but still refer‐
410           ring to week 0. This view of the calendar was retained  because  so
411           many  historical  applications  depend on it and the ISO C standard
412           strftime() function, on which many date implementations are  based,
413           was defined in this way.
414
415        *  The  international  standard,  based  on the ISO 8601:2004 standard
416           where Monday is the first weekday and the algorithm for  the  first
417           week  number  is  more complex: If the week (Monday to Sunday) con‐
418           taining January 1 has four or more days in the new year, then it is
419           week 1; otherwise, it is week 53 of the previous year, and the next
420           week is week 1. These are represented by the new conversion  speci‐
421           fications %u and %V, added as a result of international comments.
422

FUTURE DIRECTIONS

424       None.
425

SEE ALSO

427       The  Base  Definitions  volume of POSIX.1‐2008, Section 7.3.5, LC_TIME,
428       Chapter 8, Environment Variables, Section 12.2, Utility  Syntax  Guide‐
429       lines
430
431       The System Interfaces volume of POSIX.1‐2008, fprintf(), strftime()
432
434       Portions  of  this text are reprinted and reproduced in electronic form
435       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
436       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
437       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
438       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
439       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
440       event of any discrepancy between this version and the original IEEE and
441       The Open Group Standard, the original IEEE and The Open Group  Standard
442       is  the  referee document. The original Standard can be obtained online
443       at http://www.unix.org/online.html .
444
445       Any typographical or formatting errors that appear  in  this  page  are
446       most likely to have been introduced during the conversion of the source
447       files to man page format. To report such errors,  see  https://www.ker
448       nel.org/doc/man-pages/reporting_bugs.html .
449
450
451
452IEEE/The Open Group                  2013                             DATE(1P)
Impressum