lib/libc/gen/basename.3

   1 .\" $OpenBSD: basename.3,v 1.20 2007/05/31 19:19:28 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" $FreeBSD$
  18 .\"
  19 .Dd March 31, 2010
  20 .Dt BASENAME 3
  21 .Os
  22 .Sh NAME
  23 .Nm basename
  24 .Nd extract the base portion of a pathname
  25 .Sh SYNOPSIS
  26 .In libgen.h
  27 .Ft char *
  28 .Fn basename "const char *path"
  29 .Ft char *
  30 .Fn basename_r "const char *path" "char *bname"
  31 .Sh DESCRIPTION
  32 The
  33 .Fn basename
  34 function returns the last component from the pathname pointed to by
  35 .Fa path ,
  36 deleting any trailing
  37 .Sq \&/
  38 characters.
  39 If
  40 .Fa path
  41 consists entirely of
  42 .Sq \&/
  43 characters, a pointer to the string
  44 .Qq \&/
  45 is returned.
  46 If
  47 .Fa path
  48 is a null pointer or the empty string, a pointer to the string
  49 .Qq \&.
  50 is returned.
  51 .Pp
  52 The
  53 .Fn basename_r
  54 variation accepts a buffer of at least
  55 .Dv MAXPATHLEN
  56 bytes in which to store the resulting component.
  57 .Sh IMPLEMENTATION NOTES
  58 The
  59 .Fn basename
  60 function
  61 returns a pointer to internal storage space allocated on the first call
  62 that will be overwritten
  63 by subsequent calls.
  64 .Fn basename_r
  65 is therefore preferred for threaded applications.
  66 .Sh RETURN VALUES
  67 On successful completion,
  68 .Fn basename
  69 and
  70 .Fn basename_r
  71 return pointers to the last component of
  72 .Fa path .
  73 .Pp
  74 If they fail, a null pointer is returned and the global variable
  75 .Va errno
  76 is set to indicate the error.
  77 .Sh ERRORS
  78 The following error codes may be set in
  79 .Va errno :
  80 .Bl -tag -width Er
  81 .It Bq Er ENAMETOOLONG
  82 The path component to be returned was larger than
  83 .Dv MAXPATHLEN .
  84 .El
  85 .Sh SEE ALSO
  86 .Xr basename 1 ,
  87 .Xr dirname 1 ,
  88 .Xr dirname 3
  89 .Sh STANDARDS
  90 The
  91 .Fn basename
  92 function conforms to
  93 .St -xpg4.2 .
  94 .Sh HISTORY
  95 The
  96 .Fn basename
  97 function first appeared in
  98 .Ox 2.2
  99 and
 100 .Fx 4.2 .
 101 .Sh AUTHORS
 102 .An Todd C. Miller
 103 .Sh CAVEATS
 104 .Fn basename
 105 returns a pointer to internal static storage space that will be overwritten
 106 by subsequent calls.
 107 .Pp
 108 Other vendor implementations of
 109 .Fn basename
 110 may modify the contents of the string passed to
 111 .Fn basename ;
 112 this should be taken into account when writing code which calls this function
 113 if portability is desired.