[apple/libc.git] / util / mkpath_np.3

.\" Copyright (c) 2011 Apple Inc. All rights reserved.
.\" 
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd July 13, 2011
.Dt mkpath_np 3
.Os "Mac OS X"
.Sh NAME
.Nm mkpath_np
.Nd Auxiliary routine for efficiently creating paths
.Sh SYNOPSIS
.Fd #include <unistd.h>
.\"
.Ft int
.Fo mkpath_np
.Fa "const char * path"
.Fa "mode_t omode"
.Fc
.Sh DESCRIPTION
This routine allows the caller to create a path, including intermediate
directories.  It is equivalent to calling
.Xr mkdir 1
with the -p command line argument.
.Pp
Intermediate directories are created with permission bits of rwxrwxrwx (0777)
as modified by the current umask, plus write and search permission for the
owner.
.Pp
The leaf directory is created with permission bits of
.Fa omode
as modified by the current umask.
.Sh RETURN VALUES
A 0 return value indicates success.  If an error occurs, the return value is a
non-zero error code.  Note that EEXIST is returned iff the leaf directory
already exists and is a directory, so under certain circumstances, this error
value may not indicate a failure state.
.Pp
This routine does NOT modify errno.
.Sh ERRORS
Any error code that can be returned by
.Xr mkdir 2
can be returned by
.Fn mkpath_np ,
but
.Fn mkpath_np
will return the error code rather than setting errno.
.Bl -tag -width Er
.\" ==========
.It Bq Er ENOTDIR
A component of the path is not a directory (in contrast to
.Xr mkdir 2
which returns this based on the path prefix rather than the path).
.\" ==========
.It Bq Er EEXIST
The path already exists and is a directory.
.El
.Sh HISTORY
This function first appeared in
iOS 5.0.
.Sh SEE ALSO
.Xr mkdir 1 ,
.Xr chmod 2 ,
.Xr mkdir 2
Commit	Line	Data
ad3c9f2a A	1	.\" Copyright (c) 2011 Apple Inc. All rights reserved.
	2	.\"
	3	.\" @APPLE_LICENSE_HEADER_START@
	4	.\"
	5	.\" This file contains Original Code and/or Modifications of Original Code
	6	.\" as defined in and that are subject to the Apple Public Source License
	7	.\" Version 2.0 (the 'License'). You may not use this file except in
	8	.\" compliance with the License. Please obtain a copy of the License at
	9	.\" http://www.opensource.apple.com/apsl/ and read it before using this
	10	.\" file.
	11	.\"
	12	.\" The Original Code and all software distributed under the License are
	13	.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	14	.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	15	.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	16	.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	17	.\" Please see the License for the specific language governing rights and
	18	.\" limitations under the License.
	19	.\"
	20	.\" @APPLE_LICENSE_HEADER_END@
	21	.\"
	22	.Dd July 13, 2011
	23	.Dt mkpath_np 3
	24	.Os "Mac OS X"
	25	.Sh NAME
	26	.Nm mkpath_np
	27	.Nd Auxiliary routine for efficiently creating paths
	28	.Sh SYNOPSIS
	29	.Fd #include <unistd.h>
	30	.\"
	31	.Ft int
	32	.Fo mkpath_np
	33	.Fa "const char * path"
	34	.Fa "mode_t omode"
	35	.Fc
	36	.Sh DESCRIPTION
	37	This routine allows the caller to create a path, including intermediate
	38	directories. It is equivalent to calling
	39	.Xr mkdir 1
	40	with the -p command line argument.
	41	.Pp
	42	Intermediate directories are created with permission bits of rwxrwxrwx (0777)
	43	as modified by the current umask, plus write and search permission for the
	44	owner.
	45	.Pp
	46	The leaf directory is created with permission bits of
	47	.Fa omode
	48	as modified by the current umask.
	49	.Sh RETURN VALUES
	50	A 0 return value indicates success. If an error occurs, the return value is a
	51	non-zero error code. Note that EEXIST is returned iff the leaf directory
	52	already exists and is a directory, so under certain circumstances, this error
	53	value may not indicate a failure state.
	54	.Pp
	55	This routine does NOT modify errno.
	56	.Sh ERRORS
	57	Any error code that can be returned by
	58	.Xr mkdir 2
	59	can be returned by
	60	.Fn mkpath_np ,
	61	but
	62	.Fn mkpath_np
	63	will return the error code rather than setting errno.
	64	.Bl -tag -width Er
65	.\" ==========
66	.It Bq Er ENOTDIR
67	A component of the path is not a directory (in contrast to
68	.Xr mkdir 2
69	which returns this based on the path prefix rather than the path).
70	.\" ==========
71	.It Bq Er EEXIST
72	The path already exists and is a directory.
73	.El
74	.Sh HISTORY
75	This function first appeared in
76	iOS 5.0.
77	.Sh SEE ALSO
78	.Xr mkdir 1 ,
79	.Xr chmod 2 ,
80	.Xr mkdir 2