diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:22 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-24 04:52:22 +0000 |
commit | 7f3caba522f4d24764f29d83aa2de9198bb7f01c (patch) | |
tree | 66b798ea74302325d6a5c11df044cbe4bb845af1 /man/man2/get_robust_list.2 | |
parent | Adding upstream version 6.7. (diff) | |
download | manpages-upstream.tar.xz manpages-upstream.zip |
Adding upstream version 6.8.upstream/6.8upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/man2/get_robust_list.2')
-rw-r--r-- | man/man2/get_robust_list.2 | 156 |
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/ |