xattr_name_with_flags.3

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