Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 mov-
       ing 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	current	 work-
       ing  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 regu-
       lar 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  through-
       out  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	opera-
       tion 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	direc-
       tory 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 permis-
		       sion; one of the	directories  containing	 old  and  new
		       denies write permissions; or write permission 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.

       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.

       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	 path-
		       name   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 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 nondirectory
		       file, 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.

       EIO	       An I/O error occurred while making or updating a	direc-
		       tory entry.

       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 reg-
		       ular file.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |rename()	  is	Standard;  |
       |			     |renameat() is Evolving	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       chmod(2), link(2), unlink(2), attributes(5), fsattr(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 symbolic links instead of hard links
       for directories.

SunOS 5.10			  4 Nov	2002			     rename(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rename&sektion=2&manpath=SunOS+5.10>

home | help