fsetown(9) [netbsd man page]

FSETOWN(9)						   BSD Kernel Developer's Manual						FSETOWN(9)

NAME

     fsetown, fgetown, fownsignal -- file descriptor owner handling functions

SYNOPSIS

     #include <sys/file.h>

     int
     fsetown(struct lwp *l, pid_t *pgid, int cmd, const void *data);

     int
     fgetown(struct lwp *l, pid_t pgid, int cmd, void *data);

     void
     fownsignal(pid_t pgid, int signo, int code, int band, void *fdescdata);

DESCRIPTION

     These functions handle file descriptor owner related ioctls and related signal delivery.  Device drivers and other parts of the kernel call
     these functions from ioctl entry functions or I/O notification functions.

     fsetown() sets the owner of file.	cmd is an ioctl command, one of SIOCSPGRP, FIOSETOWN, and TIOCSPGRP.  data is interpreted as a pointer to
     a signed integer, the integer being the ID of the owner.  The cmd determines how exactly data should be interpreted.  If cmd is TIOCSPGRP,
     the ID needs to be positive and is interpreted as process group ID.  For SIOCSPGRP and FIOSETOWN, the passed ID is the process ID if posi-
     tive, or the process group ID if negative.

     fgetown() returns the current owner of the file.  cmd is an ioctl command, one of SIOCGPGRP, FIOGETOWN, and TIOCGPGRP.  data is interpreted
     as a pointer to a signed integer, and the value is set according to the passed cmd.  For TIOCGPGRP, the returned data value is positive
     process group ID if the owner is the process group, or negative process ID if the owner is a process.  For other ioctls, the returned value
     is the positive process ID if the owner is a process, or the negative process group ID if the owner is a process group.

     fownsignal() schedules the signo signal to be sent to the current file descriptor owner.  The signals typically used with this function are
     SIGIO and SIGURG.	The code and band arguments are sent along with the signal as additional signal specific information if SA_SIGINFO is
     activated.  If the information is not available from the context of the fownsignal() call, these should be passed as zero.  fdescdata is used
     to lookup the file descriptor for SA_SIGINFO signals.  If it is specified, the file descriptor number is sent along with the signal as addi-
     tional signal specific information.  If file descriptor data pointer is not available in the context of the fownsignal() call, NULL should be
     used instead.

     Note that a fcntl(2) F_SETOWN request is translated by the kernel to a FIOSETOWN ioctl, and F_GETOWN is translated to FIOGETOWN.  This is
     done transparently by generic code, before the device- or subsystem-specific ioctl entry function is called.

SEE ALSO

     fcntl(2), siginfo(2), signal(7), ioctl(9), signal(9)

HISTORY

     These kernel functions appeared in NetBSD 2.0.

BSD
								 December 20, 2005							       BSD

IOCTL(2)						      BSD System Calls Manual							  IOCTL(2)

NAME

     ioctl -- control device

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <sys/ioctl.h>

     int
     ioctl(int d, unsigned long request, ...);

DESCRIPTION

     The ioctl() function manipulates the underlying device parameters of special files.  In particular, many operating characteristics of charac-
     ter special files (e.g. terminals) may be controlled with ioctl() requests.  The argument d must be an open file descriptor.

     An ioctl() request has encoded in it whether the argument is an ``in'', ``out'', or ``inout'' parameter, and the size of the first variadic
     argument in bytes.  Note that there can be only one variadic argument but cannot be represented as a void * argument in the prototype because
     this would require a cast to pass integral types without warnings.  Macros and defines used in specifying an ioctl() request are located in
     the header <sys/ioctl.h>.

GENERIC IOCTLS

     Some ioctls are applicable to any file descriptor.  These include:

     FIOCLEX
	     Set close-on-exec flag.  The file will be closed when exec(3) is invoked (This is equivalent to fcntl() F_SETFD FD_CLOEXEC and the
	     fcntl() form should be preferred).

     FIONCLEX
	     Clear close-on-exec flag.	The file will remain open across exec(3) (This is equivalent to fcntl() F_SETFD 0 and the fcntl() form
	     should be preferred).

     Some generic ioctls are not implemented for all types of file descriptors.  These include:

     FIONREAD int
	     Get the number of bytes that are immediately available for reading.

     FIONWRITE int
	     Get the number of bytes in the descriptor's send queue.  These bytes are data which has been written to the descriptor but which are
	     being held by the kernel for further processing.  The nature of the required processing depends on the underlying device.	For tty
	     devices, these bytes are typically queued for delivery to the tty hardware.  For TCP sockets, these bytes have not yet been acknowl-
	     edged by the other side of the connection.  For files, this operation always returns zero as files do not have send queues.

     FIONSPACE int
	     Get the free space in the descriptor's send queue.  This value is the size of the send queue minus the number of bytes being held in
	     the queue.  Note: while this value represents the number of bytes that may be added to the queue, other resource limitations may
	     cause a write not larger than the send queue's space to be blocked.  One such limitation would be a lack of network buffers for a
	     write to a network connection.

     FIONBIO int
	     Set non-blocking I/O mode if the argument is non-zero.  In non-blocking mode, read(2) or write(2) calls return -1 and set errno to
	     EAGAIN immediately when no data is available (This is equivalent to fcntl() F_SETFL O_NONBLOCK and the fcntl() form should be pre-
	     ferred).

     FIOASYNC int
	     Set asynchronous I/O mode if the argument is non-zero (This is equivalent to fcntl() F_SETFL O_ASYNC and the fcntl() form should be
	     preferred).  In asynchronous mode, the process or process group specified by FIOSETOWN will start receiving SIGIO signals when data
	     is available.  The SIGIO signal will be delivered when data is available on the file descriptor.

     FIOSETOWN, FIOGETOWN int
	     Set/get the process or the process group (if negative) that should receive SIGIO signals when data is available (This is equivalent
	     to fcntl() F_SETOWN pid_t and the fcntl form should be preferred).

RETURN VALUES

     If an error has occurred, a value of -1 is returned and errno is set to indicate the error.

ERRORS

     ioctl() will fail if:

     [EBADF]		d is not a valid descriptor.

     [EFAULT]		argp points outside the process's allocated address space.

     [EINVAL]		request or argp is not valid.

     [ENOTTY]		d is not associated with a character special device; or the specified request does not apply to the kind of object that
			the descriptor d references.

SEE ALSO

     mt(1), execve(2), fcntl(2), intro(4), tty(4)

HISTORY

     An ioctl() function call appeared in Version 7 AT&T UNIX.

BSD
								 December 19, 2010							       BSD