Unix/Linux Go Back    


POSIX 1003.1 - man page for rename (posix section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


RENAME(P)			    POSIX Programmer's Manual				RENAME(P)

NAME
       rename - rename a file

SYNOPSIS
       #include <stdio.h>

       int rename(const char *old, const char *new);

DESCRIPTION
       The  rename()  function	shall  change  the name of a file. The old argument points to the
       pathname of the file to be renamed. The new argument points to the  new	pathname  of  the
       file.

       If  either  the	old  or new argument names a symbolic link, rename() shall operate on the
       symbolic link itself, and shall not resolve the last component of the argument. If the old
       argument  and  the  new	argument resolve to the same existing file, rename() shall return
       successfully and perform no other action.

       If the old argument points to the pathname of a file that is  not  a  directory,  the  new
       argument  shall	not  point  to	the pathname of a directory. If the link named by the new
       argument exists, it shall be removed and old renamed to new. In this case,  a  link  named
       new  shall  remain  visible to other processes throughout the renaming operation and refer
       either to the file referred to by new or old before the operation began. Write access per-
       mission	is  required  for  both the directory containing old and the directory containing
       new.

       If the old argument points to the pathname of a directory,  the	new  argument  shall  not
       point to the pathname of a file that is not a directory. If the directory named by the new
       argument exists, it shall be removed and old renamed to new. In this case,  a  link  named
       new  shall exist throughout the renaming operation and shall refer either to the directory
       referred to by new or old before the operation began. If new names an existing  directory,
       it shall be required to be an empty directory.

       If  the	old  argument points to a pathname of a symbolic link, the symbolic link shall be
       renamed. If the new argument points to a pathname of a symbolic link,  the  symbolic  link
       shall be removed.

       The  new  pathname shall not contain a path prefix that names old. Write access permission
       is required for the directory containing old and the directory containing new.  If the old
       argument  points  to  the pathname of a directory, write access permission may be required
       for the directory named by old, and, if it exists, the directory named by new.

       If the link named by the new argument exists and the file's link count becomes 0  when  it
       is removed and no process has the file open, the space occupied by the file shall be freed
       and the file shall no longer be accessible. If one or more processes have  the  file  open
       when  the last link is removed, the link shall be removed before rename() returns, but the
       removal of the file contents shall be postponed until  all  references  to  the	file  are
       closed.

       Upon  successful  completion,  rename()	shall  mark  for update the st_ctime and st_mtime
       fields of the parent directory of each file.

       If the rename() function fails for any reason other than [EIO],	any  file  named  by  new
       shall be unaffected.

RETURN VALUE
       Upon  successful  completion,  rename()	shall  return 0; otherwise, -1 shall be returned,
       errno shall be set to indicate the error,  and neither the file named by old nor the  file
       named by new shall be changed or created.

ERRORS
       The rename() function shall fail if:

       EACCES A  component of either path prefix denies search permission; or one of the directo-
	      ries containing old or new  denies  write  permissions;  or,  write  permission  is
	      required and is denied for a directory pointed to by the old or new arguments.

       EBUSY  The  directory  named  by  old  or new is currently in use by the system or another
	      process, and the implementation considers this an error.

       EEXIST or ENOTEMPTY

	      The link named by new is a directory that is not an empty directory.

       EINVAL The new directory pathname contains a path prefix that names the old directory.

       EIO    A physical I/O error has occurred.

       EISDIR The new argument points to a directory and the old argument points to a  file  that
	      is not a directory.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       EMLINK The file named by old is a directory, and the link count of the parent directory of
	      new would exceed {LINK_MAX}.

       ENAMETOOLONG

	      The length of the old or new argument exceeds {PATH_MAX} or a pathname component is
	      longer than {NAME_MAX}.

       ENOENT The  link  named by old does not name an existing file, or either old or new points
	      to an empty string.

       ENOSPC The directory that would contain new cannot be extended.

       ENOTDIR
	      A component of either path prefix is not a directory; or the old argument  names	a
	      directory and new argument names a non-directory file.

       EPERM or EACCES

	      The S_ISVTX flag is set on the directory containing the file referred to by old and
	      the caller is not the file owner, nor is the caller the directory owner,	nor  does
	      the  caller  have  appropriate  privileges;  or new refers to an existing file, the
	      S_ISVTX flag is set on the directory containing this file, and the  caller  is  not
	      the  file  owner,  nor  is the caller the directory owner, nor does the caller have
	      appropriate privileges.

       EROFS  The requested operation requires writing in a directory on a read-only file system.

       EXDEV  The links named by new and old are on different file systems and the implementation
	      does not support links between file systems.

       The rename() function may fail if:

       EBUSY  The file named by the old or new arguments is a named STREAM.

       ELOOP  More  than  {SYMLOOP_MAX}  symbolic links were encountered during resolution of the
	      path argument.

       ENAMETOOLONG

	      As a result of encountering a symbolic link in resolution of the path argument, the
	      length of the substituted pathname string exceeded {PATH_MAX}.

       ETXTBSY
	      The  file  to  be renamed is a pure procedure (shared text) file that is being exe-
	      cuted.

       The following sections are informative.

EXAMPLES
   Renaming a File
       The following example shows how to rename a file named /home/cnd/mod1 to /home/cnd/mod2.

	      #include <stdio.h>

	      int status;
	      ...
	      status = rename("/home/cnd/mod1", "/home/cnd/mod2");

APPLICATION USAGE
       Some implementations mark for update the st_ctime field of renamed files and some do  not.
       Applications  which  make use of the st_ctime field may behave differently with respect to
       renamed files unless they are designed to allow for either behavior.

RATIONALE
       This rename() function is equivalent for regular files to that defined by the ISO C  stan-
       dard.  Its  inclusion  here  expands that definition to include actions on directories and
       specifies behavior when the new parameter names a file that already exists. That  specifi-
       cation requires that the action of the function be atomic.

       One  of the reasons for introducing this function was to have a means of renaming directo-
       ries while permitting implementations to prohibit the use  of  link()  and  unlink()  with
       directories, thus constraining links to directories to those made by mkdir().

       The  specification  that  if  old  and new refer to the same file is intended to guarantee
       that:

	      rename("x", "x");

       does not remove the file.

       Renaming dot or dot-dot is prohibited in order to prevent cyclical file system paths.

       See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG]  in	rmdir()  and  [EBUSY]  in
       unlink() . For a discussion of [EXDEV], see link() .

FUTURE DIRECTIONS
       None.

SEE ALSO
       link()	,   rmdir()   ,   symlink()   ,   unlink()  ,  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <stdio.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					RENAME(P)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 08:16 AM.