Debian Codegraph @

upstream/debian-unstable/man3/FindBin.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "FindBin 3perl"
58 .TH FindBin 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 FindBin \- Locate directory of original Perl script
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& use FindBin;
69 \& use lib "$FindBin::Bin/../lib";
70 \&
71 \& use FindBin qw($Bin);
72 \& use lib "$Bin/../lib";
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 Locates the full path to the script bin directory to allow the use
77 of paths relative to the bin directory.
78 .PP
79 This allows a user to setup a directory tree for some software with
80 directories \f(CW\*(C`<root>/bin\*(C'\fR and \f(CW\*(C`<root>/lib\*(C'\fR, and then the above
81 example will allow the use of modules in the lib directory without knowing
82 where the software tree is installed.
83 .PP
84 If \f(CW\*(C`perl\*(C'\fR is invoked using the \f(CW\*(C`\-e\*(C'\fR option or the Perl script is read from
85 \&\f(CW\*(C`STDIN\*(C'\fR, then \f(CW\*(C`FindBin\*(C'\fR sets both \f(CW$Bin\fR and \f(CW$RealBin\fR to the current
86 directory.
87 .SH "EXPORTABLE VARIABLES"
88 .IX Header "EXPORTABLE VARIABLES"
89 .ie n .IP "$Bin or $Dir" 4
90 .el .IP "\f(CW$Bin\fR or \f(CW$Dir\fR" 4
91 .IX Item "$Bin or $Dir"
92 Path to the bin \fBdirectory\fR from where script was invoked
93 .ie n .IP $Script 4
94 .el .IP \f(CW$Script\fR 4
95 .IX Item "$Script"
96 \&\fBBasename\fR of the script from which \f(CW\*(C`perl\*(C'\fR was invoked
97 .ie n .IP "$RealBin or $RealDir" 4
98 .el .IP "\f(CW$RealBin\fR or \f(CW$RealDir\fR" 4
99 .IX Item "$RealBin or $RealDir"
100 \&\f(CW$Bin\fR with all links resolved
101 .ie n .IP $RealScript 4
102 .el .IP \f(CW$RealScript\fR 4
103 .IX Item "$RealScript"
104 \&\f(CW$Script\fR with all links resolved
105 .PP
106 You can also use the \f(CW\*(C`ALL\*(C'\fR tag to export all of the above variables together:
107 .PP
108 .Vb 1
109 \& use FindBin \*(Aq:ALL\*(Aq;
110 .Ve
111 .SH "KNOWN ISSUES"
112 .IX Header "KNOWN ISSUES"
113 If there are two modules using \f(CW\*(C`FindBin\*(C'\fR from different directories
114 under the same interpreter, this won't work. Since \f(CW\*(C`FindBin\*(C'\fR uses a
115 \&\f(CW\*(C`BEGIN\*(C'\fR block, it'll be executed only once, and only the first caller
116 will get it right. This is a problem under \f(CW\*(C`mod_perl\*(C'\fR and other persistent
117 Perl environments, where you shouldn't use this module. Which also means
118 that you should avoid using \f(CW\*(C`FindBin\*(C'\fR in modules that you plan to put
119 on CPAN. Call the \f(CW\*(C`again\*(C'\fR function to make sure that \f(CW\*(C`FindBin\*(C'\fR will work:
120 .PP
121 .Vb 2
122 \& use FindBin;
123 \& FindBin::again(); # or FindBin\->again;
124 .Ve
125 .PP
126 In former versions of \f(CW\*(C`FindBin\*(C'\fR there was no \f(CW\*(C`again\*(C'\fR function.
127 The workaround was to force the \f(CW\*(C`BEGIN\*(C'\fR block to be executed again:
128 .PP
129 .Vb 2
130 \& delete $INC{\*(AqFindBin.pm\*(Aq};
131 \& require FindBin;
132 .Ve
133 .SH AUTHORS
134 .IX Header "AUTHORS"
135 \&\f(CW\*(C`FindBin\*(C'\fR is supported as part of the core perl distribution. Please submit bug
136 reports at <https://github.com/Perl/perl5/issues>.
137 .PP
138 Graham Barr <\[email protected]\fR>
139 Nick Ing-Simmons <\[email protected]\fR>
140 .SH COPYRIGHT
141 .IX Header "COPYRIGHT"
142 Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
143 This program is free software; you can redistribute it and/or modify it
144 under the same terms as Perl itself.