DATE(1)                    POSIX Programmer's Manual                   DATE(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       date -- write the date and time

SSYYNNOOPPSSIISS
       date [[-u]] [[+_f_o_r_m_a_t]]

       date [[-u]] _m_m_d_d_h_h_m_m[[[[_c_c]]_y_y]]

DDEESSCCRRIIPPTTIIOONN
       The _d_a_t_e utility shall write the date and time to standard output or
       attempt to set the system date and time.  By default, the current date
       and time shall be written. If an operand beginning with ''++'' is
       specified, the output format of _d_a_t_e shall be controlled by the
       conversion specifications and other text in the operand.

OOPPTTIIOONNSS
       The _d_a_t_e utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following option shall be supported:

       --uu        Perform operations as if the _T_Z environment variable was set
                 to the string ""UUTTCC00"", or its equivalent historical value of
                 ""GGMMTT00"".  Otherwise, _d_a_t_e shall use the timezone indicated by
                 the _T_Z environment variable or the system default if that
                 variable is unset or null.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       +_f_o_r_m_a_t   When the format is specified, each conversion specifier shall
                 be replaced in the standard output by its corresponding
                 value. All other characters shall be copied to the output
                 without change. The output shall always be terminated with a
                 <newline>.

   CCoonnvveerrssiioonn SSppeecciiffiiccaattiioonnss
                 %a      Locale's abbreviated weekday name.

                 %A      Locale's full weekday name.

                 %b      Locale's abbreviated month name.

                 %B      Locale's full month name.

                 %c      Locale's appropriate date and time representation.

                 %C      Century (a year divided by 100 and truncated to an
                         integer) as a decimal number [00,99].

                 %d      Day of the month as a decimal number [01,31].

                 %D      Date in the format _m_m/_d_d/_y_y.

                 %e      Day of the month as a decimal number [1,31] in a two-
                         digit field with leading <space> character fill.

                 %h      A synonym for %%bb.

                 %H      Hour (24-hour clock) as a decimal number [00,23].

                 %I      Hour (12-hour clock) as a decimal number [01,12].

                 %j      Day of the year as a decimal number [001,366].

                 %m      Month as a decimal number [01,12].

                 %M      Minute as a decimal number [00,59].

                 %n      A <newline>.

                 %p      Locale's equivalent of either AM or PM.

                 %r      12-hour clock time [01,12] using the AM/PM notation;
                         in the POSIX locale, this shall be equivalent to
                         %%II:%%MM:%%SS %%pp.

                 %S      Seconds as a decimal number [00,60].

                 %t      A <tab>.

                 %T      24-hour clock time [00,23] in the format _H_H:_M_M:_S_S.

                 %u      Weekday as a decimal number [1,7] (1=Monday).

                 %U      Week of the year (Sunday as the first day of the
                         week) as a decimal number [00,53]. All days in a new
                         year preceding the first Sunday shall be considered
                         to be in week 0.

                 %V      Week of the year (Monday as the first day of the
                         week) as a decimal number [01,53]. If the week
                         containing January 1 has four or more days in the new
                         year, then it shall be considered week 1; otherwise,
                         it shall be the last week of the previous year, and
                         the next week shall be week 1.

                 %w      Weekday as a decimal number [0,6] (0=Sunday).

                 %W      Week of the year (Monday as the first day of the
                         week) as a decimal number [00,53]. All days in a new
                         year preceding the first Monday shall be considered
                         to be in week 0.

                 %x      Locale's appropriate date representation.

                 %X      Locale's appropriate time representation.

                 %y      Year within century [00,99].

                 %Y      Year with century as a decimal number.

                 %Z      Timezone name, or no characters if no timezone is
                         determinable.

                 %%      A <percent-sign> character.

                 See the Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n
                 _7_._3_._5, _L_C___T_I_M_E for the conversion specifier values in the
                 POSIX locale.

   MMooddiiffiieedd CCoonnvveerrssiioonn SSppeecciiffiiccaattiioonnss
       Some conversion specifiers can be modified by the EE and OO modifier
       characters to indicate a different format or specification as specified
       in the _L_C___T_I_M_E locale description (see the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _7_._3_._5, _L_C___T_I_M_E).  If the corresponding keyword
       (see eerraa, eerraa__yyeeaarr, eerraa__dd__ffmmtt, and aalltt__ddiiggiittss in the Base Definitions
       volume of POSIX.1-2017, _S_e_c_t_i_o_n _7_._3_._5, _L_C___T_I_M_E) is not specified or not
       supported for the current locale, the unmodified conversion specifier
       value shall be used.

       %Ec     Locale's alternative appropriate date and time representation.

       %EC     The name of the base year (period) in the locale's alternative
               representation.

       %Ex     Locale's alternative date representation.

       %EX     Locale's alternative time representation.

       %Ey     Offset from %%EECC (year only) in the locale's alternative
               representation.

       %EY     Full alternative year representation.

       %Od     Day of month using the locale's alternative numeric symbols.

       %Oe     Day of month using the locale's alternative numeric symbols.

       %OH     Hour (24-hour clock) using the locale's alternative numeric
               symbols.

       %OI     Hour (12-hour clock) using the locale's alternative numeric
               symbols.

       %Om     Month using the locale's alternative numeric symbols.

       %OM     Minutes using the locale's alternative numeric symbols.

       %OS     Seconds using the locale's alternative numeric symbols.

       %Ou     Weekday as a number in the locale's alternative representation
               (Monday = 1).

       %OU     Week number of the year (Sunday as the first day of the week)
               using the locale's alternative numeric symbols.

       %OV     Week number of the year (Monday as the first day of the week,
               rules corresponding to %%VV), using the locale's alternative
               numeric symbols.

       %Ow     Weekday as a number in the locale's alternative representation
               (Sunday = 0).

       %OW     Week number of the year (Monday as the first day of the week)
               using the locale's alternative numeric symbols.

       %Oy     Year (offset from %%CC) in alternative representation.

       _m_m_d_d_h_h_m_m[[[[_c_c]]_y_y]]
                 Attempt to set the system date and time from the value given
                 in the operand. This is only possible if the user has
                 appropriate privileges and the system permits the setting of
                 the system date and time. The first _m_m is the month (number);
                 _d_d is the day (number); _h_h is the hour (number, 24-hour
                 system); the second _m_m is the minute (number); _c_c is the
                 century and is the first two digits of the year (this is
                 optional); _y_y is the last two digits of the year and is
                 optional. If century is not specified, then values in the
                 range [69,99] shall refer to years 1969 to 1999 inclusive,
                 and values in the range [00,68] shall refer to years 2000 to
                 2068 inclusive. The current year is the default if _y_y is
                 omitted.

                 NNoottee::     It is expected that in a future version of this
                           standard the default century inferred from a
                           2-digit year will change. (This would apply to all
                           commands accepting a 2-digit year as input.)

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _d_a_t_e:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  Determine the locale for the interpretation of sequences of
                 bytes of text data as characters (for example, single-byte as
                 opposed to multi-byte characters in arguments).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _L_C___T_I_M_E   Determine the format and contents of date and time strings
                 written by _d_a_t_e.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _T_Z        Determine the timezone in which the time and date are
                 written, unless the --uu option is specified. If the _T_Z
                 variable is unset or null and --uu is not specified, an
                 unspecified system default timezone is used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       When no formatting operand is specified, the output in the POSIX locale
       shall be equivalent to specifying:


           date "+%a %b %e %H:%M:%S %Z %Y"

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    The date was written successfully.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Conversion specifiers are of unspecified format when not in the POSIX
       locale. Some of them can contain <newline> characters in some locales,
       so it may be difficult to use the format shown in standard output for
       parsing the output of _d_a_t_e in those locales.

       The range of values for %%SS extends from 0 to 60 seconds to accommodate
       the occasional leap second.

       Although certain of the conversion specifiers in the POSIX locale (such
       as the name of the month) are shown with initial capital letters, this
       need not be the case in other locales. Programs using these fields may
       need to adjust the capitalization if the output is going to be used at
       the beginning of a sentence.

       The date string formatting capabilities are intended for use in
       Gregorian-style calendars, possibly with a different starting year (or
       years). The %%xx and %%cc conversion specifications, however, are intended
       for local representation; these may be based on a different, non-
       Gregorian calendar.

       The %%CC conversion specification was introduced to allow a fallback for
       the %%EECC (alternative year format base year); it can be viewed as the
       base of the current subdivision in the Gregorian calendar. The century
       number is calculated as the year divided by 100 and truncated to an
       integer; it should not be confused with the use of ordinal numbers for
       centuries (for example, ``twenty-first century''.) Both the %%EEyy and %%yy
       can then be viewed as the offset from %%EECC and %%CC, respectively.

       The EE and OO modifiers modify the traditional conversion specifiers, so
       that they can always be used, even if the implementation (or the
       current locale) does not support the modifier.

       The EE modifier supports alternative date formats, such as the Japanese
       Emperor's Era, as long as these are based on the Gregorian calendar
       system. Extending the EE modifiers to other date elements may provide an
       implementation-defined extension capable of supporting other calendar
       systems, especially in combination with the OO modifier.

       The OO modifier supports time and date formats using the locale's
       alternative numerical symbols, such as Kanji or Hindi digits or ordinal
       number representation.

       Non-European locales, whether they use Latin digits in computational
       items or not, often have local forms of the digits for use in date
       formats. This is not totally unknown even in Europe; a variant of dates
       uses Roman numerals for the months: the third day of September 1991
       would be written as 3.IX.1991. In Japan, Kanji digits are regularly
       used for dates; in Arabic-speaking countries, Hindi digits are used.
       The %%dd, %%ee, %%HH, %%II, %%mm, %%SS, %%UU, %%ww, %%WW, and %%yy conversion
       specifications always return the date and time field in Latin digits
       (that is, 0 to 9). The %%OO modifier was introduced to support the use
       for display purposes of non-Latin digits. In the _L_C___T_I_M_E category in
       _l_o_c_a_l_e_d_e_f, the optional aalltt__ddiiggiittss keyword is intended for this
       purpose. As an example, assume the following (partial) _l_o_c_a_l_e_d_e_f
       source:


           alt_digits  "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
                       "IX";"X";"XI";"XII"
           d_fmt       "%e.%Om.%Y"

       With the above date, the command:


           date "+%x"

       would yield 3.IX.1991. With the same dd__ffmmtt, but without the aalltt__ddiiggiittss,
       the command would yield 3.9.1991.

EEXXAAMMPPLLEESS
        1. The following are input/output examples of _d_a_t_e used at arbitrary
           times in the POSIX locale:


               $$ date
               TTuuee JJuunn 2266 0099::5588::1100 PPDDTT 11999900

               $$ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
               DDAATTEE:: 1111//0022//9911
               TTIIMMEE:: 1133::3366::1166

               $$ date "+TIME: %r"
               TTIIMMEE:: 0011::3366::3322 PPMM

        2. Examples for Denmark, where the default date and time format is %%aa
           %%dd %%bb %%YY %%TT %%ZZ:


               $$ LANG=da_DK.iso_8859-1 date
               oonnss 0022 ookktt 11999911 1155::0033::3322 CCEETT

               $$ LANG=da_DK.iso_8859-1 \
                   date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
               DDAATTOO:: oonnssddaagg ddeenn 22.. ookkttoobbeerr 11999911
               KKLLOOKKKKEENN:: 1155::0033::5566

        3. Examples for Germany, where the default date and time format is %%aa
           %%dd.%%hh.%%YY, %%TT %%ZZ:


               $$ LANG=De_DE.88591 date
               MMii 0022..OOkktt..11999911,, 1155::0011::2211 MMEEZZ

               $$ LANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
               DDAATTUUMM:: MMiittttwwoocchh,, 0022.. OOkkttoobbeerr 11999911
               ZZEEIITT:: 1155::0022::0022

        4. Examples for France, where the default date and time format is %%aa
           %%dd %%hh %%YY %%ZZ %%TT:


               $$ LANG=Fr_FR.88591 date
               MMeerr 0022 oocctt 11999911 MMEETT 1155::0033::3322

               $$ LANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
               JJOOUURR:: MMeerrccrreeddii 0022 ooccttoobbrree 11999911
               HHEEUURREE:: 1155::0033::5566

RRAATTIIOONNAALLEE
       Some of the new options for formatting are from the ISO C standard. The
       --uu option was introduced to allow portable access to Coordinated
       Universal Time (UTC).  The string ""GGMMTT00"" is allowed as an equivalent _T_Z
       value to be compatible with all of the systems using the BSD
       implementation, where this option originated.

       The %%ee format conversion specification (adopted from System V) was
       added because the ISO C standard conversion specifications did not
       provide any way to produce the historical default _d_a_t_e output during
       the first nine days of any month.

       There are two varieties of day and week numbering supported (in
       addition to any others created with the locale-dependent %%EE and %%OO
       modifier characters):

        *  The historical variety in which Sunday is the first day of the week
           and the weekdays preceding the first Sunday of the year are
           considered week 0. These are represented by %%ww and %%UU.  A variant
           of this is %%WW, using Monday as the first day of the week, but still
           referring to week 0. This view of the calendar was retained because
           so many historical applications depend on it and the ISO C standard
           _s_t_r_f_t_i_m_e() function, on which many _d_a_t_e implementations are based,
           was defined in this way.

        *  The international standard, based on the ISO 8601:2004 standard
           where Monday is the first weekday and the algorithm for the first
           week number is more complex: If the week (Monday to Sunday)
           containing January 1 has four or more days in the new year, then it
           is week 1; otherwise, it is week 53 of the previous year, and the
           next week is week 1. These are represented by the new conversion
           specifications %%uu and %%VV, added as a result of international
           comments.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _7_._3_._5, _L_C___T_I_M_E,
       _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x
       _G_u_i_d_e_l_i_n_e_s

       The System Interfaces volume of POSIX.1-2017, _f_p_r_i_n_t_f(), _s_t_r_f_t_i_m_e()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                              DATE(1)
