1File::HomeDir(3)      User Contributed Perl Documentation     File::HomeDir(3)
2
3
4

NAME

6       File::HomeDir - Find your home and other directories, on any platform
7

SYNOPSIS

9         use File::HomeDir;
10
11         # Modern Interface (Current User)
12         $home    = File::HomeDir->my_home;
13         $desktop = File::HomeDir->my_desktop;
14         $docs    = File::HomeDir->my_documents;
15         $music   = File::HomeDir->my_music;
16         $pics    = File::HomeDir->my_pictures;
17         $videos  = File::HomeDir->my_videos;
18         $data    = File::HomeDir->my_data;
19
20         # Modern Interface (Other Users)
21         $home    = File::HomeDir->users_home('foo');
22         $desktop = File::HomeDir->users_desktop('foo');
23         $docs    = File::HomeDir->users_documents('foo');
24         $music   = File::HomeDir->users_music('foo');
25         $pics    = File::HomeDir->users_pictures('foo');
26         $video   = File::HomeDir->users_videos('foo');
27         $data    = File::HomeDir->users_data('foo');
28
29         # Legacy Interfaces
30         print "My dir is ", home(), " and root's is ", home('root'), "\n";
31         print "My dir is $~{''} and root's is $~{root}\n";
32         # These both print the same thing, something like:
33         #  "My dir is /home/user/mojo and root's is /"
34

DESCRIPTION

36       File::HomeDir is a module for dealing with issues relating to the
37       location of directories that are "owned" by a user, primarily your
38       user, and to solve these issues consistently across a wide variety of
39       platforms.
40
41       Thus, a single API is presented that can find your resources on any
42       platform.
43
44       This module provides two main interfaces.
45
46       The first is a modern File::Spec-style interface with a consistent OO
47       API and different implementation modules to support various platforms.
48       You are strongly recommended to use this interface.
49
50       The second interface is for legacy support of the original 0.07
51       interface that exported a "home()" function by default and tied the
52       "%~" variable.
53
54       It is generally not recommended that you use this interface, but due to
55       back-compatibility reasons they will remain supported until at least
56       2010.
57
58       After this date, the home() function will remain, but we will consider
59       deprecating the (namespace-polluting) "%~" tied hash, to be removed by
60       2015 (maintaining the general Perl convention of a 10 year support
61       period for legacy APIs potentially or actually in common use).
62
63   Platform Neutrality
64       In the Unix world, many different types of data can be mixed together
65       in your home directory (although on some Unix platforms this is no
66       longer the case, particularly for "desktop"-oriented platforms).
67
68       On some non-Unix platforms, seperate directories are allocated for
69       different types of data and have been for a long time.
70
71       When writing applications on top of File::HomeDir, you should thus
72       always try to use the most specific method you can. User documents
73       should be saved in "my_documents", data that supports an application
74       but isn't normally editing by the user directory should go into
75       "my_data".
76
77       On platforms that do not make any distinction, all these different
78       methods will harmlessly degrade to the main home directory, but on
79       platforms that care File::HomeDir will always try to Do The Right
80       Thing(tm).
81

METHODS

83       Two types of methods are provided. The "my_method" series of methods
84       for finding resources for the current user, and the "users_method"
85       (read as "user's method") series for finding resources for arbitrary
86       users.
87
88       This split is necesary, as on most platforms it is much easier to find
89       information about the current user compared to other users, and indeed
90       on a number you cannot find out information such as "users_desktop" at
91       all, due to security restrictions.
92
93       All methods will double check (using a "-d" test) that a directory
94       actually exists before returning it, so you may trust in the values
95       that are returned (subject to the usual caveats of race conditions of
96       directories being deleted at the moment between a directory being
97       returned and you using it).
98
99       However, because in some cases platforms may not support the concept of
100       home directories at all, any method may return "undef" (both in scalar
101       and list context) to indicate that there is no matching directory on
102       the system.
103
104       For example, most untrusted 'nobody'-type users do not have a home
105       directory. So any modules that are used in a CGI application that at
106       some level of recursion use your code, will result in calls to
107       File::HomeDir returning undef, even for a basic home() call.
108
109   my_home
110       The "my_home" method takes no arguments and returns the main
111       home/profile directory for the current user.
112
113       If the distinction is important to you, the term "current" refers to
114       the real user, and not the effective user.
115
116       This is also the case for all of the other "my" methods.
117
118       Returns the directory path as a string, "undef" if the current user
119       does not have a home directory, or dies on error.
120
121   my_desktop
122       The "my_desktop" method takes no arguments and returns the "desktop"
123       directory for the current user.
124
125       Due to the diversity and complexity of implementions required to deal
126       with implementing the required functionality fully and completely, for
127       the moment "my_desktop" is not going to be implemented.
128
129       That said, I am extremely interested in code to implement "my_desktop"
130       on Unix, as long as it is capable of dealing (as the Windows
131       implementation does) with internationalisation. It should also avoid
132       false positive results by making sure it only returns the appropriate
133       directories for the appropriate platforms.
134
135       Returns the directory path as a string, "undef" if the current user
136       does not have a desktop directory, or dies on error.
137
138   my_documents
139       The "my_documents" method takes no arguments and returns the directory
140       (for the current user) where the user's documents are stored.
141
142       Returns the directory path as a string, "undef" if the current user
143       does not have a documents directory, or dies on error.
144
145   my_music
146       The "my_music" method takes no arguments and returns the directory
147       where the current user's music is stored.
148
149       No bias is made to any particular music type or music program, rather
150       the concept of a directory to hold the user's music is made at the
151       level of the underlying operating system or (at least) desktop
152       environment.
153
154       Returns the directory path as a string, "undef" if the current user
155       does not have a suitable directory, or dies on error.
156
157   my_pictures
158       The "my_pictures" method takes no arguments and returns the directory
159       where the current user's pictures are stored.
160
161       No bias is made to any particular picture type or picture program,
162       rather the concept of a directory to hold the user's pictures is made
163       at the level of the underlying operating system or (at least) desktop
164       environment.
165
166       Returns the directory path as a string, "undef" if the current user
167       does not have a suitable directory, or dies on error.
168
169   my_videos
170       The "my_videos" method takes no arguments and returns the directory
171       where the current user's videos are stored.
172
173       No bias is made to any particular video type or video program, rather
174       the concept of a directory to hold the user's videos is made at the
175       level of the underlying operating system or (at least) desktop
176       environment.
177
178       Returns the directory path as a string, "undef" if the current user
179       does not have a suitable directory, or dies on error.
180
181   my_data
182       The "my_data" method takes no arguments and returns the directory where
183       local applications should stored their internal data for the current
184       user.
185
186       Generally an application would create a subdirectory such as ".foo",
187       beneath this directory, and store its data there. By creating your
188       directory this way, you get an accurate result on the maximum number of
189       platforms.
190
191       For example, on Unix you get "~/.foo" and on Win32 you get "~/Local
192       Settings/Application Data/.foo"
193
194       Returns the directory path as a string, "undef" if the current user
195       does not have a data directory, or dies on error.
196
197   users_home
198         $home = File::HomeDir->users_home('foo');
199
200       The "users_home" method takes a single param and is used to locate the
201       parent home/profile directory for an identified user on the system.
202
203       While most of the time this identifier would be some form of user name,
204       it is permitted to vary per-platform to support user ids or UUIDs as
205       applicable for that platform.
206
207       Returns the directory path as a string, "undef" if that user does not
208       have a home directory, or dies on error.
209
210   users_documents
211         $docs = File::HomeDir->users_documents('foo');
212
213       Returns the directory path as a string, "undef" if that user does not
214       have a documents directory, or dies on error.
215
216   users_data
217         $data = File::HomeDir->users_data('foo');
218
219       Returns the directory path as a string, "undef" if that user does not
220       have a data directory, or dies on error.
221

FUNCTIONS

223   home
224         use File::HomeDir;
225         $home = home();
226         $home = home('foo');
227         $home = File::HomeDir::home();
228         $home = File::HomeDir::home('foo');
229
230       The "home" function is exported by default and is provided for
231       compatibility with legacy applications. In new applications, you should
232       use the newer method-based interface above.
233
234       Returns the directory path to a named user's home/profile directory.
235
236       If provided no param, returns the directory path to the current user's
237       home/profile directory.
238

TIED INTERFACE

240   %~
241         $home = $~{""};
242         $home = $~{undef};
243         $home = $~{$user};
244         $home = $~{username};
245         print "... $~{''} ...";
246         print "... $~{$user} ...";
247         print "... $~{username} ...";
248
249       This calls "home($user)" or "home('username')" -- except that if you
250       ask for $~{some_user} and there is no such user, it will die.
251
252       Note that this is especially useful in double-quotish strings, like:
253
254            print "Jojo's .newsrc is ", -s "$~{jojo}/.newsrc", "b long!\n";
255             # (helpfully dies if there is no user 'jojo')
256
257       If you want to avoid the fatal errors, first test the value of
258       "home('jojo')", which will return undef (instead of dying) in case of
259       there being no such user.
260
261       Note, however, that if the hash key is "" or undef (whether thru being
262       a literal "", or a scalar whose value is empty-string or undef), then
263       this returns zero-argument "home()", i.e., your home directory:
264
265       Further, please note that because the "%~" hash compulsorily modifies a
266       hash outside of it's namespace, and presents an overly simplistic
267       approach to home directories, it is likely to ultimately be removed.
268
269       The interface is currently expected to be formally deprecated from 2010
270       (but no earlier) and removed from 2015 (but no earlier). If very heavy
271       use is found in the wild, these plans may be pushed back.
272

TO DO

274       ·   Become generally clearer on situations in which a user might not
275           have a particular resource.
276
277       ·   Add more granularity to Unix, and add support to VMS and other
278           esoteric platforms, so we can consider going core.
279
280       ·   Add consistent support for users_* methods
281

SUPPORT

283       This module is stored in an Open Repository at the following address.
284
285       http://svn.ali.as/cpan/trunk/File-HomeDir
286       <http://svn.ali.as/cpan/trunk/File-HomeDir>
287
288       Write access to the repository is made available automatically to any
289       published CPAN author, and to most other volunteers on request.
290
291       If you are able to submit your bug report in the form of new (failing)
292       unit tests, or can apply your fix directly instead of submitting a
293       patch, you are strongly encouraged to do so as the author currently
294       maintains over 100 modules and it can take some time to deal with non-
295       Critical bug reports or patches.
296
297       This will guarantee that your issue will be addressed in the next
298       release of the module.
299
300       If you cannot provide a direct test or fix, or don't have time to do
301       so, then regular bug reports are still accepted and appreciated via the
302       CPAN bug tracker.
303
304       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir
305       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir>
306
307       For other issues, for commercial enhancement or support, or to have
308       your write access enabled for the repository, contact the author at the
309       email address above.
310

ACKNOWLEDGEMENTS

312       The biggest acknowledgement must go to Chris Nandor, who wielded his
313       legendary Mac-fu and turned my initial fairly ordinary Darwin
314       implementation into something that actually worked properly everywhere,
315       and then donated a Mac OS X license to allow it to be maintained
316       properly.
317

AUTHORS

319       Adam Kennedy <adamk@cpan.org>
320
321       Sean M. Burke <sburke@cpan.org>
322
323       Chris Nandor <cnandor@cpan.org>
324
325       Stephen Steneker <stennie@cpan.org>
326

SEE ALSO

328       File::ShareDir, File::HomeDir::Win32 (legacy)
329
331       Copyright 2005 - 2009 Adam Kennedy.
332
333       Some parts copyright 2000 Sean M. Burke.
334
335       Some parts copyright 2006 Chris Nandor.
336
337       Some parts copyright 2006 Stephen Steneker.
338
339       This program is free software; you can redistribute it and/or modify it
340       under the same terms as Perl itself.
341
342       The full text of the license can be found in the LICENSE file included
343       with this module.
344
345
346
347perl v5.12.0                      2009-03-27                  File::HomeDir(3)
Impressum