Purpose
Accesses the user information in the user database.
Library
Security Library (libc.a)
Syntax
#include <usersec.h>
int getuserattr (User, Attribute, Value, Type)
char * User;
char * Attribute;
void * Value;
int Type;
char *IDtouser( UID)
uid__t UID;
char *nextuser ( Mode, Argument)
int Mode, Argument;
int putuserattr (User, Attribute, Value, Type)
char *User;
char *Attribute;
void *Value;
int Type;
Description
Attention: These subroutines and the setpwent and setgrent subroutines
should not be used simultaneously. The results can be unpredictable.
These subroutines access user information. Because
of their greater granularity and extensibility, you should use them
instead of the getpwent routines.
The getuserattr subroutine
reads a specified attribute from the user database. If the database
is not already open, this subroutine does an implicit open for reading.
A call to the getuserattr subroutine for every new user verifies
that the user exists.
Similarly, the putuserattr subroutine
writes a specified attribute into the user database. If the database
is not already open, this subroutine does an implicit open for reading
and writing. Data changed by the putuserattr subroutine must
be explicitly committed by calling the putuserattr subroutine
with a Type parameter specifying SEC_COMMIT. Until all
the data is committed, only these subroutines within the process return
written data.
New entries in the user
and group databases must first be created by invoking putuserattr with
the SEC_NEW type.
The IDtouser subroutine
translates a user ID into a user name.
The nextuser subroutine
returns the next user in a linear search of the user database. The
consistency of consecutive searches depends upon the underlying storage-access
mechanism and is not guaranteed by this subroutine.
The setuserdb and enduserdb subroutines
should be used to open and close the user database.
The enduserdb subroutine
frees all memory allocated by the getuserattr subroutine.
Parameters
- Argument
- Presently unused and must be specified as null.
- Attribute
- Specifies which attribute is read. The following possible attributes
are defined in the usersec.h file:
- S_CORECOMP
- Core compression status. The attribute type is SEC_CHAR.
- S_COREPATH
- Core path specification status. The attribute type is SEC_CHAR.
- S_COREPNAME
- Core path specification location. The attribute type is SEC_CHAR.
- S_CORENAMING
- Core naming status. The attribute type is SEC_CHAR.
- S_ID
- User ID. The attribute type is SEC_INT.
- S_PGID
- Principle group ID. The attribute type is SEC_INT.
- S_PGRP
- Principle group name. The attribute type is SEC_CHAR.
- S_GROUPS
- Groups to which the user belongs. The attribute type is SEC_LIST.
- S_ADMGROUPS
- Groups for which the user is an administrator. The attribute type
is SEC_LIST.
- S_ADMIN
- Administrative status of a user. The attribute type is SEC_BOOL.
- S_AUDITCLASSES
- Audit classes to which the user belongs. The attribute type
is SEC_LIST.
- S_AUTHSYSTEM
- Defines the user's authentication method. The attribute type
is SEC_CHAR.
- S_HOME
- Home directory. The attribute type is SEC_CHAR.
- S_SHELL
- Initial program run by a user. The attribute type is SEC_CHAR.
- S_GECOS
- Personal information for a user. The attribute type is SEC_CHAR.
- S_USRENV
- User-state environment variables. The attribute type is SEC_LIST.
- S_SYSENV
- Protected-state environment variables. The attribute type is SEC_LIST.
- S_LOGINCHK
- Specifies whether the user account can be used for local logins.
The attribute type is SEC_BOOL.
- S_HISTEXPIRE
- Defines the period of time (in weeks) that a user cannot reuse
a password. The attribute type is SEC_INT.
- S_HISTSIZE
- Specifies the number of previous passwords that the user cannot
reuse. The attribute type is SEC_INT.
- S_MAXREPEAT
- Defines the maximum number of times a user can repeat a character
in a new password. The attribute type is SEC_INT.
- S_MINAGE
- Defines the minimum age in weeks that the user's password must
exist before the user can change it. The attribute type is SEC_INT.
- S_PWDCHECKS
- Defines the password restriction methods for this account. The
attribute type is SEC_LIST.
- S_MINALPHA
- Defines the minimum number of alphabetic characters required
in a new user's password. The attribute type is SEC_INT.
- S_MINDIFF
- Defines the minimum number of characters required in a new password
that were not in the old password. The attribute type is SEC_INT.
- S_MINLEN
- Defines the minimum length of a user's password. The attribute
type is SEC_INT.
- S_MINOTHER
- Defines the minimum number of non-alphabetic characters required
in a new user's password. The attribute type is SEC_INT.
- S_DICTION
- Defines the password dictionaries for this account. The attribute
type is SEC_LIST.
- S_SUCHK
- Specifies whether the user account can be accessed with the su command.
Type SEC_BOOL.
- S_REGISTRY
- Defines the user's authentication registry. The attribute type
is SEC_CHAR.
- S_RLOGINCHK
- Specifies whether the user account can be used for remote logins
using the telnet or rlogin commands. The attribute type
is SEC_BOOL.
- S_DAEMONCHK
- Specifies whether the user account can be used for daemon execution
of programs and subsystems using the cron daemon or src.
The attribute type is SEC_BOOL.
- S_TPATH
- Defines how the account may be used on the trusted path. The
attribute type is SEC_CHAR. This attribute must be one of the
following values:
- nosak
- The secure attention key is not enabled for this account.
- notsh
- The trusted shell cannot be accessed from this account.
- always
- This account may only run trusted programs.
- on
- Normal trusted-path processing applies.
- S_TTYS
- List of ttys that can or cannot be used to access this account.
The attribute type is SEC_LIST.
- S_SUGROUPS
- Groups that can or cannot access this account. The attribute
type is SEC_LIST.
- S_EXPIRATION
- Expiration date for this account is a string in the form MMDDhhmmyy,
where MM is the month, DD is the day, hh is the hour in 0 to 24 hour
notation, mm is the minutes past the hour, and yy is the last two
digits of the year. The attribute type is SEC_CHAR. For more
information about the password expiration, see the /etc/security/user file.
- S_AUTH1
- Primary authentication methods for this account. The attribute
type is SEC_LIST.
- S_AUTH2
- Secondary authentication methods for this account. The attribute
type is SEC_LIST.
- S_UFSIZE
- Process file size soft limit. The attribute type is SEC_INT.
- S_UCPU
- Process CPU time soft limit. The attribute type is SEC_INT.
- S_UDATA
- Process data segment size soft limit. The attribute type is SEC_INT.
- S_USTACK
- Process stack segment size soft limit. Type: SEC_INT.
- S_URSS
- Process real memory size soft limit. Type: SEC_INT.
- S_UCORE
- Process core file size soft limit. The attribute type is SEC_INT.
- S_UNOFILE
- Process file descriptor table size soft limit. The attribute
type is SEC_INT.
- S_PWD
- Specifies the value of the passwd field in the /etc/passwd file.
The attribute type is SEC_CHAR.
- S_UMASK
- File creation mask for a user. The attribute type is SEC_INT.
- S_LOCKED
- Specifies whether the user's account can be logged into. The
attribute type is SEC_BOOL.
- S_ROLES
- Defines the administrative roles for this account. The attribute
type is SEC_LIST.
- S_UFSIZE_HARD
- Process file size hard limit. The attribute type is SEC_INT.
- S_UCPU_HARD
- Process CPU time hard limit. The attribute type is SEC_INT.
- S_UDATA_HARD
- Process data segment size hard limit. The attribute type is SEC_INT.
- S_USREXPORT
- Specifies if the DCE registry can overwrite the local user information
with the DCE user information during a DCE export operation. The attribute
type is SEC_BOOL.
- S_USTACK_HARD
- Process stack segment size hard limit. Type: SEC_INT.
- S_URSS_HARD
- Process real memory size hard limit. Type: SEC_INT.
- S_UCORE_HARD
- Process core file size hard limit. The attribute type is SEC_INT.
- S_UNOFILE_HARD
- Process file descriptor table size hard limit. The attribute
type is SEC_INT.
- S_DOMAINS
- The domains for the user. It can be one or more. The attribute
type is SEC_LIST.
- S_DFLT_ROLES
- The default roles for the user. It can be one or more roles. The
attribute type is SEC_LIST.
- S_MINLOWERALPHA
- Defines the minimum number of lowercase alphabetic characters
required in a new user password. The attribute type is SEC_INT.
- S_MINUPPERALPHA
- Defines the minimum number of uppercase alphabetic characters
required in a new user password. The attribute type is SEC_INT.
- S_MINDIGIT
- Defines the minimum number of digits required in a new user password.
The attribute type is SEC_INT.
- S_MINSPECIALCHAR
- Defines the minimum number of special characters required in a
new user's password. The attribute type is SEC_INT.
Note: These values are string constants that should
be used by applications both for convenience and to permit optimization
in latter implementations. Additional user-defined attributes may
be used and will be stored in the format specified by the Type parameter.
- Mode
- Specifies the search mode. This parameter can be used to delimit
the search to one or more user credentials databases. Specifying a
non-null Mode value also implicitly rewinds the search. A null Mode value
continues the search sequentially through the database. This parameter
must include one of the following values specified as a bit mask;
these are defined in the usersec.h file:
- S_LOCAL
- Locally defined users are included in the search.
- S_SYSTEM
- All credentials servers for the system are searched.
-
- Type
- Specifies the type of attribute expected. Valid types are defined
in the usersec.h file and include:
- SEC_INT
- The format of the attribute is an integer.
For the getuserattr subroutine,
the user should supply a pointer to a defined integer variable. For
the putuserattr subroutine, the user should supply an integer.
- SEC_CHAR
- The format of the attribute is a null-terminated character string.
For the getuserattr subroutine, the user should supply
a pointer to a defined character pointer variable. For the putuserattr subroutine,
the user should supply a character pointer.
- SEC_LIST
- The format of the attribute is a series of concatenated strings,
each null-terminated. The last string in the series is terminated
by two successive null characters.
For the getuserattr subroutine,
the user should supply a pointer to a defined character pointer variable.
For the putuserattr subroutine, the user should supply a character
pointer.
- SEC_BOOL
- The format of the attribute from getuserattr is an integer
with the value of either 0 (false) or 1 (true). The format of the
attribute for putuserattr is a null-terminated string containing
one of the following strings: true, false, yes, no, always, or never.
For the getuserattr subroutine, the user should supply
a pointer to a defined integer variable. For the putuserattr subroutine,
the user should supply a character pointer.
- SEC_COMMIT
- For the putuserattr subroutine, this value specified
by itself indicates that changes to the named user are to be committed
to permanent storage. The Attribute and Value parameters
are ignored. If no user is specified, the changes to all modified
users are committed to permanent storage.
- SEC_DELETE
- The corresponding attribute is deleted from the database.
- SEC_NEW
- Updates all the user database files with the new user name when
using the putuserattr subroutine.
-
- UID
- Specifies the user ID to be translated into a user name.
- User
- Specifies the name of the user for which an attribute is to
be read.
- Value
- Specifies a buffer, a pointer to a buffer, or a pointer to a
pointer depending on the Attribute and Type parameters.
See the Type parameter for more details.
Security
| Item |
Description |
|---|
| Files Accessed: |
|
| Mode |
File |
|---|
| rw |
/etc/passwd |
| rw |
/etc/group |
| rw |
/etc/security/user |
| rw |
/etc/security/limits |
| rw |
/etc/security/group |
| rw |
/etc/security/environ |
Return Values
If successful, the getuserattr subroutine
and the putuserattr subroutine return 0. Otherwise, a value
of -1 is returned and the errno global variable is set to indicate
the error.
If successful, the IDtouser and
the nextuser subroutines return a character pointer to a buffer
containing the requested user name. Otherwise, a null pointer is returned
and the errno global variable is set to indicate the error.
Error Codes
If any of these subroutines fail, the following
is returned:
| Item |
Description |
|---|
| EACCES |
Access permission is denied for the data request. |
If the
getuserattr subroutine or the
getuserattrs subroutine
fail, the following is returned:
| Item |
Description |
|---|
| EIO |
Failed to access remote user database. |
If the getuserattr and putuserattr subroutines
fail, one or more of the following is returned:
| Item |
Description |
|---|
| ENOENT |
The specified User parameter does not exist. |
| EINVAL |
The Attribute parameter does not contain one of the
defined attributes or null. |
| EINVAL |
The Value parameter does not point to a valid buffer
or to valid data for this type of attribute. Limited testing is possible
and all errors may not be detected. |
| EPERM |
Operation is not permitted. |
| ENOATTR |
The specified attribute is not defined for this user. |
If the IDtouser subroutine
fails, one or more of the following is returned:
| Item |
Description |
|---|
| ENOENT |
The specified User parameter does not exist |
If the nextuser subroutine
fails, one or more of the following is returned:
| Item |
Description |
|---|
| EINVAL |
The Mode parameter is not one of null, S_LOCAL,
or S_SYSTEM. |
| EINVAL |
The Argument parameter is not null. |
| ENOENT |
The end of the search was reached. |
Files
| Item |
Description |
|---|
| /etc/passwd |
Contains user IDs. |