Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Cwd.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 "Cwd 3pm"
61 .TH Cwd 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 Cwd \- get pathname of current working directory
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use Cwd;
72 \& my $dir = getcwd;
73 \&
74 \& use Cwd \*(Aqabs_path\*(Aq;
75 \& my $abs_path = abs_path($file);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 This module provides functions for determining the pathname of the
80 current working directory. It is recommended that getcwd (or another
81 *\fBcwd()\fR function) be used in \fIall\fR code to ensure portability.
82 .PP
83 By default, it exports the functions \fBcwd()\fR, \fBgetcwd()\fR, \fBfastcwd()\fR, and
84 \&\fBfastgetcwd()\fR (and, on Win32, \fBgetdcwd()\fR) into the caller\*(Aqs namespace.
85 .SS "getcwd and friends"
86 .IX Subsection "getcwd and friends"
87 Each of these functions are called without arguments and return the
88 absolute path of the current working directory.
89 .IP getcwd 4
90 .IX Item "getcwd"
91 .Vb 1
92 \& my $cwd = getcwd();
93 .Ve
94 .Sp
95 Returns the current working directory. On error returns \f(CW\*(C`undef\*(C'\fR,
96 with \f(CW$!\fR set to indicate the error.
97 .Sp
98 Exposes the POSIX function \fBgetcwd\fR\|(3) or re\-implements it if it\*(Aqs not
99 available.
100 .IP cwd 4
101 .IX Item "cwd"
102 .Vb 1
103 \& my $cwd = cwd();
104 .Ve
105 .Sp
106 The \fBcwd()\fR is the most natural form for the current architecture. For
107 most systems it is identical to \`pwd\` (but without the trailing line
108 terminator).
109 .IP fastcwd 4
110 .IX Item "fastcwd"
111 .Vb 1
112 \& my $cwd = fastcwd();
113 .Ve
114 .Sp
115 A more dangerous version of \fBgetcwd()\fR, but potentially faster.
116 .Sp
117 It might conceivably \fBchdir()\fR you out of a directory that it can\*(Aqt
118 \&\fBchdir()\fR you back into. If fastcwd encounters a problem it will return
119 undef but will probably leave you in a different directory. For a
120 measure of extra security, if everything appears to have worked, the
121 \&\fBfastcwd()\fR function will check that it leaves you in the same directory
122 that it started in. If it has changed it will \f(CW\*(C`die\*(C'\fR with the message
123 "Unstable directory path, current directory changed
124 unexpectedly". That should never happen.
125 .IP fastgetcwd 4
126 .IX Item "fastgetcwd"
127 .Vb 1
128 \& my $cwd = fastgetcwd();
129 .Ve
130 .Sp
131 The \fBfastgetcwd()\fR function is provided as a synonym for \fBcwd()\fR.
132 .IP getdcwd 4
133 .IX Item "getdcwd"
134 .Vb 2
135 \& my $cwd = getdcwd();
136 \& my $cwd = getdcwd(\*(AqC:\*(Aq);
137 .Ve
138 .Sp
139 The \fBgetdcwd()\fR function is also provided on Win32 to get the current working
140 directory on the specified drive, since Windows maintains a separate current
141 working directory for each drive. If no drive is specified then the current
142 drive is assumed.
143 .Sp
144 This function simply calls the Microsoft C library \fB_getdcwd()\fR function.
145 .SS "abs_path and friends"
146 .IX Subsection "abs_path and friends"
147 These functions are exported only on request. They each take a single
148 argument and return the absolute pathname for it. If no argument is
149 given they\*(Aqll use the current working directory.
150 .IP abs_path 4
151 .IX Item "abs_path"
152 .Vb 1
153 \& my $abs_path = abs_path($file);
154 .Ve
155 .Sp
156 Uses the same algorithm as \fBgetcwd()\fR. Symbolic links and relative\-path
157 components ("." and "..") are resolved to return the canonical
158 pathname, just like \fBrealpath\fR\|(3). On error returns \f(CW\*(C`undef\*(C'\fR, with \f(CW$!\fR
159 set to indicate the error.
160 .IP realpath 4
161 .IX Item "realpath"
162 .Vb 1
163 \& my $abs_path = realpath($file);
164 .Ve
165 .Sp
166 A synonym for \fBabs_path()\fR.
167 .IP fast_abs_path 4
168 .IX Item "fast_abs_path"
169 .Vb 1
170 \& my $abs_path = fast_abs_path($file);
171 .Ve
172 .Sp
173 A more dangerous, but potentially faster version of abs_path.
174 .ie n .SS $ENV{PWD}
175 .el .SS \f(CW$ENV\fP{PWD}
176 .IX Subsection "$ENV{PWD}"
177 If you ask to override your \fBchdir()\fR built\-in function,
178 .PP
179 .Vb 1
180 \& use Cwd qw(chdir);
181 .Ve
182 .PP
183 then your PWD environment variable will be kept up to date. Note that
184 it will only be kept up to date if all packages which use chdir import
185 it from Cwd.
186 .SH NOTES
187 .IX Header "NOTES"
188 .IP \(bu 4
189 Since the path separators are different on some operating systems (\*(Aq/\*(Aq
190 on Unix, \*(Aq:\*(Aq on MacPerl, etc...) we recommend you use the File::Spec
191 modules wherever portability is a concern.
192 .IP \(bu 4
193 Actually, on Mac OS, the \f(CWgetcwd()\fR, \f(CWfastgetcwd()\fR and \f(CWfastcwd()\fR
194 functions are all aliases for the \f(CWcwd()\fR function, which, on Mac OS,
195 calls \`pwd\`. Likewise, the \f(CWabs_path()\fR function is an alias for
196 \&\f(CWfast_abs_path()\fR.
197 .SH AUTHOR
198 .IX Header "AUTHOR"
199 Maintained by perl5\-porters <\fIperl5\[email protected]\fR>.
200 .SH COPYRIGHT
201 .IX Header "COPYRIGHT"
202 Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.
203 .PP
204 This program is free software; you can redistribute it and/or modify
205 it under the same terms as Perl itself.
206 .PP
207 Portions of the C code in this library are copyright (c) 1994 by the
208 Regents of the University of California. All rights reserved. The
209 license on this code is compatible with the licensing of the rest of
210 the distribution \- please see the source code in \fICwd.xs\fR for the
211 details.
212 .SH "SEE ALSO"
213 .IX Header "SEE ALSO"
214 File::chdir