Debian Codegraph @

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