.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dpkg::Path 3perl"
.TH Dpkg::Path 3perl 2024-03-10 1.22.6 libdpkg-perl
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Dpkg::Path \- some common path handling functions
.SH DESCRIPTION
.IX Header "DESCRIPTION"
It provides some functions to handle various path.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.IP get_pkg_root_dir($file) 8
.IX Item "get_pkg_root_dir($file)"
This function will scan upwards the hierarchy of directory to find out
the directory which contains the "DEBIAN" sub-directory and it will return
its path. This directory is the root directory of a package being built.
.Sp
If no DEBIAN subdirectory is found, it will return undef.
.IP relative_to_pkg_root($file) 8
.IX Item "relative_to_pkg_root($file)"
Returns the filename relative to get_pkg_root_dir($file).
.IP guess_pkg_root_dir($file) 8
.IX Item "guess_pkg_root_dir($file)"
This function tries to guess the root directory of the package build tree.
It will first use \fBget_pkg_root_dir()\fR, but it will fallback to a more
imprecise check: namely it will use the parent directory that is a
sub-directory of the debian directory.
.Sp
It can still return undef if a file outside of the debian sub-directory is
provided.
.ie n .IP "check_files_are_the_same($file1, $file2, $resolve_symlink)" 8
.el .IP "check_files_are_the_same($file1, \f(CW$file2\fR, \f(CW$resolve_symlink\fR)" 8
.IX Item "check_files_are_the_same($file1, $file2, $resolve_symlink)"
This function verifies that both files are the same by checking that the device
numbers and the inode numbers returned by \fBstat()\fR/\fBlstat()\fR are the same. If
\&\f(CW$resolve_symlink\fR is true then \fBstat()\fR is used, otherwise \fBlstat()\fR is used.
.IP canonpath($file) 8
.IX Item "canonpath($file)"
This function returns a cleaned path. It simplifies double //, and remove
/./ and /../ intelligently. For /../ it simplifies the path only if the
previous element is not a symlink. Thus it should only be used on real
filenames.
.ie n .IP "$newpath = resolve_symlink($symlink)" 8
.el .IP "\f(CW$newpath\fR = resolve_symlink($symlink)" 8
.IX Item "$newpath = resolve_symlink($symlink)"
Return the filename of the file pointed by the symlink. The new name is
canonicalized by \fBcanonpath()\fR.
.ie n .IP "check_directory_traversal($basedir, $dir)" 8
.el .IP "check_directory_traversal($basedir, \f(CW$dir\fR)" 8
.IX Item "check_directory_traversal($basedir, $dir)"
This function verifies that the directory \f(CW$dir\fR does not contain any symlink
that goes beyond \f(CW$basedir\fR (which should be either equal or a parent of \f(CW$dir\fR).
.ie n .IP "$cmdpath = find_command($command)" 8
.el .IP "\f(CW$cmdpath\fR = find_command($command)" 8
.IX Item "$cmdpath = find_command($command)"
Return the path of the command if defined and available on an absolute or
relative path or on the \f(CW$PATH\fR, undef otherwise.
.ie n .IP "$control_file = get_control_path($pkg, $filetype)" 8
.el .IP "\f(CW$control_file\fR = get_control_path($pkg, \f(CW$filetype\fR)" 8
.IX Item "$control_file = get_control_path($pkg, $filetype)"
Return the path of the control file of type \f(CW$filetype\fR for the given
package.
.ie n .IP "@control_files = get_control_path($pkg)" 8
.el .IP "\f(CW@control_files\fR = get_control_path($pkg)" 8
.IX Item "@control_files = get_control_path($pkg)"
Return the path of all available control files for the given package.
.ie n .IP "$file = find_build_file($basename)" 8
.el .IP "\f(CW$file\fR = find_build_file($basename)" 8
.IX Item "$file = find_build_file($basename)"
Selects the right variant of the given file: the arch-specific variant
("$basename.$arch") has priority over the OS-specific variant
("$basename.$os") which has priority over the default variant
("$basename"). If none of the files exists, then it returns undef.
.ie n .IP "@files = find_build_file($basename)" 8
.el .IP "\f(CW@files\fR = find_build_file($basename)" 8
.IX Item "@files = find_build_file($basename)"
Return the available variants of the given file. Returns an empty
list if none of the files exists.
.SH CHANGES
.IX Header "CHANGES"
.SS "Version 1.05 (dpkg 1.20.4)"
.IX Subsection "Version 1.05 (dpkg 1.20.4)"
New function: \fBcheck_directory_traversal()\fR.
.SS "Version 1.04 (dpkg 1.17.11)"
.IX Subsection "Version 1.04 (dpkg 1.17.11)"
Update semantics: \fBfind_command()\fR now handles an empty or undef argument.
.SS "Version 1.03 (dpkg 1.16.1)"
.IX Subsection "Version 1.03 (dpkg 1.16.1)"
New function: \fBfind_build_file()\fR
.SS "Version 1.02 (dpkg 1.16.0)"
.IX Subsection "Version 1.02 (dpkg 1.16.0)"
New function: \fBget_control_path()\fR
.SS "Version 1.01 (dpkg 1.15.8)"
.IX Subsection "Version 1.01 (dpkg 1.15.8)"
New function: \fBfind_command()\fR
.SS "Version 1.00 (dpkg 1.15.6)"
.IX Subsection "Version 1.00 (dpkg 1.15.6)"
Mark the module as public.