1 files changed, 156 insertions, 0 deletions
diff --git a/man/man2/get_robust_list.2 b/man/man2/get_robust_list.2
new file mode 100644
index 0000000..b519ca6
--- /dev/null
+++ b/man/man2/get_robust_list.2
@@ -0,0 +1,156 @@
+.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
+.\" Written by Ivana Varekova <varekova@redhat.com>
+.\" and Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" FIXME Something could be added to this page (or exit(2))
+.\" about exit_robust_list processing
+.\"
+.TH get_robust_list 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+get_robust_list, set_robust_list \- get/set list of robust futexes
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/futex.h>" \
+"   /* Definition of " "struct robust_list_head" " */"
+.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "long syscall(SYS_get_robust_list, int " pid ,
+.BI "             struct robust_list_head **" head_ptr ", size_t *" len_ptr );
+.B long syscall(SYS_set_robust_list,
+.BI "             struct robust_list_head *" head ", size_t " len );
+.fi
+.P
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+These system calls deal with per-thread robust futex lists.
+These lists are managed in user space:
+the kernel knows only about the location of the head of the list.
+A thread can inform the kernel of the location of its robust futex list using
+.BR set_robust_list ().
+The address of a thread's robust futex list can be obtained using
+.BR get_robust_list ().
+.P
+The purpose of the robust futex list is to ensure that if a thread
+accidentally fails to unlock a futex before terminating or calling
+.BR execve (2),
+another thread that is waiting on that futex is notified that
+the former owner of the futex has died.
+This notification consists of two pieces: the
+.B FUTEX_OWNER_DIED
+bit is set in the futex word, and the kernel performs a
+.BR futex (2)
+.B FUTEX_WAKE
+operation on one of the threads waiting on the futex.
+.P
+The
+.BR get_robust_list ()
+system call returns the head of the robust futex list of the thread
+whose thread ID is specified in
+.IR pid .
+If
+.I pid
+is 0,
+the head of the list for the calling thread is returned.
+The list head is stored in the location pointed to by
+.IR head_ptr .
+The size of the object pointed to by
+.I **head_ptr
+is stored in
+.IR len_ptr .
+.P
+Permission to employ
+.BR get_robust_list ()
+is governed by a ptrace access mode
+.B PTRACE_MODE_READ_REALCREDS
+check; see
+.BR ptrace (2).
+.P
+The
+.BR set_robust_list ()
+system call requests the kernel to record the head of the list of
+robust futexes owned by the calling thread.
+The
+.I head
+argument is the list head to record.
+The
+.I len
+argument should be
+.IR sizeof(*head) .
+.SH RETURN VALUE
+The
+.BR set_robust_list ()
+and
+.BR get_robust_list ()
+system calls return zero when the operation is successful,
+an error code otherwise.
+.SH ERRORS
+The
+.BR set_robust_list ()
+system call can fail with the following error:
+.TP
+.B EINVAL
+.I len
+does not equal
+.IR "sizeof(struct\ robust_list_head)" .
+.P
+The
+.BR get_robust_list ()
+system call can fail with the following errors:
+.TP
+.B EFAULT
+The head of the robust futex list can't be stored at the location
+.IR head .
+.TP
+.B EPERM
+The calling process does not have permission to see the robust futex list of
+the thread with the thread ID
+.IR pid ,
+and does not have the
+.B CAP_SYS_PTRACE
+capability.
+.TP
+.B ESRCH
+No thread with the thread ID
+.I pid
+could be found.
+.SH VERSIONS
+These system calls were added in Linux 2.6.17.
+.SH NOTES
+These system calls are not needed by normal applications.
+.P
+A thread can have only one robust futex list;
+therefore applications that wish
+to use this functionality should use the robust mutexes provided by glibc.
+.P
+In the initial implementation,
+a thread waiting on a futex was notified that the owner had died
+only if the owner terminated.
+Starting with Linux 2.6.28,
+.\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7
+notification was extended to include the case where the owner performs an
+.BR execve (2).
+.P
+The thread IDs mentioned in the main text are
+.I kernel
+thread IDs of the kind returned by
+.BR clone (2)
+and
+.BR gettid (2).
+.SH SEE ALSO
+.BR futex (2),
+.BR pthread_mutexattr_setrobust (3)
+.P
+.I Documentation/robust\-futexes.txt
+and
+.I Documentation/robust\-futex\-ABI.txt
+in the Linux kernel source tree
+.\" http://lwn.net/Articles/172149/