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

Date: Fri, 28 Jan 2005 11:00:59 +0000 

From: Jamie Lokier <jamie@shareable.org>
To: mtk-manpages@gmx.net
Subject: Update to fcntl(2) man page

Hi Michael,

I have a correction to the fcntl(2) man page.

Under the section for F_SETOWN, which describes how to set the
recipient process or group for SIGIO signals, see this paragraph:

	The process or process  group  to  receive  the  signal  can  be
	selected  by  using  the F_SETOWN command to the fcntl function.
	If the file descriptor is a socket, this also selects the recip-
	ient  of SIGURG signals that are delivered when out-of-band data
	arrives on that socket.  (SIGURG is sent in any situation  where
	select(2) would report the socket as having an "exceptional con-
	dition".)  If the file  descriptor  corresponds  to  a  terminal
	device,  then  SIGIO  signals are sent to the foreground process
	group of the terminal.

I would like to add an additional paragraph:

	The value given to F_SETOWN has a slightly different meaning
	when F_SETSIG is used in a multi-threaded process.

	If a non-zero value is given to F_SETSIG, then a positive
	value given to F_SETOWN identifies a specific thread within a
	process, instead of a whole process.  The value is a thread id
	not a process id, so you may need to pass the result of
	gettid() instead of getpid() to get sensible results when
	F_SETSIG is used.  (Thread ids are different from process ids,
	although they have the same value for some threads depending
	on details of the threading library used).

Also, this is the first paragraph of the F_SETSIG section:

	Sets the signal sent when input or output becomes  possible.   A
	value of zero means to send the default SIGIO signal.  Any other
	value (including SIGIO) is the signal to send  instead,  and  in
	this  case additional info is available to the signal handler if
	installed with SA_SIGINFO.

I'd like to append another paragraph right after that one:

	Additionally, passing a non-zero value to F_SETSIG changes the
	signal recipient from a whole process to a specific thread
	within a process.  The section on F_SETOWN gives more details.


Date: Thu, 7 Apr 2005 17:58:59 +0100
From: Jamie Lokier <jamie@shareable.org>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Subject: Re: Update to fcntl(2) man page

[[...]]

> I've been trying to follow the kernel source code to verify
> the details you describe above.  The relevant place is the 
> 'switch' in fs/fcntl.c::send_sigio_to_task() right?

Yes.

> Also, for NPTL, perhaps one needs to mention that for the main
> thread, gettid() == getpid(), which allows the traditional
> use of F_SETSIG / F_SETOWN in programs consisting of a single
> thread -- right?

Yes, that makes sense.  It's also fine for the "main thread" with
NPTL, so programs which spawn threads can still use F_SETOWN/F_SETSIG
in the main thread using getpid().


Date: Tue, 12 Apr 2005 15:25:49 +0100
From: Jamie Lokier <jamie@shareable.org>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Subject: Re: Update to fcntl(2) man page

Michael Kerrisk wrote:
>   F_SETOWN
>          Set  the  process ID or process group ID that will
>          receive SIGIO and SIGURG  signals  for  events  on
>          file  descriptor fd.  A process ID is specified as
>          a positive value; a process group ID is  specified
>          as a negative value.
> 
>          If  you  set  the  O_ASYNC  status  flag on a file
>          descriptor (either by providing this flag with the
>          open(2)  call,  or by using the F_SETFL command of
>          fcntl), a SIGIO signal is sent whenever  input  or
>          output  becomes  possible on that file descriptor.
>          F_SETSIG can be used to obtain delivery of a  sig&#8208;
>          nal other than SIGIO.
> 
>          If  the  file  descriptor  fd  refers to a socket,
>          F_SETOWN also selects the recipient of SIGURG sig&#8208;
>          nals  that  are  delivered  when  out-of-band data
>          arrives on that socket.  (SIGURG is  sent  in  any
>          situation  where select(2) would report the socket
>          as having an "exceptional condition".)
> 
>          If a non-zero value is  given  to  F_SETSIG  in  a
>          multi-threaded  process,  then  a  positive  value
>          value given to F_SETOWN has a  different  meaning:
>          instead  of being a process ID identifying a whole
>          process, it is a thread ID identifying a  specific
>          thread  within a process.  Consequently, it may be
>          necessary to pass F_SETOWN the result of  gettid()
>          instead  of  getpid() to get sensible results when
>          F_SETSIG is used.   (In  current  Linux  threading
>          implementations,  a main thread's thread ID is the
>          same as its process ID.  This means that a single-
>          threaded  program can equally use gettid() or get&#8208;
>          pid() in this scenario.)  Note, however, that  the
>          statements  in  this paragraph do not apply to the
>          SIGURG signal generated for out-of-band data on  a
>          socket:  this  signal  is  always sent to either a
>          process or a process group, depending on the value
>          given to F_SETOWN.
> 
> And the first part of the description of F_SETSIG now reads:
> 
>   F_SETSIG
>          Sets the signal sent when input or output  becomes
>          possible.   A  value  of  zero  means  to send the
>          default SIGIO signal.  Any other value  (including
>          SIGIO)  is the signal to send instead, and in this
>          case additional info is available  to  the  signal
>          handler if installed with SA_SIGINFO.
> 
>          Additionally, passing a non-zero value to F_SETSIG
>          changes the signal recipient from a whole  process
>          to  a  specific  thread within a process.  See the
>          desciption of F_SETOWN for more details.
> 
> Does the above seem okay to you?

It looks good, but: 

  1. An omission: It mentions that SIGURG is always sent to the whole
     process.  SIGIO is also sent to the whole process, instead of
     queueing a thread-specific signal, when the signal queue is full.
     Programs that mustn't miss readiness events need to handle it.

  2. The description could be confusing to LinuxThreads users, because
     all the signals are thread-specific in LinuxThreads.


Date: Tue, 12 Apr 2005 16:53:19 +0100
From: Jamie Lokier <jamie@shareable.org>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Subject: Re: Update to fcntl(2) man page

Michael Kerrisk wrote:
> >   1. An omission: It mentions that SIGURG is always sent to the whole
> >      process.  SIGIO is also sent to the whole process, instead of
> >      queueing a thread-specific signal, when the signal queue is full.
> >      Programs that mustn't miss readiness events need to handle it.
> 
> Sorry -- can you point me to the relevant code for the 
> above point please.

In 2.6:

	switch (fown->signum) {
		siginfo_t si;
		default:
			/* Queue a rt signal with the appropriate fd as its
			   value.  We use SI_SIGIO as the source, not 
			   SI_KERNEL, since kernel signals always get 
			   delivered even if we can't queue.  Failure to
			   queue in this case _should_ be reported; we fall
			   back to SIGIO in that case. --sct */
			si.si_signo = fown->signum;
			si.si_errno = 0;
		        si.si_code  = reason;
			/* Make sure we are called with one of the POLL_*
			   reasons, otherwise we could leak kernel stack into
			   userspace.  */
			if ((reason & __SI_MASK) != __SI_POLL)
				BUG();
			if (reason - POLL_IN >= NSIGPOLL)
				si.si_band  = ~0L;
			else
				si.si_band = band_table[reason - POLL_IN];
			si.si_fd    = fd;
			if (!send_sig_info(fown->signum, &si, p))
				break;
		/* fall-through: fall back on the old plain SIGIO signal */
		case 0:
			send_group_sig_info(SIGIO, SEND_SIG_PRIV, p);

2.4 is exactly the same, except:

		/* fall-through: fall back on the old plain SIGIO signal */
		case 0:
			send_sig(SIGIO, p, 1);

The fall-through happens when send_sig_info() fails, which happens
when the real-time signal queue is full.

Programs using a queued signal to track file readiness efficiently (as
an alternative to select/poll), must listen for SIGIO in addition to
the real-time signal, as otherwise they will miss notifications when
the queue is full (which happens often on a busy server).

Multi-threaded programs using NPTL must be aware this SIGIO is
process-wide - so receiving it on one thread must cause all threads to
assume a queued signal may be lost.  Programs using LinuxThreads do
not have to assume this (but it's safe if they do).


Date: Wed, 13 Apr 2005 17:25:44 +0100
From: Jamie Lokier <jamie@shareable.org>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Subject: Re: Update to fcntl(2) man page

Michael Kerrisk wrote:
> I added a few more sentences to the end of that paragraph
> on F_SETOWN:
> 
>     If a non-zero value is given  to  F_SETSIG  in  a multi-threaded
>     process  running with  a threading  library that supports thread
>     groups (e.g., NPTL),  then  a  positive  value  value  given to
>     F_SETOWN has a different meaning: instead  of being a process ID
>     identifying a whole  process, it is a  thread  ID identifying  a
>     specific thread  within a process.  Consequently, it may be nec-
>     essary to pass  F_SETOWN the result of gettid() instead  of  get
>     pid() to  get sensible results  when F_SETSIG is used.  (In cur-
>     rent Linux threading implementations, a main thread's thread  ID
>     is  the  same  as  its  process  ID.   This means that a single-
>     threaded program can equally use gettid() or  getpid()  in  this
>     scenario.)  Note, however, that the statements in this paragraph
>     do not apply to the SIGURG signal generated for out-of-band data
>     on a socket: this signal is always sent to either a process or a
>     process group, depending on the value given to  F_SETOWN.   Note
>     also  that Linux imposes a limit on the number of real-time sig-
>     nals that may be queued to a process (see getrlimit(2) and  sig-
>     nal(7)) and if this limit is reached, then the kernel reverts to
>     delivering SIGIO, and  this  signal is  delivered to the  entire 
>     process rather than to a specifc thread.
> 
> Look oay now?

Looks ood.

It will take a minor genius to translate that to working
multi-threaded RT-SIGIO code without a tutorial -- and in fact I
haven't heard of any program or library which does it (though I'm
trying to write one) -- but technically it seems to include everything.
This commit is contained in:
Michael Kerrisk 2005-04-05 05:54:09 +00:00
parent b6ac53546a
commit 7c088cb1d8
1 changed files with 17 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
man2/fcntl.2
View File

@ -385,7 +385,9 @@ would report the socket as having an "exceptional condition".)
If a non-zero value is given to
.B F_SETSIG
in a multi-threaded process, then a positive value value given to
in a multi-threaded process running with a threading library
that supports thread groups (e.g., NPTL),
then a positive value value given to
.B F_SETOWN
has a different meaning:
.\" The relevant place in the (2.6) kernel source is the
@ -417,6 +419,16 @@ depending on the value given to
.\" kill_fasync()/send_sigio()/send_sigio_to_task()
.\" to directly call send_group_sig_info()
.\" -- MTK, Apr 2005 (kernel 2.6.11)
Note also that Linux imposes a limit on the
number of real-time signals that may be queued to a
process (see
.BR getrlimit (2)
and
.BR signal (7))
and if this limit is reached, then the kernel reverts to
delivering SIGIO, and this signal is delivered to the entire
process rather than to a specifc thread.
.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05
.TP
.B F_GETSIG
Get the signal sent when input or output becomes possible. A value of
@ -802,14 +814,13 @@ will be \-1, and
will contain the (positive) process group ID.
.\" FIXME Dec 04: some limited testing on alpha and ia64 seems to
.\" indicate that ANY negative PGID value will cause F_GETOWN
.\" to misintepret the return as an error.Some other architectures
.\" to misintepret the return as an error. Some other architectures
.\" seem to have the same range check as x86. -- MTK
.SH "CONFORMING TO"
SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD,
F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are
specified in POSIX.1. F_GETOWN and F_SETOWN are BSDisms not supported
in SVr4; F_GETSIG and F_SETSIG are specific to Linux.
.BR F_NOTIFY ", " F_GETLEASE ", and " F_SETLEASE
F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW,
F_GETOWN, and F_SETOWN are specified in POSIX.1.
F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE, and F_SETLEASE
are Linux specific.
(Define the _GNU_SOURCE macro before including <fcntl.h> to
obtain these definitions.)