man3/canonicalize_file_name.3

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