xnu-2422.115.4.tar.gz

[apple/xnu.git] / bsd / man / man2 / mkdir.2

diff --git a/bsd/man/man2/mkdir.2 b/bsd/man/man2/mkdir.2
index dd305fb0d1411a337a9c62bab8508b4d76001a0f..5fba3bf5a4ea8fc705f09097a2e15c3c7d59f369 100644 (file)
--- a/bsd/man/man2/mkdir.2
+++ b/bsd/man/man2/mkdir.2
@@ -40,10 +40,12 @@
 .Nm mkdir
 .Nd make a directory file
 .Sh SYNOPSIS
-.Fd #include <sys/types.h>
 .Fd #include <sys/stat.h>
 .Ft int
-.Fn mkdir "const char *path" "mode_t mode"
+.Fo mkdir
+.Fa "const char *path"
+.Fa "mode_t mode"
+.Fc
 .Sh DESCRIPTION
 The directory
 .Fa path
@@ -51,11 +53,22 @@ is created with the access permissions specified by
 .Fa mode
 and restricted by the
 .Xr umask 2
-of the calling process.
+of the calling process. See
+.Xr chmod 2
+for the possible permission bit masks for
+.Fa mode . 
 .Pp
 The directory's owner ID is set to the process's effective user ID.
 The directory's group ID is set to that of the parent directory in
 which it is created.
+.Pp
+Note: the behavior of
+.Fn mkdir
+is undefined when mode bits other than the low 9 bits are used. Use
+.Xr chmod 2
+after
+.Fn mkdir
+to explicitly set the other bits (See example below).
 .Sh RETURN VALUES
 A 0 return value indicates success.  A -1 return value
 indicates an error, and an error code is stored in
@@ -64,49 +77,94 @@ indicates an error, and an error code is stored in
 .Fn Mkdir
 will fail and no directory will be created if:
 .Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded 
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded 
-.Dv {PATH_MAX}
-characters.
-.It Bq Er ENOENT
-A component of the path prefix does not exist.
+.\" ==========
 .It Bq Er EACCES
 Search permission is denied for a component of the path prefix.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
-.It Bq Er EROFS
-The named file resides on a read-only file system.
-.It Bq Er EEXIST
-The named file exists.
-.It Bq Er ENOSPC
-The new directory cannot be created because there is no space left
-on the file system that will contain the directory.
-.It Bq Er ENOSPC
-There are no free inodes on the file system on which the
-directory is being created.
+.\" ==========
+.It Bq Er EACCES
+Write permission is denied for the parent directory.
+.\" ==========
 .It Bq Er EDQUOT
 The new directory cannot be created because the user's
 quota of disk blocks on the file system that will
 contain the directory has been exhausted.
+.\" ==========
 .It Bq Er EDQUOT
 The user's quota of inodes on the file system on
 which the directory is being created has been exhausted.
-.It Bq Er EIO
-An I/O error occurred while making the directory entry or allocating the inode.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er EEXIST
+The named file exists.
+.\" ==========
 .It Bq Er EFAULT
 .Fa Path
 points outside the process's allocated address space.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurred while making the directory entry
+or allocating the inode.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ==========
+.It Bq Er EMLINK
+The parent directory already has {LINK_MAX} links.
+.\" ==========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 
+.Dv {NAME_MAX}
+characters, or an entire path name exceeded 
+.Dv {PATH_MAX}
+characters.
+.\" ==========
+.It Bq Er ENOENT
+A component of the path prefix does not exist
+or path is an empty string.
+.It Bq Er ENOSPC
+The new directory cannot be created because there is no space left
+on the file system that would contain it.
+.\" ==========
+.It Bq Er ENOSPC
+There are no free inodes on the file system on which the
+directory is being created.
+.\" ==========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.\" ==========
+.It Bq Er EROFS
+The parent directory resides on a read-only file system.
 .El
+.Sh EXAMPLE
+.Bd -literal -offset indent
+
+int main (int argc, const char * argv[]) 
+{
+       /* The behavior of mkdir is undefined for anything other than the "permission" bits */
+       if (mkdir("/tmp/blah", 0777))
+               perror("/tmp/blah");    
+
+       /* So we need to set the sticky/executable bits explicitly with chmod after calling mkdir */
+       if (chmod("/tmp/blah", 07777))
+               perror("/tmp/blah");    
+}
+
+.Ed 
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/stat.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.
 .Sh SEE ALSO
 .Xr chmod 2 ,
 .Xr stat 2 ,
-.Xr umask 2
+.Xr umask 2 ,
+.Xr compat 5
 .Sh STANDARDS
 The 
 .Fn mkdir