.TH rename() "" "" "System Call (libc)"
.PC "Rename a file"
.B "#include <stdio.h>"
\fBint rename(\fIold\^\fB; \fInew\^\fB)\fR
\fBchar *\fIold\^\fB, *\fInew\^\fB;\fR
.PP
.II "file, rename"
The \*(CO system call
.B rename()
changes the name of a file, from the name pointed to by
.I old
to that pointed to by
.IR new .
Both
.I old
and
.I new
must point to a valid file name.
If
.I new
names a file that already exists,
the old file is replaced by the file being renamed.
.PP
.B rename()
returns zero if it could rename
.IR old ,
and nonzero if it could not.
If
.B rename()
could not rename
.IR old ,
its name remains unchanged.
.SH Example
This example renames the file named in the first command-line argument
to the name given in the second argument.
.DM
#include <stdio.h>
#include <stdlib.h>
.DE
.DM
main(argc, argv)
int argc; char *argv[];
{
	if (argc != 3) {
		fprintf(stderr, "usage: rename from to\en");
		exit(EXIT_FAILURE);
	}
.DE
.DM
	if(rename(argv[1], argv[2])) {
		perror("rename failed");
		exit(EXIT_FAILURE);
	}
	exit(EXIT_SUCCESS);
}
.DE
.SH "See Also"
.Xr "libc," libc
.Xr "link()," link
.Xr "stdio.h," stdio.h
.Xr "unlink()" unlink
.br
\*(AS, \(sc7.9.4.2
.br
\*(PX Standard, \(sc5.5.3
.SH Notes
The ANSI Standard states that
.B rename()
fails if
.I old
is open,
or if its contents must be copied in order to rename it.
Under \*(CO, it also fails if
.I new
is already open.
