NAME

File::HomeDir -- get home directory for self or other users

SYNOPSIS

use File::HomeDir;
print "My dir is ", home(), " and root's is ", home('root'), "\n";
print "My dir is $~{''} and root's is $~{root}\n";
 # These both print the same thing, something like:
 #  "My dir is /home/user/mojo and root's is /"

DESCRIPTION

This module provides a function, home, and also ties the in-all-packages variable %~.

home()

Returns a filespec to this user's home directory.

home($user)

Returns a filespec to the home directory of the given user, or undef if no such user.

Note that the argument to this must be a defined value, and mustn't be a zero-length string, or a fatal error will result.

$~{$user}

$~{username}

"...$~{$user}..."

"...$~{username}..."

This calls home($user) or home('username') -- except that if you ask for $~{some_user} and there is no such user, a fatal error results!

Note that this is especially useful in doublequotish strings, like:

print "Jojo's .newsrc is ", -s "$~{jojo}/.newsrc", "b long!\n";
 # (helpfully dies if there is no user 'jojo')

If you want to avoid the fatal errors, first test the value of home('jojo'), which will return undef (instead of dying) in case of there being no such user.

Note, however, that if the hash key is "" or undef (whether thru being a literal "", or a scalar whose value is empty-string or undef), then this returns zero-argument home(), i.e., your home directory:

$~{""}

$~{undef}

"...$~{''}..."

These all return home(), i.e., your home directory.

If running under an OS that doesn't implement getpwid, this library tries to provide a sane return value for the no-argument home(). Under MacOS, for example, it tries returning the pathspec to the desktop folder. See source for full details.

Under OSs that don't implement getpwnam (as home($user) calls), you will always get a failed lookup, just as if you'd tried to look up the home dir for a nonexistent user on an OS that does support getpwnam.

BUGS AND CAVEATS

* One-argument home($username) is memoized. Read the source if you need it unmemoized.

* According to the fileio.c in one version of Emacs, MSWindows (NT?) does have the concept of users having home directories, more or less. But I don't know if MSWin ports of Perl allow accessing that with getpwnam. I hear that it (currently) doesn't.

* This documentation gets garbled by some AIX manual formatters. Consider perldoc -t File::HomeDir instead.

COPYRIGHT

Copyright (c) 2000 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Sean M. Burke sburke@cpan.org