util/mkpath_np.3

   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