diff options
author | kib <kib@FreeBSD.org> | 2008-04-16 13:03:12 +0000 |
---|---|---|
committer | kib <kib@FreeBSD.org> | 2008-04-16 13:03:12 +0000 |
commit | 2e4b86adc7ebc6a6f218f0ad58bf2e06954acd0d (patch) | |
tree | 03acdbf3f7e88a48d315dac76d504fadeac388b0 /lib/libc | |
parent | 52243403eb48561abd7b33995f5a4be6a56fa1f0 (diff) | |
download | FreeBSD-src-2e4b86adc7ebc6a6f218f0ad58bf2e06954acd0d.zip FreeBSD-src-2e4b86adc7ebc6a6f218f0ad58bf2e06954acd0d.tar.gz |
Man pages for the openat(2), fexecve(2) and related syscalls.
Reviewed by: ru
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/sys/access.2 | 74 | ||||
-rw-r--r-- | lib/libc/sys/chmod.2 | 81 | ||||
-rw-r--r-- | lib/libc/sys/chown.2 | 88 | ||||
-rw-r--r-- | lib/libc/sys/execve.2 | 57 | ||||
-rw-r--r-- | lib/libc/sys/link.2 | 116 | ||||
-rw-r--r-- | lib/libc/sys/mkdir.2 | 60 | ||||
-rw-r--r-- | lib/libc/sys/mkfifo.2 | 60 | ||||
-rw-r--r-- | lib/libc/sys/mknod.2 | 60 | ||||
-rw-r--r-- | lib/libc/sys/open.2 | 85 | ||||
-rw-r--r-- | lib/libc/sys/readlink.2 | 62 | ||||
-rw-r--r-- | lib/libc/sys/rename.2 | 79 | ||||
-rw-r--r-- | lib/libc/sys/stat.2 | 84 | ||||
-rw-r--r-- | lib/libc/sys/symlink.2 | 60 | ||||
-rw-r--r-- | lib/libc/sys/unlink.2 | 107 | ||||
-rw-r--r-- | lib/libc/sys/utimes.2 | 65 |
15 files changed, 1098 insertions, 40 deletions
diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2 index 3d4dbdd..0cd3c6f 100644 --- a/lib/libc/sys/access.2 +++ b/lib/libc/sys/access.2 @@ -28,11 +28,13 @@ .\" @(#)access.2 8.2 (Berkeley) 4/1/94 .\" $FreeBSD$ .\" -.Dd February 11, 2008 +.Dd April 10, 2008 .Dt ACCESS 2 .Os .Sh NAME -.Nm access , eaccess +.Nm access , +.Nm eaccess , +.Nm faccessat .Nd check accessibility of a file .Sh LIBRARY .Lb libc @@ -42,6 +44,8 @@ .Fn access "const char *path" "int mode" .Ft int .Fn eaccess "const char *path" "int mode" +.Ft int +.Fn faccessat "int fd" "const char *path" "int mode" "int flag" .Sh DESCRIPTION The .Fn access @@ -86,6 +90,38 @@ the real user ID in place of the effective user ID, the real group ID in place of the effective group ID, and the rest of the group access list. .Pp +The +.Fn faccessat +system call is equivalent to +.Fn access +except in the case where +.Fa path +specifies a relative path. +In this case the file whose accessibility is to be determined is +located relative to the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn faccessat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn access . +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_EACCESS +The checks for accessibility are performed using the effective user and group +IDs instead of the real user and group ID as required in a call to +.Fn access . +.El +.Pp Even if a process's real or effective user has appropriate privileges and indicates success for .Dv X_OK , @@ -125,6 +161,33 @@ points outside the process's allocated address space. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El +.Pp +Also, the +.Fn faccessat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SECURITY CONSIDERATIONS The .Fn access @@ -158,8 +221,15 @@ The .Fn access system call is expected to conform to .St -p1003.1-90 . +The +.Fn faccessat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn access function appeared in .At v7 . +The +.Fn faccessat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 185463d..3547aec 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -28,13 +28,14 @@ .\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd January 16, 2006 +.Dd April 10, 2008 .Dt CHMOD 2 .Os .Sh NAME .Nm chmod , .Nm fchmod , -.Nm lchmod +.Nm lchmod , +.Nm fchmodat .Nd change mode of file .Sh LIBRARY .Lb libc @@ -46,6 +47,8 @@ .Fn fchmod "int fd" "mode_t mode" .Ft int .Fn lchmod "const char *path" "mode_t mode" +.Ft int +.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" .Sh DESCRIPTION The file permission bits of the file named specified by .Fa path @@ -73,6 +76,45 @@ system call is similar to .Fn chmod but does not follow symbolic links. .Pp +The +.Fn fchmodat +is equivalent to either +.Fn chmod +or +.Fn lchmod +depending on the +.Fa flag +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, defined +in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, then the mode of the symbolic link is changed. +.El +.Pp +If +.Fn fchmodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used. +If also +.Fa flag +is zero, the behavior is identical to a call to +.Fn chmod . +.Pp A mode is created from .Em or'd permission bit masks @@ -213,6 +255,34 @@ The file resides on a read-only file system. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El +.Pp +In addition to the +.Fn chmod +errors, +.Fn fchmodat +fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Fa AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chmod 1 , .Xr chflags 2 , @@ -229,6 +299,9 @@ except for the return of .Er EFTYPE and the use of .Dv S_ISTXT . +The +.Fn fchmodat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn chmod @@ -242,3 +315,7 @@ The .Fn lchmod system call appeared in .Fx 3.0 . +The +.Fn fchmodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2 index b95612e..32c29ff 100644 --- a/lib/libc/sys/chown.2 +++ b/lib/libc/sys/chown.2 @@ -28,13 +28,14 @@ .\" @(#)chown.2 8.4 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt CHOWN 2 .Os .Sh NAME .Nm chown , .Nm fchown , -.Nm lchown +.Nm lchown , +.Nm fchownat .Nd change owner and group of a file .Sh LIBRARY .Lb libc @@ -46,6 +47,8 @@ .Fn fchown "int fd" "uid_t owner" "gid_t group" .Ft int .Fn lchown "const char *path" "uid_t owner" "gid_t group" +.Ft int +.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" .Sh DESCRIPTION The owner ID and group ID of the file named by @@ -91,6 +94,49 @@ system call is similar to .Fn chown but does not follow symbolic links. .Pp +The +.Fn fchownat +system call is equivalent to the +.Fn chown +and +.Fn lchown +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, ownership of the symbolic link is changed. +.El +.Pp +If +.Fn fchownat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical +to a call to +.Fn chown +or +.Fn lchown +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in the +.Fa flag +argument. +.Pp One of the owner or group id's may be left unchanged by specifying it as -1. .Sh RETURN VALUES @@ -152,6 +198,36 @@ The named file resides on a read-only file system. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El +.Pp +In addition to the errors specified for +.Fn chown +and +.Fn lchown , +the +.Fn fchownat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chgrp 1 , .Xr chflags 2 , @@ -163,6 +239,9 @@ The .Fn chown system call is expected to conform to .St -p1003.1-90 . +The +.Fn fchownat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn chown @@ -182,3 +261,8 @@ The system call was added in .Fx 3.0 to compensate for the loss of functionality. +.Pp +The +.Fn fchownat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index feac99b..c077008 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -28,11 +28,12 @@ .\" @(#)execve.2 8.5 (Berkeley) 6/1/94 .\" $FreeBSD$ .\" -.Dd June 1, 1994 +.Dd April 10, 2008 .Dt EXECVE 2 .Os .Sh NAME -.Nm execve +.Nm execve , +.Nm fexecve .Nd execute a file .Sh LIBRARY .Lb libc @@ -40,6 +41,8 @@ .In unistd.h .Ft int .Fn execve "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" .Sh DESCRIPTION The .Fn execve @@ -50,6 +53,15 @@ whose name is pointed to by .Fa path , called the .Em new process file . +The +.Fn fexecve +system call is equivalent to +.Fn execve +except that the file to be executed is determined by the file +descriptor +.Fa fd +instead of a +.Fa path . This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, @@ -199,6 +211,29 @@ and .Fa argv points to the array of character pointers to the arguments themselves. +.Pp +The +.Fn fexecve +ignores the file offset of +.Fa fd . +Since execute permission is checked by +.Fn fexecve , +the file descriptor +.Fa fd +need not have been +opened with the +.Dv O_EXEC +flag. +However, if the file to be executed denies read and write +permission for the process preparing to do the exec, the only way to +provide the +.Fa fd +to +.Fn fexecve +is to use the +.Dv O_EXEC +flag when opening +.Fa fd . .Sh RETURN VALUES As the .Fn execve @@ -269,6 +304,16 @@ to an illegal address. .It Bq Er EIO An I/O error occurred while reading from the file system. .El +.Pp +In addition, the +.Fn fexecve +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor open for executing. +.El .Sh CAVEAT If a program is .Em setuid @@ -281,6 +326,7 @@ of a super-user as well. .Xr ktrace 1 , .Xr _exit 2 , .Xr fork 2 , +.Xr open 2 , .Xr execl 3 , .Xr exit 3 , .Xr sysctl 3 , @@ -299,8 +345,15 @@ A future update of the Standard is expected to require this behavior, and it may become the default for non-privileged processes as well. .\" NB: update this caveat when TC1 is blessed. The support for executing interpreted programs is an extension. +The +.Fn fexecve +system call conforms to The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn execve system call appeared in .Bx 4.2 . +The +.Fn fexecve +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index edf2e03..8c0a115 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -28,11 +28,12 @@ .\" @(#)link.2 8.3 (Berkeley) 1/12/94 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt LINK 2 .Os .Sh NAME -.Nm link +.Nm link , +.Nm linkat .Nd make a hard file link .Sh LIBRARY .Lb libc @@ -40,6 +41,10 @@ .In unistd.h .Ft int .Fn link "const char *name1" "const char *name2" +.Ft int +.Fo linkat +.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" +.Fc .Sh DESCRIPTION The .Fn link @@ -79,6 +84,67 @@ The .Fa name1 argument may not be a directory. +.Pp +The +.Fn linkat +system call is equivalent to +.Fa link +except in the case where either +.Fa name1 +or +.Fa name2 +or both are relative paths. +In this case a relative path +.Fa name1 +is interpreted relative to +the directory associated with the file descriptor +.Fa fd1 +instead of the current working directory and similarly for +.Fa name2 +and the file descriptor +.Fa fd2 . +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa name1 +names a symbolic link, a new link for the target of the symbolic link is +created. +.El +.Pp +If +.Fn linkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd1 +or +.Fa fd2 +parameter, the current working directory is used for the respective +.Fa name +argument. +If both +.Fa fd1 +and +.Fa fd2 +have value +.Dv AT_FDCWD , +the behavior is identical to a call to +.Fn link . +Unless +.Fa flag +contains the +.Dv AT_SYMLINK_FOLLOW +flag, if +.Fa name1 +names a symbolic link, a new link is created for the symbolic link +.Fa name1 +and not its target. .Sh RETURN VALUES .Rv -std link .Sh ERRORS @@ -156,6 +222,42 @@ system. One of the pathnames specified is outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn link , +the +.Fn linkat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name1 +or +.Fa name2 +argument does not specify an absolute path and the +.Fa fd1 +or +.Fa fd2 +argument, respectively, is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa name1 +or +.Fa name2 +argument is not an absolute path and +.Fa fd1 +or +.Fa fd2 , +respectively, is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr readlink 2 , @@ -166,15 +268,21 @@ The .Fn link system call is expected to conform to .St -p1003.1-90 . +The +.Fn linkat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn link function appeared in .At v7 . +The +.Fn linkat +system call appeared in +.Fx 8.0 . .Pp The .Fn link system call traditionally allows the super-user to link directories which corrupts the file system coherency. -This implementation no longer permits -it. +This implementation no longer permits it. diff --git a/lib/libc/sys/mkdir.2 b/lib/libc/sys/mkdir.2 index 94317d6..332cf49 100644 --- a/lib/libc/sys/mkdir.2 +++ b/lib/libc/sys/mkdir.2 @@ -28,11 +28,12 @@ .\" @(#)mkdir.2 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt MKDIR 2 .Os .Sh NAME -.Nm mkdir +.Nm mkdir , +.Nm mkdirat .Nd make a directory file .Sh LIBRARY .Lb libc @@ -41,6 +42,8 @@ .In sys/stat.h .Ft int .Fn mkdir "const char *path" "mode_t mode" +.Ft int +.Fn mkdirat "int fd" "const char *path" "mode_t mode" .Sh DESCRIPTION The directory .Fa path @@ -53,6 +56,27 @@ of the calling process. The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to that of the parent directory in which it is created. +.Pp +The +.Fn mkdirat +system call is equivalent to +.Fn mkdir +except in the case where +.Fa path +specifies a relative path. +In this case the newly created directory is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkdirat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkdir . .Sh RETURN VALUES .Rv -std mkdir .Sh ERRORS @@ -106,6 +130,30 @@ The argument points outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn mkdir , +the +.Fn mkdirat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr chmod 2 , @@ -116,3 +164,11 @@ The .Fn mkdir system call is expected to conform to .St -p1003.1-90 . +The +.Fn mkdirat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkdirat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/mkfifo.2 b/lib/libc/sys/mkfifo.2 index 2011924..9b4ac5d 100644 --- a/lib/libc/sys/mkfifo.2 +++ b/lib/libc/sys/mkfifo.2 @@ -28,11 +28,12 @@ .\" @(#)mkfifo.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 10, 2006 +.Dd April 10, 2008 .Dt MKFIFO 2 .Os .Sh NAME -.Nm mkfifo +.Nm mkfifo , +.Nm mkfifoat .Nd make a fifo file .Sh LIBRARY .Lb libc @@ -41,6 +42,8 @@ .In sys/stat.h .Ft int .Fn mkfifo "const char *path" "mode_t mode" +.Ft int +.Fn mkfifoat "int fd" "const char *path" "mode_t mode" .Sh DESCRIPTION The .Fn mkfifo @@ -57,6 +60,27 @@ of the calling process. The fifo's owner ID is set to the process's effective user ID. The fifo's group ID is set to that of the parent directory in which it is created. +.Pp +The +.Fn mkfifoat +system call is equivalent to +.Fn mkfifo +except in the case where +.Fa path +specifies a relative path. +In this case the newly created FIFO is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkfifoat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkfifo . .Sh RETURN VALUES .Rv -std mkfifo .Sh ERRORS @@ -116,6 +140,30 @@ The argument points outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn mkfifo , +the +.Fn mkfifoat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr chmod 2 , @@ -127,3 +175,11 @@ The .Fn mkfifo system call is expected to conform to .St -p1003.1-90 . +The +.Fn mkfifoat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkfifoat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2 index 51f5876..0fc8771 100644 --- a/lib/libc/sys/mknod.2 +++ b/lib/libc/sys/mknod.2 @@ -28,11 +28,12 @@ .\" @(#)mknod.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd June 4, 1993 +.Dd April 10, 2008 .Dt MKNOD 2 .Os .Sh NAME -.Nm mknod +.Nm mknod , +.Nm mknodat .Nd make a special file node .Sh LIBRARY .Lb libc @@ -40,6 +41,8 @@ .In unistd.h .Ft int .Fn mknod "const char *path" "mode_t mode" "dev_t dev" +.Ft int +.Fn mknodat "int fd" "const char *path" "mode_t mode" "dev_t dev" .Sh DESCRIPTION The file system node .Fa path @@ -61,6 +64,27 @@ The .Fn mknod system call requires super-user privileges. +.Pp +The +.Fn mknodat +system call is equivalent to +.Fn mknod +except in the case where +.Fa path +specifies a relative path. +In this case the newly created device node is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mknodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mknod . .Sh RETURN VALUES .Rv -std mknod .Sh ERRORS @@ -114,13 +138,45 @@ file (or a .Em whiteout ) is not supported. .El +.Pp +In addition to the errors returned by the +.Fn mknod , +the +.Fn mknodat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chmod 2 , .Xr mkfifo 2 , .Xr stat 2 , .Xr umask 2 +.Sh STANDARDS +The +.Fn mknodat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn mknod function appeared in .At v6 . +The +.Fn mknodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index 423cf8b..8fc6d76 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -28,23 +28,25 @@ .\" @(#)open.2 8.2 (Berkeley) 11/16/93 .\" $FreeBSD$ .\" -.Dd January 7, 2007 +.Dd April 10, 2008 .Dt OPEN 2 .Os .Sh NAME -.Nm open -.Nd open or create a file for reading or writing +.Nm open , openat +.Nd open or create a file for reading, writing or executing .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In fcntl.h .Ft int .Fn open "const char *path" "int flags" "..." +.Ft int +.Fn openat "int fd" "const char *path" "int flags" "..." .Sh DESCRIPTION The file name specified by .Fa path is opened -for reading and/or writing as specified by the +for either execution or reading and/or writing as specified by the argument .Fa flags and the file descriptor returned to the calling process. @@ -56,7 +58,9 @@ created if it does not exist (by specifying the flag). In this case .Fn open -requires a third argument +and +.Fn openat +require an additional argument .Fa "mode_t mode" , and the file is created with mode .Fa mode @@ -65,6 +69,32 @@ as described in and modified by the process' umask value (see .Xr umask 2 ) . .Pp +The +.Fn openat +function is equivalent to the +.Fn open +function except in the case where the +.Fa path +specifies a relative path. +In this case the file to be opened is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The +.Fa flag +parameter and the optional fourth parameter correspond exactly to +the parameters of +.Fn open . +If +.Fn openat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used +and the behavior is identical to a call to +.Fn open . +.Pp The flags specified are formed by .Em or Ns 'ing the following values @@ -73,6 +103,7 @@ the following values O_RDONLY open for reading only O_WRONLY open for writing only O_RDWR open for reading and writing +O_EXEC open for execute only O_NONBLOCK do not block on open O_APPEND append on each write O_CREAT create file if it does not exist @@ -180,7 +211,7 @@ system call will not assign controlling terminals on If successful, .Fn open returns a non-negative integer, termed a file descriptor. -It returns -1 on failure. +It returns \-1 on failure. The file pointer used to mark the current position within the file is set to the beginning of the file. .Pp @@ -202,8 +233,10 @@ system call returns the current system limit. .Sh RETURN VALUES If successful, .Fn open -returns a non-negative integer, termed a file descriptor. -It returns -1 on failure, and sets +and +.Fn openat +return a non-negative integer, termed a file descriptor. +They return \-1 on failure, and set .Va errno to indicate the error. .Sh ERRORS @@ -346,13 +379,32 @@ An attempt was made to open a descriptor with an illegal combination of .Dv O_RDONLY , .Dv O_WRONLY , +.Dv O_RDWR and -.Dv O_RDWR . +.Dv O_EXEC. +.It Bq Eq EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Eq ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. .El .Sh SEE ALSO .Xr chmod 2 , .Xr close 2 , .Xr dup 2 , +.Xr fexecve 2 , .Xr fhopen 2 , .Xr getdtablesize 2 , .Xr getfh 2 , @@ -367,3 +419,18 @@ The .Fn open function appeared in .At v6 . +The +.Fn openat +function was introduced in +.Fx 8.0 . +.Sh BUGS +The Open Group Extended API Set 2 specification requires that the test +for whether +.Fa fd +is searchable is based on whether +.Fa fd +is open for searching, not whether the underlying directory currently +permits searches. +The present implementation of the +.Fa openat +checks the current permissions of directory instead. diff --git a/lib/libc/sys/readlink.2 b/lib/libc/sys/readlink.2 index 1c2593a..4b24052 100644 --- a/lib/libc/sys/readlink.2 +++ b/lib/libc/sys/readlink.2 @@ -28,11 +28,12 @@ .\" @(#)readlink.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd February 26, 2008 +.Dd April 10, 2008 .Dt READLINK 2 .Os .Sh NAME -.Nm readlink +.Nm readlink , +.Nm readlinkat .Nd read value of a symbolic link .Sh LIBRARY .Lb libc @@ -40,6 +41,10 @@ .In unistd.h .Ft ssize_t .Fn readlink "const char *restrict path" "char *restrict buf" "size_t bufsiz" +.Ft ssize_t +.Fo readlinkat +.Fa "int fd" "const char *restrict path" "char *restrict buf" "size_t bufsize" +.Fc .Sh DESCRIPTION The .Fn readlink @@ -56,6 +61,27 @@ system call does not append a .Dv NUL character to .Fa buf . +.Pp +The +.Fn readlinkat +system call is equivalent to +.Fn readlink +except in the case where +.Fa path +specifies a relative path. +In this case the symbolic link whose content is read relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn readlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn readlink . .Sh RETURN VALUES The call returns the count of characters placed in the buffer if it succeeds, or a \-1 if an error occurs, placing the error @@ -88,13 +114,45 @@ The argument extends outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn readlink , +the +.Fn readlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr lstat 2 , .Xr stat 2 , .Xr symlink 2 , .Xr symlink 7 +.Sh STANDARDS +The +.Fn readlinkat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn readlink system call appeared in .Bx 4.2 . +The +.Fn readlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 index 3c3001c..52f9588 100644 --- a/lib/libc/sys/rename.2 +++ b/lib/libc/sys/rename.2 @@ -28,7 +28,7 @@ .\" @(#)rename.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt RENAME 2 .Os .Sh NAME @@ -40,6 +40,8 @@ .In stdio.h .Ft int .Fn rename "const char *from" "const char *to" +.Ft int +.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" .Sh DESCRIPTION The .Fn rename @@ -73,6 +75,37 @@ If the final component of is a symbolic link, the symbolic link is renamed, not the file or directory to which it points. +.Pp +The +.Fn renameat +system call is equivalent to +.Fn rename +except in the case where either +.Fa from +or +.Fa to +specifies a relative path. +If +.Fa from +is a relative path, the file to be renamed is located +relative to the directory associated with the file descriptor +.Fa fromfd +instead of the current working directory. +If the +.Fa to +is a relative path, the same happens only relative to the directory associated +with +.Fa tofd . +If the +.Fn renameat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fromfd +or +.Fa tofd +parameter, the current working directory is used in the determination +of the file for the respective path parameter. .\".Sh CAVEAT .\"The system can deadlock if a loop in the file system graph is present. .\"This loop takes the form of an entry in directory @@ -215,6 +248,42 @@ The argument is a directory and is not empty. .El +.Pp +In addition to the errors returned by the +.Fn rename , +the +.Fn renameat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa from +argument does not specify an absolute path and the +.Fa fromfd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching, or the +.Fa to +argument does not specify an absolute path and the +.Fa tofd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa from +argument is not an absolute path and +.Fa fromfd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory, or the +.Fa to +argument is not an absolute path and +.Fa tofd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr open 2 , @@ -224,3 +293,11 @@ The .Fn rename system call is expected to conform to .St -p1003.1-96 . +The +.Fn renameat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn renameat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 index e767451..3085ef0 100644 --- a/lib/libc/sys/stat.2 +++ b/lib/libc/sys/stat.2 @@ -28,13 +28,14 @@ .\" @(#)stat.2 8.4 (Berkeley) 5/1/95 .\" $FreeBSD$ .\" -.Dd October 12, 2006 +.Dd April 10, 2008 .Dt STAT 2 .Os .Sh NAME .Nm stat , .Nm lstat , -.Nm fstat +.Nm fstat , +.Nm fstatat .Nd get file status .Sh LIBRARY .Lb libc @@ -47,6 +48,8 @@ .Fn lstat "const char *path" "struct stat *sb" .Ft int .Fn fstat "int fd" "struct stat *sb" +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" .Sh DESCRIPTION The .Fn stat @@ -75,6 +78,48 @@ known by the file descriptor .Fa fd . .Pp The +.Fn fstatat +system call is equivalent to +.Fn stat +and +.Fn lstat +except in the case where the +.Fa path +specifies a relative path. +In this case the status is retrieved from a file relative to +the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the status of the symbolic link is returned. +.El +.Pp +If +.Fn fstatat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn stat +or +.Fn lstat +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in +.Fa flag . +.Pp +The .Fa sb argument is a pointer to a .Vt stat @@ -315,6 +360,34 @@ The file size in bytes cannot be represented correctly in the structure pointed to by .Fa sb . .El +.Pp +In addition to the errors returned by the +.Fn lstat , +the +.Fn fstatat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr access 2 , .Xr chmod 2 , @@ -331,6 +404,9 @@ and .Fn fstat system calls are expected to conform to .St -p1003.1-90 . +The +.Fn fchownat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn stat @@ -342,6 +418,10 @@ The .Fn lstat system call appeared in .Bx 4.2 . +The +.Fn fstatat +system call appeared in +.Fx 8.0 . .Sh BUGS Applying .Fn fstat diff --git a/lib/libc/sys/symlink.2 b/lib/libc/sys/symlink.2 index 28d77f5..bfe2ede 100644 --- a/lib/libc/sys/symlink.2 +++ b/lib/libc/sys/symlink.2 @@ -28,11 +28,12 @@ .\" @(#)symlink.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt SYMLINK 2 .Os .Sh NAME -.Nm symlink +.Nm symlink , +.Nm symlinkat .Nd make symbolic link to a file .Sh LIBRARY .Lb libc @@ -40,6 +41,8 @@ .In unistd.h .Ft int .Fn symlink "const char *name1" "const char *name2" +.Ft int +.Fn symlinkat "const char *name1" "int fd" "const char *name2" .Sh DESCRIPTION A symbolic link .Fa name2 @@ -53,6 +56,27 @@ is the string used in creating the symbolic link). Either name may be an arbitrary path name; the files need not be on the same file system. +.Pp +The +.Fn symlinkat +system call is equivalent to +.Fn symlink +except in the case where +.Fa name2 +specifies a relative path. +In this case the symbolic link is created relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn symlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn symlink . .Sh RETURN VALUES .Rv -std symlink .Sh ERRORS @@ -135,6 +159,30 @@ or argument points outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn symlink , +the +.Fn symlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name2 +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa name2 +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr ln 1 , .Xr chflags 2 , @@ -143,8 +191,16 @@ points outside the process's allocated address space. .Xr readlink 2 , .Xr unlink 2 , .Xr symlink 7 +.Sh STANDARDS +The +.Fn symlinkat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn symlink system call appeared in .Bx 4.2 . +The +.Fn symlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 index 11a3b36..41a2288 100644 --- a/lib/libc/sys/unlink.2 +++ b/lib/libc/sys/unlink.2 @@ -28,11 +28,12 @@ .\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 10, 2006 +.Dd April 10, 2008 .Dt UNLINK 2 .Os .Sh NAME -.Nm unlink +.Nm unlink , +.Nm unlinkat .Nd remove directory entry .Sh LIBRARY .Lb libc @@ -40,6 +41,8 @@ .In unistd.h .Ft int .Fn unlink "const char *path" +.Ft int +.Fn unlinkat "int fd" "const char *path" "int flag" .Sh DESCRIPTION The .Fn unlink @@ -59,6 +62,49 @@ The .Fa path argument may not be a directory. +.Pp +The +.Fn unlinkat +system call is equivalent to +.Fn unlink +or +.Fn rmdir +except in the case where +.Fa path +specifies a relative path. +In this case the directory entry to be removed is determined +relative to the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_REMOVEDIR +Remove the directory entry specified by +.Fa fd +and +.Fa path +as a directory, not a normal file. +.El +.Pp +If +.Fn unlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fa unlink +or +.Fa rmdir +respectively, depending on whether or not the +.Dv AT_REMOVEDIR +bit is set in flag. .Sh RETURN VALUES .Rv -std unlink .Sh ERRORS @@ -104,21 +150,74 @@ The argument points outside the process's allocated address space. .El +.Pp +In addition to the errors returned by the +.Fn unlink , +the +.Fn unlinkat +may fail if +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EEXIST +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and the +.Fa path +argument names a directory that is not an empty directory, +or there are hard links to the directory other than dot or +a single entry in dot-dot. +.It Bq Er ENOTDIR +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and +.Fa path +does not name a directory. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr close 2 , .Xr link 2 , .Xr rmdir 2 , .Xr symlink 7 +.Sh STANDARDS +The +.Fn unlinkat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn unlink function appeared in .At v6 . +The +.Fn unlinkat +system call appeared in +.Fx 8.0 . .Pp The .Fn unlink system call traditionally allows the super-user to unlink directories which can damage the file system integrity. -This implementation no longer permits -it. +This implementation no longer permits it. diff --git a/lib/libc/sys/utimes.2 b/lib/libc/sys/utimes.2 index c67af8e..74a7dd0 100644 --- a/lib/libc/sys/utimes.2 +++ b/lib/libc/sys/utimes.2 @@ -30,13 +30,14 @@ .\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd December 9, 2006 +.Dd April 10, 2008 .Dt UTIMES 2 .Os .Sh NAME .Nm utimes , .Nm lutimes , -.Nm futimes +.Nm futimes , +.Nm futimesat .Nd set file access and modification times .Sh LIBRARY .Lb libc @@ -48,6 +49,8 @@ .Fn lutimes "const char *path" "const struct timeval *times" .Ft int .Fn futimes "int fd" "const struct timeval *times" +.Ft int +.Fn futimesat "int fd" "const char *path" "const struct timeval times[2]" .Sh DESCRIPTION The access and modification times of the file named by .Fa path @@ -97,6 +100,28 @@ changes the access and modification times of the link, while .Fn utimes changes the times of the file the link references. +.Pp +The +.Fn futimesat +system call is equivalent to +.Fn utimes +except in the case where +.Fa path +specifies a relative path. +In this case the access and modification time +is set to that of a file relative to the directory associated with the file +descriptor +.Fa fd +instead of the current working directory. +If +.Fn futimesat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical to +a call to +.Fn utimes . .Sh RETURN VALUES .Rv -std .Sh ERRORS @@ -197,10 +222,42 @@ does not match the owner of the file and is not the super-user. .It Bq Er EROFS The file system containing the file is mounted read-only. .El +.Pp +In addition to the errors returned by the +.Fn utimes , +the +.Fn futimesat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr chflags 2 , .Xr stat 2 , .Xr utime 3 +.Sh STANDARDS +The +.Fn utimes +function is expected to conform to +.St -xpg4.2 . +The +.Fn futimesat +system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn utimes @@ -212,3 +269,7 @@ and .Fn lutimes system calls first appeared in .Fx 3.0 . +The +.Fn futimesat +system call appeared in +.Fx 8.0 . |