Austin Group Defect Tracker

Aardvark Mark IV


Viewing Issue Simple Details Jump to Notes ] Issue History ] Print ]
ID Category Severity Type Date Submitted Last Update
0001380 [1003.1(2016/18)/Issue7+TC2] Base Definitions and Headers Objection Clarification Requested 2020-07-22 14:23 2021-01-15 16:23
Reporter geoffclare View Status public  
Assigned To
Priority normal Resolution Accepted  
Status Applied  
Name Geoff Clare
Organization The Open Group
User Reference
Section 3.192 Hard Link, 3.208 Link
Page Number 64, 66
Line Number 1891, 1951
Interp Status ---
Final Accepted Text
Summary 0001380: Definitions of Link and Hard Link don't match some usage
Description The term "link" is defined in XBD 3.208 as a synonym for "directory entry", and "hard link" is defined in XBD 3.192 is "The relationship between two directory entries that represent the same file"; it also says that a hard link is "the result of an execution of the ln utility (without the -s option) or the link() function".

This does not match how these terms are often used in the standard. There are many places where it uses "link" to refer to both hard links and symbolic links, e.g. in this paragraph on the fstatat() page:
The lstat() function shall be equivalent to stat(), except when path refers to a symbolic link. In that case lstat() shall return information about the link, while stat() shall return information about the file the link references.
(In the second sentence both uses of "the link" do not fit the definition; they are being used to refer back to "symbolic link" in the previous sentence.)

Also, by a strict reading of the definition, the term "hard link" should be used only in contexts where a file has multiple links, but the standard uses it to refer to cases that include the possibility of a file with only one directory entry, e.g. on the <sys/stat.h> page where st_nlink is described as the "number of hard links".

There are, of course, also places where the terms are used correctly (mainly in text that dates back to before symbolic links were added).

There are two ways the problem could be fixed:

1. Keep the current definitions and change the text in places where it misuses the terms.

2. Change the definitions, and the text in places where changing the definitions changed the meaning.

The proposed changes do the latter. This is mainly because the current definitions are at odds with the way "link" and "hard link" are commonly used outside the context of the standard. I believe changing the definitions would make the text more natural and easier to understand.
Desired Action On page 53 line 1648 section 3.130 Directory Entry, change:
Directory Entry (or Link)
to:
Directory Entry (or Hard Link)

On page 56 line 1697 section 3.144 Empty Directory, change:
A directory that contains, at most, directory entries for dot and dot-dot, and has exactly one link to it (other than its own dot entry, if one exists), in dot-dot. No other links to the directory may exist.
to:
A directory that contains, at most, directory entries for dot and dot-dot, and has exactly one hard link to it other than its own dot entry (if one exists), in dot-dot. No other hard links to the directory can exist.

On page 64 line 1891 section 3.192 Hard Link, change:
The relationship between two directory entries that represent the same file; see also Section 3.130 (on page 53). The result of an execution of the ln utility (without the -s option) or the link() function.
to:
See Directory Entry in Section 3.130 (on page 53). A file can have multiple hard links as a result of an execution of the ln utility (without the -s option) or the link() function.

On page 66 line 1951 section 3.208 Link, change:
See Directory Entry in Section 3.130 (on page 53).
to:
In the context of the file hierarchy, either a hard link or a symbolic link.

In the context of the c99 utility, the action performed by the link editor (or linker).

<small>Note:
The c99 utility is defined in detail in the Shell and Utilities volume of POSIX.1-2017.</small>

On page 235 line 7917 section <errno.h>, change:
[EMLINK] Too many links.
to:
[EMLINK] Too many hard links.

On page 236 line 7967 section <errno.h>, change:
[EXDEV] Cross-device link.
to:
[EXDEV] Improper hard link.

On page 413 line 14030 section <tar.h> LNKTYPE, change:
Link.
to:
Hard link.


Cross-volume changes to XSH ...

On page 484 line 16712 section 2.3 Error Numbers (EMLINK), change:
Too many links.
to:
Too many hard links.

On page 488 line 16865 section 2.3 Error Numbers (EXDEV), change:
Improper link. A link to a file on another file system was attempted.
to:
Improper hard link. Creation of a hard link to a file on another file system was attempted.

On page 965 line 32816 section fstatat(), change:
st_nlink shall be set to the number of links to the file
to:
st_nlink shall be set to the number of hard links to the file

On page 965 line 32823 section fstatat(), change:
the number of (hard) links to the symbolic link
to:
the number of hard links to the symbolic link

On page 1243 line 41492 section link(), change:
link one file to another file
to:
hard link one file to another file

On page 1243 line 41500,41503,41507,41525,41531 section link(), change:
a new link
to:
a new hard link

On page 1244 line 41545 section link(), change:
The number of links
to:
The number of hard links

On page 1244 line 41568 section link() EXDEV, change:
The link named by path2 and the file named by path1 are on different file systems and the implementation does not support links between file systems
to:
The file named by path1 and the directory in which the directory entry named by path2 is to be created are on different file systems and the implementation does not support hard links between file systems.

On page 1245 line 41590 section link() EXAMPLES, change:
Creating a Link to a File

The following example shows how to create a link to a file
to:
Creating a Hard Link to a File

The following example shows how to create an additional hard link to a file

On page 1245 line 41599 section link() EXAMPLES, change:
Creating a Link to a File Within a Program

In the following program example, the link() function links the
to:
Creating a Hard Link to a File Within a Program

In the following program example, the link() function hard links the

On page 1246 line 41617 section link() APPLICATION USAGE, change:
Some implementations do allow links between file systems.
to:
Some implementations do allow hard links between file systems.

On page 1246 line 41621 section link() RATIONALE, change:
Linking to a directory
to:
Creating additional hard links to a directory

On page 1246 line 41625 section link() RATIONALE, change:
allow linking of files on different file systems
to:
allow hard linking of files on different file systems

On page 1246 line 41627 section link() RATIONALE, change:
The exception for cross-file system links is intended to apply only to links that are programmatically indistinguishable from ``hard'' links.
to:
The exception for cross-file system hard links is intended to apply only to links that are programmatically indistinguishable from traditional hard links.

On page 1246 line 41634 section link() RATIONALE, change:
The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors of the link() function. The POSIX specification requires that if path1 is a symbolic link, a new link for the target of the symbolic link is created. Many systems by default or as an alternative provide a mechanism to avoid the implicit symbolic link lookup and create a new link for the symbolic link itself.

Earlier versions of this standard specified only the link() function, and required it to behave like linkat() with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4 and Linux kernels had link() behaving like linkat() with no flags, and many systems that attempted to provide a conforming link() function did so in a way that was rarely used, and when it was used did not conform to the standard (e.g., by not being atomic, or by dereferencing the symbolic link incorrectly). Since applications could not rely on link() following links in practice, the linkat() function was added taking a flag to specify the desired behavior for the application.
to:
Earlier versions of this standard specified only the link() function, and required it to behave like linkat() with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4 and Linux kernels had link() behaving like linkat() with no flags, and many systems that attempted to provide a conforming link() function did so in a way that was rarely used, and when it was used did not conform to the standard (e.g., by not being atomic, or by dereferencing the symbolic link incorrectly). Since applications could not rely on link() following symbolic links in practice, the linkat() function was added taking a flag to specify the desired behavior for the application.

On page 1816 line 58819 section rename(), change:
If the old argument points to the pathname of a file that is not a directory, the new argument shall not point to the pathname of a directory. If the link named by the new argument exists, it shall be removed and old renamed to new. In this case, a link named new shall remain visible to other threads throughout the renaming operation and refer either to the file referred to by new or old before the operation began. Write access permission is required for both the directory containing old and the directory containing new.

If the old argument points to the pathname of a directory, the new argument shall not point to the pathname of a file that is not a directory. If the directory named by the new argument exists, it shall be removed and old renamed to new. In this case, a link named new shall exist throughout the renaming operation and shall refer either to the directory referred to by new or old before the operation began. If new names an existing directory, it shall be required to be an empty directory.
to:
If the old argument names a file that is not a directory and the new argument names a directory, or old names a directory and new names a file that is not a directory, or new names a directory that is not empty, rename() shall fail. Otherwise, if the directory entry named by new exists, it shall be removed and old renamed to new. In this case, a directory entry named new shall remain visible to other threads throughout the renaming operation and refer either to the file referred to by new or old before the operation began.

(Note that the sentence about write access permission is intentionally
dropped as it duplicates line 58834.)

On page 1816 line 58837 section rename(), change:
If the link named by the new argument exists and the file's link count becomes 0
to:
If the new argument names an existing file and the file's link count becomes 0

On page 1817 line 58871 section rename() EEXIST, change:
The link named by new is a directory that is not an empty directory.
to:
The new argument names a directory that is not empty.

On page 1818 line 58883 section rename() ENOENT, change:
The link named by old does not name an existing file
to:
The old argument does not name an existing file

On page 1818 line 58905 section rename() EXDEV, change:
The links named by new and old are on different file systems and the implementation does not support links between file systems.
to:
The file named by old and the directory in which the directory entry named by new is to be created or replaced are on different file systems and the implementation does not support hard links between file systems.

On page 2197 line 70216 section unlink(), change:
The unlink() function shall remove a link to a file. If path names a symbolic link, unlink() shall remove the symbolic link named by path and shall not affect any file or directory named by the contents of the symbolic link. Otherwise, unlink() shall remove the link named by the pathname pointed to by path and shall decrement the link count of the file referenced by the link.
to:
The unlink() function shall remove the directory entry named by path and shall decrement the link count of the file referenced by the directory entry. If path names a symbolic link, unlink() shall remove the symbolic link and shall not affect any file named by the contents of the symbolic link.


Cross-volume changes to XCU ...

On page 2897 line 95692 section ln, change:
In the first synopsis form, the ln utility shall create a new directory entry (link) at the destination path specified by the target_file operand. If the -s option is specified, a symbolic link shall be created for the file specified by the source_file operand.
to:
In the first synopsis form, the ln utility shall create a new directory entry at the destination path specified by the target_file operand. If the -s option is specified, a symbolic link shall be created with the contents specified by the source_file operand (which need not name an existing file); otherwise, a hard link shall be created to the file named by the source_file operand.

On page 2897 line 95697 section ln, change:
In the second synopsis form, the ln utility shall create a new directory entry (link), or if the -s option is specified a symbolic link, for each file specified by a source_file operand, at a destination path in the existing directory named by target_dir.
to:
In the second synopsis form, the ln utility shall create a new directory entry for each source_file operand, at a destination path in the existing directory named by target_dir. If the -s option is specified, a symbolic link shall be created with the contents specified by each source_file operand (which need not name an existing file); otherwise, a hard link shall be created to each file named by a source_file operand.

On page 2899 line 95743,95745 section ln (-L & -P options), change:
create a (hard) link
to:
create a hard link

On page 3075 line 102555 section pax (-u option), change:
In copy mode, the file in the destination hierarchy shall be replaced by the file in the source hierarchy or by a link to the file in the source hierarchy if the file in the source hierarchy is newer.
to:
In copy mode, the file in the destination hierarchy shall be replaced if the file in the source hierarchy is newer.

On page 3087 line 103039 section pax (ustar Interchange Format), change:
1 (a link) or 2 (a symbolic link)
to:
1 (a hard link) or 2 (a symbolic link)

On page 3093 line 103232 section pax (CONSEQUENCES OF ERRORS), change:
cannot create a link to a file
to:
cannot create a hard link to a file

On page 3101 line 103596 section pax (RATIONALE), change:
Links are recorded in the fashion described here because a link can be to any file type. It is desirable in general to be able to restore part of an archive selectively and restore all of those files completely. If the data is not associated with each link, it is not possible to do this. However, the data associated with a file can be large, and when selective restoration is not needed, this can be a significant burden. The archive is structured so that files that have no associated data can always be restored by the name of any link name of any link, and the user may choose whether data is recorded with each instance of a file that contains data. The format permits mixing of both types of links in a single archive; this can be done for special needs, and pax is expected to interpret such archives on input properly, despite the fact that there is no pax option that would force this mixed case on output.
to:
Hard links are recorded in the fashion described here because a hard link can be to any file type. It is desirable in general to be able to restore part of an archive selectively and restore all of those files completely. If the data is not associated with each hard link, it is not possible to do this. However, the data associated with a file can be large, and when selective restoration is not needed, this can be a significant burden. The archive is structured so that files that have no associated data can always be restored by the name of any link name of any hard link, and the user can choose whether data is recorded with each instance of a file that contains data. The format permits mixing of hard links with data and hard links without data in a single archive; this can be done for special needs, and pax is expected to interpret such archives on input properly, despite the fact that there is no pax option that would force this mixed case on output.

On page 3200 line 107351 section rm (APPLICATION USAGE), change:
do not permit the removal of the last link
to:
do not permit the removal of the last hard link


Cross-volume changes to XRAT ...

On page 3491 line 117998 section A.3 Definitions, delete:
Directory Entry

Throughout POSIX.1-2017, the term ``link'' is used (about the link() function, for example) in describing the objects that point to files from directories.

Tags tc3-2008
Attached Files

- Relationships

There are no notes attached to this issue.

- Issue History
Date Modified Username Field Change
2020-07-22 14:23 geoffclare New Issue
2020-07-22 14:23 geoffclare Name => Geoff Clare
2020-07-22 14:23 geoffclare Organization => The Open Group
2020-07-22 14:23 geoffclare Section => 3.192 Hard Link, 3.208 Link
2020-07-22 14:23 geoffclare Page Number => 64, 66
2020-07-22 14:23 geoffclare Line Number => 1891, 1951
2020-07-22 14:23 geoffclare Interp Status => ---
2020-12-17 17:06 Don Cragun Status New => Resolved
2020-12-17 17:06 Don Cragun Resolution Open => Accepted
2020-12-17 17:07 Don Cragun Tag Attached: tc3-2008
2021-01-15 16:23 geoffclare Status Resolved => Applied


Mantis 1.1.6[^]
Copyright © 2000 - 2008 Mantis Group
Powered by Mantis Bugtracker