# F_GETSIG

## NAME



           F_GETOWN, F_SETOWN, F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, F_SETSIG -
           managing signals
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <fcntl.h>**
    
           **int fcntl(int** _fd_**, F_GETOWN);**
           **int fcntl(int** _fd_**, F_SETOWN, int** _arg_**);**
    
           **#define _GNU_SOURCE**
           **#include <fcntl.h>**
    
           **int fcntl(int** _fd_**, F_GETOWN_EX, struct f_owner_ex ***_arg_**);**
           **int fcntl(int** _fd_**, F_SETOWN_EX, const struct f_owner_ex ***_arg_**);**
           **int fcntl(int** _fd_**, F_GETSIG);**
           **int fcntl(int** _fd_**, F_SETSIG, int** _arg_**);**
    


## DESCRIPTION



           **F_GETOWN** , **F_SETOWN** , **F_GETOWN_EX** , **F_SETOWN_EX** , **F_GETSIG** , and
           **F_SETSIG** are used to manage I/O availability signals:
    
           **F_GETOWN**
                  Return (as the function result) the process ID or process
                  group ID currently receiving **SIGIO** and **SIGURG** signals for
                  events on file descriptor _fd_.  Process IDs are returned as
                  positive values; process group IDs are returned as negative
                  values (but see BUGS below).  _arg_ is ignored.
    
           **F_SETOWN**
                  Set the process ID or process group ID that will receive
                  **SIGIO** and **SIGURG** signals for events on the file descriptor
                  _fd_.  The target process or process group ID is specified in
                  _arg_.  A process ID is specified as a positive value; a
                  process group ID is specified as a negative value.  Most
                  commonly, the calling process specifies itself as the owner
                  (that is, _arg_ is specified as getpid(2)).
    
                  As well as setting the file descriptor owner, one must also
                  enable generation of signals on the file descriptor.  This
                  is done by using the F_SETFL(2const) operation to set the
                  **O_ASYNC** file status flag on the file descriptor.
                  Subsequently, a **SIGIO** signal is sent whenever input or
                  output becomes possible on the file descriptor.  The
                  **fcntl**() **F_SETSIG** operation can be used to obtain delivery
                  of a signal other than **SIGIO**.
    
                  Sending a signal to the owner process (group) specified by
                  **F_SETOWN** is subject to the same permissions checks as are
                  described for kill(2), where the sending process is the one
                  that employs **F_SETOWN**(but see BUGS below).  If this
                  permission check fails, then the signal is silently
                  discarded.  _Note_ : The **F_SETOWN** operation records the
                  caller's credentials at the time of the **fcntl**() call, and
                  it is these saved credentials that are used for the
                  permission checks.
    
                  If the file descriptor _fd_ refers to a socket, **F_SETOWN** also
                  selects the recipient 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 condition".)
    
                  The following was true in Linux 2.6.x up to and including
                  Linux 2.6.11:
    
                         If a nonzero value is given to **F_SETSIG** in a
                         multithreaded process running with a threading
                         library that supports thread groups (e.g., NPTL),
                         then a positive 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(2) instead of getpid(2) 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(2) or getpid(2) 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**.
    
                  The above behavior was accidentally dropped in Linux
                  2.6.12, and won't be restored.  From Linux 2.6.32 onward,
                  use **F_SETOWN_EX** to target **SIGIO** and **SIGURG** signals at a
                  particular thread.
    
           **F_GETOWN_EX**
                  Return the current file descriptor owner settings as
                  defined by a previous **F_SETOWN_EX** operation.  The
                  information is returned in the structure pointed to by _arg_ ,
                  which has the following form:
    
                      struct f_owner_ex {
                          int   type;
                          pid_t pid;
                      };
    
                  The _type_ field will have one of the values **F_OWNER_TID** ,
                  **F_OWNER_PID** , or **F_OWNER_PGRP**.  The _pid_ field is a positive
                  integer representing a thread ID, process ID, or process
                  group ID.  See **F_SETOWN_EX** for more details.
    
           **F_SETOWN_EX**
                  This operation performs a similar task to **F_SETOWN**.  It
                  allows the caller to direct I/O availability signals to a
                  specific thread, process, or process group.  The caller
                  specifies the target of signals via _arg_ , which is a pointer
                  to a _f_owner_ex_ structure.  The _type_ field has one of the
                  following values, which define how _pid_ is interpreted:
    
                  **F_OWNER_TID**
                         Send the signal to the thread whose thread ID (the
                         value returned by a call to clone(2) or gettid(2))
                         is specified in _pid_.
    
                  **F_OWNER_PID**
                         Send the signal to the process whose ID is specified
                         in _pid_.
    
                  **F_OWNER_PGRP**
                         Send the signal to the process group whose ID is
                         specified in _pid_.  (Note that, unlike with **F_SETOWN** ,
                         a process group ID is specified as a positive value
                         here.)
    
           **F_GETSIG**
                  Return (as the function result) the signal sent when input
                  or output becomes possible.  A value of zero means **SIGIO** is
                  sent.  Any other value (including **SIGIO**) is the signal sent
                  instead, and in this case additional info is available to
                  the signal handler if installed with **SA_SIGINFO**.  _arg_ is
                  ignored.
    
           **F_SETSIG**
                  Set the signal sent when input or output becomes possible
                  to the value given in _arg_.  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**.
    
                  By using **F_SETSIG** with a nonzero value, and setting
                  **SA_SIGINFO** for the signal handler (see sigaction(2)), extra
                  information about I/O events is passed to the handler in a
                  _siginfo_t_ structure.  If the _si_code_ field indicates the
                  source is **SI_SIGIO** , the _si_fd_ field gives the file
                  descriptor associated with the event.  Otherwise, there is
                  no indication which file descriptors are pending, and you
                  should use the usual mechanisms (select(2), poll(2),
                  read(2) with **O_NONBLOCK** set etc.) to determine which file
                  descriptors are available for I/O.
    
                  Note that the file descriptor provided in _si_fd_ is the one
                  that was specified during the **F_SETSIG** operation.  This can
                  lead to an unusual corner case.  If the file descriptor is
                  duplicated (dup(2) or similar), and the original file
                  descriptor is closed, then I/O events will continue to be
                  generated, but the _si_fd_ field will contain the number of
                  the now closed file descriptor.
    
                  By selecting a real time signal (value >= **SIGRTMIN**),
                  multiple I/O events may be queued using the same signal
                  numbers.  (Queuing is dependent on available memory.)
                  Extra information is available if **SA_SIGINFO** is set for the
                  signal handler, as above.
    
                  Note that Linux imposes a limit on the number of real-time
                  signals that may be queued to a process (see getrlimit(2)
                  and 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 specific
                  thread.
    
           Using these mechanisms, a program can implement fully asynchronous
           I/O without using select(2) or poll(2) most of the time.
    
           The use of **O_ASYNC** is specific to BSD and Linux.  The only use of
           **F_GETOWN** and **F_SETOWN** specified in POSIX.1 is in conjunction with
           the use of the **SIGURG** signal on sockets.  (POSIX does not specify
           the **SIGIO** signal.)  **F_GETOWN_EX** , **F_SETOWN_EX** , **F_GETSIG** , and
           **F_SETSIG** are Linux-specific.  POSIX has asynchronous I/O and the
           _aio_sigevent_ structure to achieve similar things; these are also
           available in Linux as part of the GNU C Library (glibc).
    


## RETURN VALUE



           See fcntl(2).
    
           **F_GETOWN**
                  Value of file descriptor owner.
    
           **F_GETSIG**
                  Value of signal sent when read or write becomes possible,
                  or zero for traditional **SIGIO** behavior.
    
           **F_SETOWN**
           **F_GETOWN_EX**
           **F_SETOWN_EX**
           **F_SETSIG**
                  Zero.
    
           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## ERRORS



           See fcntl(2).
    
           **EINVAL** _op_ is **F_SETSIG** and _arg_ is not an allowable signal number.
    


## STANDARDS



           **F_GETOWN**
           **F_SETOWN**
                  POSIX.1-2008.
    
           **F_GETOWN_EX**
           **F_SETOWN_EX**
           **F_GETSIG**
           **F_SETSIG**
                  Linux.  (Define the **_GNU_SOURCE** macro to obtain these
                  definitions.)
    


## BUGS



       **F_GETOWN**
           A limitation of the Linux system call conventions on some
           architectures (notably i386) means that if a (negative) process
           group ID to be returned by **F_GETOWN** falls in the range -1 to
           -4095, then the return value is wrongly interpreted by glibc as an
           error in the system call; that is, the return value of **fcntl**()
           will be -1, and _errno_ will contain the (positive) process group
           ID.  The Linux-specific **F_GETOWN_EX** operation avoids this problem.
           Since glibc 2.11, glibc makes the kernel **F_GETOWN** problem
           invisible by implementing **F_GETOWN** using **F_GETOWN_EX**.
    
       **F_SETOWN**
           In Linux 2.4 and earlier, there is bug that can occur when an
           unprivileged process uses **F_SETOWN** to specify the owner of a
           socket file descriptor as a process (group) other than the caller.
           In this case, **fcntl**() can return -1 with _errno_ set to **EPERM** , even
           when the owner process (group) is one that the caller has
           permission to send signals to.  Despite this error return, the
           file descriptor owner is set, and signals will be sent to the
           owner.
    


* * *