mirror of
https://git.FreeBSD.org/src.git
synced 2025-01-17 15:27:36 +00:00
Add a basic manpage for vn_fullpath().
Sponsored by: DARPA, McAfee Research
This commit is contained in:
Robert Watson
parent
0e5dfade00
commit
9b1faf0afb
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=124395
@ -99,7 +99,7 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
|
||||
vm_page_protect.9 vm_page_rename.9 \
|
||||
vm_page_sleep_busy.9 vm_page_unmanage.9 vm_page_wakeup.9 \
|
||||
vm_page_wire.9 vm_page_zero_fill.9 vm_set_page_size.9 \
|
||||
vn_isdisk.9 vnode.9 vput.9 vref.9 vrele.9 \
|
||||
vn_isdisk.9 vn_fullpath.9 vnode.9 vput.9 vref.9 vrele.9 \
|
||||
vslock.9 \
|
||||
zero_copy.9 zone.9
|
||||
|
||||
|
||||
98
share/man/man9/vn_fullpath.9
Normal file
98
share/man/man9/vn_fullpath.9
Normal file
@ -0,0 +1,98 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2003 Robert N. M. Watson.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice(s), this list of conditions and the following disclaimer as
|
||||
.\" the first lines of this file unmodified other than the possible
|
||||
.\" addition of one or more copyright notices.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice(s), this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
|
||||
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
|
||||
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
|
||||
.\" DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 11, 2004
|
||||
.Dt VN_FULLPATH 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm vn_fullpath
|
||||
.Nd "Convert a vnode reference to a full pathname, given a process context"
|
||||
.Sh SYNOPSIS
|
||||
.In sys/param.h
|
||||
.In sys/vnode.h
|
||||
.Ft int
|
||||
.Fn vn_fullpath "struct thread *td" "struct vnode *vp" "char **retbuf" "char **freebuf"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn
|
||||
function makes a "best effort" attempt to generate a string pathname for
|
||||
the passed (locked) vnode; the resulting path, if any, will be relative to
|
||||
the root directory of the process associated with the passed thread pointer.
|
||||
.Fn is implemented by inspecting the VFS name cache, and attempting to
|
||||
reconstruct a path from the process root to the object.
|
||||
.Pp
|
||||
This process is necessarily unreliable for several reasons: intermediate
|
||||
entries in the path may not be found in the cache; files may have more
|
||||
than one name (hard links), not all file systems use the name cache
|
||||
(specifically, most synthetic file systems don't); a single name may
|
||||
be used for more than one file (in the context of file systems covering
|
||||
other file systems); a file may have no name (if deleted but still
|
||||
open or referenced).
|
||||
However, the resulting string may still be more useable to a user than
|
||||
a vnode pointer value, or a device number and inode number.
|
||||
Code consuming the results of this function should anticipate (and
|
||||
properly handle) failure.
|
||||
.Pp
|
||||
Its arguments are:
|
||||
.Bl -tag -width freebuf
|
||||
.It Fa td
|
||||
The thread performing the call; this pointer will be dereferenced to find
|
||||
the process and its file descriptor structure, in order to identify the
|
||||
root vnode to use.
|
||||
.It Fa vp
|
||||
The vnode to search for; must be locked by the caller.
|
||||
.It Fa retbuf
|
||||
Pointer to a char * that vn_fullpath may (on success) point at a newly
|
||||
allocated buffer containing the resulting pathname.
|
||||
.It Fa freebuf
|
||||
Pointer to a char * that vn_fullpath may (on success) point at a buffer
|
||||
to be freed, when the caller is done with
|
||||
.Fa retbuf .
|
||||
.El
|
||||
.Pp
|
||||
Typical consumers will declare two character pointers: fullpath and
|
||||
freepath; they will set freepath to
|
||||
.Dv NULL ,
|
||||
and fullpath to a name to use
|
||||
in the event that the call to
|
||||
.Fn
|
||||
fails.
|
||||
After done with the value of fullpath, the caller will check if freepath
|
||||
is non-NULL, and if so, invoke
|
||||
.Xr free 9
|
||||
with a pool type of
|
||||
.Dv M_TEMP .
|
||||
.Sh RETURN VALUES
|
||||
If the vnode is successfully converted to a pathname, 0 is returned;
|
||||
otherwise, an error number is returned.
|
||||
.Sh SEE ALSO
|
||||
.Xr free 9
|
||||
.Sh AUTHORS
|
||||
This man page was written by
|
||||
.An Robert Watson Aq rwatson@FreeBSD.org .
|
||||
Loading…
Reference in New Issue
Block a user