Point out time_t vs GTime pitfalls.

2005-08-22  Matthias Clasen  <mclasen@redhat.com>

	* glib/tmpl/date.sgml: Point out time_t vs GTime pitfalls.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f6cfd08e5e8ce3c366a63f5ba589fd1d8422624f..34197f5dd0ce7cb757cbd0dcb36a7bba59a9a370 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2005-08-22  Matthias Clasen  <mclasen@redhat.com>
+
+       * glib/tmpl/date.sgml: Point out time_t vs GTime pitfalls.
+
 2005-08-15  Matthias Clasen  <mclasen@redhat.com>
 
        * glib/glib-gettexttize.xml:

diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml
index ab83317beff2ddbce39c3449d4c7fcf6697e38d0..6e4c4c938df9a7bdf9df356d9e5e97d17efd227e 100644 (file)
--- a/docs/reference/glib/tmpl/date.sgml
+++ b/docs/reference/glib/tmpl/date.sgml
@@ -53,9 +53,9 @@ representation is valid. Sometimes neither is valid. Use the API.
 
 <para>
 GLib doesn't contain any time-manipulation functions; however, there
-is a #GTime typedef which is equivalent to <type>time_t</type>, and a #GTimeVal
-struct which represents a more precise time (with microseconds). You
-can request the current time as a #GTimeVal with g_get_current_time().
+is a #GTime typedef and a #GTimeVal struct which represents a more 
+precise time (with microseconds). You can request the current time as 
+a #GTimeVal with g_get_current_time().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -76,9 +76,9 @@ code readability.
 
 <!-- ##### STRUCT GTimeVal ##### -->
 <para>
-Represents a precise time, with seconds and microseconds. Same as the
-<structname>struct timeval</structname> returned by the
-<function>gettimeofday()</function> UNIX call.
+Represents a precise time, with seconds and microseconds. 
+Similar to the <structname>struct timeval</structname> returned by 
+the <function>gettimeofday()</function> UNIX call.
 </para>
 
 @tv_sec: seconds.
@@ -139,6 +139,24 @@ month, and year.
 Simply a replacement for <type>time_t</type>. Unrelated to #GTimer.
 </para>
 
+<para>
+Note that <type>GTime</type> is defined to always be a 32bit integer,
+unlike <type>time_t</type> which may be 64bit on some systems. 
+Therefore, <type>GType</type> will overflow in the year 2038, and
+you cannot use the address of a <type>GTime</type> variable as argument 
+to the UNIX time() function. Instead, do the following:
+<informalexample>
+<programlisting>
+time_t ttime;
+GTime gtime;
+
+time (&amp;ttime);
+gtime = (GTime)ttime;
+</programlisting>
+</informalexample>
+</para>
+
+
 
 <!-- ##### ENUM GDateDMY ##### -->
 <para>