Documenting stat(2)

Documenting stat(2)

[Eric S. Raymond]

I'm trying to pin down and document the behavior of the size field in
stat(2) on Linux and under various stat emulations on Windows and the
Mac.  What I find out will be documented where it will do some good (in
particular I'll send a stat.2 man page patch to Andries Brouwer).

Here is what I think I know about stat(2) that isn't in the
Linux man pages:

* For a plain file or directory (S_IFREG or S_IFDIR), the st_size
field reports the size of the file in bytes.

* For a symlink (S_IFLNK) it reports the size of the link file, not the
size of the file the link points to. 

* For a socket or FIFO (S_IFSOCK, S_IFIFO) it reports the count of bytes
waiting to be read. 

* For a block special device (S_IFBLK) it returns 0.

I don't know what it should be expected to return for terminal or
other special devices.  My guess is number of characters waiting
in clists.

Can anyone verify, correct, or expand on the above?  Reply to 
esr@thyrsus.com, please, and thanks in advance.

(Among other things, this may turn into a substantial improvement
in the documented capabilities of Perl and Python.)
-- 
		<a href="http://www.tuxedo.org/~esr/">Eric S. Raymond</a>

The spirit of resistance to government is so valuable on certain
occasions, that I wish it always to be kept alive.  It will often be
exercised when wrong, but better so than not to be exercised at all.
I like a little rebellion now and then.  It is like a storm in the
Atmosphere.
	-- Thomas Jefferson, letter to Abigail Adams, 1787
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Linus Torvalds]

In article <20010118002812.A19810@thyrsus.com>,
Eric S. Raymond <esr@thyrsus.com> wrote:
>
>* For a socket or FIFO (S_IFSOCK, S_IFIFO) it reports the count of bytes
>waiting to be read. 

Don't depend on it. That's pretty much implementation-defined: use the
FIONREAD ioctl to fetch available info from pipes, sockets, ttys etc.

Some versions of Linux will _not_ give the size of the pipe from stat(),
if I remember correctly.  And as far as I know, no version of Linux will
have st_size mean anything at all for sockets (pipes, yes.  Both named
and unnamed - at least with the current implementation.  But not
sockets.  How could, it, anyway, as a socket name is nothing but a bind
entry, and can have many sockets associated with it?). 

>* For a block special device (S_IFBLK) it returns 0.

Again, this is not something you should depend on. Older Linuxes tried
to return the size of the block device, again if my memory serves me.

>I don't know what it should be expected to return for terminal or
>other special devices.  My guess is number of characters waiting
>in clists.

Nope. Use FIONREAD for that.

Linux will normally return 0.

>Can anyone verify, correct, or expand on the above?  Reply to 
>esr@thyrsus.com, please, and thanks in advance.

Basically, the _only_ think you should depend on is that st_size
contains:
 - for regular files, the size of the file in bytes
 - for symlinks, the length of the symlink.

That's it. Anybody who tries to use anything else is nonportable, and is
almost guaranteed to not work reliably even on just different versions
of Linux, never mind anything else.

		Linus
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Documenting stat(2)

[dmeyer]

In article <9463fj$gsq$1@penguin.transmeta.com> you write:
> Basically, the _only_ think you should depend on is that st_size
> contains:
>  - for regular files, the size of the file in bytes
>  - for symlinks, the length of the symlink.

I don't think this is right - for a symlink, stat should return the
size of the file; lstat should return the size of the symlink.

-- 
David M. Meyer
dmeyer@dmeyer.net
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Padraig Brady]

dmeyer@dmeyer.net wrote:

> In article <9463fj$gsq$1@penguin.transmeta.com> you write:
> 
>> Basically, the _only_ think you should depend on is that st_size
>> contains:
>>  - for regular files, the size of the file in bytes
>>  - for symlinks, the length of the symlink.
> 
> I don't think this is right - for a symlink, stat should return the
> size of the file; lstat should return the size of the symlink.

Nope stat should return the details of the symlink
whereas lstat should return the details of the symlink target.

But there is another ambiguity when stating symlinks.
In the current implementation the length of the symlink (name)
is the same as the symlink file size. Will this always
be the case? If not then the above statement is wrong.
i.e.

 >> - for symlinks, the length of the symlink.

should be

 >> - for symlinks, the symlink file size in bytes (currently the
 >>   length of the symlink).

Padraig.

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Felix von Leitner]

Thus spake Eric S. Raymond (esr@thyrsus.com):
> Here is what I think I know about stat(2) that isn't in the
> Linux man pages:

> * For a symlink (S_IFLNK) it reports the size of the link file, not the
> size of the file the link points to.

I think you confuse stat and lstat here.

Felix
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[dmeyer]

In article <3A66D93C.8090500@AnteFacto.com> you write:
> Nope stat should return the details of the symlink
> whereas lstat should return the details of the symlink target.

Not according to my manpages.  From stat(2):

       stat stats the file pointed to by file_name and  fills  in
       buf.

       lstat  is  identical  to  stat,  only  the  link itself is
       stated, not the file  that  is  obtained  by  tracing  the
       links.

Actually, the Solaris manpage is clearer:

     The lstat() function  obtains  file  attributes  similar  to
     stat(),  except  when  the named file is a symbolic link; in
     that case lstat() returns information about the link,  while
     stat()  returns  information  about the file the link refer-
     ences.

and a short test program:

#include <stdio.h>
#include <sys/stat.h>
#include <unistd.h>

main()
{
	struct stat buf;

	stat("stattest.c",&buf);
	printf("stat original file: %d\n",buf.st_size);

	symlink("stattest.c","a_symlink");

	stat("a_symlink",&buf);
	printf("stat symlink: %d\n",buf.st_size);

	lstat("a_symlink",&buf);
	printf("lstat symlink: %d\n",buf.st_size);
}

jhereg|dmeyer|~/dl> ./stattest
stat original file: 358
stat symlink: 358
lstat symlink: 10

stat clearly is giving the size of the target, and lstat the size of
the link.

-- 
David M. Meyer
dmeyer@dmeyer.net
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Igmar Palsenberg]

> Nope stat should return the details of the symlink
> whereas lstat should return the details of the symlink target.

It's the other way around according to the manpage, and my code also says
it's the other way around.

It's logical the way it is.. 

I use lstat to check if a config file is a symlink, and if it is, it
refuses to open it. 



	Igmar

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Mike Castle]

On Thu, Jan 18, 2001 at 09:52:02PM +0100, Igmar Palsenberg wrote:
> I use lstat to check if a config file is a symlink, and if it is, it
> refuses to open it. 

Nice race condition.

mrc
-- 
       Mike Castle       Life is like a clock:  You can work constantly
  dalgoda@ix.netcom.com  and be right all the time, or not work at all
www.netcom.com/~dalgoda/ and be right at least twice a day.  -- mrc
    We are all of us living in the shadow of Manhattan.  -- Watchmen
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Andreas Schwab]

Padraig Brady <Padraig@AnteFacto.com> writes:

|> dmeyer@dmeyer.net wrote:
|> 
|> > In article <9463fj$gsq$1@penguin.transmeta.com> you write:
|> >
|> >> Basically, the _only_ think you should depend on is that st_size
|> >> contains:
|> >>  - for regular files, the size of the file in bytes
|> >>  - for symlinks, the length of the symlink.
|> > I don't think this is right - for a symlink, stat should return the
|> > size of the file; lstat should return the size of the symlink.
|> 
|> Nope stat should return the details of the symlink
|> whereas lstat should return the details of the symlink target.

Nope, check the facts.

Andreas.

-- 
Andreas Schwab                                  "And now for something
SuSE Labs                                        completely different."
Andreas.Schwab@suse.de
SuSE GmbH, Schanzäckerstr. 10, D-90443 Nürnberg
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

Re: Documenting stat(2)

[Igmar Palsenberg]

On Thu, 18 Jan 2001, Mike Castle wrote:

> On Thu, Jan 18, 2001 at 09:52:02PM +0100, Igmar Palsenberg wrote:
> > I use lstat to check if a config file is a symlink, and if it is, it
> > refuses to open it. 
> 
> Nice race condition.

Agree, but still better then opening things that are actually a
symlink. Now would someone probably say : use the O_NOWFOLLOW option, but
since I do other checks that wouldn't be an option.

> mrc


	Igmar

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/