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

NAME

6       date - write the date and time
7

SYNOPSIS

9       date [-u] [+format]
10
11
12
13       date [-u] mmddhhmm[[cc]yy]
14
15

DESCRIPTION

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

OPTIONS

24       The  date  utility  shall  conform  to  the  Base Definitions volume of
25       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
26
27       The following option shall be supported:
28
29       -u     Perform operations as if the TZ environment variable was set  to
30              the string "UTC0" , or its equivalent historical value of "GMT0"
31              . Otherwise, date shall use the timezone  indicated  by  the  TZ
32              environment  variable  or the system default if that variable is
33              unset or null.
34
35

OPERANDS

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

ASYNCHRONOUS EVENTS

251       Default.
252

STDOUT

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

STDERR

261       The standard error shall be used only for diagnostic messages.
262

OUTPUT FILES

264       None.
265

EXTENDED DESCRIPTION

267       None.
268

EXIT STATUS

270       The following exit values shall be returned:
271
272        0     The date was written successfully.
273
274       >0     An error occurred.
275
276

CONSEQUENCES OF ERRORS

278       Default.
279
280       The following sections are informative.
281

APPLICATION USAGE

283       Conversion specifiers are of unspecified format when not in  the  POSIX
284       locale.  Some of them can contain <newline>s in some locales, so it may
285       be difficult to use the format shown in standard output for parsing the
286       output of date in those locales.
287
288       The  range of values for %S extends from 0 to 60 seconds to accommodate
289       the occasional leap second.
290
291       Although certain of the conversion specifiers in the POSIX locale (such
292       as  the name of the month) are shown with initial capital letters, this
293       need not be the case in other locales. Programs using these fields  may
294       need  to adjust the capitalization if the output is going to be used at
295       the beginning of a sentence.
296
297       The date string formatting capabilities are intended for use in  Grego‐
298       rian-style  calendars,  possibly  with  a  different  starting year (or
299       years). The %x and %c conversion specifications, however, are  intended
300       for local representation; these may be based on a different, non-Grego‐
301       rian calendar.
302
303       The %C conversion specification was introduced to allow a fallback  for
304       the  %EC  (alternative  year format base year); it can be viewed as the
305       base of the current subdivision in the Gregorian calendar. The  century
306       number  is  calculated  as  the year divided by 100 and truncated to an
307       integer; it should not be confused with the use of ordinal numbers  for
308       centuries  (for  example,  "twenty-first century".) Both the %Ey and %y
309       can then be viewed as the offset from %EC and %C , respectively.
310
311       The E and O modifiers modify the traditional conversion specifiers,  so
312       that  they  can always be used, even if the implementation (or the cur‐
313       rent locale) does not support the modifier.
314
315       The E modifier supports alternative date formats, such as the  Japanese
316       Emperor's  Era,  as  long  as these are based on the Gregorian calendar
317       system. Extending the E modifiers to other date elements may provide an
318       implementation-defined  extension  capable of supporting other calendar
319       systems, especially in combination with the O modifier.
320
321       The O modifier supports time and date formats using the locale's alter‐
322       native numerical symbols, such as Kanji or Hindi digits or ordinal num‐
323       ber representation.
324
325       Non-European locales, whether they use Latin  digits  in  computational
326       items or not, often have local forms of the digits for use in date for‐
327       mats. This is not totally unknown even in Europe; a  variant  of  dates
328       uses  Roman  numerals  for  the months: the third day of September 1991
329       would be written as 3.IX.1991. In Japan,  Kanji  digits  are  regularly
330       used  for  dates;  in Arabic-speaking countries, Hindi digits are used.
331       The %d , %e , %H , %I , %m , %S , %U , %w ,  %W  ,  and  %y  conversion
332       specifications  always  return  the date and time field in Latin digits
333       (that is, 0 to 9). The %O modifier was introduced to  support  the  use
334       for  display  purposes  of non-Latin digits. In the LC_TIME category in
335       localedef, the optional alt_digits keyword is intended  for  this  pur‐
336       pose. As an example, assume the following (partial) localedef source:
337
338
339              alt_digits  "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
340                          "IX";"X";"XI";"XII"
341              d_fmt       "%e.%Om.%Y"
342
343       With the above date, the command:
344
345
346              date "+%x"
347
348       would yield 3.IX.1991. With the same d_fmt, but without the alt_digits,
349       the command would yield 3.9.1991.
350

EXAMPLES

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

RATIONALE

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

FUTURE DIRECTIONS

439       None.
440

SEE ALSO

442       The System Interfaces volume of IEEE Std 1003.1-2001,  printf(),  strf‐
443       time()
444
446       Portions  of  this text are reprinted and reproduced in electronic form
447       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
448       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
449       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
450       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
451       event of any discrepancy between this version and the original IEEE and
452       The  Open Group Standard, the original IEEE and The Open Group Standard
453       is the referee document. The original Standard can be  obtained  online
454       at http://www.opengroup.org/unix/online.html .
455
456
457
458IEEE/The Open Group                  2003                              DATE(P)
Impressum