mirror of https://github.com/mkerrisk/man-pages
169 lines
5.1 KiB
Groff
169 lines
5.1 KiB
Groff
.\" 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>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" FIXME Something could be added to this page (or exit(2))
|
|
.\" about exit_robust_list processing
|
|
.\"
|
|
.TH GET_ROBUST_LIST 2 2021-03-22 Linux "Linux System Calls"
|
|
.SH NAME
|
|
get_robust_list, set_robust_list \- get/set list of robust futexes
|
|
.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>
|
|
.PP
|
|
.BI "long syscall(SYS_get_robust_list, int " pid ,
|
|
.BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr );
|
|
.BI "long syscall(SYS_set_robust_list,"
|
|
.BI " struct robust_list_head *" head ", size_t " len );
|
|
.fi
|
|
.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 ().
|
|
.PP
|
|
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
|
|
.BR FUTEX_OWNER_DIED
|
|
bit is set in the futex word, and the kernel performs a
|
|
.BR futex (2)
|
|
.BR FUTEX_WAKE
|
|
operation on one of the threads waiting on the futex.
|
|
.PP
|
|
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 .
|
|
.PP
|
|
Permission to employ
|
|
.BR get_robust_list ()
|
|
is governed by a ptrace access mode
|
|
.B PTRACE_MODE_READ_REALCREDS
|
|
check; see
|
|
.BR ptrace (2).
|
|
.PP
|
|
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)" .
|
|
.PP
|
|
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
|
|
.BR 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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).
|
|
.PP
|
|
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)
|
|
.PP
|
|
.IR Documentation/robust\-futexes.txt
|
|
and
|
|
.IR Documentation/robust\-futex\-ABI.txt
|
|
in the Linux kernel source tree
|
|
.\" http://lwn.net/Articles/172149/
|