# perldoc > User::pwent

---
type: CommandReference
command: User::pwent
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `use User::pwent; $pw = getpwnam('daemon')` — get passwd entry as object
- `$pw->uid`, `$pw->dir`, `$pw->shell` — access fields
- `use User::pwent qw(:FIELDS); $pw_uid, $pw_dir` — import fields as variables
- `$pw = getpw($whoever)` — auto-dispatch to `getpwuid`/`getpwnam`
- `pw_has("gecos expire quota")` — check if fields are supported

## Name

by-name interface to Perl's built-in `getpw*()` functions

## Synopsis

perl
use User::pwent;
$pw = getpwnam('daemon')       || die "No daemon user";
if ( $pw->uid == 1 && $pw->dir =~ m#^/(bin|tmp)?\z#s ) {
    print "gid 1 on root dir";
}
$real_shell = $pw->shell || '/bin/sh';
perl
use User::pwent qw(:FIELDS);
getpwnam('daemon')             || die "No daemon user";
if ( $pw_uid == 1 && $pw_dir =~ m#^/(bin|tmp)?\z#s ) {
    print "gid 1 on root dir";
}
perl
$pw = getpw($whoever);
perl
use User::pwent qw/:DEFAULT pw_has/;
if (pw_has(qw[gecos expire quota])) { .... }
if (pw_has("name uid gid passwd"))  { .... }
print "Your struct pwd has: ", scalar pw_has(), "\n";
## Description

This module's default exports override the core `getpwent()`, `getpwuid()`, and `getpwnam()` functions, replacing them with versions that return `User::pwent` objects. The object has methods corresponding to the fields of the C `passwd` structure, stripped of the leading `pw_`:

- `name`, `passwd`, `uid`, `gid`, `change`, `age`, `quota`, `comment`, `class`, `gecos`, `dir`, `shell`, `expire`

The `passwd`, `gecos`, and `shell` fields are tainted when running in taint mode.

You may import all structure fields directly into your namespace as regular variables using the `:FIELDS` import tag. Access them as variables named with a preceding `pw_` (e.g., `$pw_shell` corresponds to `$pw->shell`).

The `getpw()` function is a simple front-end that forwards a numeric argument to `getpwuid()` and the rest to `getpwnam()`.

To access this functionality without the core overrides, use an empty import list and call functions with their fully qualified names. The built-ins are always available via `CORE::`.

### System Specifics

Perl assumes no machine has more than one of `change`, `age`, or `quota`, nor more than one of `comment` or `class`. Some machines do not support `expire`, `gecos`, or `passwd`. Calling these methods returns `undef` if unimplemented.

The importable `pw_has()` function checks whether fields are supported on the build platform. It returns true if all parameters are supported, false if one or more are not, and raises an exception for unknown fields. Parameters may be a space-separated string or separate arguments. With no parameters, it returns the list of supported fields (list context) or a space-separated string (scalar context).

The `gecos` field traditionally holds 4 comma-separated fields: full name, office, work phone, home phone. An `&` should be replaced by the user's properly capitalized login name. The `shell` field, if blank, is assumed to be `/bin/sh` (Perl does not do this automatically). The `passwd` is one-way hashed. On systems with shadow passwords, Perl returns the shadow entry when called by a suitably empowered user.

See [passwd(5)](https://www.chedong.com/phpMan.php/man/passwd/5/markdown) and [getpwent(3)](https://www.chedong.com/phpMan.php/man/getpwent/3/markdown) for details.

## Examples

Parsing the `gecos` field:

perl
for (($fullname, $office, $workphone, $homephone) =
        split /\s*,\s*/, $pw->gecos)
{
    s/&/ucfirst(lc($pw->name))/ge;
}
## See Also

- [passwd(5)](https://www.chedong.com/phpMan.php/man/passwd/5/markdown) — password file format
- [getpwent(3)](https://www.chedong.com/phpMan.php/man/getpwent/3/markdown) — get password file entry
- [perlfunc](https://perldoc.perl.org/perlfunc) — Perl built-in functions