'\" te
.\" Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
.TH getuserattr 3C "10 Mar 2011" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
getuserattr, getusernam, getuseruid, free_userattr, setuserattr, enduserattr, fgetuserattr \- get user_attr entry
.SH SYNOPSIS
.LP
.nf
\fBuserattr_t *\fR\fBgetuserattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBuserattr_t *\fR\fBgetusernam\fR(\fBconst char *\fR\fI\fR\fIname\fR);
.fi

.LP
.nf
\fBuserattr_t *\fR\fBgetuseruid\fR(\fBuid_t\fR \fIuid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBfree_userattr\fR(\fBuserattr_t *\fR\fIuserattr\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetuserattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBenduserattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBuserattr_t *\fR\fBfgetuserattr\fR(\fBFILE *\fR\fIf\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetuserattr()\fR, \fBgetusernam()\fR, and \fBgetuseruid()\fR functions each return a \fBuser_attr\fR(4) entry. Entries can come from any of the sources specified in the \fBnsswitch.conf\fR(4) file. The \fBgetuserattr()\fR function enumerates user_attr entries. Successive calls to this function returns either successive \fBuser_attr\fR entries or \fBNULL\fR.
.sp
.LP
The \fBgetusernam()\fR function searches for a \fBuser_attr\fR entry with a given user name name. The \fBgetuseruid()\fR function searches for a \fBuser_attr\fR entry with a given user ID \fBuid\fR. User accounts maintained in the LDAP name service may have multiple \fBuser_attr\fR entries corresponding to specific hostnames or netgroups which are distinguished by a qualifier field. The search order gives highest precedence to an entry whose hostname matches the current hostname, followed by an entry with a netgroup that includes the current hostname. An entry without any qualifier has the lowest precedence.
.sp
.LP
The \fBfgetuserattr()\fR function does not use \fBnsswitch.conf\fR but reads and parses the next line from the stream \fIf\fR. This stream is assumed to have the format of the \fBuser_attr\fR files.
.sp
.LP
The \fBfree_userattr()\fR function releases memory allocated by the \fBgetusernam()\fR, \fBgetuserattr()\fR, and \fBfgetuserattr()\fR functions.
.sp
.LP
The internal representation of a \fBuser_attr\fR entry is a \fBuserattr_t\fR structure defined in <\fBuser_attr.h\fR> with the following members:
.sp
.in +2
.nf
char  *name;       /* name of the user */
char  *qualifier;  /* optional host or netgroup */
char  *res1;       /* reserved for future use */
char  *res2;       /* reserved for future use */
kva_t *attr;       /* list of attributes */
.fi
.in -2

.sp
.LP
The \fBsetuserattr()\fR function "rewinds" to the beginning of the enumeration of \fBuser_attr\fR entries.  Calls to \fBgetusernam()\fR may leave the enumeration in an indeterminate state, so \fBsetuserattr()\fR should be called before the first call to \fBgetuserattr()\fR. 
.sp
.LP
The \fBenduserattr()\fR function may be called to indicate that \fBuser_attr\fR processing is complete; the library may then close any open \fBuser_attr\fR file, deallocate any internal storage, and so forth.
.SH RETURN VALUES
.sp
.LP
The \fBgetuserattr()\fR function returns a pointer to a \fBuserattr_t\fR if it successfully enumerates an entry; otherwise it returns \fINULL\fR, indicating the end of the enumeration.
.sp
.LP
The \fBgetusernam()\fR function returns a pointer to a \fBuserattr_t\fR if it successfully locates the requested entry; otherwise it returns \fINULL\fR.
.SH USAGE
.sp
.LP
The \fBgetuserattr()\fR and \fBgetusernam()\fR functions both allocate memory for the pointers they return. This memory should be deallocated with the \fBfree_userattr()\fR function.
.sp
.LP
Individual attributes can be referenced in the \fBattr\fR structure by calling the \fBkva_match\fR(3C) function.
.SH WARNINGS
.sp
.LP
Because the list of legal keys is likely to expand, code  must be written to ignore unknown key-value pairs without error.
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/user_attr\fR\fR
.ad
.RS 22n
.rt  
extended user attributes
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 22n
.rt  
configuration file lookup information for the name server switch
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBgetauthattr\fR(3C), \fBgetexecattr\fR(3C), \fBgetprofattr\fR(3C), \fBuser_attr\fR(4), \fBattributes\fR(5)