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

FreeBSD Manual Pages

  
 
  

home | help
rename(2)							     rename(2)

Name
       rename -	change the name	of a file

Syntax
       rename(from, to)
       char *from, *to;

Description
       The  system  call  causes  the link named from to be renamed to.	 If to
       exists, then it is first	removed.  Both from and	to must	be of the same
       type (that is, both directories or both nondirectories) and must	reside
       on the same file	system.

       The system call guarantees that an instance of to  will	always	exist,
       even if the system should crash in the middle of	the operation.

Return Values
       A  zero	(0)  value  is	returned  if the operation succeeds. Otherwise
       returns -1, and the global variable errno indicates the reason for  the
       failure.

Restrictions
       The  system  can	 deadlock  if  a  loop	in  the	 file  system graph is
       present.and two processes issue the call	at the same time.   For	 exam-
       ple,  suppose  a	directory, contains a file, Suppose that file is hard-
       linked to a directory, and the directory	contains a file, If  is	 hard-
       linked  to a loop exists.  Now suppose one process issues the following
       call: rename (dirname/filename secondir/secondfile) At the  same	 time,
       another	process	issues the following call: rename (secondir/secondfile
       dirname/filename) In this case, the system can  deadlock.   The	system
       administrator  should  replace  hard links to directories with symbolic
       links.

Diagnostics
       The system call fails and neither of the	argument  files	 are  affected
       under the following conditions:

       [ENOTDIR]      A	component of either path prefix	is not a directory.

       [ENOENT]	      A	 component  of the from	path does not exist, or	a path
		      prefix of	to does	not exist.

       [ENOENT]	      Either from or to	points to  an  empty  string  and  the
		      environment defined is POSIX or SYSTEM_FIVE.

       [EACCES]	      A	 component of either path prefix denies	search permis-
		      sion.

       [EPERM]	      The to file exists, the  directory  containing  from  is
		      marked  sticky, and neither the containing directory nor
		      the to directory is owned	by the effective user ID.

       [EPERM]	      The directory containing from is marked sticky, and nei-
		      ther  the	containing directory nor the from directory is
		      owned by the effective user ID.

       [EXDEV]	      The link named by	to and the file	named by from  are  on
		      different	 logical  devices  (file  systems).  Note that
		      this error code is not returned  if  the	implementation
		      permits cross-device links.

       [EACCES]	      The  requested link requires writing in a	directory with
		      a	mode that denies write permission.

       [EROFS]	      The requested link requires writing in a directory on  a
		      read-only	file system.

       [EFAULT]	      The  path	points outside the process's allocated address
		      space.

       [EINVAL]	      The from is a parent directory of	to, or an  attempt  is
		      made to rename dot (.) or	dot-dot	(..).

       [ENAMETOOLONG] A	 component of either pathname exceeded 255 characters,
		      or the entire length of either  pathname	exceeded  1023
		      characters.

       [ELOOP]	      Too  many	symbolic links were encountered	in translating
		      either pathname.

       [ENOTDIR]      The from is a directory, but to is not a directory.

       [EISDIR]	      The to is	a directory, but from is not a directory.

       [ENOSPC]	      The directory in which the entry for  the	 new  name  is
		      being  placed  cannot  be	 extended, because there is no
		      space left on the	file system containing the  directory.

       [EDQUOT]	      The  directory  in  which	 the entry for the new name is
		      being placed cannot  be  extended,  because  the	user's
		      quota  of	 disk blocks on	the file system	containing the
		      directory	has been exhausted.

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

       [ENOTEMPTY]    The to is	a directory and	is not empty.

       [EBUSY]	      The directory named by from or to	is a mount point.

See Also
       open(2)

								     rename(2)

Name | Syntax | Description | Return Values | Restrictions | Diagnostics | See Also

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

home | help