boot-time: comment that it's for container not host

Comment that in Docker etc., get_boot_time returns the
boot time of the container, not of its host.
Also, give an example file instead of saying just “FILE”.

diff --git a/lib/boot-time.h b/lib/boot-time.h
index 195839a2c53d8583789bf5cbb76c1b6c91259396..7abfa12e44456f98fdf36316dd2f454f47660856 100644 (file)
--- a/lib/boot-time.h
+++ b/lib/boot-time.h
@@ -29,11 +29,16 @@ extern "C" {
 /* Store the approximate time when the machine last booted in *P_BOOT_TIME,
    and return 0.  If it cannot be determined, return -1.
 
+   If the machine is a container inside another host machine,
+   return the boot time of the container, not the host.
+   The difference can matter in GNU/Linux, where times in /proc/stat
+   might be relative to boot time of the host, not the container.
+
    This function is not multithread-safe, since on many platforms it
-   invokes the functions setutxent, getutxent, endutxent.  These
-   functions are needed because they may lock FILE (so that we don't
-   read garbage when a concurrent process writes to FILE), but their
-   drawback is that they have a common global state.  */
+   invokes the functions setutxent, getutxent, endutxent.
+   These functions may lock a file like /var/log/wtmp (so that we
+   don't read garbage when a concurrent process writes to that file),
+   but their drawback is that they have a common global state.  */
 extern int get_boot_time (struct timespec *p_boot_time);