-bash: lstat: command not found

Question

I'm using a Macbook Pro running El Capitan v 10.11.6. I am learning about symlinks, and in the man ln page, I found the following:

A stat(2) on a symbolic link will return the linked-to file; an lstat(2) must be done to obtain information about the link.

As a test, I created a symlink to a file (in another filesystem, if it matters), as follows:

ln -s /Volumes/foobardir/foobarfile foobarlink

Then I ran lstat foobarlink to get information on the symlink file itself, but I got the following output:

-bash: lstat: command not found

The command which lstat returns nothing, which confirms that there is no executable with this name in my filepath.

I am able to execute stat foobarlink, but I am not sure if the returned stats are for the linked file or the symlink itself. I do see today's date in timestamp form among the output for that command, while running stat foobarfile shows a date from a few months ago. So I'm guessing this is the output I'm looking for, but I'd like a 2nd opinion.

By the way, running which stat returns /usr/bin/stat. A grep in the /usr/bin directory for all executables with stat in their name returns the following:

• db_stat
• diffstat
• httpdstat.d
• jstat
• jstatd
• lockstat
• lpstat
• nfsstat
• plockstat
• snmpnetstat
• snmpstatus
• stat
• uustat
• vm_stat

As I stated above, my guess is that stat returns the output that I had expected lstat to return. My questions are:

• why is lstat apparently not installed in my system, when man lstat recognizes lstat as a valid command?
• Why include manual information for an executable you don't ship with?
• brew search lstat returns no results. Is it possible to install lstat to my local machine somehow, and are there even any advantages to doing so?

Solution

Section 1 of the BSD Manual is for general commands. Section 2 is for system calls, i.e., function calls you might make if programming for your system in the C language, or one of its derivatives.

The number in parentheses indicates what section of the manual the entry is from. In this case, lstat(2) indicates that this page provides information on a system call, not on a standalone binary which can be executed at the command-line.

---

If you typed man lstat, you would see the manual page for the lstat system call. stat, by contrast, is the name of both a system call and a standalone utility. If you type man stat, you will by default get the manual page for the command line utility. To see the system call manual page, you would need to explicitly tell man which section of the manual to search:

man 2 stat

---

https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man5/manpages.5.html is an (outdated) link listing all the sections of the BSD Manual. The sections will be the same on your system, but I can't find that there is a man page explicitly listing the sections.

Comments

[Kevin]

try stat -L .

[Kevin]

Try man(1), it usually contains a list of sections.

[JdeBP]

The manual page pointed to in the answer is a manual page explicitly listing the sections.

[Richie Thomas]

@user4556274 you mentioned System 2 calls are for programming for your system in the C language, or one of its derivatives. If I want to write a script and use the lstat command, how would I go about that? Will lstat work in a file if I set the file extension to .c and compile it? Or can I use the C-shell shebang (i.e. #!/bin/csh -f)?

[HTNW]

lstat can be used in a C program with #include <sys/stat.h> (listed in man page synopsis). csh, while it is named after C, only has a more C-like syntax than other shells. It does not actually compile C code and is not a variant of the C language. If you want to use lstat in a script, then you just use the stat command. The command stat uses lstat by default, unless you use the -L switch, in which case it uses stat.