man3/canonicalize_file_name.3


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

'\" t
.\" Copyright 2013 Michael Kerrisk <mtk.manpages@gmail.com>
.\" (Replaces an earlier page by Walter Harms and Michael Kerrisk)
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH canonicalize_file_name 3 2023-07-20 "Linux man-pages 6.05.01"
.SH NAME
canonicalize_file_name \- return the canonicalized absolute pathname
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
.B #include <stdlib.h>
.PP
.BI "char *canonicalize_file_name(const char *" path ");"
.fi
.SH DESCRIPTION
The
.BR canonicalize_file_name ()
function returns a null-terminated string containing
the canonicalized absolute pathname corresponding to
.IR path .
In the returned string, symbolic links are resolved, as are
.I .
and
.I ..
pathname components.
Consecutive slash
.RI ( / )
characters are replaced by a single slash.
.PP
The returned string is dynamically allocated by
.BR canonicalize_file_name ()
and the caller should deallocate it with
.BR free (3)
when it is no longer required.
.PP
The call
.I canonicalize_file_name(path)
is equivalent to the call:
.PP
.in +4n
.EX
realpath(path, NULL);
.EE
.in
.SH RETURN VALUE
On success,
.BR canonicalize_file_name ()
returns a null-terminated string.
On error (e.g., a pathname component is unreadable or does not exist),
.BR canonicalize_file_name ()
returns NULL and sets
.I errno
to indicate the error.
.SH ERRORS
See
.BR realpath (3).
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR canonicalize_file_name ()
T}	Thread safety	MT-Safe
.TE
.sp 1
.SH STANDARDS
GNU.
.SH SEE ALSO
.BR readlink (2),
.BR realpath (3)