Debian Codegraph @

upstream/opensuse-tumbleweed/man3/FindBin.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "FindBin 3pm"
61 .TH FindBin 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 FindBin \- Locate directory of original Perl script
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use FindBin;
72 \& use lib "$FindBin::Bin/../lib";
73 \&
74 \& use FindBin qw($Bin);
75 \& use lib "$Bin/../lib";
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 Locates the full path to the script bin directory to allow the use
80 of paths relative to the bin directory.
81 .PP
82 This allows a user to setup a directory tree for some software with
83 directories \f(CW\*(C`<root>/bin\*(C'\fR and \f(CW\*(C`<root>/lib\*(C'\fR, and then the above
84 example will allow the use of modules in the lib directory without knowing
85 where the software tree is installed.
86 .PP
87 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
88 \&\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
89 directory.
90 .SH "EXPORTABLE VARIABLES"
91 .IX Header "EXPORTABLE VARIABLES"
92 .ie n .IP "$Bin or $Dir" 4
93 .el .IP "\f(CW$Bin\fR or \f(CW$Dir\fR" 4
94 .IX Item "$Bin or $Dir"
95 Path to the bin \fBdirectory\fR from where script was invoked
96 .ie n .IP $Script 4
97 .el .IP \f(CW$Script\fR 4
98 .IX Item "$Script"
99 \&\fBBasename\fR of the script from which \f(CW\*(C`perl\*(C'\fR was invoked
100 .ie n .IP "$RealBin or $RealDir" 4
101 .el .IP "\f(CW$RealBin\fR or \f(CW$RealDir\fR" 4
102 .IX Item "$RealBin or $RealDir"
103 \&\f(CW$Bin\fR with all links resolved
104 .ie n .IP $RealScript 4
105 .el .IP \f(CW$RealScript\fR 4
106 .IX Item "$RealScript"
107 \&\f(CW$Script\fR with all links resolved
108 .PP
109 You can also use the \f(CW\*(C`ALL\*(C'\fR tag to export all of the above variables together:
110 .PP
111 .Vb 1
112 \& use FindBin \*(Aq:ALL\*(Aq;
113 .Ve
114 .SH "KNOWN ISSUES"
115 .IX Header "KNOWN ISSUES"
116 If there are two modules using \f(CW\*(C`FindBin\*(C'\fR from different directories
117 under the same interpreter, this won\*(Aqt work. Since \f(CW\*(C`FindBin\*(C'\fR uses a
118 \&\f(CW\*(C`BEGIN\*(C'\fR block, it\*(Aqll be executed only once, and only the first caller
119 will get it right. This is a problem under \f(CW\*(C`mod_perl\*(C'\fR and other persistent
120 Perl environments, where you shouldn\*(Aqt use this module. Which also means
121 that you should avoid using \f(CW\*(C`FindBin\*(C'\fR in modules that you plan to put
122 on CPAN. Call the \f(CW\*(C`again\*(C'\fR function to make sure that \f(CW\*(C`FindBin\*(C'\fR will work:
123 .PP
124 .Vb 2
125 \& use FindBin;
126 \& FindBin::again(); # or FindBin\->again;
127 .Ve
128 .PP
129 In former versions of \f(CW\*(C`FindBin\*(C'\fR there was no \f(CW\*(C`again\*(C'\fR function.
130 The workaround was to force the \f(CW\*(C`BEGIN\*(C'\fR block to be executed again:
131 .PP
132 .Vb 2
133 \& delete $INC{\*(AqFindBin.pm\*(Aq};
134 \& require FindBin;
135 .Ve
136 .SH AUTHORS
137 .IX Header "AUTHORS"
138 \&\f(CW\*(C`FindBin\*(C'\fR is supported as part of the core perl distribution. Please submit bug
139 reports at <https://github.com/Perl/perl5/issues>.
140 .PP
141 Graham Barr <\[email protected]\fR>
142 Nick Ing\-Simmons <\[email protected]\fR>
143 .SH COPYRIGHT
144 .IX Header "COPYRIGHT"
145 Copyright (c) 1995 Graham Barr & Nick Ing\-Simmons. All rights reserved.
146 This program is free software; you can redistribute it and/or modify it
147 under the same terms as Perl itself.