copyfile.3

   1 .\"
   2 .\" Copyright (c) 2002 Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd April 27, 2006
   5 .Dt COPYFILE 3
   6 .Os
   7 .Sh NAME
   8 .Nm copyfile , fcopyfile ,
   9 .Nm copyfile_state_alloc , copyfile_state_free ,
  10 .Nm copyfile_state_get , copyfile_state_set
  11 .Nd copy a file
  12 .Sh LIBRARY
  13 .Lb libc
  14 .Sh SYNOPSIS
  15 .In copyfile.h
  16 .Ft int
  17 .Fn copyfile "const char *from" "const char *to" "copyfile_state_t state" "copyfile_flags_t flags"
  18 .Ft int
  19 .Fn fcopyfile "int from" "int to" "copyfile_state_t state" "copyfile_flags_t flags"
  20 .Ft copyfile_state_t
  21 .Fn copyfile_state_alloc "void"
  22 .Ft int
  23 .Fn copyfile_state_free "copyfile_state_t state"
  24 .Ft int
  25 .Fn copyfile_state_get "copyfile_state_t state" "uint32_t flag" "void * dst"
  26 .Ft int
  27 .Fn copyfile_state_set "copyfile_state_t state" "uint32_t flag" "const void * src"
  28 .Sh DESCRIPTION
  29 These functions are used to copy a file's data and/or metadata.  (Metadata
  30 consists of permissions, extended attributes, access control lists, and so
  31 forth.)
  32 .Pp
  33 The
  34 .Fn copyfile_state_alloc
  35 function initializes a
  36 .Vt copyfile_state_t
  37 object (which is an opaque data type).
  38 This object can be passed to
  39 .Fn copyfile
  40 and
  41 .Fn fcopyfile ;
  42 .Fn copyfile_state_get
  43 and
  44 .Fn copyfile_state_set
  45 can be used to manipulate the state (see below).
  46 The
  47 .Fn copyfile_state_free
  48 function is used to deallocate the object and its contents.
  49 .Pp
  50 The
  51 .Fn copyfile
  52 function can copy the named
  53 .Va from
  54 file to the named
  55 .Va to
  56 file; the
  57 .Fn fcopyfile
  58 function does the same, but using the file descriptors of already-opened
  59 files.
  60 If the
  61 .Va state
  62 parameter is the return value from
  63 .Fn copyfile_state_alloc ,
  64 then
  65 .Fn copyfile
  66 and
  67 .Fn fcopyfile
  68 will use the information from the state object; if it is
  69 .Dv NULL ,
  70 then both functions will work normally, but less control will be available to the caller.
  71 The
  72 .Va flags
  73 parameter controls which contents are copied:
  74 .Bl -tag -width COPYFILE_XATTR
  75 .It Dv COPYFILE_ACL
  76 Copy the source file's access control lists.
  77 .It Dv COPYFILE_STAT
  78 Copy the source file's POSIX information (mode, modification time, etc.).
  79 .It Dv COPYFILE_XATTR
  80 Copy the source file's extended attributes.
  81 .It Dv COPYFILE_DATA
  82 Copy the source file's data.
  83 .El
  84 .Pp
  85 These values may be or'd together; several convenience macros are provided:
  86 .Bl -tag -width COPYFILE_SECURITY
  87 .It Dv COPYFILE_SECURITY
  88 Copy the source file's POSIX and ACL information; equivalent to
  89 .Dv (COPYFILE_STAT|COPYFILE_ACL) .
  90 .It Dv COPYFILE_METADATA
  91 Copy the metadata; equivalent to
  92 .Dv (COPYFILE_SECURITY|COPYFILE_XATTR) .
  93 .It Dv COPYFILE_ALL
  94 Copy the entire file; equivalent to
  95 .Dv (COPYFILE_METADATA|COPYFILE_DATA) .
  96 .El
  97 .Pp
  98 The
  99 .Fn copyfile
 100 and
 101 .Fn fcopyfile
 102 functions can also have their behavior modified by the following flags:
 103 .Bl -tag -width COPYFILE_NOFOLLOW_SRC
 104 .It Dv COPYFILE_CHECK
 105 Return a bitmask (corresponding to the
 106 .Va flags
 107 argument) indicating which contents would be copied; no data are actually
 108 copied.  (E.g., if
 109 .Va flags
 110 was set to
 111 .Dv COPYFILE_CHECK|COPYFILE_METADATA ,
 112 and the
 113 .Va from
 114 file had extended attributes but no ACLs, the return value would be
 115 .Dv COPYFILE_XATTR .)
 116 .It Dv COPYFILE_PACK
 117 Serialize the
 118 .Va from
 119 file.  The
 120 .Va to
 121 file is an AppleDouble-format file.
 122 .It Dv COPYFILE_UNPACK
 123 Unserialize the
 124 .Va from
 125 file.  The
 126 .Va from
 127 file is an AppleDouble-format file; the
 128 .Va to
 129 file will have the extended attributes, ACLs, resource fork, and
 130 FinderInfo data from the
 131 .Va to
 132 file, regardless of the
 133 .Va flags
 134 argument passed in.
 135 .It Dv COPYFILE_EXCL
 136 Fail if the
 137 .Va to
 138 file already exists.  (This is only applicable for the
 139 .Fn copyfile
 140 function.)
 141 .It Dv COPYFILE_NOFOLLOW_SRC
 142 Do not follow the
 143 .Va from
 144 file, if it is a symbolic link.  (This is only applicable for the
 145 .Fn copyfile
 146 function.)
 147 .It Dv COPYFILE_NOFOLLOW_DST
 148 Do not follow the
 149 .Va to
 150 file, if it is a symbolic link.  (This is only applicable for the
 151 .Fn copyfile
 152 function.)
 153 .It Dv COPYFILE_MOVE
 154 Unlink (remove) the
 155 .Fa from
 156 file.  (This is only applicable for the
 157 .Fn copyfile
 158 function.)
 159 .It Dv COPYFILE_UNLINK
 160 Unlink the
 161 .Va to
 162 file before starting.  (This is only applicable for the
 163 .Fn copyfile
 164 function.)
 165 .It Dv COPYFILE_NOFOLLOW
 166 This is a convenience macro, equivalent to
 167 .Dv (COPYFILE_NOFOLLOW_DST|COPYFILE_NOFOLLOW_SRC) .
 168 .El
 169 .Pp
 170 The
 171 .Fn copyfile_state_get
 172 and
 173 .Fn copyfile_state_set
 174 functions can be used to manipulate the
 175 .Ft copyfile_state_t
 176 object returned by
 177 .Fn copyfile_state_alloc .
 178 In both functions, the
 179 .Va dst
 180 parameter's type depends on the
 181 .Va flag
 182 parameter that is passed in.
 183 .Bl -tag -width COPYFILE_STATE_DST_FILENAME
 184 .It Dv COPYFILE_STATE_SRC_FD
 185 .It Dv COPYFILE_STATE_DST_FD
 186 Get or set the file descriptor associated with the source (or destination)
 187 file.
 188 If this has not been initialized yet, the value will be -2.
 189 The
 190 .Va dst
 191 (for
 192 .Fn copyfile_state_get )
 193 and
 194 .Va src
 195 (for
 196 .Fn copyfile_state_set )
 197 parameters are pointers to
 198 .Vt int .
 199 .It Dv COPYFILE_STATE_SRC_FILENAME
 200 .It Dv COPYFILE_STATE_DST_FILENAME
 201 Get or set the filename associated with the source (or destination)
 202 file.  If it has not been initialized yet, the value will be
 203 .Dv NULL .
 204 For
 205 .Fn copyfile_state_set ,
 206 the
 207 .Va src
 208 parameter is a pointer to a C string
 209 (i.e.,
 210 .Vt char* );
 211 .Fn copyfile_state_set
 212 makes a private copy of this string.
 213 For
 214 .Fn copyfile_state_get
 215 function, the
 216 .Va dst
 217 parameter is a pointer to a pointer to a C string
 218 (i.e.,
 219 .Vt char** );
 220 the returned value is a pointer to the
 221 .Va state 's
 222 copy, and must not be modified or released.
 223 .It Dv COPYFILE_STATE_QUARANTINE
 224 Get or set the quarantine information with the source file.
 225 The
 226 .Va src
 227 parameter is a pointer to a
 228 .Vt qtn_file_t
 229 object (see
 230 .Pa <quarantine.h> ).
 231 In the case of
 232 .Dv COPYFILE_STATE_SET ,
 233 the object is cloned; in the case of
 234 .Dv COPYFILE_STATE_GET ,
 235 the object is simply returned, and it is up to the
 236 caller to clone it if desired.
 237 .El
 238 .Sh RETURN VALUES
 239 Except when given the
 240 .Dv COPYFILE_CHECK
 241 flag,
 242 .Fn copyfile
 243 and
 244 .Fn fcopyfile
 245 return less than 0 on error, and 0 on success.
 246 All of the other functions return 0 on success, and less than 0
 247 on error.
 248 .Sh ERRORS
 249 .Fn copyfile
 250 and
 251 .Fn fcopyfile
 252 will fail if:
 253 .Bl -tag -width Er
 254 .It Bq Er EINVAL
 255 Either the
 256 .Va from
 257 or
 258 .Va to
 259 parameter was a
 260 .Dv NULL
 261 pointer (
 262 .Fn copyfile ),
 263 or a negative number (
 264 .Fn fcopyfile ).
 265 .It Bq Er ENOMEM
 266 A memory allocation failed.
 267 .It Bq Er ENOTSUP
 268 The source file was not a directory, symbolic link, or regular file.
 269 .El
 270 In addition, both functions may set
 271 .Dv errno
 272 via an underlying library or system call.
 273 .Sh EXAMPLES
 274 .Bd -literal -offset indent
 275 /* Initialize a state variable */
 276 copyfile_state_t s;
 277 s = copyfile_state_alloc();
 278 /* Copy the data and extended attributes of one file to another */
 279 copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
 280 /* Convert a file to an AppleDouble file for serialization */
 281 copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
 282 /* Release the state variable */
 283 copyfile_state_free(s);
 284 /* A more complex way to call copyfile() */
 285 s = copyfile_state_alloc();
 286 copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
 287 /* One of src or dst must be set... rest can come from the state */
 288 copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
 289 /* Now copy the same source file to another destination file */
 290 copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
 291 copyfile_state_free(s);
 292 .Ed
 293 .Sh BUGS
 294 Both
 295 .Fn copyfile
 296 functions lack a way to set the input or output block size.
 297 .Sh HISTORY
 298 The
 299 .Fn copyfile
 300 API was introduced in Mac OS X 10.5.