#!/usr/bin/perl -wT
# IBM_PROLOG_BEGIN_TAG 
# This is an automatically generated prolog. 
#  
# bos720 src/perl/libext/Passwd/Passwd.pm 1.2 
#  
# Licensed Materials - Property of IBM 
#  
# COPYRIGHT International Business Machines Corp. 2005 
# All Rights Reserved 
#  
# US Government Users Restricted Rights - Use, duplication or 
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 
#  
# IBM_PROLOG_END_TAG 

# @(#)09     1.2  src/perl/libext/Passwd/Passwd.pm, perl_libaix, bos720 8/8/05 14:43:00

package LibExt::Passwd;

use strict;
use warnings;

require Exporter;
our @ISA = qw/Exporter/;

my @funcs = qw/getpass setpass/;

our @EXPORT      = ( @funcs );
our @EXPORT_OK   = ( @funcs );
our %EXPORT_TAGS = ( func => \@funcs,
                     all  => \@EXPORT_OK );

our $VERSION = '1.0';

require XSLoader;
XSLoader::load('LibExt::Passwd', $VERSION);

1;
__END__

=head1 NAME

LibExt::Passwd - Utility routines for password manipulation

=head1 SYNOPSIS

    use LibExt::Passwd;
    use LibExt::Passwd qw/getpass setpass/;
    use LibExt::Passwd qw/ :func         /;
    use LibExt::Passwd qw/ :all          /;

    print("Enter a user name: ");
    $userName = <STDIN>;
    chomp($userName);

    $passwd = LibExt::Passwd::getpass("Enter a password for $userName: ");

    print("Setting password for $userName: ");
    $rc = LibExt::Passwd::setpass($userName, $passwd);
    if ($rc) {
        print("Success\n");
    } else {
        print("Failure: $!\n");
    }

=head1 DESCRIPTION

A collection of useful routines for password manipulation. Currently has
functionality for obtaining and setting user passwords.

=head1 FUNCTIONS

=over 4

=item STRING getpass(PROMPT)

Reads a password from the process' controlling terminal, without echo. This
routine writes the prompt, if any, to the process's controlling terminal,
disables echoing, reads the password and restores the terminal state.

Returns the password on success. On failure, returns undef and sets $!. This
routine reads at the most PASS_MAX bytes from the terminal.

Also see:

The C <getpass()> subroutine.

The C <stdlib.h> header file.

The C <sys/limits.h> header file.

=item BOOL setpass(USERNAME, PASSWORD)

Sets a user's password. This routine must be invoked with root privileges.
To delete the user's password pass an empty string or an undef for PASSWORD.

Returns true on success. On failure, returns false and sets $!.

Also see:

The C <chpass()> subroutine.

The C <usersec.h> header file.

=back

=cut