loginrestrictions Subroutine

Purpose

Determines if a user is allowed to access the system.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>
#include <login.h>
int loginrestrictions (Name, Mode, Tty, Msg)
char * Name;
int  Mode;
char * Tty;
char ** Msg;
Note: This subroutine is not thread-safe.

Description

The loginrestrictions subroutine determines if the user specified by the Name parameter is allowed to access the system. The Mode parameter gives the mode of account usage and the Tty parameter defines the terminal used for access. The Msg parameter returns an informational message explaining why the loginrestrictions subroutine failed.

This subroutine is unsuccessful if any of the following conditions exists:

Note: The loginrestrictions subroutine is not safe in a multi-threaded environment. To use loginrestrictions in a threaded application, the application must keep the integrity of each thread.

Parameters

Item Description
Name Specifies the user's login name whose account is to be validated.
Mode Specifies the mode of usage. Valid values as defined in the login.h file are listed below. The Mode parameter has a value of 0 or one of the following values:
S_LOGIN
Verifies that local logins are permitted for this account.
S_SU
Verifies that the su command is permitted and the current process has a group ID that can invoke the su command to switch to the account.
S_DAEMON
Verifies the account can invoke daemon or batch programs through the src or cron subsystems.
S_RLOGIN
Verifies the account can be used for remote logins through the rlogind or telnetd programs.
Tty Specifies the terminal of the originating activity. If this parameter is a null pointer or a null string, no tty origin checking is done.
Msg Returns an informative message indicating why the loginrestrictions subroutine failed. Upon return, the value is either a pointer to a valid string within memory allocated storage or a null value. If a message is displayed, it is provided based on the user interface.

Security

Access Control:The calling process must have access to the account information in the user database and the port information in the port database.

File Accessed:

Mode Files
r /etc/security/user
r /etc/security/login.cfg
r /etc/security/portlog
r /etc/passwd

Return Values

If the account is valid for the specified usage, the loginrestrictions subroutine returns a value of 0. Otherwise, a value of -1 is returned, the errno global value is set to the appropriate error code, and the Msg parameter returns an informative message explaining why the specified account usage is invalid.

Error Codes

The loginrestrictions subroutine fails if one or more of the following values is true:

Item Description
ENOENT The user specified does not have an account.
ESTALE The user's account is expired.
EPERM The user's account is locked, the specified terminal is locked, the user has had too many unsuccessful login attempts, or the user cannot log in because the /etc/nologin file exists.
EACCES One of the following conditions exists:
  • The specified terminal does not have access to the specified account.
  • The Mode parameter is the S_SU value and the current process is not permitted to use the su command to access the specified user.
  • Access to the account is not permitted in the specified mode.
  • Access to the account is not permitted at the current time.
  • Access to the system with the specified terminal is not permitted at the current time.
EAGAIN The Mode parameter is either the S_LOGIN value or the S_RLOGIN value, and all the user licenses are in use.
EINVAL The Mode parameter has a value other than S_LOGIN, S_SU, S_DAEMON, S_RLOGIN, or 0.