Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1982:28ee7ab54a90

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added the "Time" section to the development guide.
author Vladimir Homutov <vl@nginx.com>
date Tue, 02 May 2017 16:25:33 +0300
parents 082724c57c38
children 7660d6390a9d
comparison
equal deleted inserted replaced
1981:082724c57c38 1982:28ee7ab54a90
646 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal> 646 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
647 in case of error. 647 in case of error.
648 </para> 648 </para>
649 649
650 </section> 650 </section>
651
652 </section>
653
654
655 <section name="Time" id="time">
656
657 <para>
658 The <literal>ngx_time_t</literal> structure represents time split into seconds
659 and milliseconds with specification of GMT offset:
660 <programlisting>
661 typedef struct {
662 time_t sec;
663 ngx_uint_t msec;
664 ngx_int_t gmtoff;
665 } ngx_time_t;
666 </programlisting>
667 The <literal>ngx_tm_t</literal> is an alias for <literal>struct tm</literal>
668 on UNIX platforms and <literal>SYSTEMTIME</literal> on Windows.
669 </para>
670
671 <para>
672 To obtain current time, usually it is enough to access one of available global
673 variables, representing the cached time value in desired format.
674 The <literal>ngx_current_msec</literal> variable holds milliseconds elapsed
675 since Epoch and truncated to <literal>ngx_msec_t</literal>.
676 </para>
677
678 <para>
679 Available string representations are:
680
681 <list type="bullet">
682
683 <listitem>
684 <literal>ngx_cached_err_log_time</literal> — used in error log:
685 "<literal>1970/09/28 12:00:00</literal>"
686 </listitem>
687
688 <listitem>
689 <literal>ngx_cached_http_log_time</literal> — used in HTTP access log:
690 "<literal>28/Sep/1970:12:00:00 +0600</literal>"
691 </listitem>
692
693 <listitem>
694 <literal>ngx_cached_syslog_time</literal> — used in syslog:
695 "<literal>Sep 28 12:00:00</literal>"
696 </listitem>
697
698 <listitem>
699 <literal>ngx_cached_http_time</literal> — used in HTTP for headers:
700 "<literal>Mon, 28 Sep 1970 06:00:00 GMT</literal>"
701 </listitem>
702
703 <listitem>
704 <literal>ngx_cached_http_log_iso8601</literal> — in the ISO 8601
705 standard format:
706 "<literal>1970-09-28T12:00:00+06:00</literal>"
707 </listitem>
708
709 </list>
710 </para>
711
712 <para>
713 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros
714 returning current value of seconds are a preferred way to access cached
715 time value.
716 </para>
717
718 <para>
719 To obtain the time explicitly, <literal>ngx_gettimeofday()</literal> may
720 be used, which updates its argument (pointer to
721 <literal>struct timeval</literal>).
722 Time is always updated when nginx returns to event loop from system calls.
723 To update the time immediately, call <literal>ngx_time_update()</literal>,
724 or <literal>ngx_time_sigsafe_update()</literal> if you need it in the
725 signal handler context.
726 </para>
727
728 <para>
729 The following functions convert <literal>time_t</literal> into broken-down time
730 representation, either <literal>ngx_tm_t</literal> or
731 <literal>struct tm</literal> for those with <literal>libc</literal> prefix:
732
733 <list type="bullet">
734
735 <listitem>
736 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — result time is UTC
737 </listitem>
738
739 <listitem>
740 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — result time is
741 relative to the timezone
742 </listitem>
743
744 </list>
745
746 The <literal>ngx_http_time(buf, time)</literal> returns string
747 representation suitable for use with HTTP headers (for example,
748 "<literal>Mon, 28 Sep 1970 06:00:00 GMT</literal>").
749 Another possible conversion is provided by
750 <literal>ngx_http_cookie_time(buf, time)</literal> that produces format suitable
751 for HTTP cookies ("<literal>Thu, 31-Dec-37 23:55:55 GMT</literal>").
752 </para>
651 753
652 </section> 754 </section>
653 755
654 756
655 <section name="Containers" id="containers"> 757 <section name="Containers" id="containers">