LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

attributes.7: Comment out "Unsafe features" 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2014-10-18 10:52:27 +02:00
parent 6761fb0c02
commit e7b42ec654
1 changed files with 151 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

302
man7/attributes.7
View File

@ -167,157 +167,157 @@ they are not to be regarded as a promise of future behavior.
Other keywords that appear in safety notes are defined in subsequent sections. Other keywords that appear in safety notes are defined in subsequent sections.
.\" .\"
.\" .\"
.SS Unsafe features .\" .SS Unsafe features
Functions that are unsafe to call in certain contexts are annotated with .\" Functions that are unsafe to call in certain contexts are annotated with
keywords that document their features that make them unsafe to call. .\" keywords that document their features that make them unsafe to call.
AS-Unsafe features in this section indicate the functions are never safe .\" AS-Unsafe features in this section indicate the functions are never safe
to call when asynchronous signals are enabled. .\" to call when asynchronous signals are enabled.
AC-Unsafe features .\" AC-Unsafe features
indicate they are never safe to call when asynchronous cancellation is .\" indicate they are never safe to call when asynchronous cancellation is
enabled. .\" .\" enabled.
There are no MT-Unsafe marks in this section. .\" There are no MT-Unsafe marks in this section.
.TP .\" .TP
.I code .\" .\" .I code
Functions marked with .\" Functions marked with
.I lock .\" .I lock
as an AS-Unsafe feature may be .\" as an AS-Unsafe feature may be
interrupted by a signal while holding a non-recursive lock. .\" .\" interrupted by a signal while holding a non-recursive lock.
If the signal handler calls another such function that takes the same lock, .\" If the signal handler calls another such function that takes the same lock,
the result is a deadlock. .\" the result is a deadlock.
.\"
Functions annotated with .\" Functions annotated with
.I lock .\" .I lock
as an AC-Unsafe feature may, if canceled asynchronously, .\" as an AC-Unsafe feature may, if canceled asynchronously,
fail to release a lock that would have been released if their execution .\" fail to release a lock that would have been released if their execution
had not been interrupted by asynchronous thread cancellation. .\" had not been interrupted by asynchronous thread cancellation.
Once a lock is left taken, attempts to take that lock will block indefinitely. .\" Once a lock is left taken, attempts to take that lock will block indefinitely.
.TP .\" .TP
.I corrupt .\" .I corrupt
Functions marked with .\" Functions marked with
.I corrupt .\" .\" .I corrupt
as an AS-Unsafe feature may corrupt .\" as an AS-Unsafe feature may corrupt
data structures and misbehave when they interrupt, .\" data structures and misbehave when they interrupt,
or are interrupted by, another such function. .\" or are interrupted by, another such function.
Unlike functions marked with .\" Unlike functions marked with
.IR lock , .\" .IR lock ,
these take recursive locks to avoid MT-Safety problems, .\" these take recursive locks to avoid MT-Safety problems,
but this is not enough to stop a signal handler from observing .\" but this is not enough to stop a signal handler from observing
a partially-updated data structure. .\" a partially-updated data structure.
Further corruption may arise from the interrupted function's .\" Further corruption may arise from the interrupted function's
failure to notice updates made by signal handlers. .\" failure to notice updates made by signal handlers.
.\"
Functions marked with .\" Functions marked with
.I corrupt .\" .I corrupt
as an AC-Unsafe feature may leave .\" as an AC-Unsafe feature may leave
data structures in a corrupt, partially updated state. .\" data structures in a corrupt, partially updated state.
Subsequent uses of the data structure may misbehave. .\" Subsequent uses of the data structure may misbehave.
.\"
.\" A special case, probably not worth documenting separately, involves .\" .\" A special case, probably not worth documenting separately, involves
.\" reallocing, or even freeing pointers. Any case involving free could .\" .\" reallocing, or even freeing pointers. Any case involving free could
.\" be easily turned into an ac-safe leak by resetting the pointer before .\" .\" be easily turned into an ac-safe leak by resetting the pointer before
.\" releasing it; I don't think we have any case that calls for this sort .\" .\" releasing it; I don't think we have any case that calls for this sort
.\" of fixing. Fixing the realloc cases would require a new interface: .\" .\" of fixing. Fixing the realloc cases would require a new interface:
.\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce .\" .\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce
.\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before .\" .\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before
.\" releasing the old memory. The ac-unsafe realloc could be implemented .\" .\" releasing the old memory. The ac-unsafe realloc could be implemented
.\" in terms of an internal interface with this semantics (say .\" .\" in terms of an internal interface with this semantics (say
.\" __acsafe_realloc), but since realloc can be overridden, the function .\" .\" __acsafe_realloc), but since realloc can be overridden, the function
.\" we call to implement realloc should not be this internal interface, .\" .\" we call to implement realloc should not be this internal interface,
.\" but another internal interface that calls __acsafe_realloc if realloc .\" .\" but another internal interface that calls __acsafe_realloc if realloc
.\" was not overridden, and calls the overridden realloc with async .\" .\" was not overridden, and calls the overridden realloc with async
.\" cancel disabled. --lxoliva .\" .\" cancel disabled. --lxoliva
.TP .\" .TP
.I heap .\" .I heap
Functions marked with .\" Functions marked with
.I heap .\" .I heap
may call heap memory management functions from the .\" may call heap memory management functions from the
.BR malloc (3)/ free (3) .\" .BR malloc (3)/ free (3)
family of functions and are only as safe as those functions. .\" family of functions and are only as safe as those functions.
This note is thus equivalent to: .\" This note is thus equivalent to:
.\"
| AS-Unsafe lock | AC-Unsafe lock fd mem | .\" | AS-Unsafe lock | AC-Unsafe lock fd mem |
.\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} .\" .\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
.\" .\" .\"
.\" Check for cases that should have used plugin instead of or in .\" .\" Check for cases that should have used plugin instead of or in
.\" addition to this. Then, after rechecking gettext, adjust i18n if .\" .\" addition to this. Then, after rechecking gettext, adjust i18n if
.\" needed. .\" .\" needed.
.TP .\" .TP
.I dlopen .\" .I dlopen
Functions marked with .\" Functions marked with
.I dlopen .\" .I dlopen
use the dynamic loader to load .\" use the dynamic loader to load
shared libraries into the current execution image. .\" shared libraries into the current execution image.
This involves opening files, mapping them into memory, .\" This involves opening files, mapping them into memory,
allocating additional memory, resolving symbols, .\" allocating additional memory, resolving symbols,
applying relocations and more, .\" applying relocations and more,
all of this while holding internal dynamic loader locks. .\" all of this while holding internal dynamic loader locks.
.\"
The locks are enough for these functions to be AS- and AC-Unsafe, .\" The locks are enough for these functions to be AS- and AC-Unsafe,
but other issues may arise. .\" but other issues may arise.
At present this is a placeholder for all .\" At present this is a placeholder for all
potential safety issues raised by .\" potential safety issues raised by
.BR dlopen (3). .\" .BR dlopen (3).
.\"
.\" dlopen runs init and fini sections of the module; does this mean .\" .\" dlopen runs init and fini sections of the module; does this mean
.\" dlopen always implies plugin? .\" .\" dlopen always implies plugin?
.TP .\" .TP
.I plugin .\" .I plugin
Functions annotated with .\" Functions annotated with
.I plugin .\" .I plugin
may run code from plugins that .\" may run code from plugins that
may be external to the GNU C Library. .\" may be external to the GNU C Library.
Such plugin functions are assumed to be .\" Such plugin functions are assumed to be
MT-Safe, AS-Unsafe and AC-Unsafe. .\" MT-Safe, AS-Unsafe and AC-Unsafe.
Examples of such plugins are stack unwinding libraries, .\" Examples of such plugins are stack unwinding libraries,
name service switch (NSS) and character set conversion (iconv) back-ends. .\" name service switch (NSS) and character set conversion (iconv) back-ends.
.\"
Although the plugins mentioned as examples are all brought in by means .\" Although the plugins mentioned as examples are all brought in by means
of dlopen, the .\" of dlopen, the
.I plugin .\" .I plugin
keyword does not imply any direct .\" keyword does not imply any direct
involvement of the dynamic loader or the .\" involvement of the dynamic loader or the
.I libdl .\" .I libdl
interfaces, .\" interfaces,
those are covered by .\" those are covered by
.IR dlopen . .\" .IR dlopen .
For example, if one function loads a module and finds the addresses .\" For example, if one function loads a module and finds the addresses
of some of its functions, .\" of some of its functions,
while another just calls those already-resolved functions, .\" while another just calls those already-resolved functions,
the former will be marked with .\" the former will be marked with
.IR dlopen , .\" .IR dlopen ,
whereas the latter will get the .\" whereas the latter will get the
.IR plugin . .\" .IR plugin .
When a single function takes all of these actions, then it gets both marks. .\" When a single function takes all of these actions, then it gets both marks.
.TP .\" .TP
.I i18n .\" .I i18n
Functions marked with .\" Functions marked with
.I i18n .\" .I i18n
may call internationalization .\" may call internationalization
functions of the .\" functions of the
.BR gettext (3) .\" .BR gettext (3)
family and will be only as safe as those .\" family and will be only as safe as those
functions. .\" functions.
This note is thus equivalent to: .\" This note is thus equivalent to:
.\"
| MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt | .\" | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt |
.\"
.\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} .\" .\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}}
.TP .\" .TP
.I timer .\" .I timer
Functions marked with .\" Functions marked with
.I timer .\" .I timer
use the .\" use the
.BR alarm (3) .\" .BR alarm (3)
function or .\" function or
similar to set a time-out for a system call or a long-running operation. .\" similar to set a time-out for a system call or a long-running operation.
In a multi-threaded program, there is a risk that the time-out signal .\" In a multi-threaded program, there is a risk that the time-out signal
will be delivered to a different thread, .\" will be delivered to a different thread,
thus failing to interrupt the intended thread. .\" thus failing to interrupt the intended thread.
Besides being MT-Unsafe, such functions are always .\" Besides being MT-Unsafe, such functions are always
AS-Unsafe, because calling them in signal handlers may interfere with .\" AS-Unsafe, because calling them in signal handlers may interfere with
timers set in the interrupted code, and AC-Unsafe, .\" timers set in the interrupted code, and AC-Unsafe,
because there is no safe way to guarantee an earlier timer .\" because there is no safe way to guarantee an earlier timer
will be reset in case of asynchronous cancellation. .\" will be reset in case of asynchronous cancellation.
.\" .\"
.\" .\"
.SS Conditionally safe features .SS Conditionally safe features