Add some more *at() system calls.
[dragonfly.git] / lib / libc / sys / mkdir.2
CommitLineData
984263bc
MD
1.\" Copyright (c) 1983, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
984263bc
MD
12.\" 4. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" @(#)mkdir.2 8.2 (Berkeley) 12/11/93
6d98f93c 29.\" $FreeBSD: src/lib/libc/sys/mkdir.2,v 1.28 2008/06/30 08:46:09 danger Exp $
984263bc 30.\"
6d98f93c 31.Dd August 6, 2010
984263bc
MD
32.Dt MKDIR 2
33.Os
34.Sh NAME
6d98f93c
SW
35.Nm mkdir ,
36.Nm mkdirat
984263bc
MD
37.Nd make a directory file
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
984263bc
MD
41.In sys/stat.h
42.Ft int
43.Fn mkdir "const char *path" "mode_t mode"
6d98f93c
SW
44.Ft int
45.Fn mkdirat "int fd" "const char *path" "mode_t mode"
984263bc
MD
46.Sh DESCRIPTION
47The directory
48.Fa path
49is created with the access permissions specified by
50.Fa mode
51and restricted by the
52.Xr umask 2
53of the calling process.
54.Pp
55The directory's owner ID is set to the process's effective user ID.
56The directory's group ID is set to that of the parent directory in
57which it is created.
6d98f93c
SW
58.Pp
59The
60.Fn mkdirat
61system call is equivalent to
62.Fn mkdir
63except in the case where
64.Fa path
65specifies a relative path.
66In this case the newly created directory is created relative to the
67directory associated with the file descriptor
68.Fa fd
69instead of the current working directory.
70If
71.Fn mkdirat
72is passed the special value
73.Dv AT_FDCWD
74in the
75.Fa fd
76parameter, the current working directory is used and the behavior is
77identical to a call to
78.Fn mkdir .
984263bc
MD
79.Sh RETURN VALUES
80.Rv -std mkdir
81.Sh ERRORS
6d98f93c
SW
82The
83.Fn mkdir
84system call
984263bc
MD
85will fail and no directory will be created if:
86.Bl -tag -width Er
87.It Bq Er ENOTDIR
88A component of the path prefix is not a directory.
89.It Bq Er ENAMETOOLONG
90A component of a pathname exceeded 255 characters,
91or an entire path name exceeded 1023 characters.
92.It Bq Er ENOENT
93A component of the path prefix does not exist.
94.It Bq Er EACCES
95Search permission is denied for a component of the path prefix,
96or write permission is denied
97on the parent directory of the directory to be created.
98.It Bq Er ELOOP
99Too many symbolic links were encountered in translating the pathname.
6d98f93c
SW
100.It Bq Er EPERM
101The parent directory of the directory to be created has its immutable flag set,
102see the
103.Xr chflags 2
104manual page for more information.
984263bc 105.It Bq Er EROFS
6d98f93c
SW
106The named directory would reside on a read-only file system.
107.It Bq Er EMLINK
108The new directory cannot be created because the parent directory contains
109too many subdirectories.
984263bc
MD
110.It Bq Er EEXIST
111The named file exists.
112.It Bq Er ENOSPC
113The new directory cannot be created because there is no space left
114on the file system that will contain the directory.
115.It Bq Er ENOSPC
116There are no free inodes on the file system on which the
117directory is being created.
118.It Bq Er EDQUOT
119The new directory cannot be created because the user's
120quota of disk blocks on the file system that will
121contain the directory has been exhausted.
122.It Bq Er EDQUOT
123The user's quota of inodes on the file system on
124which the directory is being created has been exhausted.
125.It Bq Er EIO
126An I/O error occurred while making the directory entry or allocating the inode.
127.It Bq Er EIO
128An I/O error occurred while reading from or writing to the file system.
129.It Bq Er EFAULT
6d98f93c
SW
130The
131.Fa path
132argument
984263bc
MD
133points outside the process's allocated address space.
134.El
6d98f93c
SW
135.Pp
136In addition to the errors returned by the
137.Fn mkdir ,
138the
139.Fn mkdirat
140may fail if:
141.Bl -tag -width Er
142.It Bq Er EBADF
143The
144.Fa path
145argument does not specify an absolute path and the
146.Fa fd
147argument is neither
148.Dv AT_FDCWD
149nor a valid file descriptor open for searching.
150.It Bq Er ENOTDIR
151The
152.Fa path
153argument is not an absolute path and
154.Fa fd
155is neither
156.Dv AT_FDCWD
157nor a file descriptor associated with a directory.
158.El
984263bc 159.Sh SEE ALSO
6d98f93c 160.Xr chflags 2 ,
984263bc
MD
161.Xr chmod 2 ,
162.Xr stat 2 ,
163.Xr umask 2
164.Sh STANDARDS
165The
166.Fn mkdir
6d98f93c 167system call is expected to conform to
984263bc 168.St -p1003.1-90 .
6d98f93c
SW
169The
170.Fn mkdirat
171system call follows The Open Group Extended API Set 2 specification.
172.Sh HISTORY
173The
174.Fn mkdirat
175system call appeared in
176.Dx 2.7 .