1 GETUSERATTR(3SECDB)             Security Attributes Database Library Functions
   2 
   3 
   4 
   5 NAME
   6        getuserattr, getusernam, getuseruid, free_userattr, setuserattr,
   7        enduserattr, fgetuserattr - get user_attr entry
   8 
   9 SYNOPSIS
  10        cc [ flag... ] file... -lsecdb  -lsocket  -lnsl [ library... ]
  11        #include <user_attr.h>
  12 
  13        userattr_t *getuserattr(void);
  14 
  15 
  16        userattr_t *getusernam(const char *name);
  17 
  18 
  19        userattr_t *getuseruid(uid_t uid);
  20 
  21 
  22        void free_userattr(userattr_t *userattr);
  23 
  24 
  25        void setuserattr(void);
  26 
  27 
  28        void enduserattr(void);
  29 
  30 
  31        userattr_t *fgetuserattr(FILE *f);
  32 
  33 
  34 DESCRIPTION
  35        The getuserattr(), getusernam(), and getuseruid() functions each return
  36        a user_attr(4) entry. Entries can come from any of the sources
  37        specified in the nsswitch.conf(4) file. The getuserattr() function
  38        enumerates user_attr entries. The getusernam() function searches for a
  39        user_attr entry with a given user name name. The getuseruid() function
  40        searches for a user_attr entry with a given user ID uid. Successive
  41        calls to these functions return either successive user_attr entries or
  42        NULL.
  43 
  44 
  45        The fgetuserattr() function does not use nsswitch.conf but reads and
  46        parses the next line from the stream f. This stream is assumed to have
  47        the format of the user_attr files.
  48 
  49 
  50        The free_userattr() function releases memory allocated by the
  51        getusernam(), getuserattr(), and fgetuserattr() functions.
  52 
  53 
  54        The internal representation of a user_attr entry is a userattr_t
  55        structure defined in <user_attr.h> with the following members:
  56 
  57          char  *name;       /* name of the user */
  58          char  *qualifier;  /* reserved for future use */
  59          char  *res1;       /* reserved for future use */
  60          char  *res2;       /* reserved for future use */
  61          kva_t *attr;       /* list of attributes */
  62 
  63 
  64 
  65        The setuserattr() function "rewinds" to the beginning of the
  66        enumeration of user_attr entries.  Calls to getusernam() may leave the
  67        enumeration in an indeterminate state, so setuserattr() should be
  68        called before the first call to getuserattr().
  69 
  70 
  71        The enduserattr() function may be called to indicate that user_attr
  72        processing is complete; the library may then close any open user_attr
  73        file, deallocate any internal storage, and so forth.
  74 
  75 RETURN VALUES
  76        The getuserattr() function returns a pointer to a userattr_t if it
  77        successfully enumerates an entry; otherwise it returns NULL, indicating
  78        the end of the enumeration.
  79 
  80 
  81        The getusernam() function returns a pointer to a userattr_t if it
  82        successfully locates the requested entry; otherwise it returns NULL.
  83 
  84 USAGE
  85        The getuserattr() and getusernam() functions both allocate memory for
  86        the pointers they return. This memory should be deallocated with the
  87        free_userattr() function.
  88 
  89 
  90        Individual attributes can be referenced in the attr structure by
  91        calling the kva_match(3SECDB) function.
  92 
  93 WARNINGS
  94        Because the list of legal keys is likely to expand, code must be
  95        written to ignore unknown key-value pairs without error.
  96 
  97 FILES
  98        /etc/user_attr
  99                              extended user attributes
 100 
 101 
 102        /etc/nsswitch.conf
 103                              configuration file lookup information for the
 104                              name service switch
 105 
 106 
 107 ATTRIBUTES
 108        See attributes(5) for descriptions of the following attributes:
 109 
 110 
 111 
 112 
 113        +---------------+-----------------+
 114        |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
 115        +---------------+-----------------+
 116        |MT-Level       | MT-Safe         |
 117        +---------------+-----------------+
 118 
 119 SEE ALSO
 120        getauthattr(3SECDB), getexecattr(3SECDB), getprofattr(3SECDB),
 121        kva_match(3SECDB), user_attr(4), attributes(5)
 122 
 123 
 124 
 125                                 August 13, 2018            GETUSERATTR(3SECDB)