Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for renameat (opensolaris section 2)

rename(2)				   System Calls 				rename(2)

NAME
       rename, renameat - change the name of a file

SYNOPSIS
       #include <stdio.h>

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

       #include <unistd.h>

       int renameat(int fromfd, const char *old, int tofd,
	    const char *new);

   XPG3
       #include <unistd.h>

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

DESCRIPTION
       The  rename() function changes 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 path name of the file.

       The renameat() function renames an entry in a directory, possibly moving the entry into	a
       different  directory.   See fsattr(5). If the old argument is an absolute path, the fromfd
       is ignored.  Otherwise it is resolved relative to the fromfd argument rather than the cur-
       rent  working  directory.   Similarly, if the new argument is not absolute, it is resolved
       relative to the tofd argument.  If either fromfd or tofd have the value AT_FDCWD,  defined
       in  <fcntl.h>,  and  their respective paths are relative, the path is resolved relative to
       the current working directory.

       Current implementation restrictions will cause the renameat() function to return an  error
       if  an  attempt	is made to rename an extended attribute file to a regular (non-attribute)
       file, or to rename a regular file to an extended attribute file.

       If old and new both refer to the same existing file, the rename() and renameat() functions
       return successfully and performs no other action.

       If old points to the pathname of a file that is not a directory, new must not point to the
       pathname of a directory. If the link named by new exists, it will be removed and old  will
       be  renamed  to new. In this case, a link named new must remain visible to other processes
       throughout the renaming operation and will refer to either the file referred to by new  or
       the file referred to as old before the operation began.

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

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

       If  the	directory  containing  old has the sticky bit set,  at least one of the following
       conditions listed below must be true:

	   o	  the user must own old

	   o	  the user must own the directory containing old

	   o	  old must be writable by the user

	   o	  the user must be a privileged user

       If new exists, and the directory containing new is writable and has the sticky bit set, at
       least  one of the following conditions must be true:

	   o	  the user must own new

	   o	  the user must own the directory containing new

	   o	  new must be writable by the user

	   o	  the user must be a privileged user

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

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

RETURN VALUES
       Upon  successful  completion, 0 is returned. Otherwise, -1 is returned and errno is set to
       indicate an error.

ERRORS
       The rename() function will fail if:

       EACCES	       A component of either path prefix denies search	permission;  one  of  the
		       directories containing old and new denies write permissions; or write per-
		       mission is denied by a directory pointed to by old or new.

       EBUSY	       The new argument is a directory and the mount point  for  a  mounted  file
		       system.

       EDQUOT	       The  directory where the new name entry is being placed cannot be extended
		       because the user's quota of disk blocks	on  that  file	system	has  been
		       exhausted.

       EEXIST	       The  link  named  by  new is a directory containing entries other than `.'
		       (the directory itself) and `..' (the parent directory).

       EFAULT	       Either old or new references an invalid address.

       EILSEQ	       The path argument includes non-UTF8 characters and the file system accepts
		       only file names where all characters are part of the UTF-8 character code-
		       set.

       EINVAL	       The new argument directory pathname contains a path prefix that names  the
		       old  directory,	or  an	attempt  was  made to rename a regular file to an
		       extended attribute or from an extended attribute to a regular file.

       EIO	       An I/O error occurred while making or updating a directory entry.

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

       ELOOP	       Too many symbolic links were encountered in translating the pathname.

       ENAMETOOLONG    The  length  of	old  or new exceeds  PATH_MAX, or a pathname component is
		       longer than  NAME_MAX while _POSIX_NO_TRUNC is in effect.

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

       ENOENT	       The  link  named by old does not name an existing file, a component of the
		       path prefix of new does not exist, 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 old names a
		       directory and new names a file that is not a directory, or tofd and  dirfd
		       in renameat() do not reference a directory.

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

       EXDEV	       The links named by old and new are on different file systems.

       The renameat() functions will fail if:

       ENOTSUP	  An attempt was made to rename a regular file as an attribute file or to  rename
		  an attribute file as a regular file.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+--------------------------------+
       |      ATTRIBUTE TYPE	     |	      ATTRIBUTE VALUE	      |
       +-----------------------------+--------------------------------+
       |Interface Stability	     |Committed 		      |
       +-----------------------------+--------------------------------+
       |MT-Level		     |Async-Signal-Safe 	      |
       +-----------------------------+--------------------------------+
       |Standard		     |For rename(), see standards(5). |
       +-----------------------------+--------------------------------+

SEE ALSO
       chmod(2), link(2), unlink(2), attributes(5), fsattr(5), standards(5)

NOTES
       The system can deadlock if there is a loop in the file system graph. Such a loop can occur
       if there is an entry in directory a, a/name1, that is a hard link to directory b,  and  an
       entry in directory b, b/name2, that is a hard link to directory a. When such a loop exists
       and two separate processes attempt to rename a/name1 to b/name2 and  b/name2  to  a/name1,
       the  system  may deadlock attempting to lock  both directories for modification.  Use sym-
       bolic links instead of hard links  for directories.

SunOS 5.11				    4 Oct 2007					rename(2)


All times are GMT -4. The time now is 11:27 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password