NAME File::HomeDir - Get the home directory for yourself or other users SYNOPSIS use File::HomeDir; # Modern Interface (Current User) $home = File::HomeDir->my_home; $docs = File::HomeDir->my_documents; $data = File::HomeDir->my_data; # Modern Interface (Other Users) $home = File::HomeDir->users_home('foo'); $docs = File::HomeDir->users_documents('foo'); $data = File::HomeDir->users_data('foo'); # Legacy Interfaces 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 File::HomeDir is a module for dealing with issues relating to the location of directories for various purposes that are "owned" by a user, and to solve these problems consistently across a wide variety of platforms. This module provides two main interfaces. A modern File::Spec-style interface with a consistent OO API and different implementation modules to support various platforms, and a legacy interface from version 0.07 that exported a home() function by default and tied the %~ variable. Platform Neutrality In the Unix world, many different types of data can be mixed together in your home directory. On some other platforms, seperate directories are allocated for different types of data. When writing applications, you should try to use the most specific method you can. User documents should be saved in "my_documents", data to support an application should go in "my_data". On platforms that do not make this distinction, all these methods will harmlessly degrade to the main home directory, but on platforms that care "File::HomeDir" will Do The Right Thing(tm). METHODS Two types of methods are provided. The "my_method" series of methods for finding resources for the current user, and the "users_method" (read as "user's method") series for finding resources for arbitrary users. This split is necesary, as on many platforms it is MUCH easier to find information about the current user compared to other users. All methods via a "-d" test that the directory actually exists before returning. my_home The "my_home" takes no arguments and returns the main home/profile directory for the current user. Returns the directory path as a string, or dies if it cannot be found. my_documents The "my_documents" takes no arguments and returns the directory for the current user where the user's documents are stored. Returns the directory path as a string, or dies if it cannot be found. my_data The "my_data" takes no arguments and returns the directory where local applications should stored their internal data for the current user. Generally an application would create a subdirectory such as ".foo", beneath this directory, and store its data there. By creating your directory this way, you get an accurate result on the maximum number of platforms. For example, on Unix you get "~/.foo" and on Win32 you get "~/Local Settings/Application Data/.foo" Returns the directory path as a string, or dies if it cannot be found. users_home $home = File::HomeDir->users_home('foo'); The "users_home" method takes a single param and is used to locate the parent home/profile directory for an identified user on the system. While most of the time this identifier would be some form of user name, it is permitted to vary per-platform to support user ids or UUIDs as applicable for that platform. Returns the directory path as a string, or dies if it cannot be found. users_documents $docs = File::HomeDir->users_documents('foo'); Returns the directory path as a string, or dies if it cannot be found. users_data Returns the directory path as a string, or dies if it cannot be found. FUNCTIONS home use File::HomeDir; $home = home(); $home = home('foo'); $home = File::HomeDir::home(); $home = File::HomeDir::home('foo'); The "home" function is exported by default and is provided for compatibility with legacy applications. In new applications, you should use the newer method-based interface above. Returns the directory path to a named user's home/profile directory. If provided no param, returns the directory path to the current user's home/profile directory. TIED INTERFACE %~ $home = $~{""}; $home = $~{undef}; $home = $~{$user}; $home = $~{username}; print "... $~{''} ..."; print "... $~{$user} ..."; print "... $~{username} ..."; This calls "home($user)" or "home('username')" -- except that if you ask for $~{some_user} and there is no such user, it will die. Note that this is especially useful in double-quotish 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: TO DO - Become generally clearer on situations in which a user might not have a particular resource. - Add support for the root Mac user (requested by JKEENAN). - Add support for my_desktop (requested by RRWO) - Add support for my_music (requested by MIYAGAWA) - Merge remaining edge case code in File::HomeDir::Win32 - Add more granularity to Unix, and add support to VMS and other esoteric platforms, so we can consider going core. Anyone wishing to add support for the above are welcome to get an account to my SVN and add it directly. SUPPORT Bugs should be always be reported via the CPAN bug tracker at For other issues, or commercial enhancement or support, contact the author. AUTHORS Adam Kennedy Original implementation by: Sean M. Burke "sburke@cpan.org" SEE ALSO File::ShareDir, File::HomeDir::Win32 (legacy) COPYRIGHT Copyright 2005-2006 Adam Kennedy. All rights reserved. Some parts copyright 2000 Sean M. Burke. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module.