unlinkat()

Remove a link to a file at a given location

Synopsis:

#include <fcntl.h>

int unlinkat( int dirfd,
              const char* const path,
              int flags );

Arguments:

dirfd

A file descriptor that indicates the base directory for relative file paths. The symbolic link name given in path is appended to the directory associated with dirfd, to produce the full link path. You can set this argument to AT_FDCWD to use the current working directory as the base directory.

Note: You must use a file descriptor obtained from an open() call with the O_DIRECTORY flag set. Otherwise, the function fails and sets errno to ENOTDIR.

If path specifies an absolute path, dirfd has no effect.

path

The name of the file that you want to unlink.

flags

A bitfield of the following flags:

AT_REMOVEDIR — remove the directory entry specified by dirfd and path as a directory, not a normal file

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The unlinkat() function removes a link to a file if:

The given path names a symbolic link; the removal doesn't affect the target file or directory.
The given path doesn't name a symbolic link; after doing the removal, unlinkat() decrements the link count of the target file.
If the link count of the file becomes zero, and no process has the file open, then the space that the file occupies is freed, and no one can access the file anymore.

If one or more processes have the file open when the last link is removed, the link is removed, but the removal of the file is delayed until all references to it have been closed.

Note: To remove a directory, call rmdir() or remove().

Returns:

0: The operation succeeded.
Nonzero: The operation failed (errno is set).

Errors:

EACCES

One of the following is true:

Search permission is denied on a component of the path prefix of path.
Write permission is denied for the parent directory of the symbolic link to be removed.
The access mode of the dirfd file descriptor is not O_SEARCH and the underlying directory doesn't permit directory searches.
The S_ISVTX flag is set on the directory containing the file referred to by path and the process does not satisfy the directory protection criteria. To learn about these criteria, see the chmod() reference.

EBADF

The path argument does not specify an absolute path and the dirfd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching.

EBUSY

The file named by path cannot be unlinked because it's being used by the system or another process and the target filesystem or resource manager considers this to be an error. Or, the path argument refers to a named STREAM file.

EEXIST

The AT_REMOVEDIR bit is set in flag and path names a directory that is not empty, or there are hard links to the directory other than dot or a single entry in dot-dot.

EINVAL

An invalid value was specified for flag.

ELOOP

During resolution of the path argument, a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered.

ENAMETOOLONG

The length of the path string exceeds PATH_MAX, the resolution of a symbolic link within path produced a result longer than PATH_MAX, or a pathname component is longer than NAME_MAX.

ENOENT

The named file doesn't exist, or path is an empty string.

ENONEMPTY

The AT_REMOVEDIR bit is set in flag and path names a directory that is not empty, or there are hard links to the directory other than dot or a single entry in dot-dot.

ENOSYS

The unlinkat() function isn't implemented for the filesystem underlying the specified path.

ENOTDIR

One of the following is true:

A component of the path prefix names an existing file that is neither a directory nor a symbolic link to one.
The pathname argument contains at least one non-slash character, ends with at least one slash character (/), and the last component names an existing file that is neither a directory nor a symbolic link to one.
The AT_REMOVEDIR bit is set in flag and path doesn't name a directory.
The file descriptor in dirfd was created without O_DIRECTORY set.

EPERM

The file named by path is a directory, and either the calling process doesn't have the appropriate privileges or the target filesystem or resource manager prohibits using unlinkat() on directories. Or, the S_ISVTX flag is set on the directory containing the file named by path and the process does not satisfy the directory protection criteria. To learn about these criteria, see the chmod() reference.

EROFS

The directory entry to be unlinked resides on a read-only filesystem.

ETXTBSY

The entry to be unlinked is the last directory entry to a pure procedure (shared text) file that's currently being executed.

Classification:

POSIX 2008

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes