From 04c95a3bb599c97e327a75d8e7a2ee73020e4021 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 18 Oct 2014 12:54:19 +0200 Subject: [PATCH] attributes.7: Comment out 'fd' text Signed-off-by: Michael Kerrisk --- man7/attributes.7 | 84 +++++++++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/man7/attributes.7 b/man7/attributes.7 index bb68d9dad..81454ae2b 100644 --- a/man7/attributes.7 +++ b/man7/attributes.7 @@ -725,48 +725,48 @@ running or asynchronous signals are enabled, and so the data structure can be considered effectively constant in these contexts, which makes the former safe. -.TP -.I fd -Functions annotated with -.I fd -as an AC-Safety issue may leak file -descriptors if asynchronous thread cancellation interrupts their -execution. - -Functions that allocate or deallocate file descriptors will generally be -marked as such. -Even if they attempted to protect the file descriptor -allocation and deallocation with cleanup regions, -allocating a new descriptor and storing its number where the cleanup region -could release it cannot be performed as a single atomic operation. -Similarly, -releasing the descriptor and taking it out of the data structure -normally responsible for releasing it cannot be performed atomically. -There will always be a window in which the descriptor cannot be released -because it was not stored in the cleanup handler argument yet, -or it was already taken out before releasing it. -It cannot be taken out after release: -an open descriptor could mean either that the descriptor still -has to be closed, -or that it already did so but the descriptor was -reallocated by another thread or signal handler. - -Such leaks could be internally avoided, with some performance penalty, -by temporarily disabling asynchronous thread cancellation. -However, -since callers of allocation or deallocation functions would have to do -this themselves, to avoid the same sort of leak in their own layer, -it makes more sense for the library to assume they are taking care of it -than to impose a performance penalty that is redundant when the problem -is solved in upper layers, and insufficient when it is not. - -This remark by itself does not cause a function to be regarded as -AC-Unsafe. -However, cumulative effects of such leaks may pose a -problem for some programs. -If this is the case, -suspending asynchronous cancellation for the duration of calls -to such functions is recommended. +.\" .TP +.\" .I fd +.\" Functions annotated with +.\" .I fd +.\" as an AC-Safety issue may leak file +.\" descriptors if asynchronous thread cancellation interrupts their +.\" execution. +.\" +.\" Functions that allocate or deallocate file descriptors will generally be +.\" marked as such. +.\" Even if they attempted to protect the file descriptor +.\" allocation and deallocation with cleanup regions, +.\" allocating a new descriptor and storing its number where the cleanup region +.\" could release it cannot be performed as a single atomic operation. +.\" Similarly, +.\" releasing the descriptor and taking it out of the data structure +.\" normally responsible for releasing it cannot be performed atomically. +.\" There will always be a window in which the descriptor cannot be released +.\" because it was not stored in the cleanup handler argument yet, +.\" or it was already taken out before releasing it. +.\" .\" It cannot be taken out after release: +.\" an open descriptor could mean either that the descriptor still +.\" has to be closed, +.\" or that it already did so but the descriptor was +.\" reallocated by another thread or signal handler. +.\" +.\" Such leaks could be internally avoided, with some performance penalty, +.\" by temporarily disabling asynchronous thread cancellation. +.\" However, +.\" since callers of allocation or deallocation functions would have to do +.\" this themselves, to avoid the same sort of leak in their own layer, +.\" it makes more sense for the library to assume they are taking care of it +.\" than to impose a performance penalty that is redundant when the problem +.\" is solved in upper layers, and insufficient when it is not. +.\" +.\" This remark by itself does not cause a function to be regarded as +.\" AC-Unsafe. +.\" However, cumulative effects of such leaks may pose a +.\" problem for some programs. +.\" If this is the case, +.\" suspending asynchronous cancellation for the duration of calls +.\" to such functions is recommended. .TP .I mem Functions annotated with