Changeset View
Standalone View
lib/libc/sys/unlink.2
Show All 22 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 | .\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd November 11, 2018 | .Dd January 16, 2019 | ||||
.Dt UNLINK 2 | .Dt UNLINK 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm unlink , | .Nm unlink , | ||||
.Nm unlinkat | .Nm unlinkat | ||||
.Nd remove directory entry | .Nd remove directory entry | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In unistd.h | .In unistd.h | ||||
.Ft int | .Ft int | ||||
.Fn unlink "const char *path" | .Fn unlink "const char *path" | ||||
.Ft int | .Ft int | ||||
.Fn unlinkat "int fd" "const char *path" "int flag" | .Fn unlinkat "int dfd" "const char *path" "int flag" | ||||
.Ft int | |||||
.Fn funlinkat "int dfd" "const char *path" "int fd" "int flag" | |||||
jilles: I would prefer a different order that keeps the directory fd and path together. | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn unlink | .Fn unlink | ||||
system call | system call | ||||
removes the link named by | removes the link named by | ||||
.Fa path | .Fa path | ||||
from its directory and decrements the link count of the | from its directory and decrements the link count of the | ||||
file which was referenced by the link. | file which was referenced by the link. | ||||
Show All 15 Lines | |||||
.Fn unlink | .Fn unlink | ||||
or | or | ||||
.Fn rmdir | .Fn rmdir | ||||
except in the case where | except in the case where | ||||
.Fa path | .Fa path | ||||
specifies a relative path. | specifies a relative path. | ||||
In this case the directory entry to be removed is determined | In this case the directory entry to be removed is determined | ||||
relative to the directory associated with the file descriptor | relative to the directory associated with the file descriptor | ||||
.Fa fd | .Fa dfd | ||||
instead of the current working directory. | instead of the current working directory. | ||||
.Pp | .Pp | ||||
The values for | The values for | ||||
.Fa flag | .Fa flag | ||||
are constructed by a bitwise-inclusive OR of flags from the following list, | are constructed by a bitwise-inclusive OR of flags from the following list, | ||||
defined in | defined in | ||||
.In fcntl.h : | .In fcntl.h : | ||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
Show All 22 Lines | |||||
parameter, the current working directory is used and the behavior is | parameter, the current working directory is used and the behavior is | ||||
identical to a call to | identical to a call to | ||||
.Fa unlink | .Fa unlink | ||||
or | or | ||||
.Fa rmdir | .Fa rmdir | ||||
respectively, depending on whether or not the | respectively, depending on whether or not the | ||||
.Dv AT_REMOVEDIR | .Dv AT_REMOVEDIR | ||||
bit is set in flag. | bit is set in flag. | ||||
.Pp | |||||
The | |||||
.Fn funlinkat | |||||
system call can be used to unlink an already-opened file, unless that | |||||
file has been replaced since it was opened. | |||||
It is equivalent to | |||||
.Fn unlinkat | |||||
in the case where | |||||
Done Inline ActionsThis is grammatically incorrect English. Nor is "name" defined as an argument. It should be "path". I suggest except in the case where the file specified by .Fa path is already open as the file descriptor .Fa fd . asomers: This is grammatically incorrect English. Nor is "name" defined as an argument. It should be… | |||||
.Fa path | |||||
is already open as the file descriptor | |||||
Done Inline ActionsThis seems to mean to say: except in the case where .Fa fd is not \-1. It may be worth it to change this -1 to another value to improve error detection, just like FD_ATCWD is not -1 in most implementations. jilles: This seems to mean to say:
```
except in the case where
.Fa fd
is not \-1.
```
It may be worth… | |||||
Done Inline ActionsToo many except's ? It is not clear if second 'except' is sub-except of the first or not. kib: Too many except's ? It is not clear if second 'except' is sub-except of the first or not. | |||||
.Fa fd . | |||||
Done Inline ActionsWhat happens if those arguments are not corresponding? The "equivalent to" descriptor suggests that in this case, the path will still be removed. But that's not what actually happens. You should probably amend the description to say that fdunlinkat is equivalent to unlinkat "in the case where" (note lack of "except"). Then add that "otherwise the path will not be removed and an error will be returned. But that still leaves the reader in a state of mystery, wondering why this syscall exists at all. An explanatory statement would help. So something like this: The .Fn fdunlinkat system call can be used to unlink an already-opened file, unless that file has been replaced since it was opened. It is equivalent to .Fn unlinkat in the case where .Fa name is already open as the file descriptor .Fa fd . Otherwise, the path will not be removed and an error will be returned. asomers: What happens if those arguments are not corresponding? The "equivalent to" descriptor suggests… | |||||
Otherwise, the path will not be removed and an error will be returned. | |||||
The | |||||
.Fa fd | |||||
Not Done Inline Actions'are corresponding' sounds weird and unprecise. You might say 'point to the same file' e.g. kib: 'are corresponding' sounds weird and unprecise. You might say 'point to the same file' e.g. | |||||
can be set the | |||||
.Dv FD_NONE . | |||||
In that case | |||||
Done Inline ActionsYou should start a new sentence for "In that case". asomers: You should start a new sentence for "In that case". | |||||
.Fn funlinkat | |||||
behaves exactly like | |||||
.Fn unlinkat . | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
.Rv -std unlink | .Rv -std unlink | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn unlink | .Fn unlink | ||||
succeeds unless: | succeeds unless: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er ENOTDIR | .It Bq Er ENOTDIR | ||||
▲ Show 20 Lines • Show All 98 Lines • ▼ Show 20 Lines | |||||
.Fn unlinkat , | .Fn unlinkat , | ||||
and the absolute | and the absolute | ||||
.Fa path | .Fa path | ||||
does not have its tail fully contained under the topping directory, | does not have its tail fully contained under the topping directory, | ||||
or the relative | or the relative | ||||
.Fa path | .Fa path | ||||
escapes it. | escapes it. | ||||
.El | .El | ||||
.Pp | |||||
In addition to the errors returned by | |||||
.Fn unlinkat , | |||||
.Fn funlinkat | |||||
Done Inline ActionsYou can remove this "the". asomers: You can remove this "the". | |||||
Not Done Inline ActionsYou still need to remove the "the" before .Fn unlinkat. asomers: You still need to remove the "the" before `.Fn unlinkat`. | |||||
may fail if: | |||||
.Bl -tag -width Er | |||||
.It Bq Er EDEADLK | |||||
Done Inline ActionsI find this error code to be not specific enough for the case. I believe that callers of this syscall would be interested to know that the file was renamed before the attempt to remove. kib: I find this error code to be not specific enough for the case. I believe that callers of this… | |||||
Done Inline ActionsDo you have any particular errno on your main? 35 EAGAIN Resource temporarily unavailable. oshogbo: Do you have any particular errno on your main?
Now I thinking about:
```
35 EAGAIN Resource… | |||||
Not Done Inline ActionsI do not have preference, it should be an error logically impossible with the normal delete. We assign unusual meaning to it anway. EGAIN, EDEADLK, ESPIPE all look good enough. kib: I do not have preference, it should be an error logically impossible with the normal delete. We… | |||||
Done Inline ActionsReusing EAGAIN here has the problem that in other EAGAIN cases there is a reasonable possibility that the same call will succeed later (for example, after fork() failed and other processes have terminated or after recv() failed and the other side sent some data). Although fdunlinkat() may succeed after having failed because of a mismatch (for example, if the file was renamed back), this feels like a contrived situation. If you want to repurpose an existing error, EDEADLK, ESPIPE or EMLINK look more reasonable, but still not very nice. A new errno may be more appropriate. jilles: Reusing `EAGAIN` here has the problem that in other `EAGAIN` cases there is a reasonable… | |||||
Done Inline ActionsChanging size of sys_errlist is a mess. I do not think that it is worth to induce it for such reason. kib: Changing size of sys_errlist is a mess. I do not think that it is worth to induce it for such… | |||||
Not Done Inline ActionsI don't think introducing new errnos should be impossible; apart from this one, ETIME should really be a unique error and not an alias for ETIMEDOUT. Regarding sys_errlist, perhaps we should make this such that dynamically linked applications directly accessing sys_errlist will be limited to the current 97 elements or 6.0's 93 elements (exporting a separate sys_nerr for them) and stop worrying about adding new errors. jilles: I don't think introducing new errnos should be impossible; apart from this one, `ETIME` should… | |||||
Not Done Inline ActionsETIME would simplify porting the linux kernel code, indeed. Introducing new error codes is sure possible, with the consequences and significant amount of work. I do not feel that introducing the error code for fdunlinkat() race failure worth the efforts. Unix API has very strong tradition of overloading error codes. I do not mean EINVAL fail, but other EXXX usage is mostly frivolous and does not cause objections when used not for the situation directly described by the errstr. I do not object strongly for addition if this would be done by somebody else, but myself I would certainly decided to go with the existing number. kib: ETIME would simplify porting the linux kernel code, indeed. Introducing new error codes is… | |||||
The file descriptor is not associated with the path. | |||||
.El | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr chflags 2 , | .Xr chflags 2 , | ||||
.Xr close 2 , | .Xr close 2 , | ||||
.Xr link 2 , | .Xr link 2 , | ||||
.Xr rmdir 2 , | .Xr rmdir 2 , | ||||
.Xr symlink 7 | .Xr symlink 7 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The | The | ||||
.Fn unlinkat | .Fn unlinkat | ||||
system call follows The Open Group Extended API Set 2 specification. | system call follows The Open Group Extended API Set 2 specification. | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Fn unlink | .Fn unlink | ||||
function appeared in | function appeared in | ||||
.At v1 . | .At v1 . | ||||
The | The | ||||
.Fn unlinkat | .Fn unlinkat | ||||
system call appeared in | system call appeared in | ||||
.Fx 8.0 . | .Fx 8.0 . | ||||
The | |||||
.Fn funlinkat | |||||
system call appeared in | |||||
.Fx 13.0 . | |||||
Done Inline ActionsIt should be 12.1 by now. asomers: It should be 12.1 by now. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Fn unlink | .Fn unlink | ||||
system call traditionally allows the super-user to unlink directories which | system call traditionally allows the super-user to unlink directories which | ||||
can damage the file system integrity. | can damage the file system integrity. | ||||
This implementation no longer permits it. | This implementation no longer permits it. |
I would prefer a different order that keeps the directory fd and path together.