The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=619e49b2ba58e1ffd2ab111fef6d1e87d77e7391
commit 619e49b2ba58e1ffd2ab111fef6d1e87d77e7391 Author: Konstantin Belousov <[email protected]> AuthorDate: 2026-02-27 00:10:36 +0000 Commit: Konstantin Belousov <[email protected]> CommitDate: 2026-03-05 23:46:53 +0000 renameat2(2): document Reviewed by: markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D55539 --- lib/libsys/Makefile.sys | 3 ++- lib/libsys/rename.2 | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 1 deletion(-) diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys index eac28fbd2fe9..76855e0ae54d 100644 --- a/lib/libsys/Makefile.sys +++ b/lib/libsys/Makefile.sys @@ -513,7 +513,8 @@ MLINKS+=readlink.2 readlinkat.2 MLINKS+=recv.2 recvfrom.2 \ recv.2 recvmmsg.2 \ recv.2 recvmsg.2 -MLINKS+=rename.2 renameat.2 +MLINKS+=rename.2 renameat.2 \ + rename.2 renameat2.2 MLINKS+=rtprio.2 rtprio_thread.2 MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \ sched_get_priority_max.2 sched_rr_get_interval.2 diff --git a/lib/libsys/rename.2 b/lib/libsys/rename.2 index 1806321245ec..dbad50edb9a9 100644 --- a/lib/libsys/rename.2 +++ b/lib/libsys/rename.2 @@ -39,6 +39,16 @@ .Fn rename "const char *from" "const char *to" .Ft int .Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" +.In sys/fcntl.h +.In stdio.h +.Ft int +.Fo renameat2 +.Fa "int fromfd" +.Fa "const char *from" +.Fa "int tofd" +.Fa "const char *to" +.Fa "unsigned int flags" +.Fc .Sh DESCRIPTION The .Fn rename @@ -112,6 +122,28 @@ or .Fa tofd parameter, the current working directory is used in the determination of the file for the respective path parameter. +.Pp +The +.Fn renameat2 +system call takes an additional +.Fa flags +argument. +If +.Fa flags +is zero, the +.Fn renameat2 +call operates identically to +.Fn renameat . +Additionally, the following flags can be specified: +.Bl -tag -width AT_RENAME_NOREPLACE +.It Dv AT_RENAME_NOREPLACE +If the path specified by +.Fa tofd +and +.Fa to +exists, the request fails with the error +.Er EEXIST . +.El .Sh RETURN VALUES .Rv -std rename .Sh ERRORS @@ -298,6 +330,35 @@ file descriptor lacks the .Dv CAP_RENAMEAT_TARGET right. .El +.Pp +In addition to the errors returned by the +.Fn renameat +system call, the +.Fn renameat2 +system call may fail if: +.Bl -tag -width Er +.It Bq Er EEXIST +The +.Dv AT_RENAME_NOREPLACE +flag was provided, and a file exists at the path specified by +.Fa to . +.It Bq Er EOPNOTSUPP +One of the +.Fa flags +specified is not supported by the filesystem where the to-be +renamed file is located. +.El +.Sh CAVEATS +If the filesystem which owns the file to be renamed does not +implement the +.Dv AT_RENAME_NOREPLACE +flag, it is possible that due to race with target file creation, +the error returned by the +.Fn renameat2 +system call would be non-deterministically either +.Er EEXIST +or +.Er EOPNOTSUPP . .Sh SEE ALSO .Xr chflags 2 , .Xr open 2 , @@ -315,3 +376,7 @@ The .Fn renameat system call appeared in .Fx 8.0 . +The +.Fn renameat2 +system call appeared in +.Fx 16.0 .
