Bug 100494 - Missing description of "birth time of the inode" in man stat
Summary: Missing description of "birth time of the inode" in man stat
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2006-07-18 20:20 UTC by Dr. Markus Waldeck
Modified: 2006-10-07 22:50 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Dr. Markus Waldeck 2006-07-18 20:20:16 UTC
"birthtime" always corresponds with the comment /* time of file creation */ in /usr/include/sys/stat.h.

man stat mentions ONE time "birth time of the inode":
The time file was last accessed or modified, of when the
inode was last changed, or the birth time of the inode.

There is no further explanation of the meaning and the correlation to the "time of file creation".

Fix: 

Add the explanation
How-To-Repeat: man stat
Comment 1 Maxim Konovalov 2006-09-18 16:06:49 UTC
Hi Markus,

There is xref to stat(2) man page with the st_birthtime field
description.  Does this suit you?

-- 
Maxim Konovalov
Comment 2 Maxim Konovalov 2006-09-28 07:35:06 UTC
Added to the audit trail.

-- 
Maxim Konovalov

---------- Forwarded message ----------
Date: Tue, 26 Sep 2006 03:09:49 -0400 (EDT)
From: waldeck@gmx.de
To: undisclosed-recipients:  ;
Subject: Re: Re: Re: docs/100494

Hi Maxim,

you did not answer my last email!

> I'm not sure I understand your quiestion completely.  In UFS2 there is
> a lazy inode allocation mechanism but it is irrelevant to the topic
> because st_birthtime is an attribute of the file the inode refers.

Summary:
1. birthtime is NOT a standard Un!x feature.
2. The biological term "birth" is misleading and unsuitable!
3. A clear and evident definition is required!
4. During the file creation a inode is allocated.
5. This time is saved in st_birthtime.

man 1 stat should be:
> a, m, c, B
>		     The time file was last accessed or modified, of when the
> 		     inode was last changed, or the time of file creation
>                    (the so called birth time of the inode).

instead of:
> 		     inode was last changed, or the birth time of the inode.

man 2 stat should be:
> 		     st_birthtime  Time when the file was created and the inode was allocated.
                                                 ^^^^
instead of:
> 		     st_birthtime  Time when the inode was created.

Thanks!

Markus
Comment 3 Ceri Davies 2006-10-07 22:47:21 UTC
Your new statements are incorrect; birthtime refers to when the inode
was allocated, not when the file was created.  The implications of
using any term other than the self-descriptive "birth time" really are
unclear (for instance, when is a file restored from backup created?) and
so we're really better off just using the term "birth time".

Ceri
Comment 4 Ceri Davies freebsd_committer freebsd_triage 2006-10-07 22:47:36 UTC
State Changed
From-To: open->closed

The term "birth time" is as unambiguous as we can get here.  It is /not/ 
the time that the file was created.