1*61183Sbostic.\" Copyright (c) 1983, 1991, 1993 2*61183Sbostic.\" The Regents of the University of California. All rights reserved. 320251Smckusick.\" 443568Strent.\" %sccs.include.redist.man% 520251Smckusick.\" 6*61183Sbostic.\" @(#)rename.2 8.1 (Berkeley) 06/04/93 738053Sbostic.\" 847208Scael.Dd 947208Scael.Dt RENAME 2 1047208Scael.Os BSD 4.2 1147208Scael.Sh NAME 1247208Scael.Nm rename 1347208Scael.Nd change the name of a file 1447208Scael.Sh SYNOPSIS 1547208Scael.Fd #include <stdio.h> 1647208Scael.Ft int 1747208Scael.Fn rename "const char *from" "const char *to" 1847208Scael.Sh DESCRIPTION 1947208Scael.Fn Rename 2020251Smckusickcauses the link named 2147208Scael.Fa from 2220251Smckusickto be renamed as 2347208Scael.Fa to . 2420251SmckusickIf 2547208Scael.Fa to 2647208Scaelexists, it is first removed. 2720251SmckusickBoth 2847208Scael.Fa from 2920251Smckusickand 3047208Scael.Fa to 3120251Smckusickmust be of the same type (that is, both directories or both 3220251Smckusicknon-directories), and must reside on the same file system. 3347208Scael.Pp 3447208Scael.Fn Rename 3520251Smckusickguarantees that an instance of 3647208Scael.Fa to 3720251Smckusickwill always exist, even if the system should crash in 3820251Smckusickthe middle of the operation. 3947208Scael.Pp 4028350SmckusickIf the final component of 4147208Scael.Fa from 4228350Smckusickis a symbolic link, 4328350Smckusickthe symbolic link is renamed, 4428350Smckusicknot the file or directory to which it points. 4547208Scael.Sh CAVEAT 4620251SmckusickThe system can deadlock if a loop in the file system graph is present. 4747208ScaelThis loop takes the form of an entry in directory 4847208Scael.Ql Pa a , 4947208Scaelsay 5047208Scael.Ql Pa a/foo , 5147208Scaelbeing a hard link to directory 5247208Scael.Ql Pa b , 5347208Scaeland an entry in 5447208Scaeldirectory 5547208Scael.Ql Pa b , 5647208Scaelsay 5747208Scael.Ql Pa b/bar , 5847208Scaelbeing a hard link 5947208Scaelto directory 6047208Scael.Ql Pa a . 6120251SmckusickWhen such a loop exists and two separate processes attempt to 6247208Scaelperform 6347208Scael.Ql rename a/foo b/bar 6447208Scaeland 6547208Scael.Ql rename b/bar a/foo , 6620251Smckusickrespectively, 6720251Smckusickthe system may deadlock attempting to lock 6820251Smckusickboth directories for modification. 6920251SmckusickHard links to directories should be 7020251Smckusickreplaced by symbolic links by the system administrator. 7147208Scael.Sh RETURN VALUES 7220251SmckusickA 0 value is returned if the operation succeeds, otherwise 7347208Scael.Fn rename 7447208Scaelreturns -1 and the global variable 7547208Scael.Va errno 7620251Smckusickindicates the reason for the failure. 7747208Scael.Sh ERRORS 7847208Scael.Fn Rename 7920251Smckusickwill fail and neither of the argument files will be 8047208Scaelaffected if: 8147208Scael.Bl -tag -width ENAMETOOLONG 8247208Scael.It Bq Er EINVAL 8321004SmckusickEither pathname contains a character with the high-order bit set. 8447208Scael.It Bq Er ENAMETOOLONG 8521004SmckusickA component of either pathname exceeded 255 characters, 8621004Smckusickor the entire length of either path name exceeded 1023 characters. 8747208Scael.It Bq Er ENOENT 8847208ScaelA component of the 8947208Scael.Fa from 9047208Scaelpath does not exist, 9147208Scaelor a path prefix of 9247208Scael.Fa to 9347208Scaeldoes not exist. 9447208Scael.It Bq Er EACCES 9520251SmckusickA component of either path prefix denies search permission. 9647208Scael.It Bq Er EACCES 9721004SmckusickThe requested link requires writing in a directory with a mode 9821004Smckusickthat denies write permission. 9947208Scael.It Bq Er EPERM 10047208ScaelThe directory containing 10147208Scael.Fa from 10247208Scaelis marked sticky, 10347208Scaeland neither the containing directory nor 10447208Scael.Fa from 10524440Smckusickare owned by the effective user ID. 10647208Scael.It Bq Er EPERM 10747208ScaelThe 10847208Scael.Fa to 10947208Scaelfile exists, 11047208Scaelthe directory containing 11147208Scael.Fa to 11247208Scaelis marked sticky, 11347208Scaeland neither the containing directory nor 11447208Scael.Fa to 11524440Smckusickare owned by the effective user ID. 11647208Scael.It Bq Er ELOOP 11721004SmckusickToo many symbolic links were encountered in translating either pathname. 11847208Scael.It Bq Er ENOTDIR 11921004SmckusickA component of either path prefix is not a directory. 12047208Scael.It Bq Er ENOTDIR 12147208Scael.Fa from 12247208Scaelis a directory, but 12347208Scael.Fa to 12447208Scaelis not a directory. 12547208Scael.It Bq Er EISDIR 12647208Scael.Fa to 12747208Scaelis a directory, but 12847208Scael.Fa from 12947208Scaelis not a directory. 13047208Scael.It Bq Er EXDEV 13147208ScaelThe link named by 13247208Scael.Fa to 13347208Scaeland the file named by 13447208Scael.Fa from 13520251Smckusickare on different logical devices (file systems). Note that this error 13620251Smckusickcode will not be returned if the implementation permits cross-device 13720251Smckusicklinks. 13847208Scael.It Bq Er ENOSPC 13924440SmckusickThe directory in which the entry for the new name is being placed 14024440Smckusickcannot be extended because there is no space left on the file 14124440Smckusicksystem containing the directory. 14247208Scael.It Bq Er EDQUOT 14324440SmckusickThe directory in which the entry for the new name 14424440Smckusickis being placed cannot be extended because the 14524440Smckusickuser's quota of disk blocks on the file system 14624440Smckusickcontaining the directory has been exhausted. 14747208Scael.It Bq Er EIO 14821004SmckusickAn I/O error occurred while making or updating a directory entry. 14947208Scael.It Bq Er EROFS 15020251SmckusickThe requested link requires writing in a directory on a read-only file 15120251Smckusicksystem. 15247208Scael.It Bq Er EFAULT 15347208Scael.Em Path 15420251Smckusickpoints outside the process's allocated address space. 15547208Scael.It Bq Er EINVAL 15647208Scael.Fa From 15720251Smckusickis a parent directory of 15847208Scael.Fa to , 15947208Scaelor an attempt is made to rename 16047208Scael.Ql \&. 16147208Scaelor 16247208Scael.Ql \&.. . 16347208Scael.It Bq Er ENOTEMPTY 16447208Scael.Fa To 16521004Smckusickis a directory and is not empty. 16647208Scael.El 16747208Scael.Sh SEE ALSO 16847208Scael.Xr open 2 16955727Sbostic.Xr symlink 7 17047208Scael.Sh STANDARDS 17147208Scael.Fn Rename 17247208Scaelconforms to IEEE Std 1003.1-1988 17347208Scael.Pq Dq Tn POSIX . 174