12288 getfacl and setfacl could stand improvement

   1 ACL_TOTEXT(3SEC)     File Access Control Library Functions    ACL_TOTEXT(3SEC)
   2 
   3 
   4 
   5 NAME
   6        acl_totext, acl_fromtext - convert internal representation  to or from
   7        external representation
   8 
   9 SYNOPSIS
  10        cc [ flag... ] file... -lsec [ library... ]
  11        #include <sys/acl.h>
  12 
  13        char *acl_totext(acl_t *aclp, int flags);
  14 
  15 
  16        int acl_fromtext(char *acltextp, acl_t **aclp);
  17 
  18 
  19 DESCRIPTION
  20        The acl_totext() function converts an internal ACL representation
  21        pointed to by aclp into an external ACL representation. The memory for
  22        the external text string is obtained using malloc(3C). The caller is
  23        responsible for freeing the memory upon completion.
  24 
  25 
  26        The format of the external ACL is controlled by the flags argument.
  27        Values for flags are constructed by a bitwise-inclusive-OR of flags
  28        from the following list, defined in <sys/acl.h>.
  29 
  30        ACL_COMPACT_FMT
  31                           For NFSv4 ACLs, the ACL entries will be formatted
  32                           using the compact ACL format detailed in ls(1) for
  33                           the -V option.
  34 
  35 
  36        ACL_APPEND_ID
  37                           Append the uid or gid for additional user or group
  38                           entries.  This flag is used to construt ACL entries
  39                           in a manner that is suitable for archive utilities
  40                           such as tar(1). When the ACL is translated from the
  41                           external format to internal representation using
  42                           acl_fromtext(), the appended ID will be used to
  43                           populate the uid or gid field of the ACL entry when
  44                           the user or group name does not exist on the host
  45                           system. The appended id will be ignored when the
  46                           user or group name does exist on the system.
  47 
  48 
  49        ACL_SID_FMT
  50                           For NFSv4 ACLs, the ACL entries for user or group
  51                           entries will use the usersid or groupsid format when
  52                           the "id" field in the ACL entry is an ephemeral uid
  53                           or gid.  The raw sid format will only be used when
  54                           the "id" cannot be resolved to a windows name.
  55 
  56 
  57 
  58        The acl_fromtext() function converts an external ACL representation
  59        pointed to by acltextp into an internal ACL representation. The memory
  60        for the list of ACL entries is obtained using malloc(3C). The caller is
  61        responsible for freeing the memory upon completion. Depending on type
  62        of ACLs a file system supports, one of two external external
  63        representations are possible. For POSIX draft file systems such as ufs,
  64        the external representation is described in acltotext(3SEC). The
  65        external ACL representation For NFSv4-style ACLs is detailed as
  66        follows.
  67 
  68 
  69        Each acl_entry contains one ACL entry. The external representation of
  70        an ACL entry contains three, four or five colon separated fields. The
  71        first field contains the ACL entry type. The entry type keywords are
  72        defined as:
  73 
  74        everyone@
  75                     This ACL entry specifies the access granted to any user or
  76                     group that does not match any previous ACL entry.
  77 
  78 
  79        group
  80                     This ACL entry with a GID specifies the access granted to
  81                     a additional group of the object.
  82 
  83 
  84        group@
  85                     This ACL entry with no GID specified in the ACL entry
  86                     field specifies the access granted to the owning group of
  87                     the object.
  88 
  89 
  90        groupsid
  91                     This ACL entry with a SID or Windows name specifies the
  92                     access granted to a Windows group. This type of entry is
  93                     for a CIFS server created file.
  94 
  95 
  96        owner@
  97                     This ACL entry with no UID specified in the ACL entry
  98                     field specifies the access granted to the owner of the
  99                     object.
 100 
 101 
 102        sid
 103                     This ACL entry with a SID or Windows name when the entry
 104                     could be either a group or a user.
 105 
 106 
 107        user
 108                     This ACL entry with a UID specifies the access granted to
 109                     a additional user of the object.
 110 
 111 
 112        usersid
 113                     This ACL entry with a SID or Windows name specifies the
 114                     access granted to a Windows user. This type of entry is
 115                     for a CIFS server created file.
 116 
 117 
 118 
 119        The second field contains the ACL entry ID, and is used only for user
 120        or group ACL entries. This field is not used for owner@, group@, or
 121        everyone@ entries.
 122 
 123        uid
 124               This field contains a user-name or user-ID. If the user-name
 125               cannot be resolved to a UID, then the entry is assumed to be a
 126               numeric UID.
 127 
 128 
 129        gid
 130               This field contains a group-name or group-ID. If the group-name
 131               can't be resolved to a GID, then the entry is assumed to be a
 132               numeric GID.
 133 
 134 
 135 
 136        The third field contains the discretionary access permissions. The
 137        format of the permissions depends on whether ACL_COMPACT_FMT is
 138        specified. When the flags field does not request ACL_COMPACT_FMT, the
 139        following format is used with a forward slash (/) separating the
 140        permissions.
 141 
 142        add_file
 143                            Add a file to a directory.
 144 
 145 
 146        add_subdirectory
 147                            Add a subdirectory.
 148 
 149 
 150        append
 151                            Append data.
 152 
 153 
 154        delete
 155                            Delete.
 156 
 157 
 158        delete_child
 159                            Delete child.
 160 
 161 
 162        execute
 163                            Execute permission.
 164 
 165 
 166        list_directory
 167                            List a directory.
 168 
 169 
 170        read_acl
 171                            Read ACL.
 172 
 173 
 174        read_data
 175                            Read permission.
 176 
 177 
 178        read_attributes
 179                            Read attributes.
 180 
 181 
 182        read_xattr
 183                            Read named attributes.
 184 
 185 
 186        synchronize
 187                            Synchronize.
 188 
 189 
 190        write_acl
 191                            Write ACL.
 192 
 193 
 194        write_attributes
 195                            Write attributes.
 196 
 197 
 198        write_data
 199                            Write permission.
 200 
 201 
 202        write_owner
 203                            Write owner.
 204 
 205 
 206        write_xattr
 207                            Write named attributes.
 208 
 209 
 210 
 211        This format allows permissions to be specified as, for example:
 212        read_data/read_xattr/read_attributes.
 213 
 214 
 215        When ACL_COMPACT_FMT is specified, the permissions consist of 14 unique
 216        letters.  A hyphen (-) character is used to indicate that the
 217        permission at that position is not specified.
 218 
 219        a
 220             read attributes
 221 
 222 
 223        A
 224             write attributes
 225 
 226 
 227        c
 228             read ACL
 229 
 230 
 231        C
 232             write ACL
 233 
 234 
 235        d
 236             delete
 237 
 238 
 239        D
 240             delete child
 241 
 242 
 243        o
 244             write owner
 245 
 246 
 247        p
 248             append
 249 
 250 
 251        r
 252             read_data
 253 
 254 
 255        R
 256             read named attributes
 257 
 258 
 259        s
 260             synchronize
 261 
 262 
 263        w
 264             write_data
 265 
 266 
 267        W
 268             write named attributes
 269 
 270 
 271        x
 272             execute
 273 
 274 
 275 
 276        This format allows compact permissions to be represented as, for
 277        example: rw--d-a-------
 278 
 279 
 280        The fourth field is optional when ACL_COMPACT_FMT is not specified, in
 281        which case the field will be present only when the ACL entry has
 282        inheritance flags set. The following is the list of inheritance flags
 283        separated by a slash (/) character.
 284 
 285        dir_inherit
 286                        ACE_DIRECTORY_INHERIT_ACE
 287 
 288 
 289        file_inherit
 290                        ACE_FILE_INHERIT_ACE
 291 
 292 
 293        inherit_only
 294                        ACE_INHERIT_ONLY_ACE
 295 
 296 
 297        no_propagate
 298                        ACE_NO_PROPAGATE_INHERIT_ACE
 299 
 300 
 301 
 302        When ACL_COMPACT_FMT is specified the inheritance will always be
 303        present and is represented as positional arguments. A hyphen (-)
 304        character is used to indicate that the inheritance flag at that
 305        position is not specified.
 306 
 307        d
 308             dir_inherit
 309 
 310 
 311        f
 312             file_inherit
 313 
 314 
 315        F
 316             failed access (not currently supported)
 317 
 318 
 319        i
 320             inherit_only
 321 
 322 
 323        n
 324             no_propagate
 325 
 326 
 327        S
 328             successful access (not currently supported)
 329 
 330 
 331 
 332        The fifth field contains the type of the ACE (allow or deny):
 333 
 334        allow
 335                 The mask specified in field three should be allowed.
 336 
 337 
 338        deny
 339                 The mask specified in field three should be denied.
 340 
 341 
 342 RETURN VALUES
 343        Upon successful completion, the acl_totext() function returns a pointer
 344        to a text string. Otherwise, it returns NULL.
 345 
 346 
 347        Upon successful completion, the acl_fromtext() function returns 0.
 348        Otherwise, the return value is set to one of the following:
 349 
 350        EACL_FIELD_NOT_BLANK
 351                                    A field that should be blank is not blank.
 352 
 353 
 354        EACL_FLAGS_ERROR
 355                                    An invalid ACL flag was specified.
 356 
 357 
 358        EACL_INHERIT_ERROR
 359                                    An invalid inheritance field was specified.
 360 
 361 
 362        EACL_INVALID_ACCESS_TYPE
 363                                    An invalid access type was specified.
 364 
 365 
 366        EACL_INVALID_STR
 367                                    The string is NULL.
 368 
 369 
 370        EACL_INVALID_USER_GROUP
 371                                    The required user or group name not found.
 372 
 373 
 374        EACL_MISSING_FIELDS
 375                                    The ACL needs more fields to be specified.
 376 
 377 
 378        EACL_PERM_MASK_ERROR
 379                                    The permission mask is invalid.
 380 
 381 
 382        EACL_UNKNOWN_DATA
 383                                    Unknown data was found in the ACL.
 384 
 385 
 386 EXAMPLES
 387        Example 1 Examples of permissions when ACL_COMPACT_FMT is not
 388        specified.
 389 
 390          user:joe:read_data/write_data:file_inherit/dir_inherit:allow
 391 
 392 
 393 
 394          owner@:read_acl:allow,user:tom:read_data:file_inherit/inherit_only:deny
 395 
 396 
 397 
 398        Example 2 Examples of permissions when ACL_COMPACT_FMT is specified.
 399 
 400          user:joe:rw------------:fd----:allow
 401 
 402 
 403 
 404          owner@:----------c---:------allow,user:tom:r-------------:f-i---:deny
 405 
 406 
 407 
 408 ATTRIBUTES
 409        See attributes(5) for descriptions of the following attributes:
 410 
 411 
 412 
 413 
 414        +--------------------+-----------------+
 415        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 416        +--------------------+-----------------+
 417        |Interface Stability | Committed       |
 418        +--------------------+-----------------+
 419        |MT-Level            | Safe            |
 420        +--------------------+-----------------+
 421 
 422 SEE ALSO
 423        ls(1), tar(1), acl(2), malloc(3C), aclfromtext(3SEC), acl(5),
 424        attributes(5)
 425 
 426 
 427 
 428                                  June 16, 2008                ACL_TOTEXT(3SEC)
--- EOF ---