Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006018OCamldocumentationpublic2013-05-22 15:162015-12-11 19:19
Assigned To 
PrioritynormalSeverityminorReproducibilityhave not tried
StatusclosedResolutionno change required 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0006018: Signalhandling not detailed enough: sigaction(2) not mentioned anywhere
DescriptionThe reliable Unix signals need the function sigaction(2) to install the signal-related action.
sigaction(2) is one of the signal functions, accompanied by sigprocmask(2), sigsuspend(2), sigpending(2).

In the doc for the Unix-module, there is only mentioned, that signal numbers must be taken from Sys-module, and that signal handlers also will be set via Sys-module.

When reading the description in Sys-module it is also not mentioned that sigaction(2) is used.

So, when looking only at the docs for Sys- and Unix-module, it is not clear if signal(2) or sigaction(2) is used to establish the signal handler.

Someone coming from the C-world will miss sigaction(2) at least to be mentioned. That it is used as "hidden magic" under the hood of Sys-module is not enough, IMHO.
sigpending(2) and the other signal-functions are also available in Unix-module.

So it would be more consequently (from the Unix-systems view) to also make sigaction(2) available in Unix-module.

To have all signal-installation handling in Sys-module also makes sense somehow (regarding platform-independence), but then it should be mentioned that sigaction(2) is used in case of Unix-systems via the Sys-module. (This is not so consequently regarding platform-seperation, because Unix-stuff should belong to Unix-module).

The state of the docs and implementation looks like a compromise between platform-independence in usage of the modules vs. platform-seperation.
Put signal-installation into Sys independent of platform makes sense; seperate Unixoid systemhandler-installation intto Unix-module also makes sense.
So, the way it is done at the moment, is ok from a certain point of view.

But in in both cases, the documentation need to mention sigaction(2) somehow, somewhere; otherwise switching from C to OCaml can be confusing at this point.

Something like:
  "OCaml is weird, it has sigprocmask(2) and sigpending(2) and so on, but does
   not provide sigaction(2). Can this be seen as a reliable language?
   Is there some hidden sigaction(2) magic? If so, it might be seen as
   reliable, but weird."
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
xleroy (administrator)
2013-06-10 15:15

This looks like a fine hair being split.

All POSIX-compliant systems define signal() [from the C standard library] on top of sigaction() [from POSIX].

Likewise, OCaml defines Sys.signal in terms of sigaction() on POSIX hosts and of signal() on other hosts. We're not stupid.

oliver (reporter)
2013-06-11 00:20

I did not said, you are stupid.
Contrary... I think the OCaml core developers are very intelligent and did good work.

But the problem between signal() and sigaction()/sigprocmask()/...
is mentioned in W.R. Stevens' "Advanced Programming in the Unix Environment", a fundamental book on unix programming, as you surely know.

So, who read that book and did programming in C, then switch to OCaml, will miss sigaction()-call.

This is especially, because the other calls, like sigprocmask() are not also
hidden by OCaml abstractions.
So on the one hand sigaction() is abstracted away, on the other hand, the other functions are available.

And regarding the Stevens' book (which I think even today is some kind of reference), this IMHO does not look like "a fine hair being split".

It would be just some sentences in the documentation.

- Issue History
Date Modified Username Field Change
2013-05-22 15:16 oliver New Issue
2013-06-10 15:15 xleroy Note Added: 0009453
2013-06-10 15:15 xleroy Status new => resolved
2013-06-10 15:15 xleroy Resolution open => no change required
2013-06-11 00:20 oliver Note Added: 0009454
2015-12-11 19:19 xleroy Status resolved => closed
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker