home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / attr_set.z / attr_set
Encoding:
Text File  |  2001-04-17  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      attr_set, attr_setf - set the value of a user attribute of a filesystem
  10.      object
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////aaaattttttttrrrriiiibbbbuuuutttteeeessss....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaattttttttrrrr____sssseeeetttt ((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ppppaaaatttthhhh,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrnnnnaaaammmmeeee,,,,
  16.                    ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrvvvvaaaalllluuuueeee,,,, ccccoooonnnnsssstttt iiiinnnntttt vvvvaaaalllluuuueeeelllleeeennnnggggtttthhhh,,,,
  17.                    iiiinnnntttt ffffllllaaaaggggssss))));;;;
  18.  
  19.      iiiinnnntttt aaaattttttttrrrr____sssseeeettttffff ((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrnnnnaaaammmmeeee,,,,
  20.                     ccccoooonnnnsssstttt cccchhhhaaaarrrr ****aaaattttttttrrrrvvvvaaaalllluuuueeee,,,, ccccoooonnnnsssstttt iiiinnnntttt vvvvaaaalllluuuueeeelllleeeennnnggggtttthhhh,,,,
  21.                     iiiinnnntttt ffffllllaaaaggggssss))));;;;
  22.  
  23. OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW
  24.      The _a_t_t_r group of system calls implement the ability for a user to attach
  25.      name/value pairs to objects within the filesystem.
  26.  
  27.      They could be used to store meta-information about the file.  For example
  28.      "character-set=kanji" could tell a document browser to use the Kanji
  29.      character set when displaying that document and "thumbnail=..." could
  30.      provide a reduced resolution overview of a high resolution graphic image.
  31.  
  32.      The _n_a_m_e_s can be up to MAXNAMELEN bytes in length, terminated by the
  33.      first 0 byte.  The intent is that they be printable ASCII (or other
  34.      character set) names for the attribute.
  35.  
  36.      The _v_a_l_u_e_s can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary
  37.      binary data.
  38.  
  39.      Attributes can be attached to all types of inodes:  regular files,
  40.      directories, symbolic links, device nodes, etc.
  41.  
  42.      There are 2 disjoint attribute name spaces associated with every
  43.      filesystem object.  They are the rrrrooooooootttt and uuuusssseeeerrrr address spaces.  The rrrrooooooootttt
  44.      address space is accessible only to privileged users, and only then by
  45.      specifying a flag argument to the function call.  A privileged user can
  46.      be either the superuser in an IIIIRRRRIIIIXXXX environment, or a user with
  47.      CCCCAAAAPPPP____DDDDEEEEVVVVIIIICCCCEEEE____MMMMGGGGTTTT capability.  Other users will not see or be able to modify
  48.      attributes in the rrrrooooooootttt address space.  The uuuusssseeeerrrr address space is
  49.      protected by the normal file permissions mechanism, so the owner of the
  50.      file can decide who is able to see and/or modify the value of attributes
  51.      on any particular file.
  52.  
  53.      Attributes are currently fully supported only in the XFS and CXFS
  54.      filesystem types.  Other filesystem types may provide a partial
  55.      implementation.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))
  71.  
  72.  
  73.  
  74. DESCRIPTION
  75.      The _a_t_t_r__s_e_t and _a_t_t_r__s_e_t_f functions provide a way to create attributes
  76.      and set/change their values.
  77.  
  78.      _P_a_t_h points to a path name for a filesystem object, and _f_d refers to the
  79.      file descriptor associated with a file.  If the attribute _a_t_t_r_n_a_m_e does
  80.      not exist, an attribute with the given name and value will be created and
  81.      associated with that indicated filesystem object.  If an attribute with
  82.      that name already exists on that filesystem object, the existing value is
  83.      replaced with the new value given in this call.  The new attribute value
  84.      is copied from the _a_t_t_r_v_a_l_u_e buffer for a total of _v_a_l_u_e_l_e_n_g_t_h bytes.
  85.      The _f_l_a_g_s argument can contain the following symbols bitwise OR'ed
  86.      together:
  87.  
  88.      ATTR_ROOT
  89.           Look for _a_t_t_r_n_a_m_e in the rrrrooooooootttt address space, not in the uuuusssseeeerrrr address
  90.           space.  (limited to use by super-user only)
  91.  
  92.      ATTR_DONTFOLLOW
  93.           Do not follow symbolic links when resolving a _p_a_t_h on an _a_t_t_r__s_e_t
  94.           function call.  The default is to follow symbolic links.
  95.  
  96.      ATTR_CREATE
  97.           Return an error (EEXIST) if an attribute of the given name already
  98.           exists on the indicated filesystem object, otherwise create an
  99.           attribute with the given name and value.  This flag is used to
  100.           implement a pure create operation, without this flag _a_t_t_r__s_e_t will
  101.           create the attribute if it does not already exist.  An error
  102.           (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE are
  103.           set in the same call.
  104.  
  105.      ATTR_REPLACE
  106.           Return an error (ENOATTR) if an attribute of the given name does not
  107.           already exist on the indicated filesystem object, otherwise replace
  108.           the existing attribute's value with the given value.  This flag is
  109.           used to implement a pure replacement operation, without this flag
  110.           _a_t_t_r__s_e_t will create the attribute if it does not already exist.  An
  111.           error (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE
  112.           are set in the same call.
  113.  
  114.      _a_t_t_r__s_e_t will fail if one or more of the following are true:
  115.  
  116.      [ENOATTR]        The attribute name given is not associated with the
  117.                       indicated filesystem object and the ATTR_REPLACE flag
  118.                       bit was set.
  119.  
  120.      [E2BIG]          The value of the given attribute is too large, it
  121.                       exceeds the maximum allowable size of an attribute
  122.                       value.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))
  137.  
  138.  
  139.  
  140.      [EEXIST]         The attribute name given is already associated with the
  141.                       indicated filesystem object and the ATTR_CREATE flag bit
  142.                       was set.
  143.  
  144.      [ENOENT]         The named file does not exist.
  145.  
  146.      [EPERM]          The effective user ID does not match the owner of the
  147.                       file and the effective user ID is not super-user.
  148.  
  149.      [ENOTDIR]        A component of the path prefix is not a directory.
  150.  
  151.      [EACCES]         Search permission is denied on a component of the path
  152.                       prefix.
  153.  
  154.      [EINVAL]         A bit was set in the _f_l_a_g argument that is not defined
  155.                       for this system call, or both the ATTR_CREATE and
  156.                       ATTR_REPLACE flags bits were set.
  157.  
  158.      [EFAULT]         _P_a_t_h, _a_t_t_r_n_a_m_e, or _a_t_t_r_v_a_l_u_e points outside the
  159.                       allocated address space of the process.
  160.  
  161.      [ELOOP]          A path name lookup involved too many symbolic links.
  162.  
  163.      [ENAMETOOLONG]   The length of _p_a_t_h exceeds {_M_A_X_P_A_T_H_L_E_N}, or a pathname
  164.                       component is longer than {_M_A_X_N_A_M_E_L_E_N}.
  165.  
  166.      _a_t_t_r__s_e_t_f will fail if:
  167.  
  168.      [ENOATTR]      The attribute name given is not associated with the
  169.                     indicated filesystem object and the ATTR_REPLACE flag bit
  170.                     was set.
  171.  
  172.      [E2BIG]        The value of the given attribute is too large, it exceeds
  173.                     the maximum allowable size of an attribute value.
  174.  
  175.      [EEXIST]       The attribute name given is already associated with the
  176.                     indicated filesystem object and the ATTR_CREATE flag bit
  177.                     was set.
  178.  
  179.      [EINVAL]       A bit was set in the _f_l_a_g argument that is not defined for
  180.                     this system call, or both the ATTR_CREATE and ATTR_REPLACE
  181.                     flags bits were set, or _f_d refers to a socket, not a file.
  182.  
  183.      [EFAULT]       _A_t_t_r_n_a_m_e, or _a_t_t_r_v_a_l_u_e points outside the allocated
  184.                     address space of the process.
  185.  
  186.      [EBADF]        _F_d does not refer to a valid descriptor.
  187.  
  188. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  189.      attr(1),
  190.      attr_get(2), attr_getf(2),
  191.      attr_list(2), attr_listf(2)
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))                                                        AAAATTTTTTTTRRRR____SSSSEEEETTTT((((2222))))
  203.  
  204.  
  205.  
  206.      attr_multi(2), attr_multif(2)
  207.      attr_remove(2), attr_removef(2),
  208.  
  209. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  210.      Upon successful completion, a value of 0 is returned.  Otherwise, a value
  211.      of -1 is returned and _e_r_r_n_o is set to indicate the error.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.