xattr_name_with_flags.3

   1 .\"
   2 .\" Copyright (c) 2013 Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd December 21, 2016
   5 .Dt XATTR_NAME_WITH_FLAGS 3
   6 .Os
   7 .Sh NAME
   8 .Nm xattr_preserve_for_intent , xattr_name_with_flags , xattr_name_without_flags ,
   9 .Nm xattr_flags_from_name , xattr_intent_with_flags
  10 .Sh LIBRARY
  11 .Lb libc
  12 .Sh SYNOPSIS
  13 .In xattr_flags.h
  14 .Ft int
  15 .Fn xattr_preserve_for_intent "const char *" "xattr_operation_intent_t"
  16 .Ft char *
  17 .Fn xattr_name_with_flags "const char *" "xattr_flags_t"
  18 .Ft char *
  19 .Fn xattr_name_without_flags "const char *"
  20 .Ft xattr_flags_t
  21 .Fn xattr_flags_from_name "const char *"
  22 .Ft int
  23 .Fn xattr_intent_with_flags "xattr_operation_intent_t" "xattr_flags_t"
  24 .Sh DESCRIPTION
  25 These functions are used in conjunction with copying extended attributes from
  26 one file to another.  Various types of copying (an "intent") check flags to
  27 determine which is allowed or not.
  28 .Pp
  29 The
  30 .Fn xattr_name_with_flags
  31 function returns an extended attribute name with the appropriate flags encoded
  32 as a string; the
  33 .Fn xattr_name_without_flags
  34 undoes this, giving the name of the extended attribute without the flags
  35 encoding.  The slight inverse of that is
  36 .Fn xattr_flags_from_name ,
  37 which will return the flags encoded in a name.
  38 .Pp
  39 The values returned by
  40 .Fn xattr_name_with_flags
  41 and
  42 .Fn xattr_name_without_flags
  43 are allocated using
  44 .Xr malloc 3 ,
  45 and should be released by the caller, using
  46 .Xr free 3 .
  47 .Pp
  48 These functions also have an internal table of pre-defined names, maintained
  49 by the operating system.
  50 .Pp
  51 The function
  52 .Fn xattr_intent_with_flags
  53 will return 0 if the
  54 .Ar flags
  55 argument indicates it should not be preserved for the given
  56 intent, or 1 if it should.
  57 .Pp
  58 The function
  59 .Fn xattr_preserve_for_intent
  60 combines the functions above, and will return zero if the
  61 named extended attribute should be preserved during a copy for
  62 the given intent.
  63 .Sh INTENT
  64 The type
  65 .Dt xattr_operation_intent_t
  66 is an integral type, which is used to indicate what the intent for the operation
  67 is.  The following intent values are defined:
  68 .Bl -tag -width XATTR_OPERATION_INTENT_SHARE
  69 .It Dv XATTR_OPERATION_INTENT_COPY
  70 Indicates that the intent is to simply copy from the source to the destination.
  71 E.g., with cp.  Most extended attributes should generally be preserved in this
  72 case.
  73 .It Dv XATTR_OPERATION_INTENT_SAVE
  74 Indicates that intent is to perform a save (perhaps as in a "safe save").
  75 This differs from a copy in that the content may be changing; the destination
  76 may be over-writing or replacing the source, and some extended attributes should
  77 not be preserved during this process.
  78 .It Dv XATTR_OPERATION_INTENT_SHARE
  79 Indicates that the intent is to share, or export, the object.  For example,
  80 saving as an attachment in an email message, or placing in a public folder.
  81 Sensitive information should probably not be preserved in this case.
  82 .It Dv XATTR_OPERATION_INTENT_SYNC
  83 Indicates that the intent is to sync the object to a service like iCloud.
  84 .El
  85 .Sh FLAGS
  86 Various flags are defined by the type
  87 .Dt xattr_flags_t ;
  88 the currently-defined values for this are
  89 .Bl -tag -width XATTR_FLAG_CONTENT_DEPENDENT
  90 .It Dv XATTR_FLAG_NO_EXPORT
  91 This indicates that the extended attribute should not be exported, or shared.
  92 This is used with
  93 .Dv XATTR_OPERATION_INTENT_SHARE .
  94 .It Dv XATTR_FLAG_CONTENT_DEPENDENT
  95 This indicates that the extended attribute is tied to the contents of the
  96 file (or vice versa), such that it should be re-created when the contents
  97 are changed.  A checksum, for example, should not be copied, and would thus
  98 be marked with this flag.
  99 .It Dv XATTR_FLAG_NEVER_PRESERVE
 100 This indicates that the extended attribute should never be copied from a
 101 source object to a destination, no matter what the given intent is.
 102 .It Dv XATTR_FLAG_SYNCABLE
 103 This indicates that the extended attribute should be copied when the file
 104 is synced on services like iCloud. Sync services tends to want the metadata
 105 synced to be kept to a bare minimum, and may enforce additional restrictions
 106 on the acceptable size and number of extended attributes.
 107 .El
 108 .Sh EXAMPLE
 109 The following example is a simple function that, given an extended attribute
 110 name and an operation intent, will return whether or not the extended attribute
 111 should be copied.  (This essentially does what
 112 .Fn xattr_preserve_for_intent
 113 does.)
 114 .Bd -literal -offset indent
 115 int
 116 ShouldCopyEA(const char *eaName, xattr_operation_intent_t intent)
 117 {
 118         xattr_flags_t flags = xattr_flags_from_name(eaName);
 119         return xattr_intent_with_flags(intent, flags);
 120 }
 121 .Ed
 122 .Sh HISTORY
 123 These functions first appeared in Mac OS in 2013.