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"