getuserattr, IDtouser, nextuser, or putuserattr Subroutine

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.

If the domainlessgroups attribute is set in the /etc/secvars.cfg file, the Lightweight Directory Access Protocol (LDAP) group ID can be assigned to LOCAL user as primary group ID and vice versa.

The attribute type is SEC_INT.

S_PGRP

Principle group name.

If the domainlessgroups attribute is set in the /etc/secvars.cfg file, the LDAP group can be assigned to LOCAL user as primary group and vice versa.

The attribute type is SEC_CHAR.

S_GROUPS

Groups to which the user belongs.

If the domainlessgroups attribute is set in the /etc/secvars.cfg file, the LDAP group can be assigned to LOCAL user and vice versa.

The attribute type is SEC_LIST.

S_ADMGROUPS

Groups for which the user is an administrator.

If the domainlessgroups attribute is set in the /etc/secvars.cfg file, the LDAP group can be assigned to LOCAL user and vice versa.

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.

If the domainlessgroups attribute is set in the /etc/secvars.cfg file, the LDAP group can be assigned to LOCAL user and vice versa.

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.