It's just as informative, and takes less space.
Signed-off-by: Alejandro Colomar <alx@kernel.org>
.nf
.B #include <unistd.h>
.P
-.BI "int access(const char *" pathname ", int " mode );
+.BI "int access(const char *" path ", int " mode );
.P
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <unistd.h>
.P
-.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
-mode ", int " flags );
+.BI "int faccessat(int " dirfd ", const char *" path ", int " mode \
+", int " flags );
/* But see C library/kernel differences, below */
.P
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <unistd.h>
.P
.B int syscall(SYS_faccessat2,
-.BI " int " dirfd ", const char *" pathname ", int " mode \
+.BI " int " dirfd ", const char *" path ", int " mode \
", int " flags );
.fi
.P
.SH DESCRIPTION
.BR access ()
checks whether the calling process can access the file
-.IR pathname .
+.IR path .
If
-.I pathname
+.I path
is a symbolic link, it is dereferenced.
.P
The
.BR access (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR access ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.TP
.BR AT_EMPTY_PATH " (since Linux 5.8)"
If
-.I pathname
+.I path
is an empty string, operate on the file referred to by
.I dirfd
(which may have been obtained using the
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
is a symbolic link, do not dereference it:
instead return information about the link itself.
.P
.B EACCES
The requested access would be denied to the file, or search permission
is denied for one of the directories in the path prefix of
-.IR pathname .
+.IR path .
(See also
.BR path_resolution (7).)
.TP
.B EBADF
.RB ( faccessat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
nor a valid file descriptor.
.TP
.B EFAULT
-.I pathname
+.I path
points outside your accessible address space.
.TP
.B EINVAL
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
A component of
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOMEM
.TP
.B ENOTDIR
A component used as a directory in
-.I pathname
+.I path
is not, in fact, a directory.
.TP
.B ENOTDIR
.RB ( faccessat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
the glibc wrapper function falls back to the use of
.BR access ().
When
-.I pathname
-is a relative pathname,
+.I path
+is relative,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
that corresponds to the
.P
A file is accessible only if the permissions on each of the
directories in the path prefix of
-.I pathname
+.I path
grant search (i.e., execute) access.
If any directory is inaccessible, then the
.BR access ()
.nf
.B #include <sys/stat.h>
.P
-.BI "int chmod(const char *" pathname ", mode_t " mode );
+.BI "int chmod(const char *" path ", mode_t " mode );
.BI "int fchmod(int " fd ", mode_t " mode );
.P
.BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
.B #include <sys/stat.h>
.P
-.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
+.BI "int fchmodat(int " dirfd ", const char *" path ", mode_t " \
mode ", int " flags );
.fi
.P
.IP \[bu] 3
.BR chmod ()
changes the mode of the file specified whose pathname is given in
-.IR pathname ,
+.IR path ,
which is dereferenced if it is a symbolic link.
.IP \[bu]
.BR fchmod ()
.BR chmod (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR chmod ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
is a symbolic link, do not dereference it:
instead operate on the link itself.
This flag is not currently implemented.
.TP
.B EBADF
.RB ( fchmodat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
nor a valid file descriptor.
.TP
.B EFAULT
-.I pathname
+.I path
points outside your accessible address space.
.TP
.B EINVAL
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
.TP
.B ENOTDIR
.RB ( fchmodat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
is unavailable, the glibc wrapper function falls back to the use of
.BR chmod ().
When
-.I pathname
+.I path
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
.nf
.B #include <unistd.h>
.P
-.BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group );
+.BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
-.BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group );
+.BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <unistd.h>
.P
-.BI "int fchownat(int " dirfd ", const char *" pathname ,
+.BI "int fchownat(int " dirfd ", const char *" path ,
.BI " uid_t " owner ", gid_t " group ", int " flags );
.fi
.P
.IP \[bu] 3
.BR chown ()
changes the ownership of the file specified by
-.IR pathname ,
+.IR path ,
which is dereferenced if it is a symbolic link.
.IP \[bu]
.BR fchown ()
.BR chown (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR chown ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
If
-.I pathname
+.I path
is an empty string, operate on the file referred to by
.I dirfd
(which may have been obtained using the
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
is a symbolic link, do not dereference it:
instead operate on the link itself, like
.BR lchown ().
.TP
.B EBADF
.RB ( fchownat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
nor a valid file descriptor.
.TP
.B EFAULT
-.I pathname
+.I path
points outside your accessible address space.
.TP
.B EINVAL
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
.TP
.B ENOTDIR
.RB ( fchownat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
and
.BR lchown ().
When
-.I pathname
-is a relative pathname,
+.I path
+is relative,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
that corresponds to the
.nf
.B #include <unistd.h>
.P
-.BI "int execve(const char *" pathname ", char *const _Nullable " argv [],
+.BI "int execve(const char *" path ", char *const _Nullable " argv [],
.BI " char *const _Nullable " envp []);
.fi
.SH DESCRIPTION
.BR execve ()
executes the program referred to by
-.IR pathname .
+.IR path .
This causes the program that is currently being run by the calling process
to be replaced with a new program, with newly initialized stack, heap,
and (initialized and uninitialized) data segments.
.P
-.I pathname
+.I path
must be either a binary executable, or a script
starting with a line of the form:
.P
.BR execve ().
.P
If the set-user-ID bit is set on the program file referred to by
-.IR pathname ,
+.IR path ,
then the effective user ID of the calling process is changed
to that of the owner of the program file.
Similarly, if the set-group-ID bit is set on the program file,
.in +4n
.SY \f[I]interpreter\f[]
.RI [ optional-arg ]
-.I pathname
+.I path
.IR arg ...
.YS
.in
is too large,
an argument or environment string is too long,
or the full
-.I pathname
+.I path
of the executable is too long.
The terminating null byte is counted as part of the string length.
.TP
.B EACCES
Search permission is denied on a component of the path prefix of
-.I pathname
+.I path
or the name of a script interpreter.
(See also
.BR path_resolution (7).)
For a more detailed explanation of this error, see NOTES.
.TP
.B EFAULT
-.I pathname
+.I path
or one of the pointers in the vectors
.I argv
or
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.I pathname
+.I path
or the name of a script or ELF interpreter.
.TP
.B ELOOP
The per-process limit on the number of open file descriptors has been reached.
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENFILE
The system-wide limit on the total number of open files has been reached.
.TP
.B ENOENT
-The file
-.I pathname
+.I path
or a script or ELF interpreter does not exist.
.TP
.B ENOEXEC
.TP
.B ENOTDIR
A component of the path prefix of
-.I pathname
+.I path
or a script or ELF interpreter is not a directory.
.TP
.B EPERM
.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <unistd.h>
.P
-.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "int execveat(int " dirfd ", const char *" path ,
.BI " char *const _Nullable " argv [],
.BI " char *const _Nullable " envp [],
.BI " int " flags );
system call executes the program referred to by the combination of
.I dirfd
and
-.IR pathname .
+.IR path .
It operates in exactly the same way as
.BR execve (2),
except for the differences described in this manual page.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR execve (2)).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.P
If
-.I pathname
+.I path
is an empty string and the
.B AT_EMPTY_PATH
flag is specified, then the file descriptor
.TP
.B AT_EMPTY_PATH
If
-.I pathname
+.I path
is an empty string, operate on the file referred to by
.I dirfd
(which may have been obtained using the
If the file identified by
.I dirfd
and a non-NULL
-.I pathname
+.I path
is a symbolic link, then the call fails with the error
.BR ELOOP .
.SH RETURN VALUE
The following additional errors can occur for
.BR execveat ():
.TP
-.I pathname
+.I path
is relative but
.I dirfd
is neither
and the file identified by
.I dirfd
and a non-NULL
-.I pathname
+.I path
is a symbolic link.
.TP
.B ENOENT
The program identified by
.I dirfd
and
-.I pathname
+.I path
requires the use of an interpreter program
(such as a script starting with "#!"), but the file descriptor
.I dirfd
See BUGS.
.TP
.B ENOTDIR
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
A string of the second form occurs when the script is specified via both
.I dirfd
and
-.IR pathname ;
+.IR path ;
in this case,
.I P
is the value given in
-.IR pathname .
+.IR path .
.P
For the same reasons described in
.BR fexecve (3),
.P
.BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
.BI " uint64_t " mask ", int " dirfd ,
-.BI " const char *_Nullable " pathname );
+.BI " const char *_Nullable " path );
.fi
.SH DESCRIPTION
For an overview of the fanotify API, see
.TP
.B FAN_MARK_DONT_FOLLOW
If
-.I pathname
+.I path
is a symbolic link, mark the link itself, rather than the file to which it
refers.
(By default,
.BR fanotify_mark ()
dereferences
-.I pathname
+.I path
if it is a symbolic link.)
.TP
.B FAN_MARK_ONLYDIR
.TP
.B FAN_MARK_MOUNT
Mark the mount specified by
-.IR pathname .
+.IR path .
If
-.I pathname
+.I path
is not itself a mount point, the mount containing
-.I pathname
+.I path
will be marked.
All directories, subdirectories, and the contained files of the mount
will be monitored.
.BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
.\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
Mark the filesystem specified by
-.IR pathname .
+.IR path .
The filesystem containing
-.I pathname
+.I path
will be marked.
All the contained files and directories of the filesystem from any mount
point will be monitored.
The filesystem object to be marked is determined by the file descriptor
.I dirfd
and the pathname specified in
-.IR pathname :
+.IR path :
.IP \[bu] 3
If
-.I pathname
+.I path
is NULL,
.I dirfd
defines the filesystem object to be marked.
.IP \[bu]
If
-.I pathname
+.I path
is NULL, and
.I dirfd
takes the special value
the current working directory is to be marked.
.IP \[bu]
If
-.I pathname
+.I path
is absolute, it defines the filesystem object to be marked, and
.I dirfd
is ignored.
.IP \[bu]
If
-.I pathname
+.I path
is relative, and
.I dirfd
does not have the value
.BR AT_FDCWD ,
then the filesystem object to be marked is determined by interpreting
-.I pathname
+.I path
relative the directory referred to by
.IR dirfd .
.IP \[bu]
If
-.I pathname
+.I path
is relative, and
.I dirfd
has the value
.BR AT_FDCWD ,
then the filesystem object to be marked is determined by interpreting
-.I pathname
+.I path
relative to the current working directory.
(See
.BR openat (2)
.IR fanotify_fd .
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
The filesystem object indicated by
.I dirfd
and
-.I pathname
+.I path
has a mark that was updated without the
.B FAN_MARK_EVICTABLE
flag,
The filesystem object indicated by
.I dirfd
and
-.I pathname
+.I path
has a mark that was updated with the
.B FAN_MARK_IGNORE
flag,
The filesystem object indicated by
.I dirfd
and
-.I pathname
+.I path
has a mark that was updated with the
.B FAN_MARK_IGNORE
and
and
.I dirfd
and
-.I pathname
+.I path
specify a directory.
.TP
.B ENODEV
The filesystem object indicated by
.I dirfd
and
-.I pathname
+.I path
is associated with a filesystem that reports zero
.I fsid
(e.g.,
The filesystem object indicated by
.I dirfd
and
-.I pathname
+.I path
does not exist.
This error also occurs when trying to remove a mark from an object
which is not marked.
and
.I dirfd
and
-.I pathname
+.I path
do not specify a directory.
.TP
.B ENOTDIR
and
.I dirfd
and
-.I pathname
+.I path
do not specify a directory.
.TP
.B ENOTDIR
and
.I dirfd
and
-.I pathname
+.I path
do not specify a directory.
.TP
.B EOPNOTSUPP
The object indicated by
-.I pathname
+.I path
is associated with a filesystem
that does not support the encoding of file handles.
This error can be returned only with an fanotify group that identifies
.TP
.B EXDEV
The filesystem object indicated by
-.I pathname
+.I path
resides within a filesystem subvolume (e.g.,
.BR btrfs (5))
which uses a different
.BR FAN_MARK_FLUSH ,
.IR dirfd ,
and
-.I pathname
+.I path
must specify a valid filesystem object, even though this object is not used.
.IP \[bu]
.\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/time.h>
.P
-.BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname ,
+.BI "[[deprecated]] int futimesat(int " dirfd ", const char *" path ,
.BI " const struct timeval " times [2]);
.fi
.P
.BR utimes (2),
except for the differences described in this manual page.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.BR futimesat ():
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
nor a valid file descriptor.
.TP
.B ENOTDIR
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.SH VERSIONS
.SS glibc
If
-.I pathname
+.I path
is NULL, then the glibc
.BR futimesat ()
wrapper function updates the times for the file referred to by
.nf
.B #include <sys/inotify.h>
.P
-.BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask );
+.BI "int inotify_add_watch(int " fd ", const char *" path ", uint32_t " mask );
.fi
.SH DESCRIPTION
.BR inotify_add_watch ()
adds a new watch, or modifies an existing watch,
for the file whose location is specified in
-.IR pathname ;
+.IR path ;
the caller must have read permission for this file.
The
.I fd
argument is a file descriptor referring to the
inotify instance whose watch list is to be modified.
The events to be monitored for
-.I pathname
+.I path
are specified in the
.I mask
bit-mask argument.
.BR inotify_add_watch ()
returns a unique watch descriptor for this inotify instance,
for the filesystem object (inode) that corresponds to
-.IR pathname .
+.IR path .
If the filesystem object
was not previously being watched by this inotify instance,
then the watch descriptor is newly allocated.
contains
.B IN_MASK_CREATE
and
-.I pathname
+.I path
refers to a file already being watched by the same
.IR fd .
.TP
.B EFAULT
-.I pathname
+.I path
points outside of the process's accessible address space.
.TP
.B EINVAL
is not an inotify file descriptor.
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
A directory component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOMEM
contains
.B IN_ONLYDIR
and
-.I pathname
+.I path
is not a directory.
.SH STANDARDS
Linux.
.B #include <sys/stat.h>
.\" .B #include <unistd.h>
.P
-.BI "int mkdir(const char *" pathname ", mode_t " mode );
+.BI "int mkdir(const char *" path ", mode_t " mode );
.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <sys/stat.h>
.P
-.BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode );
+.BI "int mkdirat(int " dirfd ", const char *" path ", mode_t " mode );
.fi
.P
.RS -4
.SH DESCRIPTION
.BR mkdir ()
attempts to create a directory named
-.IR pathname .
+.IR path .
.P
The argument
.I mode
.BR mkdir (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR mkdir ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.B EACCES
The parent directory does not allow write permission to the process,
or one of the directories in
-.I pathname
+.I path
did not allow search permission.
(See also
.BR path_resolution (7).)
.TP
.B EBADF
.RB ( mkdirat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
exhausted.
.TP
.B EEXIST
-.I pathname
+.I path
already exists (not necessarily as a directory).
This includes the case where
-.I pathname
+.I path
is a symbolic link, dangling or not.
.TP
.B EFAULT
-.IR pathname " points outside your accessible address space."
+.I path
+points outside your accessible address space.
.TP
.B EINVAL
The final component ("basename") of the new directory's
-.I pathname
+.I path
is invalid
(e.g., it contains characters not permitted by the underlying filesystem).
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B EMLINK
The number of links to the parent directory would exceed
.BR LINK_MAX .
.TP
.B ENAMETOOLONG
-.IR pathname " was too long."
+.I path
+was too long.
.TP
.B ENOENT
A directory component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOMEM
.TP
.B ENOSPC
The device containing
-.I pathname
+.I path
has no room for the new directory.
.TP
.B ENOSPC
.TP
.B ENOTDIR
A component used as a directory in
-.I pathname
+.I path
is not, in fact, a directory.
.TP
.B ENOTDIR
.RB ( mkdirat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.TP
.B EPERM
The filesystem containing
-.I pathname
+.I path
does not support the creation of directories.
.TP
.B EROFS
-.I pathname
+.I path
refers to a file on a read-only filesystem.
.TP
.B EOVERFLOW
is unavailable, the glibc wrapper function falls back to the use of
.BR mkdir ().
When
-.I pathname
-is a relative pathname,
+.I path
+is relative,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
that corresponds to the
.nf
.B #include <sys/stat.h>
.P
-.BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev );
+.BI "int mknod(const char *" path ", mode_t " mode ", dev_t " dev );
.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <sys/stat.h>
.P
-.BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \
+.BI "int mknodat(int " dirfd ", const char *" path ", mode_t " mode \
", dev_t " dev );
.fi
.P
.BR mknod ()
creates a filesystem node (file, device special file, or
named pipe) named
-.IR pathname ,
+.IR path ,
with attributes specified by
.I mode
and
otherwise it is ignored.
.P
If
-.I pathname
+.I path
already exists, or is a symbolic link, this call fails with an
.B EEXIST
error.
.BR mknod (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR mknod ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.B EACCES
The parent directory does not allow write permission to the process,
or one of the directories in the path prefix of
-.I pathname
+.I path
did not allow search permission.
(See also
.BR path_resolution (7).)
.TP
.B EBADF
.RB ( mknodat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
exhausted.
.TP
.B EEXIST
-.I pathname
+.I path
already exists.
This includes the case where
-.I pathname
+.I path
is a symbolic link, dangling or not.
.TP
.B EFAULT
-.IR pathname " points outside your accessible address space."
+.I path
+points outside your accessible address space.
.TP
.B EINVAL
.I mode
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.IR pathname " was too long."
+.I path
+was too long.
.TP
.B ENOENT
A directory component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOMEM
.TP
.B ENOSPC
The device containing
-.I pathname
+.I path
has no room for the new node.
.TP
.B ENOTDIR
A component used as a directory in
-.I pathname
+.I path
is not, in fact, a directory.
.TP
.B ENOTDIR
.RB ( mknodat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.\" Linux 2.2 and earlier; in Linux 2.4 and later, unprivileged can
.\" use mknod() to make these files.
also returned if the filesystem containing
-.I pathname
+.I path
does not support the type of node requested.
.TP
.B EROFS
-.I pathname
+.I path
refers to a file on a read-only filesystem.
.SH VERSIONS
POSIX.1-2001 says: "The only portable use of
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
-.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname ,
+.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
.BI " unsigned int " flags ", struct mount_attr *" attr \
", size_t " size );
.fi
.BR mount_setattr ()
system call changes the mount properties of a mount or an entire mount tree.
If
-.I pathname
-is a relative pathname,
+.I path
+is relative,
then it is interpreted relative to
the directory referred to by the file descriptor
.IR dirfd .
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to
the current working directory of the calling process.
If
-.I pathname
+.I path
is the empty string and
.B AT_EMPTY_PATH
is specified in
.TP
.B AT_EMPTY_PATH
If
-.I pathname
+.I path
is the empty string,
change the mount properties on
.I dirfd
.SH ERRORS
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
The pathname specified via the
.I dirfd
and
-.I pathname
+.I path
arguments to
.BR mount_setattr ()
isn't a mount point.
#include <unistd.h>
\&
static inline int
-mount_setattr(int dirfd, const char *pathname, unsigned int flags,
+mount_setattr(int dirfd, const char *path, unsigned int flags,
struct mount_attr *attr, size_t size)
{
- return syscall(SYS_mount_setattr, dirfd, pathname, flags,
+ return syscall(SYS_mount_setattr, dirfd, path, flags,
attr, size);
}
\&
}
\&
static inline int
-move_mount(int from_dirfd, const char *from_pathname,
- int to_dirfd, const char *to_pathname, unsigned int flags)
+move_mount(int from_dirfd, const char *from_path,
+ int to_dirfd, const char *to_path, unsigned int flags)
{
- return syscall(SYS_move_mount, from_dirfd, from_pathname,
- to_dirfd, to_pathname, flags);
+ return syscall(SYS_move_mount, from_dirfd, from_path,
+ to_dirfd, to_path, flags);
}
\&
static const struct option longopts[] = {
.nf
.B #include <fcntl.h>
.P
-.BI "int open(const char *" pathname ", int " flags ", ..."
+.BI "int open(const char *" path ", int " flags ", ..."
.BI " \f[R]/*\f[] mode_t " mode " \f[R]*/\f[] );"
.P
-.BI "int creat(const char *" pathname ", mode_t " mode );
+.BI "int creat(const char *" path ", mode_t " mode );
.P
-.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..."
+.BI "int openat(int " dirfd ", const char *" path ", int " flags ", ..."
.BI " \f[R]/*\f[] mode_t " mode " \f[R]*/\f[] );"
.P
/* Documented separately, in \c
.BR openat2 (2):\c
\& */
-.BI "int openat2(int " dirfd ", const char *" pathname ,
+.BI "int openat2(int " dirfd ", const char *" path ,
.BI " const struct open_how *" how ", size_t " size );
.fi
.P
The
.BR open ()
system call opens the file specified by
-.IR pathname .
+.IR path .
If the specified file does not exist,
it may optionally (if
.B O_CREAT
(see below).
A file descriptor is a reference to an open file description;
this reference is unaffected if
-.I pathname
+.I path
is subsequently removed or modified to refer to a different file.
For further details on open file descriptions, see NOTES.
.P
.TP
.B O_CREAT
If
-.I pathname
+.I path
does not exist, create it as a regular file.
.IP
The owner (user ID) of the new file is set to the effective user ID
.TP
.B O_DIRECTORY
If
-.I pathname
+.I path
is not a directory, cause the open to fail.
.\" But see the following and its replies:
.\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
if this flag is specified in conjunction with
.BR O_CREAT ,
and
-.I pathname
+.I path
already exists, then
.BR open ()
fails with the error
When these two flags are specified, symbolic links are not followed:
.\" POSIX.1-2001 explicitly requires this behavior.
if
-.I pathname
+.I path
is a symbolic link, then
.BR open ()
fails regardless of where the symbolic link points.
can be used without
.B O_CREAT
if
-.I pathname
+.I path
refers to a block device.
If the block device is in use by the system (e.g., mounted),
.BR open ()
.TP
.B O_NOCTTY
If
-.I pathname
+.I path
refers to a terminal device\[em]see
.BR tty (4)\[em]it
will not become the process's controlling terminal even if the
.TP
.B O_NOFOLLOW
If the trailing component (i.e., basename) of
-.I pathname
+.I path
is a symbolic link, then the open fails, with the error
.BR ELOOP .
Symbolic links in earlier components of the pathname will still be
.B ELOOP
error that can occur in this case is indistinguishable from the case where
an open fails because there are too many symbolic links found
-while resolving components in the prefix part of the pathname.)
+while resolving components in the path prefix of the pathname.)
.IP
This flag is a FreeBSD extension, which was added in Linux 2.1.126,
and has subsequently been standardized in POSIX.1-2008.
does not require read permission on the object.
.IP
If
-.I pathname
+.I path
is a symbolic link and the
.B O_NOFOLLOW
flag is also specified,
with an empty pathname to have the calls operate on the symbolic link.
.IP
If
-.I pathname
+.I path
refers to an automount point that has not yet been triggered, so no
other filesystem is mounted on it, then the call returns a file
descriptor referring to the automount directory without triggering a mount.
.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
Create an unnamed temporary regular file.
The
-.I pathname
+.I path
argument specifies a directory;
an unnamed inode will be created in that directory's filesystem.
Anything written to the resulting file will be lost when
The
.I dirfd
argument is used in conjunction with the
-.I pathname
+.I path
argument as follows:
.IP \[bu] 3
If the pathname given in
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.IP \[bu]
If the pathname given in
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR open ()).
.IP \[bu]
If the pathname given in
-.I pathname
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
flag.
.P
If the pathname given in
-.I pathname
+.I path
is relative, and
.I dirfd
is not a valid file descriptor, an error
(Specifying an invalid file descriptor number in
.I dirfd
can be used as a means to ensure that
-.I pathname
+.I path
is absolute.)
.\"
.SS openat2(2)
.B EACCES
The requested access to the file is not allowed, or search permission
is denied for one of the directories in the path prefix of
-.IR pathname ,
+.IR path ,
or the file did not exist yet and write access to the parent directory
is not allowed.
(See also
.TP
.B EBADF
.RB ( openat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
was specified in
.I flags
and
-.I pathname
+.I path
refers to a block device that is in use by the system (e.g., it is mounted).
.TP
.B EDQUOT
blocks or inodes on the filesystem has been exhausted.
.TP
.B EEXIST
-.I pathname
+.I path
already exists and
.BR O_CREAT " and " O_EXCL
were used.
.TP
.B EFAULT
-.I pathname
+.I path
points outside your accessible address space.
.TP
.B EFBIG
was specified in
.I flags
and the final component ("basename") of the new file's
-.I pathname
+.I path
is invalid
(e.g., it contains characters not permitted by the underlying filesystem).
.TP
.B EINVAL
The final component ("basename") of
-.I pathname
+.I path
is invalid
(e.g., it contains characters not permitted by the underlying filesystem).
.TP
.B EISDIR
-.I pathname
+.I path
refers to a directory and the access requested involved writing
(that is,
.B O_WRONLY
is set).
.TP
.B EISDIR
-.I pathname
+.I path
refers to an existing directory,
.B O_TMPFILE
and one of
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ELOOP
-.I pathname
+.I path
was a symbolic link, and
.I flags
specified
.BR getrlimit (2)).
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
was too long.
.TP
.B ENFILE
The system-wide limit on the total number of open files has been reached.
.TP
.B ENODEV
-.I pathname
+.I path
refers to a device special file and no corresponding device exists.
(This is a Linux kernel bug; in this situation
.B ENXIO
.TP
.B ENOENT
A directory component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOENT
-.I pathname
+.I path
refers to a nonexistent directory,
.B O_TMPFILE
and one of
Insufficient kernel memory was available.
.TP
.B ENOSPC
-.I pathname
+.I path
was to be created but the device containing
-.I pathname
+.I path
has no room for the new file.
.TP
.B ENOTDIR
A component used as a directory in
-.I pathname
+.I path
is not, in fact, a directory, or
.B O_DIRECTORY
was specified and
-.I pathname
+.I path
was not a directory.
.TP
.B ENOTDIR
.RB ( openat ())
-.I pathname
+.I path
is a relative pathname and
.I dirfd
is a file descriptor referring to a file other than a directory.
.TP
.B EOPNOTSUPP
The filesystem containing
-.I pathname
+.I path
does not support
.BR O_TMPFILE .
.TP
.B EOVERFLOW
-.I pathname
+.I path
refers to a regular file that is too large to be opened.
The usual scenario here is that an application compiled
on a 32-bit platform without
.BR fcntl (2).
.TP
.B EROFS
-.I pathname
+.I path
refers to a file on a read-only filesystem and write access was
requested.
.TP
.B ETXTBSY
-.I pathname
+.I path
refers to an executable image which is currently being executed and
write access was requested.
.TP
.B ETXTBSY
-.I pathname
+.I path
refers to a file that is currently in use as a swap file, and the
.B O_TRUNC
flag was specified.
.TP
.B ETXTBSY
-.I pathname
+.I path
refers to a file that is currently being read by the kernel (e.g., for
module/firmware loading), and write access was requested.
.TP
are specified in
.I flags
and the file specified by
-.I pathname
+.I path
does not exist,
.BR open ()
will create a regular file (i.e.,
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
.P
-.BI "int name_to_handle_at(int " dirfd ", const char *" pathname ,
+.BI "int name_to_handle_at(int " dirfd ", const char *" path ,
.BI " struct file_handle *" handle ,
.BI " int *" mount_id ", int " flags );
.BI "int open_by_handle_at(int " mount_fd ", struct file_handle *" handle ,
the file specified by the
.I dirfd
and
-.I pathname
+.I path
arguments.
The file handle is returned via the argument
.IR handle ,
may fail.
.P
Together, the
-.I pathname
+.I path
and
.I dirfd
arguments identify the file for which a handle is to be obtained.
There are four distinct cases:
.IP \[bu] 3
If
-.I pathname
+.I path
is a nonempty string containing an absolute pathname,
then a handle is returned for the file referred to by that pathname.
In this case,
is ignored.
.IP \[bu]
If
-.I pathname
+.I path
is a nonempty string containing a relative pathname and
.I dirfd
has the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working directory of the caller,
and a handle is returned for the file to which it refers.
.IP \[bu]
If
-.I pathname
+.I path
is a nonempty string containing a relative pathname and
.I dirfd
is a file descriptor referring to a directory, then
-.I pathname
+.I path
is interpreted relative to the directory referred to by
.IR dirfd ,
and a handle is returned for the file to which it refers.
for an explanation of why "directory file descriptors" are useful.)
.IP \[bu]
If
-.I pathname
+.I path
is an empty string and
.I flags
specifies the value
.I mount_id
argument returns an identifier for the filesystem
mount that corresponds to
-.IR pathname .
+.IR path .
This corresponds to the first field in one of the records in
.IR /proc/self/mountinfo .
Opening the pathname in the fifth field of that record yields a file
By default,
.BR name_to_handle_at ()
does not dereference
-.I pathname
+.I path
if it is a symbolic link, and thus returns a handle for the link itself.
If
.B AT_SYMLINK_FOLLOW
is specified in
.IR flags ,
-.I pathname
+.I path
is dereferenced if it is a symbolic link
(so that the call returns a handle for the file referred to by the link).
.P
can fail with the following errors:
.TP
.B EFAULT
-.IR pathname ,
+.IR path ,
.IR mount_id ,
or
.I handle
.BR MAX_HANDLE_SZ .
.TP
.B ENOENT
-.I pathname
+.I path
is an empty string, but
.B AT_EMPTY_PATH
was not specified in
includes
.B AT_EMPTY_PATH
and
-.I pathname
+.I path
is an empty string.
.TP
.B EOPNOTSUPP
is not an open file descriptor.
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
a stateless fashion with respect to the files it serves.
.P
If
-.I pathname
+.I path
refers to a symbolic link and
.I flags
does not specify
main(int argc, char *argv[])
{
int mount_id, fhsize, flags, dirfd;
- char *pathname;
+ char *path;
struct file_handle *fhp;
\&
if (argc != 2) {
- fprintf(stderr, "Usage: %s pathname\[rs]n", argv[0]);
+ fprintf(stderr, "Usage: %s path\[rs]n", argv[0]);
exit(EXIT_FAILURE);
}
\&
- pathname = argv[1];
+ path = argv[1];
\&
/* Allocate file_handle structure. */
\&
dirfd = AT_FDCWD; /* For name_to_handle_at() calls */
flags = 0; /* For name_to_handle_at() calls */
fhp\->handle_bytes = 0;
- if (name_to_handle_at(dirfd, pathname, fhp,
- &mount_id, flags) != \-1
+ if (name_to_handle_at(dirfd, path, fhp, &mount_id, flags) != \-1
|| errno != EOVERFLOW)
{
fprintf(stderr, "Unexpected result from name_to_handle_at()\[rs]n");
\&
/* Get file handle from pathname supplied on command line. */
\&
- if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == \-1)
+ if (name_to_handle_at(dirfd, path, fhp, &mount_id, flags) == \-1)
err(EXIT_FAILURE, "name_to_handle_at");
\&
/* Write mount ID, file handle size, and file handle to stdout,
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
-.BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname ,
+.BI "long syscall(SYS_openat2, int " dirfd ", const char *" path ,
.BI " struct open_how *" how ", size_t " size );
.fi
.P
The
.BR openat2 ()
system call opens the file specified by
-.IR pathname .
+.IR path .
If the specified file does not exist, it may optionally (if
.B O_CREAT
is specified in
As with
.BR openat (2),
if
-.I pathname
-is a relative pathname, then it is interpreted relative to the
+.I path
+is relative, then it is interpreted relative to the
directory referred to by the file descriptor
.I dirfd
(or the current working directory of the calling process, if
is the special value
.BR AT_FDCWD ).
If
-.I pathname
-is an absolute pathname, then
+.I path
+is absolute, then
.I dirfd
is ignored (unless
.I how.resolve
contains
.BR RESOLVE_IN_ROOT ,
in which case
-.I pathname
+.I path
is resolved relative to
.IR dirfd ).
.P
The
.I how
argument specifies how
-.I pathname
+.I path
should be opened, and acts as a superset of the
.I flags
and
This is a bit-mask of flags that modify the way in which
.B all
components of
-.I pathname
+.I path
will be resolved.
(See
.BR path_resolution (7)
is not a descendant of the directory indicated by
.IR dirfd .
This causes absolute symbolic links (and absolute values of
-.IR pathname )
+.IR path )
to be rejected.
.IP
Currently, this flag also disables magic-link resolution (see below).
Treat the directory referred to by
.I dirfd
as the root directory while resolving
-.IR pathname .
+.IR path .
Absolute symbolic links are interpreted relative to
.IR dirfd .
If a prefix component of
-.I pathname
+.I path
equates to
.IR dirfd ,
then an immediately following
is traditionally equivalent to
.IR / ).
If
-.I pathname
-is an absolute path, it is also interpreted relative to
+.I path
+is absolute, it is also interpreted relative to
.IR dirfd .
.IP
The effect of this flag is as though the calling process had used
flag.
.IP
If the trailing component (i.e., basename) of
-.I pathname
+.I path
is a magic link,
.I how.resolve
contains
.BR RESOLVE_NO_MAGICLINKS .
.IP
If the trailing component (i.e., basename) of
-.I pathname
+.I path
is a symbolic link,
.I how.resolve
contains
.B RESOLVE_NO_SYMLINKS
flag,
which affects the treatment of symbolic links in all of the components of
-.IR pathname ,
+.IR path ,
differs from the effect of the
.B O_NOFOLLOW
file creation flag (in
.IR how.flags ),
which affects the handling of symbolic links only in the final component of
-.IR pathname .
+.IR path .
.IP
Applications that employ the
.B RESOLVE_NO_SYMLINKS
Disallow traversal of mount points during path resolution (including all bind
mounts).
Consequently,
-.I pathname
+.I path
must either be on the same mount as the directory referred to by
.IR dirfd ,
or on the same mount as the current working directory if
.B #include <unistd.h>
.P
.BI "ssize_t readlink(size_t " bufsiz ;
-.BI " const char *restrict " pathname ,
+.BI " const char *restrict " path ,
.BI " char " buf "[restrict " bufsiz "], size_t " bufsiz );
.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
.P
.BI "ssize_t readlinkat(size_t " bufsiz ;
-.BI " int " dirfd ", const char *restrict " pathname ,
+.BI " int " dirfd ", const char *restrict " path ,
.BI " char " buf "[restrict " bufsiz "], size_t " bufsiz );
.P
.fi
.SH DESCRIPTION
.BR readlink ()
places the contents of the symbolic link
-.I pathname
+.I path
in the buffer
.IR buf ,
which has size
.BR readlink (),
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR readlink ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.P
Since Linux 2.6.39,
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
-.I pathname
+.I path
can be an empty string,
in which case the call operates on the symbolic link referred to by
.I dirfd
.TP
.B EBADF
.RB ( readlinkat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
.TP
.B EINVAL
The named file (i.e., the final filename component of
-.IR pathname )
+.IR path )
is not a symbolic link.
.TP
.B EIO
.TP
.B ENOTDIR
.RB ( readlinkat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
is unavailable, the glibc wrapper function falls back to the use of
.BR readlink ().
When
-.I pathname
-is a relative pathname,
+.I path
+is relative,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
that corresponds to the
struct stat sb;
\&
if (argc != 2) {
- fprintf(stderr, "Usage: %s <pathname>\[rs]n", argv[0]);
+ fprintf(stderr, "Usage: %s <path>\[rs]n", argv[0]);
exit(EXIT_FAILURE);
}
\&
.nf
.B #include <unistd.h>
.P
-.BI "int rmdir(const char *" pathname );
+.BI "int rmdir(const char *" path );
.fi
.SH DESCRIPTION
.BR rmdir ()
.TP
.B EACCES
Write access to the directory containing
-.I pathname
+.I path
was not allowed, or one of the directories in the path prefix of
-.I pathname
+.I path
did not allow search permission.
(See also
.BR path_resolution (7).)
.TP
.B EBUSY
-.I pathname
+.I path
is currently in use by the system or some process that prevents its
removal.
On Linux, this means
-.I pathname
+.I path
is currently used as a mount point
or is the root directory of the calling process.
.TP
.B EFAULT
-.IR pathname " points outside your accessible address space."
+.I path
+points outside your accessible address space.
.TP
.B EINVAL
-.I pathname
+.I path
has
.I .
as last component.
.TP
.B ELOOP
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.IR pathname " was too long."
+.I path
+was too long.
.TP
.B ENOENT
A directory component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOMEM
Insufficient kernel memory was available.
.TP
.B ENOTDIR
-.IR pathname ,
+.IR path ,
or a component used as a directory in
-.IR pathname ,
+.IR path ,
is not, in fact, a directory.
.TP
.B ENOTEMPTY
-.I pathname
+.I path
contains entries other than
-.IR . " and " .. " ;"
+.I .
+and
+.IR .. ;
or,
-.I pathname
+.I path
has
.I ..
as its final component.
.TP
.B EPERM
The directory containing
-.I pathname
+.I path
has the sticky bit
.RB ( S_ISVTX )
set and the process's effective user ID is neither the user ID
.TP
.B EPERM
The filesystem containing
-.I pathname
+.I path
does not support the removal of directories.
.TP
.B EROFS
-.I pathname
+.I path
refers to a directory on a read-only filesystem.
.SH STANDARDS
POSIX.1-2008.
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
-.BI "int syscall(SYS_spu_create, const char *" pathname \
-", unsigned int " flags ,
+.BI "int syscall(SYS_spu_create, const char *" path ", unsigned int " flags ,
.BI " mode_t " mode ", int " neighbor_fd );
.fi
.P
Cell Broadband Engine Architecture in order to access Synergistic
Processor Units (SPUs).
It creates a new logical context for an SPU in
-.I pathname
+.I path
and returns a file descriptor associated with it.
-.I pathname
+.I path
must refer to a nonexistent directory in the mount point of
the SPU filesystem
.RB ( spufs ).
If
.BR spu_create ()
is successful, a directory is created at
-.I pathname
+.I path
and it is populated with the files described in
.BR spufs (7).
.P
other operations are not defined.
A logical SPU
context is destroyed (along with all files created within the context's
-.I pathname
+.I path
directory) once the last reference to the context has gone;
this usually occurs when the file descriptor returned by
.BR spu_create ()
the group to be switched in and out as a single unit.)
.IP
A new directory will be created at the location specified by the
-.I pathname
+.I path
argument.
This gang may be used to hold other SPU contexts, by providing
a pathname that is within the gang directory to further calls to
An SPU context already exists at the given pathname.
.TP
.B EFAULT
-.I pathname
+.I path
is not a valid string pointer in the
calling process's address space.
.TP
.B EINVAL
-.I pathname
+.I path
is not a directory in the
.BR spufs (7)
mount point, or invalid flags have been provided.
.TP
.B ELOOP
Too many symbolic links were found while resolving
-.IR pathname .
+.IR path .
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached.
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENFILE
.TP
.B ENOENT
Part of
-.I pathname
+.I path
could not be resolved.
.TP
.B ENOMEM
.TP
.B ENOTDIR
A part of
-.I pathname
+.I path
is not a directory.
.TP
.B EPERM
.B CAP_SYS_NICE
capability.
.SH FILES
-.I pathname
+.I path
must point to a location beneath the mount point of
.BR spufs .
By convention, it gets mounted in
.nf
.B #include <sys/stat.h>
.P
-.BI "int stat(const char *restrict " pathname ,
+.BI "int stat(const char *restrict " path ,
.BI " struct stat *restrict " statbuf );
.BI "int fstat(int " fd ", struct stat *" statbuf );
-.BI "int lstat(const char *restrict " pathname ,
+.BI "int lstat(const char *restrict " path ,
.BI " struct stat *restrict " statbuf );
.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
.P
-.BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
+.BI "int fstatat(int " dirfd ", const char *restrict " path ,
.BI " struct stat *restrict " statbuf ", int " flags );
.fi
.P
and
.BR lstat ()\[em]execute
(search) permission is required on all of the directories in
-.I pathname
+.I path
that lead to the file.
.P
.BR stat ()
and
.BR fstatat ()
retrieve information about the file pointed to by
-.IR pathname ;
+.IR path ;
the differences for
.BR fstatat ()
are described below.
is identical to
.BR stat (),
except that if
-.I pathname
+.I path
is a symbolic link, then it returns information about the link itself,
not the file that the link refers to.
.P
and
.BR fstat ().
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
for a relative pathname).
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR stat ()
.BR lstat ()).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
If
-.I pathname
+.I path
is an empty string
(or NULL, since Linux 6.11)
operate on the file referred to by
.TP
.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
Don't automount the terminal ("basename") component of
-.I pathname.
+.I path.
Since Linux 3.1 this flag is ignored.
Since Linux 4.11 this flag is implied.
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
is a symbolic link, do not dereference it:
instead return information about the link itself, like
.BR lstat ().
.B EACCES
Search permission is denied for one of the directories
in the path prefix of
-.IR pathname .
+.IR path .
(See also
.BR path_resolution (7).)
.TP
.TP
.B EBADF
.RB ( fstatat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
Too many symbolic links encountered while traversing the path.
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
A component of
-.I pathname
+.I path
does not exist or is a dangling symbolic link.
.TP
.B ENOENT
-.I pathname
+.I path
is an empty string and
.B AT_EMPTY_PATH
was not specified in
.TP
.B ENOTDIR
A component of the path prefix of
-.I pathname
+.I path
is not a directory.
.TP
.B ENOTDIR
.RB ( fstatat ())
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.TP
.B EOVERFLOW
-.I pathname
+.I path
or
.I fd
refers to a file whose size, inode number,
struct stat sb;
\&
if (argc != 2) {
- fprintf(stderr, "Usage: %s <pathname>\[rs]n", argv[0]);
+ fprintf(stderr, "Usage: %s <path>\[rs]n", argv[0]);
exit(EXIT_FAILURE);
}
\&
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
.P
-.BI "int statx(int " dirfd ", const char *_Nullable restrict " pathname ,
+.BI "int statx(int " dirfd ", const char *_Nullable restrict " path ,
.BI " int " flags ", unsigned int " mask ,
.BI " struct statx *restrict " statxbuf );
.fi
.BR statx ()
with a pathname,
execute (search) permission is required on all of the directories in
-.I pathname
+.I path
that lead to the file.
.P
.BR statx ()
uses
-.IR pathname ,
+.IR path ,
.IR dirfd ,
and
.I flags
.TP
An absolute pathname
If
-.I pathname
+.I path
begins with a slash,
then it is an absolute pathname that identifies the target file.
In this case,
.TP
A relative pathname
If
-.I pathname
+.I path
is a string that begins with a character other than a slash and
.I dirfd
is
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is a relative pathname that is interpreted relative to the process's
current working directory.
.TP
A directory-relative pathname
If
-.I pathname
+.I path
is a string that begins with a character other than a slash and
.I dirfd
is a file descriptor that refers to a directory, then
-.I pathname
+.I path
is a relative pathname that is interpreted relative to the directory
referred to by
.IR dirfd .
.TP
By file descriptor
If
-.I pathname
+.I path
is an empty string (or NULL since Linux 6.11) and the
.B AT_EMPTY_PATH
flag is specified in
.B AT_EMPTY_PATH
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
If
-.I pathname
+.I path
is an empty string (or NULL since Linux 6.11),
operate on the file referred to by
.I dirfd
.TP
.B AT_NO_AUTOMOUNT
Don't automount the terminal ("basename") component of
-.I pathname
+.I path
if it is a directory that is an automount point.
This allows the caller to gather attributes of an automount point
(rather than the location it would mount).
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
is a symbolic link, do not dereference it:
instead return information about the link itself, like
.BR lstat (2).
.B EACCES
Search permission is denied for one of the directories
in the path prefix of
-.IR pathname .
+.IR path .
(See also
.BR path_resolution (7).)
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
nor a valid file descriptor.
.TP
.B EFAULT
-.I pathname
+.I path
or
.I statxbuf
points to a location outside the process's accessible address space
.B AT_EMPTY_PATH
is specified in
.IR flags ,
-pathname is allowed to be NULL).
+.I path
+is allowed to be NULL).
.TP
.B EINVAL
Invalid flag specified in
Too many symbolic links encountered while traversing the pathname.
.TP
.B ENAMETOOLONG
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
A component of
-.I pathname
+.I path
does not exist, or
-.I pathname
+.I path
is an empty string and
.B AT_EMPTY_PATH
was not specified in
.TP
.B ENOTDIR
A component of the path prefix of
-.I pathname
+.I path
is not a directory or
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.nf
.B #include <unistd.h>
.P
-.BI "int unlink(const char *" pathname );
+.BI "int unlink(const char *" path );
.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
.P
-.BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags );
+.BI "int unlinkat(int " dirfd ", const char *" path ", int " flags );
.fi
.P
.RS -4
flag)
except for the differences described here.
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative, then it is interpreted relative to the directory
referred to by the file descriptor
.I dirfd
.BR rmdir (2)
for a relative pathname).
.P
-If the pathname given in
-.I pathname
+If
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR unlink ()
and
.BR rmdir (2)).
.P
-If the pathname given in
-.I pathname
+If
+.I path
is absolute, then
.I dirfd
is ignored.
performs the equivalent of
.BR unlink ()
on
-.IR pathname .
+.IR path .
If the
.B AT_REMOVEDIR
flag is specified, it
performs the equivalent of
.BR rmdir (2)
on
-.IR pathname .
+.IR path .
.P
See
.BR openat (2)
.TP
.B EACCES
Write access to the directory containing
-.I pathname
+.I path
is not allowed for the process's effective UID, or one of the
directories in
-.I pathname
+.I path
did not allow search permission.
(See also
.BR path_resolution (7).)
.TP
.B EBUSY
-The file
-.I pathname
+.I path
cannot be unlinked because it is being used by the system
or another process;
for example, it is a mount point
active but otherwise nameless inode ("NFS silly renamed").
.TP
.B EFAULT
-.I pathname
+.I path
points outside your accessible address space.
.TP
.B EIO
An I/O error occurred.
.TP
.B EISDIR
-.I pathname
+.I path
refers to a directory.
(This is the non-POSIX value returned since Linux 2.1.132.)
.TP
.B ELOOP
Too many symbolic links were encountered in translating
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
-.IR pathname " was too long."
+.I path
+was too long.
.TP
.B ENOENT
A component in
-.I pathname
+.I path
does not exist or is a dangling symbolic link, or
-.I pathname
+.I path
is empty.
.TP
.B ENOMEM
.TP
.B ENOTDIR
A component used as a directory in
-.I pathname
+.I path
is not, in fact, a directory.
.TP
.B EPERM
.TP
.BR EPERM " or " EACCES
The directory containing
-.I pathname
+.I path
has the sticky bit
.RB ( S_ISVTX )
set and the process's effective UID is neither the UID of the file to
.BR FS_IOC_SETFLAGS (2const).)
.TP
.B EROFS
-.I pathname
+.I path
refers to a file on a read-only filesystem.
.P
The same errors that occur for
.BR unlinkat ():
.TP
.B EBADF
-.I pathname
+.I path
is relative but
.I dirfd
is neither
.IR flags .
.TP
.B EISDIR
-.I pathname
+.I path
refers to a directory, and
.B AT_REMOVEDIR
was not specified in
.IR flags .
.TP
.B ENOTDIR
-.I pathname
+.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
or
.BR rmdir (2).
When
-.I pathname
-is a relative pathname,
+.I path
+is relative,
glibc constructs a pathname based on the symbolic link in
.I /proc/self/fd
that corresponds to the
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
.P
-.BI "int utimensat(int " dirfd ", const char *" pathname ,
+.BI "int utimensat(int " dirfd ", const char *" path ,
.BI " const struct timespec " times "[_Nullable 2], int " flags );
.BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);"
.fi
With
.BR utimensat ()
the file is specified via the pathname given in
-.IR pathname .
+.IR path .
With
.BR futimens ()
the file whose timestamps are to be updated is specified via
.\"
.SS utimensat() specifics
If
-.I pathname
+.I path
is relative, then by default it is interpreted relative to the
directory referred to by the open file descriptor,
.I dirfd
for an explanation of why this can be useful.
.P
If
-.I pathname
+.I path
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
-.I pathname
+.I path
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).
.P
If
-.I pathname
+.I path
is absolute, then
.I dirfd
is ignored.
.TP
.BR AT_EMPTY_PATH " (since Linux 5.8)"
If
-.I pathname
+.I path
is an empty string, operate on the file referred to by
.I dirfd
(which may have been obtained using the
.TP
.B AT_SYMLINK_NOFOLLOW
If
-.I pathname
+.I path
specifies a symbolic link, then update the timestamps of the link,
rather than the file to which it refers.
.SH RETURN VALUE
.TP
.B EBADF
.RB ( utimensat ())
-.I pathname
+.I path
is relative but
.I dirfd
is neither
was
.BR AT_FDCWD ,
and
-.I pathname
+.I path
is NULL or an invalid address.
.TP
.B EINVAL
.TP
.B EINVAL
.\" SUSv4 does not specify this error.
-.I pathname
+.I path
is NULL,
.I dirfd
is not
.B ELOOP
.RB ( utimensat ())
Too many symbolic links were encountered in resolving
-.IR pathname .
+.IR path .
.TP
.B ENAMETOOLONG
.RB ( utimensat ())
-.I pathname
+.I path
is too long.
.TP
.B ENOENT
.RB ( utimensat ())
A component of
-.I pathname
+.I path
does not refer to an existing directory or file,
or
-.I pathname
+.I path
is an empty string.
.TP
.B ENOTDIR
.RB ( utimensat ())
-.I pathname
-is a relative pathname, but
+.I path
+is relative, but
.I dirfd
is neither
.B AT_FDCWD
nor a file descriptor referring to a directory;
or, one of the prefix components of
-.I pathname
+.I path
is not a directory.
.TP
.B EPERM
.B ESRCH
.RB ( utimensat ())
Search permission is denied for one of the prefix components of
-.IR pathname .
+.IR path .
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
To support this, the Linux
.BR utimensat ()
system call implements a nonstandard feature: if
-.I pathname
+.I path
is NULL, then the call modifies the timestamps of
the file referred to by the file descriptor
.I dirfd
Note, however, that the glibc wrapper for
.BR utimensat ()
disallows passing NULL as the value for
-.IR pathname :
+.IR path :
the wrapper function returns the error
.B EINVAL
in this case.
succeeds even if the file referred to by
.I dirfd
and
-.I pathname
+.I path
does not exist.
.SH BUGS
Several bugs afflict
projects / thirdparty / man-pages.git / commitdiff
