1 files changed, 86 insertions, 0 deletions
diff --git a/man/man2/lookup_dcookie.2 b/man/man2/lookup_dcookie.2
new file mode 100644
index 000000000..acc5e43e6
--- /dev/null
+++ b/man/man2/lookup_dcookie.2
@@ -0,0 +1,86 @@
+.\" Copyright (C) 2003 John Levon <levon@movementarian.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH lookup_dcookie 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+lookup_dcookie \- return a directory entry's path
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer ,
+.BI "            size_t " len );
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR lookup_dcookie (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+Look up the full path of the directory entry specified by the value
+.IR cookie .
+The cookie is an opaque identifier uniquely identifying a particular
+directory entry.
+The buffer given is filled in with the full path of the directory entry.
+.P
+For
+.BR lookup_dcookie ()
+to return successfully,
+the kernel must still hold a cookie reference to the directory entry.
+.SH RETURN VALUE
+On success,
+.BR lookup_dcookie ()
+returns the length of the path string copied into the buffer.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+The buffer was not valid.
+.TP
+.B EINVAL
+The kernel has no registered cookie/directory entry mappings at the
+time of lookup, or the cookie does not refer to a valid directory entry.
+.TP
+.B ENAMETOOLONG
+The name could not fit in the buffer.
+.TP
+.B ENOMEM
+The kernel could not allocate memory for the temporary buffer holding
+the path.
+.TP
+.B EPERM
+The process does not have the capability
+.B CAP_SYS_ADMIN
+required to look up cookie values.
+.TP
+.B ERANGE
+The buffer was not large enough to hold the path of the directory entry.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.5.43.
+.P
+The
+.B ENAMETOOLONG
+error was added in Linux 2.5.70.
+.SH NOTES
+.BR lookup_dcookie ()
+is a special-purpose system call, currently used only by the
+.BR oprofile (1)
+profiler.
+It relies on a kernel driver to register cookies for directory entries.
+.P
+The path returned may be suffixed by the string " (deleted)" if the directory
+entry has been removed.
+.SH SEE ALSO
+.BR oprofile (1)