From c3ca2b03a6dca3d8bc04fbe14f5449871dac3e52 Mon Sep 17 00:00:00 2001
From: elad <elad@NetBSD.org>
Date: Tue, 16 Jan 2007 13:21:14 +0000
Subject: [PATCH] Add man-page for pathname(9) routines, but don't link to
 build yet.

---
 share/man/man9/pathname.9 | 79 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 share/man/man9/pathname.9

diff --git a/share/man/man9/pathname.9 b/share/man/man9/pathname.9
new file mode 100644
index 000000000000..bd10a6706a76
--- /dev/null
+++ b/share/man/man9/pathname.9
@@ -0,0 +1,79 @@
+.\" $NetBSD: pathname.9,v 1.1 2007/01/16 13:21:14 elad Exp $
+.\"
+.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
+.\" 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, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
+.\"
+.Dd January 16, 2007
+.Dt PATHNAME 9
+.Os
+.Sh NAME
+.Nm pathname
+.Nd pathname management interface
+.Sh SYNOPSIS
+.In sys/namei.h
+.Sh DESCRIPTION
+The
+.Nm
+interface provides an easy way to manage memory buffers used to hold pathnames.
+It provides three functions:
+.Pp
+.Bl -tag
+.It Ft pathname_t Fn pathname_get "const char *dirp" "enum uio_segflg seg"
+Takes a pointer to a pathname buffer,
+.Ar dirp ,
+and an argument indicating in what address space it is located at,
+.Ar seg ;
+.Dv UIO_SYSSPACE
+or
+.Dv UIO_USERSPACE
+for kernel-space and user-space, respectively.
+.It Ft char * Fn pathname_path "pathname_t pn"
+Takes a
+.Ft pathname_t
+argument as returned from a previous call to
+.Fn pathname_get ,
+.Ar pn ,
+and returns a pointer to the pathname buffer.
+This pointer is safe to use in the kernel.
+.It Ft void pathname_put "pathname_t pn"
+Frees all memory associated with
+.Ar pn .
+.Fn kmem_zalloc
+is the equivalent of
+.Fn kmem_alloc ,
+except that it initializes the memory to zero.
+.Sh SEE ALSO
+.Xr namei 9
+.Sh AUTHORS
+.An Elad Efrat Aq elad@NetBSD.org
+.Sh CAVEATS
+If the buffer is located in kernel-space,
+.Fn pathname_get
+will reuse it.
+.Pp
+The
+.Nm
+interface is experimental and subject to change.
+Its existence should not be relied on.