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 /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 'man2/get_robust_list.2')
-rw-r--r-- | man2/get_robust_list.2 | 156 |
1 files changed, 0 insertions, 156 deletions
diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2 deleted file mode 100644 index bd8682a..0000000 --- a/man2/get_robust_list.2 +++ /dev/null @@ -1,156 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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/ |