This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod typo fixes (from Marcel Grunauer <marcel.grunauer@lovely.net>)
[perl5.git] / lib / User / pwent.pm
CommitLineData
36477c24
PP
1package User::pwent;
2use strict;
3
17f410f9
GS
4use 5.005_64;
5our(@EXPORT, @EXPORT_OK, %EXPORT_TAGS);
36477c24
PP
6BEGIN {
7 use Exporter ();
36477c24
PP
8 @EXPORT = qw(getpwent getpwuid getpwnam getpw);
9 @EXPORT_OK = qw(
10 $pw_name $pw_passwd $pw_uid
11 $pw_gid $pw_quota $pw_comment
12 $pw_gecos $pw_dir $pw_shell
13 );
14 %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
15}
16use vars @EXPORT_OK;
17
8cc95fdb
PP
18# Class::Struct forbids use of @ISA
19sub import { goto &Exporter::import }
20
21use Class::Struct qw(struct);
36477c24
PP
22struct 'User::pwent' => [
23 name => '$',
24 passwd => '$',
25 uid => '$',
26 gid => '$',
27 quota => '$',
28 comment => '$',
cf04b53c 29 gecos => '$',
36477c24
PP
30 dir => '$',
31 shell => '$',
32];
33
34sub populate (@) {
35 return unless @_;
36 my $pwob = new();
37
38 ( $pw_name, $pw_passwd, $pw_uid,
39 $pw_gid, $pw_quota, $pw_comment,
40 $pw_gecos, $pw_dir, $pw_shell, ) = @$pwob = @_;
41
42 return $pwob;
43}
44
45sub getpwent ( ) { populate(CORE::getpwent()) }
46sub getpwnam ($) { populate(CORE::getpwnam(shift)) }
b4730b2b
TC
47sub getpwuid ($) { populate(CORE::getpwuid(shift)) }
48sub getpw ($) { ($_[0] =~ /^\d+/) ? &getpwuid : &getpwnam }
36477c24
PP
49
501;
51__END__
52
53=head1 NAME
54
2ae324a7 55User::pwent - by-name interface to Perl's built-in getpw*() functions
36477c24
PP
56
57=head1 SYNOPSIS
58
59 use User::pwent;
60 $pw = getpwnam('daemon') or die "No daemon user";
61 if ( $pw->uid == 1 && $pw->dir =~ m#^/(bin|tmp)?$# ) {
62 print "gid 1 on root dir";
63 }
64
65 use User::pwent qw(:FIELDS);
66 getpwnam('daemon') or die "No daemon user";
67 if ( $pw_uid == 1 && $pw_dir =~ m#^/(bin|tmp)?$# ) {
68 print "gid 1 on root dir";
69 }
70
71 $pw = getpw($whoever);
72
73=head1 DESCRIPTION
74
75This module's default exports override the core getpwent(), getpwuid(),
76and getpwnam() functions, replacing them with versions that return
77"User::pwent" objects. This object has methods that return the similarly
78named structure field name from the C's passwd structure from F<pwd.h>;
79namely name, passwd, uid, gid, quota, comment, gecos, dir, and shell.
80
81You may also import all the structure fields directly into your namespace
82as regular variables using the :FIELDS import tag. (Note that this still
83overrides your core functions.) Access these fields as
84variables named with a preceding C<pw_> in front their method names.
85Thus, C<$passwd_obj-E<gt>shell()> corresponds to $pw_shell if you import
86the fields.
87
ae83f377 88The getpw() function is a simple front-end that forwards
36477c24
PP
89a numeric argument to getpwuid() and the rest to getpwnam().
90
91To access this functionality without the core overrides,
92pass the C<use> an empty import list, and then access
93function functions with their full qualified names.
94On the other hand, the built-ins are still available
95via the C<CORE::> pseudo-package.
96
97=head1 NOTE
98
8cc95fdb 99While this class is currently implemented using the Class::Struct
36477c24
PP
100module to build a struct-like class, you shouldn't rely upon this.
101
102=head1 AUTHOR
103
104Tom Christiansen