setpwdb or endpwdb Subroutine

Purpose

Opens or closes the authentication database.

Library

Security Library (libc.a)

Syntax

#include <userpw.h>

int setpwdb ( Mode)
int Mode;

int endpwdb ( )

Description

These functions are used to open and close access to the authentication database. Programs that call either the getuserpw or putuserpw subroutine should call the setpwdb subroutine to open the database and the endpwdb subroutine to close the database.

The setpwdb subroutine opens the authentication database in the specified mode, if it is not already open. The open count is increased by 1.

The endpwdb subroutine decreases the open count by one and closes the authentication database when this count drops to 0. Subsequent references to individual data items can cause a memory access violation. The endpwdb subroutine also frees the space that was allocated by either the getuserpw, putuserpw, or putuserpwhist subroutine. For security reasons, freeing the space clears the password field. Any uncommitted changed data is lost.

Parameters

Item Description
Mode Specifies the mode of the open. This parameter may contain one or more of the following values, defined in the usersec.h file:
S_READ
Specifies read access.
S_WRITE
Specifies update access.

Return Values

The setpwdb and endpwdb subroutines return a value of 0 to indicate success. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The setpwdb and endpwdb subroutines fail if the following is true:

Item Description
EACCES Access permission is denied for the data request.

Both of these functions return errors from other subroutines.

Security

Access Control: The calling process must have access to the authentication data.

Files Accessed:

Modes File
rw /etc/security/passwd
rw /etc/passwd