1 files changed, 262 insertions, 0 deletions
diff --git a/man3p/rename.3p b/man3p/rename.3p
new file mode 100644
index 000000000..ac1fb0076
--- /dev/null
+++ b/man3p/rename.3p
@@ -0,0 +1,262 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "RENAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" rename 
+.SH NAME
+rename \- rename a file
+.SH SYNOPSIS
+.LP
+\fB#include <stdio.h>
+.br
+.sp
+int rename(const char *\fP\fIold\fP\fB, const char *\fP\fInew\fP\fB);
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIrename\fP() function shall change the name of a file. The \fIold\fP
+argument points to the pathname of the file to be
+renamed. The \fInew\fP argument points to the new pathname of the
+file.
+.LP
+If
+either the \fIold\fP or \fInew\fP argument names a symbolic link,
+\fIrename\fP() shall operate on the symbolic link itself, and
+shall not resolve the last component of the argument. If the \fIold\fP
+argument and the \fInew\fP argument resolve to the same
+existing file, \fIrename\fP() shall return successfully and perform
+no other action.
+.LP
+If the \fIold\fP argument points to the pathname of a file that is
+not a directory, the \fInew\fP argument shall not point to
+the pathname of a directory. If the link named by the \fInew\fP argument
+exists, it shall be removed and \fIold\fP renamed to
+\fInew\fP. In this case, a link named \fInew\fP shall remain visible
+to other processes throughout the renaming operation and
+refer either to the file referred to by \fInew\fP or \fIold\fP before
+the operation began. Write access permission is required
+for both the directory containing \fIold\fP and the directory containing
+\fInew\fP.
+.LP
+If the \fIold\fP argument points to the pathname of a directory, the
+\fInew\fP argument shall not point to the pathname of a
+file that is not a directory. If the directory named by the \fInew\fP
+argument exists, it shall be removed and \fIold\fP renamed
+to \fInew\fP. In this case, a link named \fInew\fP shall exist throughout
+the renaming operation and shall refer either to the
+directory referred to by \fInew\fP or \fIold\fP before the operation
+began. If \fInew\fP names an existing directory, it shall
+be required to be an empty directory.
+.LP
+If the \fIold\fP argument points to a pathname of a symbolic link,
+the symbolic link shall be renamed. If the \fInew\fP
+argument points to a pathname of a symbolic link, the symbolic link
+shall be removed.
+.LP
+The \fInew\fP pathname shall not contain a path prefix that names
+\fIold\fP. Write access permission is required for the
+directory containing \fIold\fP and the directory containing \fInew\fP.
+If the \fIold\fP argument points to the pathname of a
+directory, write access permission may be required for the directory
+named by \fIold\fP, and, if it exists, the directory named by
+\fInew\fP.
+.LP
+If the link named by the \fInew\fP argument exists and the file's
+link count becomes 0 when it is removed and no process has
+the file open, the space occupied by the file shall be freed and the
+file shall no longer be accessible. If one or more processes
+have the file open when the last link is removed, the link shall be
+removed before \fIrename\fP() returns, but the removal of the
+file contents shall be postponed until all references to the file
+are closed.
+.LP
+Upon successful completion, \fIrename\fP() shall mark for update the
+\fIst_ctime\fP and \fIst_mtime\fP fields of the parent
+directory of each file.
+.LP
+If the \fIrename\fP() function fails for any reason other than [EIO],
+any file named by \fInew\fP shall be unaffected. 
+.SH RETURN VALUE
+.LP
+Upon successful completion, \fIrename\fP() shall return 0; otherwise,
+-1 shall be returned,   \fIerrno\fP shall
+be set to indicate the error,  and neither the file named by
+\fIold\fP nor the file named by \fInew\fP shall be changed or created.
+.SH ERRORS
+.LP
+The \fIrename\fP() function shall fail if:
+.TP 7
+.B EACCES
+A
+component of either path prefix denies search permission; or one of
+the directories containing \fIold\fP or \fInew\fP denies
+write permissions; or, write permission is required and is denied
+for a directory pointed to by the \fIold\fP or \fInew\fP
+arguments. 
+.TP 7
+.B EBUSY
+The directory named by \fIold\fP or \fInew\fP is currently in use
+by the system or another process, and the implementation
+considers this an error. 
+.TP 7
+.B EEXIST \fRor\fP ENOTEMPTY
+.sp
+The link named by \fInew\fP is a directory that is not an empty directory.
+.TP 7
+.B EINVAL
+The \fInew\fP directory pathname contains a path prefix that names
+the \fIold\fP directory. 
+.TP 7
+.B EIO
+A
+physical I/O error has occurred. 
+.TP 7
+.B EISDIR
+The \fInew\fP argument points to a directory and the \fIold\fP argument
+points to a file that is not a directory. 
+.TP 7
+.B ELOOP
+A
+loop exists in symbolic links encountered during resolution of the
+\fIpath\fP argument. 
+.TP 7
+.B EMLINK
+The file named by \fIold\fP is a directory, and the link count of
+the parent directory of \fInew\fP would exceed {LINK_MAX}. 
+.TP 7
+.B ENAMETOOLONG
+.sp
+The length of the \fIold\fP or \fInew\fP argument exceeds {PATH_MAX}
+or a pathname component is longer than {NAME_MAX}. 
+.TP 7
+.B ENOENT
+The link named by \fIold\fP does not name an existing file, or either
+\fIold\fP or \fInew\fP points to an empty string. 
+.TP 7
+.B ENOSPC
+The directory that would contain \fInew\fP cannot be extended. 
+.TP 7
+.B ENOTDIR
+A
+component of either path prefix is not a directory; or the \fIold\fP
+argument names a directory and \fInew\fP argument names a
+non-directory file. 
+.TP 7
+.B EPERM \fRor\fP EACCES
+.sp
+The S_ISVTX flag is set on the directory containing the file referred
+to by \fIold\fP and the caller is not the file owner, nor is
+the caller the directory owner, nor does the caller have appropriate
+privileges; or \fInew\fP refers to an existing file, the
+S_ISVTX flag is set on the directory containing this file, and the
+caller is not the file owner, nor is the caller the directory
+owner, nor does the caller have appropriate privileges. 
+.TP 7
+.B EROFS
+The requested operation requires writing in a directory on a read-only
+file system. 
+.TP 7
+.B EXDEV
+The links named by \fInew\fP and \fIold\fP are on different file systems
+and the implementation does not support links between
+file systems. 
+.sp
+.LP
+The \fIrename\fP() function may fail if:
+.TP 7
+.B EBUSY
+The file named by the \fIold\fP or \fInew\fP arguments is a named
+STREAM. 
+.TP 7
+.B ELOOP
+More than {SYMLOOP_MAX} symbolic links were encountered during resolution
+of the \fIpath\fP argument. 
+.TP 7
+.B ENAMETOOLONG
+.sp
+As a result of encountering a symbolic link in resolution of the \fIpath\fP
+argument, the length of the substituted pathname
+string exceeded {PATH_MAX}. 
+.TP 7
+.B ETXTBSY
+The file to be renamed is a pure procedure (shared text) file that
+is being executed. 
+.sp
+.LP
+\fIThe following sections are informative.\fP
+.SH EXAMPLES
+.SS Renaming a File
+.LP
+The following example shows how to rename a file named \fB/home/cnd/mod1\fP
+to \fB/home/cnd/mod2\fP.
+.sp
+.RS
+.nf
+
+\fB#include <stdio.h>
+.sp
+
+int status;
+\&...
+status = rename("/home/cnd/mod1", "/home/cnd/mod2");
+\fP
+.fi
+.RE
+.SH APPLICATION USAGE
+.LP
+Some implementations mark for update the \fIst_ctime\fP field of renamed
+files and some do not. Applications which make use of
+the \fIst_ctime\fP field may behave differently with respect to renamed
+files unless they are designed to allow for either
+behavior.
+.SH RATIONALE
+.LP
+This \fIrename\fP() function is equivalent for regular files to that
+defined by the ISO\ C standard. Its inclusion here
+expands that definition to include actions on directories and specifies
+behavior when the \fInew\fP parameter names a file that
+already exists. That specification requires that the action of the
+function be atomic.
+.LP
+One of the reasons for introducing this function was to have a means
+of renaming directories while permitting implementations to
+prohibit the use of \fIlink\fP() and \fIunlink\fP()
+with directories, thus constraining links to directories to those
+made by \fImkdir\fP().
+.LP
+The specification that if \fIold\fP and \fInew\fP refer to the same
+file is intended to guarantee that:
+.sp
+.RS
+.nf
+
+\fBrename("x", "x");
+\fP
+.fi
+.RE
+.LP
+does not remove the file.
+.LP
+Renaming dot or dot-dot is prohibited in order to prevent cyclical
+file system paths.
+.LP
+See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in \fIrmdir\fP()
+and [EBUSY] in \fIunlink\fP() . For a discussion of [EXDEV], see \fIlink\fP()
+\&.
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIlink\fP() , \fIrmdir\fP() , \fIsymlink\fP() ,
+\fIunlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
+\fI<stdio.h>\fP
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group. In the
+event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .