lib/libc/sys/fhreadlink.2

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   2 .\"
   3 .\" Copyright (c) 2018 Gandi
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd November 30, 2022
  27 .Dt FHREADLINK 2
  28 .Os
  29 .Sh NAME
  30 .Nm fhreadlink
  31 .Nd read value of a symbolic link
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/mount.h
  37 .Ft int
  38 .Fn fhreadlink "fhandle_t *fhp" "char *buf" "size_t bufsize"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn fhreadlink
  43 system call
  44 places the contents of the symbolic link
  45 .Fa fhp
  46 in the buffer
  47 .Fa buf ,
  48 which has size
  49 .Fa bufsiz .
  50 The
  51 .Fn fhreadlink
  52 system call does not append a
  53 .Dv NUL
  54 character to
  55 .Fa buf .
  56 .Pp
  57 .Sh RETURN VALUES
  58 The call returns the count of characters placed in the buffer
  59 if it succeeds, or a \-1 if an error occurs, placing the error
  60 code in the global variable
  61 .Va errno .
  62 .Sh ERRORS
  63 The
  64 .Fn readlink
  65 system call
  66 will fail if:
  67 .Bl -tag -width Er
  68 .It Bq Er ENOENT
  69 The named file does not exist.
  70 .It Bq Er ELOOP
  71 Too many symbolic links were encountered in translating the file handle
  72 .Fa fhp .
  73 .It Bq Er EINVAL
  74 The named file is not a symbolic link.
  75 .It Bq Er EIO
  76 An I/O error occurred while reading from the file system.
  77 .It Bq Er EINTEGRITY
  78 Corrupted data was detected while reading from the file system.
  79 .It Bq Er EFAULT
  80 The
  81 .Fa buf
  82 argument
  83 extends outside the process's allocated address space.
  84 .It Bq Er ESTALE
  85 The file handle
  86 .Fa fhp
  87 is no longer valid
  88 .El
  89 .El
  90 .Sh SEE ALSO
  91 .Xr fhstat 2 ,
  92 .Xr fhlink 2 ,
  93 .Sh HISTORY
  94 The
  95 .Fn fhreadlink
  96 system call first appeared in
  97 .Fx 12.1 .