@node rename, file system
@subheading Syntax

@example
#include <stdio.h>

int rename(const char *oldname, const char *newname);
@end example

@subheading Description

This function renames an existing file or directory @var{oldname} to
@var{newname}.  If @var{newname} exists, then it is first removed.  If
@var{newname} is a directory, it must be empty (or else @var{errno} will
be set to @code{ENOTEMPTY}), and must not include @var{oldname} in its
path prefix (otherwise, @var{errno} will be set to @code{EINVAL}).  If
@var{newname} exists, both @var{oldname} and @var{newname} must be of the
same type (both directories or both regular files) (or else @var{errno}
will be set to @code{ENOTDIR} or @code{EISDIR}), and must reside on the
same logical device (otherwise, @var{errno} will be set to @code{EXDEV}). 
Wildcards are not allowed in either @var{oldname} or @var{newname}.  DOS
won't allow renaming a current directory even on a non-default drive (you
will get the @code{EBUSY} or @code{EINVAL} in @var{errno}).
@code{ENAMETOOLONG} will be returned for pathnames which are longer than
the limit imposed by DOS.  If @var{oldname} doesn't exist, @var{errno}
will be set to @code{ENOENT}.  For most of the other calamities, DOS will
usually set @var{errno} to @code{EACCES}.

If anything goes wrong during the operation of @code{rename()}, the
function tries very hard to leave the things as ther were before it was
invoked, but it might not always succeed.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability ansi, posix

@subheading Example

@example
rename("c:/mydir/some.doc", "c:/yourdir/some.sav");
rename("c:/path1/mydir", "c:/path2");
@end example

@c -------------------------------------------------------------------------

@node _rename, file system
@subheading Syntax

@example
#include <stdio.h>

int _rename(const char *oldname, const char *newname);
@end example

@subheading Description

This function renames an existing file or directory @var{oldname} to
@var{newname}.  It is much smaller that @code{rename} (@pxref{rename}),
but it can only rename a directory so it stays under the same parent, it
cannot move directories between different branches of the directory
tree.  This means that in the following example, the first call will
succeed, while the second will fail:

@example
_rename("c:/path1/mydir", "c:/path1/yourdir");
_rename("c:/path1/mydir", "c:/path2");
@end example

On systems that support long filenames (@pxref{_use_lfn}),
@code{_rename} can also move directories (so that both calls in the
above example succeed there), unless the @samp{LFN} environment variable
is set to @kbd{n}, or the @code{_CRT0_FLAG_NO_LFN} is set in the
@code{_crt0_startup_flags} variable, @xref{_crt0_startup_flags}.

If you don't need the extra functionality offered by @code{rename}
(which usually is only expected by Unix-born programs), you can use
@code{_rename} instead and thus make your program a lot smaller.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix