+/*
+ * Linux provides extended attributes through the <sys/xattr.h> API.
+ * Any file or link can have attributes assigned to it (provided that they are
+ * supported by the backing filesystem). Each attribute has to be placed in a
+ * namespace, of which "user" is the most common. Namespaces are specified as
+ * a prefix to the attribute name, proceeded by a '.' (e.g. user.myattribute)
+ *
+ * FreeBSD provides extended attributes through the <sys/extattr.h> API.
+ * Behaviour is very similar to Linux EA's, but the namespace is specified
+ * through an enum-style parameter rather than as a prefix to an attribute
+ * name. There are also differences in the behaviour of the "list attributes"
+ * system calls.
+ *
+ * This file merges the two implementations into a single API for use by the
+ * Mono.Unix.Syscall.*xattr methods. No matter which OS you are on, things
+ * should "just work" the same as anywhere else.
+ *
+ * The API provided here leans more towards the Linux implementation. Attribute
+ * namespaces are provided as prefixes to the attribute name (followed by '.').
+ * There is no limit to the namespaces accepted by the Linux side of this
+ * implementation, but you are obviously limited to the ones available to you
+ * on the system.
+ * FreeBSD namespaces have to be converted from the textual prefix into their
+ * relevant number so that they can be used in the FreeBSD system calls.
+ * This means that the only namespaces available are the ones known by in this
+ * file (see bsd_extattr_namespaces). However, you can also specify the
+ * numericalnamespace index yourself, by using an attribute name such as
+ * "5.myattr".
+ * (this will obviously fail on Linux, your code will no longer be 'portable')
+ *
+ * Linux {,l,f}setxattr calls have a flags parameter which allow you to control
+ * what should happen if an attribute with the same name does (or doesn't)
+ * already exist. The 'flags' parameter is available here, but because FreeBSD
+ * does not support this kind of refinement, it will fail on FreeBSD if you
+ * specify anything other than XATTR_AUTO (XATTR_AUTO will create the attribute
+ * if it doesn't already exist, and overwrite the existing attribute if it
+ * already set).
+ *
+ * For usage and behaviour information, see the monodoc documentation on the
+ * Mono.Unix.Syscall class.
+ */
+