Return to rename.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/rename.2, revision 1.1.1.1

1.1       root        1: .TH RENAME 2 "12 February 1983"
                      2: .UC 4
                      3: .SH NAME
                      4: rename \- change the name of a file
                      5: .SH SYNOPSIS
                      6: .ft B
                      7: .nf
                      8: rename(from, to)
                      9: char *from, *to;
                     10: .fi
                     11: .ft R
                     12: .SH DESCRIPTION
                     13: .I Rename
                     14: causes the link named
                     15: .I from
                     16: to be renamed as
                     17: .IR to .
                     18: If 
                     19: .I to
                     20: exists, then it is first removed.
                     21: Both 
                     22: .I from
                     23: and
                     24: .I to
                     25: must be of the same type (that is, both directories or both
                     26: non-directories), and must reside on the same file system.
                     27: .PP
                     28: .I Rename
                     29: guarantees that an instance of
                     30: .I to
                     31: will always exist, even if the system should crash in
                     32: the middle of the operation.
                     33: .SH CAVEAT
                     34: The system can deadlock if a loop in the file system graph is present.
                     35: This loop takes the form of an entry in directory \*(lqa\*(rq,
                     36: say \*(lqa/foo\*(rq,
                     37: being a hard link to directory \*(lqb\*(rq, and an entry in
                     38: directory \*(lqb\*(rq, say \*(lqb/bar\*(rq, being a hard link
                     39: to directory \*(lqa\*(rq.
                     40: When such a loop exists and two separate processes attempt to
                     41: perform \*(lqrename a/foo b/bar\*(rq and \*(lqrename b/bar a/foo\*(rq,
                     42: respectively, 
                     43: the system may deadlock attempting to lock
                     44: both directories for modification.
                     45: Hard links to directories should be
                     46: replaced by symbolic links by the system administrator.
                     47: .SH "RETURN VALUE"
                     48: A 0 value is returned if the operation succeeds, otherwise
                     49: .I rename
                     50: returns \-1 and the global variable 
                     51: .I errno
                     52: indicates the reason for the failure.
                     53: .SH "ERRORS
                     54: .I Rename
                     55: will fail and neither of the argument files will be
                     56: affected if any of the following are true:
                     57: .TP 15
                     58: [ENOTDIR]
                     59: A component of either path prefix is not a directory.
                     60: .TP 15
                     61: [ENOENT]
                     62: A component of either path prefix does not exist.
                     63: .TP 15
                     64: [EACCES]
                     65: A component of either path prefix denies search permission.
                     66: .TP 15
                     67: [ENOENT]
                     68: The file named by \fIfrom\fP does not exist.
                     69: .TP 15
                     70: [EPERM]
                     71: The file named by \fIfrom\fP is a directory and the effective
                     72: user ID is not super-user.
                     73: .TP 15
                     74: [EXDEV]
                     75: The link named by \fIto\fP and the file named by \fIfrom\fP
                     76: are on different logical devices (file systems).  Note that this error
                     77: code will not be returned if the implementation permits cross-device
                     78: links.
                     79: .TP 15
                     80: [EACCES]
                     81: The requested link requires writing in a directory with a mode
                     82: that denies write permission.
                     83: .TP 15
                     84: [EROFS]
                     85: The requested link requires writing in a directory on a read-only file
                     86: system.
                     87: .TP 15
                     88: [EFAULT]
                     89: .I Path
                     90: points outside the process's allocated address space.
                     91: .TP 15
                     92: [EINVAL]
                     93: .I From
                     94: is a parent directory of
                     95: .IR to .
                     96: .SH "SEE ALSO"
                     97: open(2)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.