From msmith@atrad.adelaide.edu.au  Mon Mar 18 19:36:46 1996
Received: from genesis.atrad.adelaide.edu.au (genesis.atrad.adelaide.edu.au [129.127.96.120])
          by freefall.freebsd.org (8.7.3/8.7.3) with ESMTP id TAA28662
          for <FreeBSD-gnats-submit@freebsd.org>; Mon, 18 Mar 1996 19:36:43 -0800 (PST)
Received: from msmith@localhost by genesis.atrad.adelaide.edu.au (8.6.12/8.6.9) id NAA28024; Tue, 19 Mar 1996 13:27:02 +1030
Message-Id: <199603190257.NAA28024@genesis.atrad.adelaide.edu.au>
Date: Tue, 19 Mar 1996 13:27:02 +1030
From: Michael Smith <msmith@atrad.adelaide.edu.au>
Reply-To: msmith@atrad.adelaide.edu.au
To: FreeBSD-gnats-submit@freebsd.org
Subject: stat manpage unclear about st_mtime & friends
X-Send-Pr-Version: 3.2

>Number:         1089
>Category:       docs
>Synopsis:       stat manpage unclear about st_mtime & friends
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bde
>State:          closed
>Quarter:
>Keywords:
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Mar 18 19:40:02 PST 1996
>Closed-Date:    Sat Jan 11 13:46:50 PST 1997
>Last-Modified:  Sat Jan 11 13:47:32 PST 1997
>Originator:     Michael Smith
>Release:        FreeBSD 2.1-STABLE i386 (and all up to -current)
>Organization:
Genesis Software
>Environment:

	stat(2) manpage.

>Description:

Consider this portion of the stat(2) manapage (trimmed):

     struct stat {
	...
         struct timespec st_atimespec;  /* time of last access */
         struct timespec st_mtimespec;  /* time of last data modification */
         struct timespec st_ctimespec;  /* time of last file status change */
	...
     };

     The time-related fields of struct stat are as follows:

     st_atime     Time when file data last accessed.  Changed by the mknod(2),
	...
     st_mtime     Time when file data last modified.  Changed by the mknod(2),
	...
     st_ctime     Time when file status was last changed (inode data modifica-
	...


It should be mentioned that the names 'st_atime' 'st_mtime' and 'st_ctime'
are compatability macros which referece the ts_sec fields in the timespec
structs for each of the three.

>How-To-Repeat:

	None

>Fix:
	
     The time-related fields of struct stat are as follows:

     st_atimespec  Time when file data last accessed.  Changed by the mknod(2),
                   utimes(2) and read(2) system calls.

     st_mtimespec  Time when file data last modified.  Changed by the mknod(2),
                   utimes(2) and write(2) system calls.

     st_ctimespec Time when file status was last changed (inode data modifica-
                  tion).  Changed by the chmod(2),  chown(2),  link(2),
                  mknod(2),  rename(2),  unlink(2),  utimes(2) and write(2)
                  system calls.

     The names 'st_atime', 'st_mtime' and 'st_ctime' are supported for
     compatability's sake via preprocessor macros which reference the
     ts_sec fields of the corresponding timestruct.





>Release-Note:
>Audit-Trail:

From: Bruce Evans <bde@zeta.org.au>
To: FreeBSD-gnats-submit@freebsd.org, msmith@atrad.adelaide.edu.au
Cc:  Subject: Re: docs/1089: stat manpage unclear about st_mtime & friends
Date: Tue, 19 Mar 1996 17:49:06 +1100

 >Consider this portion of the stat(2) manapage (trimmed):
 
 >     struct stat {
 >	...
 >         struct timespec st_atimespec;  /* time of last access */
 > ...
 
 The man page was apparently once copied from stat.h.  Bits have rotted.
 There are now ordinary st_atime etc. fields for the _POSIX_SOURCE case.
 
 >     The time-related fields of struct stat are as follows:
 
 >     st_atime     Time when file data last accessed.  Changed by the mknod(2),
 > ...
 
 >It should be mentioned that the names 'st_atime' 'st_mtime' and 'st_ctime'
 >are compatability macros which referece the ts_sec fields in the timespec
 >structs for each of the three.
 
 Should it?  This is an implementation detail, and the implementation is
 different for the _POSIX_SOURCE case.
 
 Bruce
State-Changed-From-To: open->analyzed 
State-Changed-By: wosch 
State-Changed-When: Tue Sep 24 17:17:26 PDT 1996 
State-Changed-Why:  
Analyzed by Bruce. 



Responsible-Changed-From-To: freebsd-bugs->bde 
Responsible-Changed-By: wosch 
Responsible-Changed-When: Tue Sep 24 17:17:26 PDT 1996 
Responsible-Changed-Why:  
State-Changed-From-To: analyzed->closed 
State-Changed-By: mpp 
State-Changed-When: Sat Jan 11 13:46:50 PST 1997 
State-Changed-Why:  
The man page was brought into line with the actualy 
contents of stat.h, and a litle blurb about st_mtime & friends 
was also added. 
>Unformatted:
