man3/canonicalize_file_name.3

   1 '\" t
   2 .\" Copyright 2013 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" (Replaces an earlier page by Walter Harms and Michael Kerrisk)
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH canonicalize_file_name 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 canonicalize_file_name \- return the canonicalized absolute pathname
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  16 .B #include <stdlib.h>
  17 .PP
  18 .BI "char *canonicalize_file_name(const char *" path ");"
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR canonicalize_file_name ()
  23 function returns a null-terminated string containing
  24 the canonicalized absolute pathname corresponding to
  25 .IR path .
  26 In the returned string, symbolic links are resolved, as are
  27 .I .
  28 and
  29 .I ..
  30 pathname components.
  31 Consecutive slash
  32 .RI ( / )
  33 characters are replaced by a single slash.
  34 .PP
  35 The returned string is dynamically allocated by
  36 .BR canonicalize_file_name ()
  37 and the caller should deallocate it with
  38 .BR free (3)
  39 when it is no longer required.
  40 .PP
  41 The call
  42 .I canonicalize_file_name(path)
  43 is equivalent to the call:
  44 .PP
  45 .in +4n
  46 .EX
  47 realpath(path, NULL);
  48 .EE
  49 .in
  50 .SH RETURN VALUE
  51 On success,
  52 .BR canonicalize_file_name ()
  53 returns a null-terminated string.
  54 On error (e.g., a pathname component is unreadable or does not exist),
  55 .BR canonicalize_file_name ()
  56 returns NULL and sets
  57 .I errno
  58 to indicate the error.
  59 .SH ERRORS
  60 See
  61 .BR realpath (3).
  62 .SH ATTRIBUTES
  63 For an explanation of the terms used in this section, see
  64 .BR attributes (7).
  65 .TS
  66 allbox;
  67 lbx lb lb
  68 l l l.
  69 Interface       Attribute       Value
  70 T{
  71 .na
  72 .nh
  73 .BR canonicalize_file_name ()
  74 T}      Thread safety   MT-Safe
  75 .TE
  76 .sp 1
  77 .SH STANDARDS
  78 GNU.
  79 .SH SEE ALSO
  80 .BR readlink (2),
  81 .BR realpath (3)