STAT(2)                                         Linux Programmer’s Manual                                         STAT(2)



NAME
       stat, fstat, lstat - get file status

SYNOPSIS
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <unistd.h>

       int stat(const char *path, struct stat *buf);
       int fstat(int fd, struct stat *buf);
       int lstat(const char *path, struct stat *buf);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       lstat(): _BSD_SOURCE || _XOPEN_SOURCE >= 500

DESCRIPTION
       These  functions  return  information  about a file.  No permissions are required on the file itself, but — in the
       case of stat() and lstat() — execute (search) permission is required on all of the directories in path  that  lead
       to the file.

       stat() stats the file pointed to by path and fills in buf.

       lstat()  is  identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the
       file that it refers to.

       fstat() is identical to stat(), except that the file to be stat-ed is specified by the file descriptor fd.

       All of these system calls return a stat structure, which contains the following fields:

           struct stat {
               dev_t     st_dev;     /* ID of device containing file */
               ino_t     st_ino;     /* inode number */
               mode_t    st_mode;    /* protection */
               nlink_t   st_nlink;   /* number of hard links */
               uid_t     st_uid;     /* user ID of owner */
               gid_t     st_gid;     /* group ID of owner */
               dev_t     st_rdev;    /* device ID (if special file) */
               off_t     st_size;    /* total size, in bytes */
               blksize_t st_blksize; /* blocksize for file system I/O */
               blkcnt_t  st_blocks;  /* number of 512B blocks allocated */
               time_t    st_atime;   /* time of last access */
               time_t    st_mtime;   /* time of last modification */
               time_t    st_ctime;   /* time of last status change */
           };

       The st_dev field describes the device on which this file resides.  (The major(3) and minor(3) macros may be useful
       to decompose the device ID in this field.)

       The st_rdev field describes the device that this file (inode) represents.

       The st_size field gives the size of the file (if it is a regular file or a symbolic link) in bytes.  The size of a
       symlink is the length of the pathname it contains, without a trailing null byte.

       The st_blocks field indicates the number of blocks allocated to the file, 512-byte units.  (This  may  be  smaller
       than st_size/512 when the file has holes.)

       The st_blksize field gives the "preferred" blocksize for efficient file system I/O.  (Writing to a file in smaller
       chunks may cause an inefficient read-modify-rewrite.)

       Not all of the Linux file systems implement all of the time fields.  Some file system types allow mounting in such
       a way that file and/or directory accesses do not cause an update of the st_atime field.  (See noatime, nodiratime,
       and relatime in mount(8), and related information in mount(2).)

       The field st_atime is changed by file accesses, for example, by execve(2), mknod(2), pipe(2), utime(2) and read(2)
       (of more than zero bytes).  Other routines, like mmap(2), may or may not update st_atime.

       The  field st_mtime is changed by file modifications, for example, by mknod(2), truncate(2), utime(2) and write(2)
       (of more than zero bytes).  Moreover, st_mtime of a directory is changed by the creation or deletion of  files  in
       that directory.  The st_mtime field is not changed for changes in owner, group, hard link count, or mode.

       The  field  st_ctime  is changed by writing or by setting inode information (i.e., owner, group, link count, mode,
       etc.).

       The following POSIX macros are defined to check the file type using the st_mode field:

           S_ISREG(m)  is it a regular file?

           S_ISDIR(m)  directory?

           S_ISCHR(m)  character device?

           S_ISBLK(m)  block device?

           S_ISFIFO(m) FIFO (named pipe)?

           S_ISLNK(m)  symbolic link? (Not in POSIX.1-1996.)

           S_ISSOCK(m) socket? (Not in POSIX.1-1996.)

       The following flags are defined for the st_mode field:

           S_IFMT     0170000   bit mask for the file type bit fields
           S_IFSOCK   0140000   socket
           S_IFLNK    0120000   symbolic link
           S_IFREG    0100000   regular file
           S_IFBLK    0060000   block device
           S_IFDIR    0040000   directory
           S_IFCHR    0020000   character device
           S_IFIFO    0010000   FIFO
           S_ISUID    0004000   set UID bit
           S_ISGID    0002000   set-group-ID bit (see below)
           S_ISVTX    0001000   sticky bit (see below)
           S_IRWXU    00700     mask for file owner permissions
           S_IRUSR    00400     owner has read permission
           S_IWUSR    00200     owner has write permission
           S_IXUSR    00100     owner has execute permission
           S_IRWXG    00070     mask for group permissions
           S_IRGRP    00040     group has read permission
           S_IWGRP    00020     group has write permission
           S_IXGRP    00010     group has execute permission
           S_IRWXO    00007     mask for permissions for others (not in group)
           S_IROTH    00004     others have read permission
           S_IWOTH    00002     others have write permission
           S_IXOTH    00001     others have execute permission

       The set-group-ID bit (S_ISGID) has several special uses.  For a directory it indicates that BSD semantics is to be
       used  for  that  directory:  files created there inherit their group ID from the directory, not from the effective
       group ID of the creating process, and directories created there will also get the S_ISGID bit  set.   For  a  file
       that  does  not  have  the group execution bit (S_IXGRP) set, the set-group-ID bit indicates mandatory file/record
       locking.

       The sticky bit (S_ISVTX) on a directory means that a file in that directory can be renamed or deleted only by  the
       owner of the file, by the owner of the directory, and by a privileged process.

RETURN VALUE
       On success, zero is returned.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       EACCES Search  permission is denied for one of the directories in the path prefix of path.  (See also path_resolu‐
              tion(7).)

       EBADF  fd is bad.

       EFAULT Bad address.

       ELOOP  Too many symbolic links encountered while traversing the path.

       ENAMETOOLONG
              File name too long.

       ENOENT A component of the path path does not exist, or the path is an empty string.

       ENOMEM Out of memory (i.e., kernel memory).

       ENOTDIR
              A component of the path is not a directory.

       EOVERFLOW
              (stat()) path refers to a file whose size cannot be represented in the type       off_t.   This  can  occur
              when  an  application  compiled  on a 32-bit platform without -D_FILE_OFFSET_BITS=64 calls stat() on a file
              whose size exceeds (2<<31)-1 bits.

CONFORMING TO
       These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.

       Use of the st_blocks and st_blksize fields may be less portable.  (They were introduced in BSD.   The  interpreta‐
       tion differs between systems, and possibly on a single system when NFS mounts are involved.)

       POSIX  does not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX bits,
       but instead demands the use of the macros S_ISDIR(),  etc.   The  S_ISLNK()  and  S_ISSOCK()  macros  are  not  in
       POSIX.1-1996, but both are present in POSIX.1-2001; the former is from SVID 4, the latter from SUSv2.

       Unix  V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX prescribes the synonyms S_IRUSR, S_IWUSR,
       S_IXUSR.

   Other Systems
       Values that have been (or are) in use on various systems:

       hex    name       ls   octal    description
       f000   S_IFMT          170000   mask for file type
       0000                   000000   SCO out-of-service inode; BSD unknown
                                       type; SVID-v2 and XPG2 have both
                                       0 and 0100000 for ordinary file
       1000   S_IFIFO    p|   010000   FIFO (named pipe)
       2000   S_IFCHR    c    020000   character special (V7)
       3000   S_IFMPC         030000   multiplexed character special (V7)
       4000   S_IFDIR    d/   040000   directory (V7)
       5000   S_IFNAM         050000   XENIX named special file
                                       with two subtypes, distinguished by
                                       st_rdev values 1, 2
       0001   S_INSEM    s    000001   XENIX semaphore subtype of IFNAM
       0002   S_INSHD    m    000002   XENIX shared data subtype of IFNAM
       6000   S_IFBLK    b    060000   block special (V7)
       7000   S_IFMPB         070000   multiplexed block special (V7)
       8000   S_IFREG    -    100000   regular (V7)
       9000   S_IFCMP         110000   VxFS compressed
       9000   S_IFNWK    n    110000   network special (HP-UX)
       a000   S_IFLNK    l@   120000   symbolic link (BSD)
       b000   S_IFSHAD        130000   Solaris shadow inode for ACL
                                       (not seen by userspace)
       c000   S_IFSOCK   s=   140000   socket (BSD; also "S_IFSOC" on VxFS)
       d000   S_IFDOOR   D>   150000   Solaris door

       e000   S_IFWHT    w%   160000   BSD whiteout (not used for inode)
       0200   S_ISVTX         001000   sticky bit: save swapped text even
                                       after use (V7)
                                       reserved (SVID-v2)
                                       On non-directories: don’t cache this
                                       file (SunOS)
                                       On directories: restricted deletion
                                       flag (SVID-v4.2)
       0400   S_ISGID         002000   set-group-ID on execution (V7)
                                       for directories: use BSD semantics for
                                       propagation of GID
       0400   S_ENFMT         002000   System V file locking enforcement (shared
                                       with S_ISGID)
       0800   S_ISUID         004000   set-user-ID on execution (V7)
       0800   S_CDF           004000   directory is a context dependent
                                       file (HP-UX)

       A sticky command appeared in Version 32V AT&T UNIX.

NOTES
       Since kernel 2.5.48, the stat structure supports nanosecond resolution for the three file timestamp fields.  Glibc
       exposes  the nanosecond component of each field using names either of the form st_atim.tv_nsec, if the _BSD_SOURCE
       or _SVID_SOURCE feature test macro is defined, or of the form st_atimensec, if neither of these macros is defined.
       On  file systems that do not support sub-second timestamps, these nanosecond fields are returned with the value 0.

       On Linux, lstat() will generally not trigger automounter action, whereas stat() will.

       For most files under the /proc directory, stat() does not return the file size in the st_size field;  instead  the
       field is returned with the value 0.

   Underlying kernel interface
       Over time, increases in the size of the stat structure have led to three successive versions of stat(): sys_stat()
       (slot __NR_oldstat), sys_newstat() (slot __NR_stat), and sys_stat64() (new in kernel 2.4; slot __NR_stat64).   The
       glibc  stat() wrapper function hides these details from applications, invoking the most recent version of the sys‐
       tem call provided by the kernel, and repacking the returned information if required  for  old  binaries.   Similar
       remarks apply for fstat() and lstat().

EXAMPLE
       The following program calls stat() and displays selected fields in the returned stat structure.

       #include <sys/types.h>
       #include <sys/stat.h>
       #include <time.h>
       #include <stdio.h>
       #include <stdlib.h>

       int
       main(int argc, char *argv[])
       {
           struct stat sb;

           if (argc != 2) {
               fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           if (stat(argv[1], &sb) == -1) {
               perror("stat");
               exit(EXIT_SUCCESS);
           }

           printf("File type:                ");

           switch (sb.st_mode & S_IFMT) {
           case S_IFBLK:  printf("block device\n");            break;
           case S_IFCHR:  printf("character device\n");        break;
           case S_IFDIR:  printf("directory\n");               break;
           case S_IFIFO:  printf("FIFO/pipe\n");               break;
           case S_IFLNK:  printf("symlink\n");                 break;
           case S_IFREG:  printf("regular file\n");            break;
           case S_IFSOCK: printf("socket\n");                  break;
           default:       printf("unknown?\n");                break;
           }

           printf("I-node number:            %ld\n", (long) sb.st_ino);

           printf("Mode:                     %lo (octal)\n",
                   (unsigned long) sb.st_mode);

           printf("Link count:               %ld\n", (long) sb.st_nlink);
           printf("Ownership:                UID=%ld   GID=%ld\n",
                   (long) sb.st_uid, (long) sb.st_gid);

           printf("Preferred I/O block size: %ld bytes\n",
                   (long) sb.st_blksize);
           printf("File size:                %lld bytes\n",
                   (long long) sb.st_size);
           printf("Blocks allocated:         %lld\n",
                   (long long) sb.st_blocks);

           printf("Last status change:       %s", ctime(&sb.st_ctime));
           printf("Last file access:         %s", ctime(&sb.st_atime));
           printf("Last file modification:   %s", ctime(&sb.st_mtime));

           exit(EXIT_SUCCESS);
       }

SEE ALSO
       access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capabilities(7), symlink(7)

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-12-01                                                STAT(2)
###############################
###############################
FUTEX(2)                                        Linux Programmer’s Manual                                        FUTEX(2)



NAME
       futex - Fast Userspace Locking system call

SYNOPSIS
       #include <linux/futex.h>
       #include <sys/time.h>

       int futex(int *uaddr, int op, int val, const struct timespec *timeout,
                 int *uaddr2, int val3);

DESCRIPTION
       The  futex()  system  call provides a method for a program to wait for a value at a given address to change, and a
       method to wake up anyone waiting on a particular address (while the addresses for the same memory in separate pro‐
       cesses  may  not  be  equal, the kernel maps them internally so the same memory mapped in different locations will
       correspond for futex() calls).  It is typically used to implement the contended case of a lock in  shared  memory,
       as described in futex(7).

       When  a futex(7) operation did not finish uncontended in userspace, a call needs to be made to the kernel to arbi‐
       trate.  Arbitration can either mean putting the calling process to sleep or, conversely, waking a waiting process.

       Callers  of  this  function  are  expected  to adhere to the semantics as set out in futex(7).  As these semantics
       involve writing non-portable assembly instructions, this in turn probably means that most users will  in  fact  be
       library authors and not general application developers.

       The  uaddr  argument  needs  to point to an aligned integer which stores the counter.  The operation to execute is
       passed via the op argument, along with a value val.

       Five operations are currently defined:

       FUTEX_WAIT
              This operation atomically verifies that the futex address uaddr still contains the value  val,  and  sleeps
              awaiting  FUTEX_WAKE on this futex address.  If the timeout argument is non-NULL, its contents describe the
              maximum duration of the wait, which is infinite otherwise.  The arguments uaddr2 and val3 are ignored.

              For futex(7), this call is executed if decrementing the  count  gave  a  negative  value  (indicating  con‐
              tention), and will sleep until another process releases the futex and executes the FUTEX_WAKE operation.

       FUTEX_WAKE
              This  operation  wakes  at most val processes waiting on this futex address (i.e., inside FUTEX_WAIT).  The
              arguments timeout, uaddr2 and val3 are ignored.

              For futex(7), this is executed if incrementing the count showed that there were  waiters,  once  the  futex
              value has been set to 1 (indicating that it is available).

       FUTEX_FD (present up to and including Linux 2.6.25)
              To support asynchronous wakeups, this operation associates a file descriptor with a futex.  If another pro‐
              cess executes a FUTEX_WAKE, the process will receive the signal number that was passed in val.  The calling
              process  must  close  the  returned  file descriptor after use.  The arguments timeout, uaddr2 and val3 are
              ignored.

              To prevent race conditions, the caller should test if the futex has been upped after FUTEX_FD returns.

              Because it was inherently racy, FUTEX_FD has been removed from Linux 2.6.26 onwards.

       FUTEX_REQUEUE (since Linux 2.5.70)
              This operation was introduced in order to avoid a "thundering herd" effect when FUTEX_WAKE is used and  all
              processes woken up need to acquire another futex.  This call wakes up val processes, and requeues all other
              waiters on the futex at address uaddr2.  The arguments timeout and val3 are ignored.

       FUTEX_CMP_REQUEUE (since Linux 2.6.7)
              There was a race in the intended use of FUTEX_REQUEUE, so FUTEX_CMP_REQUEUE was introduced.  This is  simi‐
              lar  to  FUTEX_REQUEUE, but first checks whether the location uaddr still contains the value val3.  If not,
              the operation fails with the error EAGAIN.  The argument timeout is ignored.

RETURN VALUE
       Depending on which operation was executed, the returned value for a successful call can have differing meanings.

       FUTEX_WAIT
              Returns 0 if the process was woken by a FUTEX_WAKE call.  In case of timeout, the operation fails with  the
              error  ETIMEDOUT.   If  the  futex  was not equal to the expected value, the operation fails with the error
              EWOULDBLOCK.  Signals (see signal(7)) or other spurious wakeups cause FUTEX_WAIT to  fail  with  the  error
              EINTR.

       FUTEX_WAKE
              Returns the number of processes woken up.

       FUTEX_FD
              Returns the new file descriptor associated with the futex.

       FUTEX_REQUEUE
              Returns the number of processes woken up.

       FUTEX_CMP_REQUEUE
              Returns the number of processes woken up.

       In the event of an error, all operations return -1, and set errno to indicate the error.

ERRORS
       EACCES No read access to futex memory.

       EAGAIN FUTEX_CMP_REQUEUE  found  an  unexpected  futex  value.   (This  probably  indicates  a  race; use the safe
              FUTEX_WAKE now.)

       EFAULT Error in getting timeout information from userspace.

       EINVAL An operation was not defined or error in page alignment.

       ENFILE The system limit on the total number of open files has been reached.

       ENOSYS Invalid operation specified in op.

VERSIONS
       Initial futex support was merged in Linux 2.5.7 but with different semantics from what  was  described  above.   A
       4-argument system call with the semantics given here was introduced in Linux 2.5.40.  In Linux 2.5.70 one argument
       was added.  In Linux 2.6.7 a sixth argument was added — messy, especially on the s390 architecture.

CONFORMING TO
       This system call is Linux-specific.

NOTES
       To reiterate, bare futexes are not intended as an easy-to-use abstraction for end-users.   (There  is  no  wrapper
       function  for  this system call in glibc.)  Implementors are expected to be assembly literate and to have read the
       sources of the futex userspace library referenced below.

SEE ALSO
       futex(7)

       Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux (proceedings of  the  Ottawa  Linux  Symposium  2002),
       futex example library, futex-*.tar.bz2 <URL:ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/>.

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-11-27                                               FUTEX(2)
GETTIMEOFDAY(2)                                 Linux Programmer’s Manual                                 GETTIMEOFDAY(2)



NAME
       gettimeofday, settimeofday - get / set time

SYNOPSIS
       #include <sys/time.h>

       int gettimeofday(struct timeval *tv, struct timezone *tz);
       int settimeofday(const struct timeval *tv, const struct timezone *tz);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       settimeofday(): _BSD_SOURCE

DESCRIPTION
       The  functions  gettimeofday() and settimeofday() can get and set the time as well as a timezone.  The tv argument
       is a struct timeval (as specified in <sys/time.h>):

           struct timeval {
               time_t      tv_sec;     /* seconds */
               suseconds_t tv_usec;    /* microseconds */
           };

       and gives the number of seconds and microseconds since the Epoch (see time(2)).  The tz argument is a struct time‐
       zone:

           struct timezone {
               int tz_minuteswest;     /* minutes west of Greenwich */
               int tz_dsttime;         /* type of DST correction */
           };

       If either tv or tz is NULL, the corresponding structure is not set or returned.

       The  use of the timezone structure is obsolete; the tz argument should normally be specified as NULL.  The tz_dst‐
       time field has never been used under Linux; it has not been and will not be supported by libc or glibc.  Each  and
       every occurrence of this field in the kernel source (other than the declaration) is a bug.  Thus, the following is
       purely of historic interest.

       The field tz_dsttime contains a symbolic constant (values are given below) that indicates in  which  part  of  the
       year  Daylight  Saving  Time  is in force.  (Note: its value is constant throughout the year: it does not indicate
       that DST is in force, it just selects an algorithm.)  The daylight saving time algorithms defined are as follows :

           DST_NONE     /* not on dst */
           DST_USA      /* USA style dst */
           DST_AUST     /* Australian style dst */
           DST_WET      /* Western European dst */
           DST_MET      /* Middle European dst */
           DST_EET      /* Eastern European dst */
           DST_CAN      /* Canada */
           DST_GB       /* Great Britain and Eire */
           DST_RUM      /* Rumania */
           DST_TUR      /* Turkey */
           DST_AUSTALT  /* Australian style with shift in 1986 */

       Of  course  it  turned  out  that the period in which Daylight Saving Time is in force cannot be given by a simple
       algorithm, one per country; indeed, this period is determined  by  unpredictable  political  decisions.   So  this
       method  of  representing  timezones  has  been abandoned.  Under Linux, in a call to settimeofday() the tz_dsttime
       field should be zero.

       Under Linux there are some peculiar "warp clock" semantics associated with the settimeofday() system  call  if  on
       the  very  first  call  (after  booting)  that has a non-NULL tz argument, the tv argument is NULL and the tz_min‐
       uteswest field is non-zero.  In such a case it is assumed that the CMOS clock is on local time, and that it has to
       be incremented by this amount to get UTC system time.  No doubt it is a bad idea to use this feature.

       Macros for operating on timeval structures are described in timeradd(3).

RETURN VALUE
       gettimeofday()  and  settimeofday()  return 0 for success, or -1 for failure (in which case errno is set appropri‐
       ately).

ERRORS
       EFAULT One of tv or tz pointed outside the accessible address space.

       EINVAL Timezone (or something else) is invalid.

       EPERM  The calling process has insufficient privilege to call settimeofday(); under Linux the  CAP_SYS_TIME  capa‐
              bility is required.

CONFORMING TO
       SVr4, 4.3BSD.  POSIX.1-2001 describes gettimeofday() but not settimeofday().  POSIX.1-2008 marks gettimeofday() as
       obsolete.

NOTES
       Traditionally, the fields of struct timeval were of type long.

SEE ALSO
       date(1), adjtimex(2), time(2), ctime(3), ftime(3), capabilities(7), time(7)

COLOPHON
       This page is part of release 3.15 of the Linux man-pages project.  A description of the project,  and  information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-08-21                                        GETTIMEOFDAY(2)
###############################
###############################
POLL(2)                                         Linux Programmer’s Manual                                         POLL(2)



NAME
       poll, ppoll - wait for some event on a file descriptor

SYNOPSIS
       #include <poll.h>

       int poll(struct pollfd *fds, nfds_t nfds, int timeout);

       #define _GNU_SOURCE
       #include <poll.h>

       int ppoll(struct pollfd *fds, nfds_t nfds,
               const struct timespec *timeout, const sigset_t *sigmask);

DESCRIPTION
       poll() performs a similar task to select(2): it waits for one of a set of file descriptors to become ready to per‐
       form I/O.

       The set of file descriptors to be monitored is specified in the fds argument, which is an array of nfds structures
       of the following form:

           struct pollfd {
               int   fd;         /* file descriptor */
               short events;     /* requested events */
               short revents;    /* returned events */
           };

       The field fd contains a file descriptor for an open file.

       The field events is an input parameter, a bit mask specifying the events the application is interested in.

       The  field  revents is an output parameter, filled by the kernel with the events that actually occurred.  The bits
       returned in revents can include any of those specified in events, or one of the values POLLERR, POLLHUP, or  POLL‐
       NVAL.   (These  three  bits are meaningless in the events field, and will be set in the revents field whenever the
       corresponding condition is true.)

       If none of the events requested (and no error) has occurred for any of the file descriptors,  then  poll()  blocks
       until one of the events occurs.

       The  timeout argument specifies an upper limit on the time for which poll() will block, in milliseconds.  Specify‐
       ing a negative value in timeout means an infinite timeout.

       The bits that may be set/returned in events and revents are defined in <poll.h>:

              POLLIN There is data to read.

              POLLPRI
                     There is urgent data to read (e.g., out-of-band data on TCP socket; pseudo-terminal master in packet
                     mode has seen state change in slave).

              POLLOUT
                     Writing now will not block.

              POLLRDHUP (since Linux 2.6.17)
                     Stream socket peer closed connection, or shut down writing half of connection.  The _GNU_SOURCE fea‐
                     ture test macro must be defined in order to obtain this definition.

              POLLERR
                     Error condition (output only).

              POLLHUP
                     Hang up (output only).

              POLLNVAL
                     Invalid request: fd not open (output only).

       When compiling with _XOPEN_SOURCE defined, one also has the following, which convey no further information  beyond
       the bits listed above:

              POLLRDNORM
                     Equivalent to POLLIN.

              POLLRDBAND
                     Priority band data can be read (generally unused on Linux).

              POLLWRNORM
                     Equivalent to POLLOUT.

              POLLWRBAND
                     Priority data may be written.

       Linux also knows about, but does not use POLLMSG.

   ppoll()
       The  relationship  between  poll()  and ppoll() is analogous to the relationship between select(2) and pselect(2):
       like pselect(2), ppoll() allows an application to safely wait until either a  file  descriptor  becomes  ready  or
       until a signal is caught.

       Other than the difference in the timeout argument, the following ppoll() call:

           ready = ppoll(&fds, nfds, timeout, &sigmask);

       is equivalent to atomically executing the following calls:

           sigset_t origmask;

           sigprocmask(SIG_SETMASK, &sigmask, &origmask);
           ready = poll(&fds, nfds, timeout);
           sigprocmask(SIG_SETMASK, &origmask, NULL);

       See the description of pselect(2) for an explanation of why ppoll() is necessary.

       If the sigmask argument is specified as NULL, then no signal mask manipulation is performed (and thus ppoll() dif‐
       fers from poll() only in the precision of the timeout argument).

       The timeout argument specifies an upper limit on the amount of time that ppoll() will block.  This argument  is  a
       pointer to a structure of the following form:

           struct timespec {
               long    tv_sec;         /* seconds */
               long    tv_nsec;        /* nanoseconds */
           };

       If timeout is specified as NULL, then ppoll() can block indefinitely.

RETURN VALUE
       On success, a positive number is returned; this is the number of structures which have non-zero revents fields (in
       other words, those descriptors with events or errors reported).  A value of 0 indicates that the  call  timed  out
       and no file descriptors were ready.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       EBADF  An invalid file descriptor was given in one of the sets.

       EFAULT The array given as argument was not contained in the calling program’s address space.

       EINTR  A signal occurred before any requested event; see signal(7).

       EINVAL The nfds value exceeds the RLIMIT_NOFILE value.

       ENOMEM There was no space to allocate file descriptor tables.

VERSIONS
       The poll() system call was introduced in Linux 2.1.23.  The poll() library call was introduced in libc 5.4.28 (and
       provides emulation using select(2) if your kernel does not have a poll() system call).

       The ppoll() system call was added to Linux in kernel 2.6.16.  The ppoll() library call was added in glibc 2.4.

CONFORMING TO
       poll() conforms to POSIX.1-2001.  ppoll() is Linux-specific.

NOTES
       Some implementations define the non-standard constant INFTIM with the value -1 for use as a  timeout.   This  con‐
       stant is not provided in glibc.

   Linux Notes
       The  Linux  ppoll()  system  call  modifies  its timeout argument.  However, the glibc wrapper function hides this
       behavior by using a local variable for the timeout argument that is passed to the system call.   Thus,  the  glibc
       ppoll() function does not modify its timeout argument.

BUGS
       See the discussion of spurious readiness notifications under the BUGS section of select(2).

SEE ALSO
       select(2), select_tut(2), feature_test_macros(7), time(7)

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-04-23                                                POLL(2)
###############################
###############################
READV(2)                                        Linux Programmer’s Manual                                        READV(2)



NAME
       readv, writev - read or write data into multiple buffers

SYNOPSIS
       #include <sys/uio.h>

       ssize_t readv(int fd, const struct iovec *iov, int iovcnt);

       ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

DESCRIPTION
       The  readv()  function  reads iovcnt buffers from the file associated with the file descriptor fd into the buffers
       described by iov ("scatter input").

       The writev() function writes iovcnt buffers of data described by iov to the file associated with the file descrip‐
       tor fd ("gather output").

       The pointer iov points to an array of iovec structures, defined in <sys/uio.h> as:

           struct iovec {
               void  *iov_base;    /* Starting address */
               size_t iov_len;     /* Number of bytes to transfer */
           };

       The readv() function works just like read(2) except that multiple buffers are filled.

       The writev() function works just like write(2) except that multiple buffers are written out.

       Buffers  are  processed  in  array  order.   This  means that readv() completely fills iov[0] before proceeding to
       iov[1], and so on.  (If there is insufficient data, then not all buffers pointed to by iov may be filled.)   Simi‐
       larly, writev() writes out the entire contents of iov[0] before proceeding to iov[1], and so on.

       The data transfers performed by readv() and writev() are atomic: the data written by writev() is written as a sin‐
       gle block that is not intermingled with output from writes in other processes (but see pipe(7) for an  exception);
       analogously, readv() is guaranteed to read a contiguous block of data from the file, regardless of read operations
       performed in other threads or processes that have file descriptors referring to the  same  open  file  description
       (see open(2)).

RETURN VALUE
       On  success,  the  readv()  function returns the number of bytes read; the writev() function returns the number of
       bytes written.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       The errors are as given for read(2) and write(2).  Additionally the following error is defined:

       EINVAL The sum of the iov_len values overflows an ssize_t value.  Or, the vector count iovcnt is less than zero or
              greater than the permitted maximum.

CONFORMING TO
       4.4BSD  (the  readv()  and writev() functions first appeared in 4.2BSD), POSIX.1-2001.  Linux libc5 used size_t as
       the type of the iovcnt argument, and int as return type for these functions.

NOTES
   Linux Notes
       POSIX.1-2001 allows an implementation to place a limit on the number of items that  can  be  passed  in  iov.   An
       implementation  can advertise its limit by defining IOV_MAX in <limits.h> or at run time via the return value from
       sysconf(_SC_IOV_MAX).  On Linux, the limit advertised by these mechanisms is 1024, which is the true kernel limit.
       However,  the  glibc  wrapper  functions  do some extra work if they detect that the underlying kernel system call
       failed because this limit was exceeded.  In the case of readv() the wrapper function allocates a temporary  buffer
       large  enough for all of the items specified by iov, passes that buffer in a call to read(2), copies data from the
       buffer to the locations specified by the iov_base fields of the elements of iov, and then frees the  buffer.   The
       wrapper function for writev() performs the analogous task using a temporary buffer and a call to write(2).

BUGS
       It  is  not  advisable to mix calls to functions like readv() or writev(), which operate on file descriptors, with
       the functions from the stdio library; the results will be undefined and probably not what you want.

EXAMPLE
       The following code sample demonstrates the use of writev():

           char *str0 = "hello ";
           char *str1 = "world\n";
           struct iovec iov[2];
           ssize_t nwritten;

           iov[0].iov_base = str0;
           iov[0].iov_len = strlen(str0);
           iov[1].iov_base = str1;
           iov[1].iov_len = strlen(str1);

           nwritten = writev(STDOUT_FILENO, iov, 2);

SEE ALSO
       read(2), write(2)

COLOPHON
       This page is part of release 3.15 of the Linux man-pages project.  A description of the project,  and  information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2002-10-17                                               READV(2)
###############################
###############################
READV(2)                                        Linux Programmer’s Manual                                        READV(2)



NAME
       readv, writev - read or write data into multiple buffers

SYNOPSIS
       #include <sys/uio.h>

       ssize_t readv(int fd, const struct iovec *iov, int iovcnt);

       ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

DESCRIPTION
       The  readv()  function  reads iovcnt buffers from the file associated with the file descriptor fd into the buffers
       described by iov ("scatter input").

       The writev() function writes iovcnt buffers of data described by iov to the file associated with the file descrip‐
       tor fd ("gather output").

       The pointer iov points to an array of iovec structures, defined in <sys/uio.h> as:

           struct iovec {
               void  *iov_base;    /* Starting address */
               size_t iov_len;     /* Number of bytes to transfer */
           };

       The readv() function works just like read(2) except that multiple buffers are filled.

       The writev() function works just like write(2) except that multiple buffers are written out.

       Buffers  are  processed  in  array  order.   This  means that readv() completely fills iov[0] before proceeding to
       iov[1], and so on.  (If there is insufficient data, then not all buffers pointed to by iov may be filled.)   Simi‐
       larly, writev() writes out the entire contents of iov[0] before proceeding to iov[1], and so on.

       The data transfers performed by readv() and writev() are atomic: the data written by writev() is written as a sin‐
       gle block that is not intermingled with output from writes in other processes (but see pipe(7) for an  exception);
       analogously, readv() is guaranteed to read a contiguous block of data from the file, regardless of read operations
       performed in other threads or processes that have file descriptors referring to the  same  open  file  description
       (see open(2)).

RETURN VALUE
       On  success,  the  readv()  function returns the number of bytes read; the writev() function returns the number of
       bytes written.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       The errors are as given for read(2) and write(2).  Additionally the following error is defined:

       EINVAL The sum of the iov_len values overflows an ssize_t value.  Or, the vector count iovcnt is less than zero or
              greater than the permitted maximum.

CONFORMING TO
       4.4BSD  (the  readv()  and writev() functions first appeared in 4.2BSD), POSIX.1-2001.  Linux libc5 used size_t as
       the type of the iovcnt argument, and int as return type for these functions.

NOTES
   Linux Notes
       POSIX.1-2001 allows an implementation to place a limit on the number of items that  can  be  passed  in  iov.   An
       implementation  can advertise its limit by defining IOV_MAX in <limits.h> or at run time via the return value from
       sysconf(_SC_IOV_MAX).  On Linux, the limit advertised by these mechanisms is 1024, which is the true kernel limit.
       However,  the  glibc  wrapper  functions  do some extra work if they detect that the underlying kernel system call
       failed because this limit was exceeded.  In the case of readv() the wrapper function allocates a temporary  buffer
       large  enough for all of the items specified by iov, passes that buffer in a call to read(2), copies data from the
       buffer to the locations specified by the iov_base fields of the elements of iov, and then frees the  buffer.   The
       wrapper function for writev() performs the analogous task using a temporary buffer and a call to write(2).

BUGS
       It  is  not  advisable to mix calls to functions like readv() or writev(), which operate on file descriptors, with
       the functions from the stdio library; the results will be undefined and probably not what you want.

EXAMPLE
       The following code sample demonstrates the use of writev():

           char *str0 = "hello ";
           char *str1 = "world\n";
           struct iovec iov[2];
           ssize_t nwritten;

           iov[0].iov_base = str0;
           iov[0].iov_len = strlen(str0);
           iov[1].iov_base = str1;
           iov[1].iov_len = strlen(str1);

           nwritten = writev(STDOUT_FILENO, iov, 2);

SEE ALSO
       read(2), write(2)

COLOPHON
       This page is part of release 3.15 of the Linux man-pages project.  A description of the project,  and  information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2002-10-17                                               READV(2)
###############################
###############################
##############################
ACCESS(2)                                       Linux Programmer’s Manual                                       ACCESS(2)



NAME
       access - check real user’s permissions for a file

SYNOPSIS
       #include <unistd.h>

       int access(const char *pathname, int mode);

DESCRIPTION
       access()  checks  whether the calling process can access the file pathname.  If pathname is a symbolic link, it is
       dereferenced.

       The mode specifies the accessibility check(s) to be performed, and is either the value F_OK, or a mask  consisting
       of  the bitwise OR of one or more of R_OK, W_OK, and X_OK.  F_OK tests for the existence of the file.  R_OK, W_OK,
       and X_OK test whether the file exists and grants read, write, and execute permissions, respectively.

       The check is done using the calling process’s real UID and GID, rather than the effective  IDs  as  is  done  when
       actually  attempting  an operation (e.g., open(2)) on the file.  This allows set-user-ID programs to easily deter‐
       mine the invoking user’s authority.

       If the calling process is privileged (i.e., its real UID is zero), then an X_OK check is successful for a  regular
       file if execute permission is enabled for any of the file owner, group, or other.

RETURN VALUE
       On  success (all requested permissions granted), zero is returned.  On error (at least one bit in mode asked for a
       permission that is denied, or some other error occurred), -1 is returned, and errno is set appropriately.

ERRORS
       access() shall fail if:

       EACCES The requested access would be denied to the file, or search permission is denied for one of the directories
              in the path prefix of pathname.  (See also path_resolution(7).)

       ELOOP  Too many symbolic links were encountered in resolving pathname.

       ENAMETOOLONG
              pathname is too long.

       ENOENT A component of pathname does not exist or is a dangling symbolic link.

       ENOTDIR
              A component used as a directory in pathname is not, in fact, a directory.

       EROFS  Write permission was requested for a file on a read-only file system.

       access() may fail if:

       EFAULT pathname points outside your accessible address space.

       EINVAL mode was incorrectly specified.

       EIO    An I/O error occurred.

       ENOMEM Insufficient kernel memory was available.

       ETXTBSY
              Write access was requested to an executable which is being executed.

CONFORMING TO
       SVr4, 4.3BSD, POSIX.1-2001.

NOTES
       Warning:  Using  access()  to  check if a user is authorized to, for example, open a file before actually doing so
       using open(2) creates a security hole, because the user might exploit the short time interval between checking and
       opening the file to manipulate it.  For this reason, the use of this system call should be avoided.

       access()  returns an error if any of the access types in mode is denied, even if some of the other access types in
       mode are permitted.

       If the calling process has appropriate privileges (i.e., is superuser),  POSIX.1-2001  permits  implementation  to
       indicate  success  for  an X_OK check even if none of the execute file permission bits are set.  Linux does not do
       this.

       A file is only accessible if the permissions on each of the directories in  the  path  prefix  of  pathname  grant
       search  (i.e., execute) access.  If any directory is inaccessible, then the access() call will fail, regardless of
       the permissions on the file itself.

       Only access bits are checked, not the file type or contents.  Therefore, if a directory is found to  be  writable,
       it probably means that files can be created in the directory, and not that the directory can be written as a file.
       Similarly, a DOS file may be found to be "executable," but the execve(2) call will still fail.

       access() may not work correctly on NFS file systems with UID mapping enabled, because UID mapping is done  on  the
       server and hidden from the client, which checks permissions.

BUGS
       In  kernel  2.4 (and earlier) there is some strangeness in the handling of X_OK tests for superuser.  If all cate‐
       gories of execute permission are disabled for a non-directory file, then the only access() test that returns -1 is
       when  mode  is specified as just X_OK; if R_OK or W_OK is also specified in mode, then access() returns 0 for such
       files.  Early 2.6 kernels (up to and including 2.6.3) also behaved in the same way as kernel 2.4.

       In kernels before 2.6.20, access() ignored the effect of the MS_NOEXEC flag if it was used to mount(2) the  under‐
       lying file system.  Since kernel 2.6.20, access() honors this flag.

SEE ALSO
       chmod(2), chown(2), faccessat(2), open(2), setgid(2), setuid(2), stat(2), euidaccess(3), credentials(7), path_res‐
       olution(7)

COLOPHON
       This page is part of release 3.15 of the Linux man-pages project.  A description of the project,  and  information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2007-07-10                                              ACCESS(2)
##############################
##############################
GETDENTS(2)                                     Linux Programmer’s Manual                                     GETDENTS(2)



NAME
       getdents - get directory entries

SYNOPSIS
       int getdents(unsigned int fd, struct linux_dirent *dirp,
                    unsigned int count);

DESCRIPTION
       This  is not the function you are interested in.  Look at readdir(3) for the POSIX conforming C library interface.
       This page documents the bare kernel system call interface.

       The system call getdents() reads several linux_dirent structures from the directory referred to by the  open  file
       descriptor fd into the buffer pointed to by dirp.  The argument count is specifies the size of that buffer.

       The linux_dirent structure is declared as follows:

           struct linux_dirent {
               unsigned long  d_ino;     /* Inode number */
               unsigned long  d_off;     /* Offset to next linux_dirent */
               unsigned short d_reclen;  /* Length of this linux_dirent */
               char           d_name[];  /* Filename (null-terminated) */
                                   /* length is actually (d_reclen - 2 -
                                      offsetof(struct linux_dirent, d_name) */
               /*
               char           pad;       // Zero padding byte */
               char           d_type;    // File type (only since Linux 2.6.4;
                                         // offset is (d_reclen - 1))
               */

           }

       d_ino  is  an  inode  number.   d_off  is  the  distance  from the start of the directory to the start of the next
       linux_dirent.  d_reclen is the size of this entire linux_dirent.  d_name is a null-terminated filename.

       d_type is a byte at the end of the structure that indicates the file type.  It contains one of the following  val‐
       ues (defined in <dirent.h>):

       DT_BLK      This is a block device.

       DT_CHR      This is a character device.

       DT_DIR      This is a directory.

       DT_FIFO     This is a named pipe (FIFO).

       DT_LNK      This is a symbolic link.

       DT_REG      This is a regular file.

       DT_SOCK     This is a Unix domain socket.

       DT_UNKNOWN  The file type is unknown.

       Currently,  only some file systems (among them: ext2, etx3, and ext4) have full support returning the file type in
       d_type.  All applications must properly handle a return of DT_UNKNOWN.

RETURN VALUE
       On success, the number of bytes read is returned.  On end of directory, 0 is returned.  On error, -1 is  returned,
       and errno is set appropriately.

ERRORS
       EBADF  Invalid file descriptor fd.

       EFAULT Argument points outside the calling process’s address space.

       EINVAL Result buffer is too small.

       ENOENT No such directory.

       ENOTDIR
              File descriptor does not refer to a directory.

CONFORMING TO
       SVr4.

NOTES
       Glibc  does  not  provide  a  wrapper for this system call; call it using syscall(2).  You will need to define the
       linux_dirent structure yourself.

       This call supersedes readdir(2).

EXAMPLE
       The program below demonstrates the use of getdents().  The following output shows an example of what we  see  when
       running this program on an ext2 directory:

           $ ./a.out /testfs/
           --------------- nread=120 ---------------
           i-node#  file type  d_reclen  d_off   d_name
                  2  directory    16         12  .
                  2  directory    16         24  ..
                 11  directory    24         44  lost+found
                 12  regular      16         56  a
             228929  directory    16         68  sub
              16353  directory    16         80  sub2
             130817  directory    16       4096  sub3

   Program source

       #define HAVE_D_TYPE     /* Remove for kernels < 2.6.4 */
       #define _GNU_SOURCE
       #include <dirent.h>     /* Defines DT_* constants */
       #include <fcntl.h>
       #include <stdio.h>
       #include <unistd.h>
       #include <stdlib.h>
       #include <sys/stat.h>
       #include <sys/syscall.h>

       #define handle_error(msg) \
               do { perror(msg); exit(EXIT_FAILURE); } while (0)

       struct linux_dirent {
           long           d_ino;
           off_t          d_off;
           unsigned short d_reclen;
           char           d_name[];
       };

       #define BUF_SIZE 1024

       int
       main(int argc, char *argv[])
       {
           int fd, nread;
           char buf[BUF_SIZE];
           struct linux_dirent *d;
           int bpos;
       #ifdef HAVE_D_TYPE
           char d_type;
       #endif

           fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
           if (fd == -1)
               handle_error("open");

           for ( ; ; ) {
               nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
               if (nread == -1)
                   handle_error("getdents");

               if (nread == 0)
                   break;

               printf("--------------- nread=%d ---------------\n", nread);
               printf("i-node#  file type  d_reclen  d_off   d_name\n");
               for (bpos = 0; bpos < nread;) {
                   d = (struct linux_dirent *) (buf + bpos);
                   printf("%8ld  ", d->d_ino);
       #ifdef HAVE_D_TYPE
                   d_type = *(buf + bpos + d->d_reclen - 1);
                   printf("%-10s ", (d_type == DT_REG) ?  "regular" :
                                    (d_type == DT_DIR) ?  "directory" :
                                    (d_type == DT_FIFO) ? "FIFO" :
                                    (d_type == DT_SOCK) ? "socket" :
                                    (d_type == DT_LNK) ?  "symlink" :
                                    (d_type == DT_BLK) ?  "block dev" :
                                    (d_type == DT_CHR) ?  "char dev" : "???");
       #endif
                   printf("%4d %10lld  %s\n", d->d_reclen,
                           (long long) d->d_off, (char *) d->d_name);
                   bpos += d->d_reclen;
               }
           }

           exit(EXIT_SUCCESS);
       }

SEE ALSO
       readdir(2), readdir(3)

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-11-11                                            GETDENTS(2)
##############################
##############################
MPROTECT(2)                                     Linux Programmer’s Manual                                     MPROTECT(2)



NAME
       mprotect - set protection on a region of memory

SYNOPSIS
       #include <sys/mman.h>

       int mprotect(const void *addr, size_t len, int prot);

DESCRIPTION
       mprotect() changes protection for the calling process’s memory page(s) containing any part of the address range in
       the interval [addr, addr+len-1].  addr must be aligned to a page boundary.

       If the calling process tries to access memory in a manner that violates the protection, then the kernel  generates
       a SIGSEGV signal for the process.

       prot is either PROT_NONE or a bitwise-or of the other values in the following list:

       PROT_NONE  The memory cannot be accessed at all.

       PROT_READ  The memory can be read.

       PROT_WRITE The memory can be modified.

       PROT_EXEC  The memory can be executed.

RETURN VALUE
       On success, mprotect() returns zero.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       EACCES The  memory  cannot  be given the specified access.  This can happen, for example, if you mmap(2) a file to
              which you have read-only access, then ask mprotect() to mark it PROT_WRITE.

       EINVAL addr is not a valid pointer, or not a multiple of the system page size.

       ENOMEM Internal kernel structures could not be allocated.

       ENOMEM Addresses in the range [addr, addr+len] are invalid for the address space of the process, or specify one or
              more pages that are not mapped.  (Before kernel 2.4.19, the error EFAULT was incorrectly produced for these
              cases.)

CONFORMING TO
       SVr4, POSIX.1-2001.  POSIX says that the behavior of mprotect() is unspecified if it is applied  to  a  region  of
       memory that was not obtained via mmap(2).

NOTES
       On  Linux  it is always permissible to call mprotect() on any address in a process’s address space (except for the
       kernel vsyscall area).  In particular it can be used to change existing code mappings to be writable.

       Whether PROT_EXEC has any effect different from PROT_READ is architecture- and kernel version-dependent.  On  some
       hardware architectures (e.g., i386), PROT_WRITE implies PROT_READ.

       POSIX.1-2001 says that an implementation may permit access other than that specified in prot, but at a minimum can
       only allow write access if PROT_WRITE has been set, and must not allow any access if PROT_NONE has been set.

EXAMPLE
       The program below allocates four pages of memory, makes the third of these pages read-only, and  then  executes  a
       loop that walks upwards through the allocated region modifying bytes.

       An example of what we might see when running the program is the following:

           $ ./a.out
           Start of region:        0x804c000
           Got SIGSEGV at address: 0x804e000

   Program source

       #include <unistd.h>
       #include <signal.h>
       #include <stdio.h>
       #include <malloc.h>
       #include <stdlib.h>
       #include <errno.h>
       #include <sys/mman.h>

       #define handle_error(msg) \
           do { perror(msg); exit(EXIT_FAILURE); } while (0)

       char *buffer;

       static void
       handler(int sig, siginfo_t *si, void *unused)
       {
           printf("Got SIGSEGV at address: 0x%lx\n",
                   (long) si->si_addr);
           exit(EXIT_FAILURE);
       }

       int
       main(int argc, char *argv[])
       {
           char *p;
           int pagesize;
           struct sigaction sa;

           sa.sa_flags = SA_SIGINFO;
           sigemptyset(&sa.sa_mask);
           sa.sa_sigaction = handler;
           if (sigaction(SIGSEGV, &sa, NULL) == -1)
               handle_error("sigaction");

           pagesize = sysconf(_SC_PAGE_SIZE);
           if (pagesize == -1)
               handle_error("sysconf");

           /* Allocate a buffer aligned on a page boundary;
              initial protection is PROT_READ | PROT_WRITE */

           buffer = memalign(pagesize, 4 * pagesize);
           if (buffer == NULL)
               handle_error("memalign");

           printf("Start of region:        0x%lx\n", (long) buffer);

           if (mprotect(buffer + pagesize * 2, pagesize,
                       PROT_NONE) == -1)
               handle_error("mprotect");

           for (p = buffer ; ; )
               *(p++) = 'a';

           printf("Loop completed\n");     /* Should never happen */
           exit(EXIT_SUCCESS);
       }

SEE ALSO
       mmap(2), sysconf(3)

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-08-06                                            MPROTECT(2)
##############################
##############################
FCNTL(2)                                        Linux Programmer’s Manual                                        FCNTL(2)



NAME
       fcntl - manipulate file descriptor

SYNOPSIS
       #include <unistd.h>
       #include <fcntl.h>

       int fcntl(int fd, int cmd, ... /* arg */ );

DESCRIPTION
       fcntl()  performs  one  of the operations described below on the open file descriptor fd.  The operation is deter‐
       mined by cmd.

       fcntl() can take an optional third argument.  Whether or not this argument is required is determined by cmd.   The
       required  argument type is indicated in parentheses after each cmd name (in most cases, the required type is long,
       and we identify the argument using the name arg), or void is specified if the argument is not required.

   Duplicating a file descriptor
       F_DUPFD (long)
              Find the lowest numbered available file descriptor greater than or equal to arg and make it be  a  copy  of
              fd.  This is different from dup2(2), which uses exactly the descriptor specified.

              On success, the new descriptor is returned.

              See dup(2) for further details.

       F_DUPFD_CLOEXEC (long; since Linux 2.6.24)
              As  for F_DUPFD, but additionally set the close-on-exec flag for the duplicate descriptor.  Specifying this
              flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag.  For an
              explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

   File descriptor flags
       The  following  commands manipulate the flags associated with a file descriptor.  Currently, only one such flag is
       defined: FD_CLOEXEC, the close-on-exec flag.  If the FD_CLOEXEC bit is 0, the file  descriptor  will  remain  open
       across an execve(2), otherwise it will be closed.

       F_GETFD (void)
              Read the file descriptor flags; arg is ignored.

       F_SETFD (long)
              Set the file descriptor flags to the value specified by arg.

   File status flags
       Each  open  file  description has certain associated status flags, initialized by open(2) and possibly modified by
       fcntl().  Duplicated file descriptors (made with dup(2), fcntl(F_DUPFD), fork(2), etc.) refer  to  the  same  open
       file description, and thus share the same file status flags.

       The file status flags and their semantics are described in open(2).

       F_GETFL (void)
              Read the file status flags; arg is ignored.

       F_SETFL (long)
              Set the file status flags to the value specified by arg.  File access mode (O_RDONLY, O_WRONLY, O_RDWR) and
              file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored.  On Linux  this  command
              can only change the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags.

   Advisory locking
       F_GETLK, F_SETLK and F_SETLKW are used to acquire, release, and test for the existence of record locks (also known
       as file-segment or file-region locks).  The third argument, lock, is a pointer to a structure that  has  at  least
       the following fields (in unspecified order).

           struct flock {
               ...
               short l_type;    /* Type of lock: F_RDLCK,
                                   F_WRLCK, F_UNLCK */
               short l_whence;  /* How to interpret l_start:
                                   SEEK_SET, SEEK_CUR, SEEK_END */
               off_t l_start;   /* Starting offset for lock */
               off_t l_len;     /* Number of bytes to lock */
               pid_t l_pid;     /* PID of process blocking our lock
                                   (F_GETLK only) */
               ...
           };

       The  l_whence, l_start, and l_len fields of this structure specify the range of bytes we wish to lock.  Bytes past
       the end of the file may be locked, but not bytes before the start of the file.

       l_start is the starting offset for the lock, and is interpreted relative to either: the  start  of  the  file  (if
       l_whence  is  SEEK_SET); the current file offset (if l_whence is SEEK_CUR); or the end of the file (if l_whence is
       SEEK_END).  In the final two cases, l_start can be a negative number provided the offset does not lie  before  the
       start of the file.

       l_len  specifies the number of bytes to be locked.  If l_len is positive, then the range to be locked covers bytes
       l_start up to and including l_start+l_len-1.  Specifying 0 for l_len has  the  special  meaning:  lock  all  bytes
       starting  at  the  location  specified by l_whence and l_start through to the end of file, no matter how large the
       file grows.

       POSIX.1-2001 allows (but does not require) an implementation to support a negative l_len value; if l_len is  nega‐
       tive,  the interval described by lock covers bytes l_start+l_len up to and including l_start-1.  This is supported
       by Linux since kernel versions 2.4.21 and 2.5.49.

       The l_type field can be used to place a read (F_RDLCK) or a write (F_WRLCK) lock on a file.  Any  number  of  pro‐
       cesses  may hold a read lock (shared lock) on a file region, but only one process may hold a write lock (exclusive
       lock).  An exclusive lock excludes all other locks, both shared and exclusive.  A single process can hold only one
       type  of  lock  on  a file region; if a new lock is applied to an already-locked region, then the existing lock is
       converted to the new lock type.  (Such conversions may involve splitting, shrinking, or coalescing with an  exist‐
       ing  lock  if  the byte range specified by the new lock does not precisely coincide with the range of the existing
       lock.)

       F_SETLK (struct flock *)
              Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the  bytes
              specified  by  the  l_whence,  l_start, and l_len fields of lock.  If a conflicting lock is held by another
              process, this call returns -1 and sets errno to EACCES or EAGAIN.

       F_SETLKW (struct flock *)
              As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.   If
              a  signal is caught while waiting, then the call is interrupted and (after the signal handler has returned)
              returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

       F_GETLK (struct flock *)
              On input to this call, lock describes a lock we would like to place on the file.   If  the  lock  could  be
              placed,  fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the
              other fields of the structure unchanged.  If one or more incompatible locks would prevent this  lock  being
              placed,  then  fcntl() returns details about one of these locks in the l_type, l_whence, l_start, and l_len
              fields of lock and sets l_pid to be the PID of the process holding that lock.

       In order to place a read lock, fd must be open for reading.  In order to place a write lock, fd must be  open  for
       writing.  To place both types of lock, open a file read-write.

       As  well  as being removed by an explicit F_UNLCK, record locks are automatically released when the process termi‐
       nates or if it closes any file descriptor referring to a file on which locks are held.  This is bad: it means that
       a  process  can  lose  the  locks  on a file like /etc/passwd or /etc/mtab when for some reason a library function
       decides to open, read and close it.

       Record locks are not inherited by a child created via fork(2), but are preserved across an execve(2).

       Because of the buffering performed by the stdio(3) library, the use  of  record  locking  with  routines  in  that
       package should be avoided; use read(2) and write(2) instead.

   Mandatory locking
       (Non-POSIX.)  The above record locks may be either advisory or mandatory, and are advisory by default.

       Advisory locks are not enforced and are useful only between cooperating processes.

       Mandatory  locks  are  enforced  for  all  processes.  If a process tries to perform an incompatible access (e.g.,
       read(2) or write(2)) on a file region that has an incompatible  mandatory  lock,  then  the  result  depends  upon
       whether the O_NONBLOCK flag is enabled for its open file description.  If the O_NONBLOCK flag is not enabled, then
       system call is blocked until the lock is removed or converted to a mode that is compatible with  the  access.   If
       the O_NONBLOCK flag is enabled, then the system call fails with the error EAGAIN or EWOULDBLOCK.

       To  make  use of mandatory locks, mandatory locking must be enabled both on the file system that contains the file
       to be locked, and on the file itself.  Mandatory locking is enabled on a file system using the "-o mand" option to
       mount(8), or the MS_MANDLOCK flag for mount(2).  Mandatory locking is enabled on a file by disabling group execute
       permission on the file and enabling the set-group-ID permission bit (see chmod(1) and chmod(2)).

       The Linux implementation of mandatory locking is unreliable.  See BUGS below.

   Managing signals
       F_GETOWN, F_SETOWN, F_GETSIG and F_SETSIG are used to manage I/O availability signals:

       F_GETOWN (void)
              Return (as the function result) the process ID or process group currently receiving SIGIO and  SIGURG  sig‐
              nals  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 (long)
              Set the process ID or process group ID that will receive SIGIO  and  SIGURG  signals  for  events  on  file
              descriptor fd to the ID given 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)).

              If  you  set  the O_ASYNC status flag on a file descriptor 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 signal other than SIGIO.  If this permission check fails, then the signal is silently
              discarded.

              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 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".)

              If a non-zero 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.   Note  also  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.

       F_GETSIG (void)
              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  addi‐
              tional info is available to the signal handler if installed with SA_SIGINFO.  arg is ignored.

       F_SETSIG (long)
              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.

              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 description of F_SETOWN for more details.

              By using F_SETSIG with a non-zero 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 mecha‐
              nisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are avail‐
              able for I/O.

              By  selecting a real time signal (value >= SIGRTMIN), multiple I/O events may be queued using the same sig‐
              nal numbers.  (Queuing is dependent on available memory).  Extra information is available if SA_SIGINFO  is
              set for the signal handler, as above.

       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, F_GETOWN, F_SETOWN is specific to BSD and Linux.  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).

   Leases
       F_SETLEASE and F_GETLEASE (Linux 2.4 onwards) are used (respectively) to establish a new lease, and  retrieve  the
       current lease, on the open file description referred to by the file descriptor fd.  A file lease provides a mecha‐
       nism whereby the process holding the lease (the "lease holder") is notified (via delivery of a signal) when a pro‐
       cess (the "lease breaker") tries to open(2) or truncate(2) the file referred to by that file descriptor.

       F_SETLEASE (long)
              Set or remove a file lease according to which of the following values is specified in the integer arg:

              F_RDLCK
                     Take  out  a read lease.  This will cause the calling process to be notified when the file is opened
                     for writing or is truncated.  A read lease can only be placed on a file descriptor  that  is  opened
                     read-only.

              F_WRLCK
                     Take out a write lease.  This will cause the caller to be notified when the file is opened for read‐
                     ing or writing or is truncated.  A write lease may be placed on a file only if there  are  no  other
                     open file descriptors for the file.

              F_UNLCK
                     Remove our lease from the file.

       Leases  are  associated  with  an open file description (see open(2)).  This means that duplicate file descriptors
       (created by, for example, fork(2) or dup(2)) refer to the same lease, and this lease may be modified  or  released
       using any of these descriptors.  Furthermore, the lease is released by either an explicit F_UNLCK operation on any
       of these duplicate descriptors, or when all such descriptors have been closed.

       Leases may only be taken out on regular files.  An unprivileged process may only take out a lease on a file  whose
       UID  (owner)  matches  the  file  system UID of the process.  A process with the CAP_LEASE capability may take out
       leases on arbitrary files.

       F_GETLEASE (void)
              Indicates what type of lease is associated with  the  file  descriptor  fd  by  returning  either  F_RDLCK,
              F_WRLCK,  or F_UNLCK, indicating, respectively, a read lease , a write lease, or no lease.  arg is ignored.

       When a process (the "lease breaker") performs an open(2) or truncate(2) that conflicts with  a  lease  established
       via  F_SETLEASE, the system call is blocked by the kernel and the kernel notifies the lease holder by sending it a
       signal (SIGIO by default).  The lease holder should respond to receipt of this signal by doing whatever cleanup is
       required  in  preparation  for the file to be accessed by another process (e.g., flushing cached buffers) and then
       either remove or downgrade its lease.  A lease is removed by performing an F_SETLEASE command  specifying  arg  as
       F_UNLCK.  If the lease holder currently holds a write lease on the file, and the lease breaker is opening the file
       for reading, then it is sufficient for the lease holder to downgrade the lease to a read lease.  This is  done  by
       performing an F_SETLEASE command specifying arg as F_RDLCK.

       If  the  lease  holder  fails  to  downgrade  or  remove  the  lease  within  the  number  of seconds specified in
       /proc/sys/fs/lease-break-time then the kernel forcibly removes or downgrades the lease holder’s lease.

       Once the lease has been voluntarily or forcibly removed or downgraded, and assuming  the  lease  breaker  has  not
       unblocked its system call, the kernel permits the lease breaker’s system call to proceed.

       If  the  lease  breaker’s  blocked open(2) or truncate(2) is interrupted by a signal handler, then the system call
       fails with the error EINTR, but the other steps still occur as described above.  If the lease breaker is killed by
       a  signal  while  blocked  in open(2) or truncate(2), then the other steps still occur as described above.  If the
       lease breaker specifies the O_NONBLOCK flag when calling open(2), then the call immediately fails with  the  error
       EWOULDBLOCK, but the other steps still occur as described above.

       The default signal used to notify the lease holder is SIGIO, but this can be changed using the F_SETSIG command to
       fcntl().  If a F_SETSIG command is performed (even one specifying SIGIO), and the signal  handler  is  established
       using  SA_SIGINFO, then the handler will receive a siginfo_t structure as its second argument, and the si_fd field
       of this argument will hold the descriptor of the leased file that has been accessed by another process.  (This  is
       useful if the caller holds leases against multiple files).

   File and directory change notification (dnotify)
       F_NOTIFY (long)
              (Linux  2.4  onwards) Provide notification when the directory referred to by fd or any of the files that it
              contains is changed.  The events to be notified are specified in arg, which is  a  bit  mask  specified  by
              ORing together zero or more of the following bits:

              DN_ACCESS   A file was accessed (read, pread, readv)
              DN_MODIFY   A file was modified (write, pwrite, writev, truncate, ftruncate).
              DN_CREATE   A file was created (open, creat, mknod, mkdir, link, symlink, rename).
              DN_DELETE   A file was unlinked (unlink, rename to another directory, rmdir).
              DN_RENAME   A file was renamed within this directory (rename).
              DN_ATTRIB   The attributes of a file were changed (chown, chmod, utime[s]).

              (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined.)

              Directory  notifications  are  normally "one-shot", and the application must re-register to receive further
              notifications.  Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in  effect
              until explicitly removed.

              A  series  of  F_NOTIFY requests is cumulative, with the events in arg being added to the set already moni‐
              tored.  To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

              Notification occurs via delivery of a signal.  The default signal is SIGIO, but this can be  changed  using
              the  F_SETSIG command to fcntl().  In the latter case, the signal handler receives a siginfo_t structure as
              its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure
              contains  the  file  descriptor  which generated the notification (useful when establishing notification on
              multiple directories).

              Especially when using DN_MULTISHOT, a real time signal should be used for notification,  so  that  multiple
              notifications can be queued.

              NOTE:  New  applications should use the inotify interface (available since kernel 2.6.13), which provides a
              much superior interface for obtaining notifications of file system events.  See inotify(7).

RETURN VALUE
       For a successful call, the return value depends on the operation:

       F_DUPFD  The new descriptor.

       F_GETFD  Value of flags.

       F_GETFL  Value of flags.

       F_GETLEASE
                Type of lease held on file descriptor.

       F_GETOWN Value of descriptor owner.

       F_GETSIG Value of signal sent when read or write becomes possible, or zero for traditional SIGIO behavior.

       All other commands
                Zero.

       On error, -1 is returned, and errno is set appropriately.

ERRORS
       EACCES or EAGAIN
              Operation is prohibited by locks held by other processes.

       EAGAIN The operation is prohibited because the file has been memory-mapped by another process.

       EBADF  fd is not an open file descriptor, or the command was F_SETLK or F_SETLKW and the file descriptor open mode
              doesn’t match with the type of lock requested.

       EDEADLK
              It was detected that the specified F_SETLKW command would cause a deadlock.

       EFAULT lock is outside your accessible address space.

       EINTR  For F_SETLKW, the command was interrupted by a signal; see signal(7).  For F_GETLK and F_SETLK, the command
              was interrupted by a signal before the lock was checked or acquired.  Most likely  when  locking  a  remote
              file (e.g., locking over NFS), but can sometimes happen locally.

       EINVAL For  F_DUPFD,  arg is negative or is greater than the maximum allowable value.  For F_SETSIG, arg is not an
              allowable signal number.

       EMFILE For F_DUPFD, the process already has the maximum number of file descriptors open.

       ENOLCK Too many segment locks open, lock table is full, or a remote locking protocol failed  (e.g.,  locking  over
              NFS).

       EPERM  Attempted to clear the O_APPEND flag on a file that has the append-only attribute set.

CONFORMING TO
       SVr4,  4.3BSD,  POSIX.1-2001.   Only the operations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK,
       F_SETLKW, F_GETOWN, and F_SETOWN are specified in POSIX.1-2001.

       F_DUPFD_CLOEXEC is specified in POSIX.1-2008.

       F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE, and F_SETLEASE are Linux-specific.  (Define  the  _GNU_SOURCE  macro  to
       obtain these definitions.)

NOTES
       The errors returned by dup2(2) are different from those returned by F_DUPFD.

       Since kernel 2.0, there is no interaction between the types of lock placed by flock(2) and fcntl().

       Several systems have more fields in struct flock such as, for example, l_sysid.  Clearly, l_pid alone is not going
       to be very useful if the process holding the lock may live on a different machine.

BUGS
       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.

       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.

       The implementation of mandatory locking in all known versions of Linux is subject to race conditions which  render
       it  unreliable:  a write(2) call that overlaps with a lock may modify data after the mandatory lock is acquired; a
       read(2) call that overlaps with a lock may detect changes to data that were made  only  after  a  write  lock  was
       acquired.  Similar races exist between mandatory locks and mmap(2).  It is therefore inadvisable to rely on manda‐
       tory locking.

SEE ALSO
       dup2(2), flock(2), open(2), socket(2), lockf(3), capabilities(7), feature_test_macros(7)

       See also Documentation/locks.txt, Documentation/mandatory.txt, and Documentation/dnotify.txt in the kernel source.

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2008-09-05                                               FCNTL(2)
##############################
##############################
IOCTL(2)                                        Linux Programmer’s Manual                                        IOCTL(2)



NAME
       ioctl - control device

SYNOPSIS
       #include <sys/ioctl.h>

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

DESCRIPTION
       The ioctl() function manipulates the underlying device parameters of special files.  In particular, many operating
       characteristics of character special files (e.g., terminals) may be controlled with ioctl() requests.   The  argu‐
       ment d must be an open file descriptor.

       The second argument is a device-dependent request code.  The third argument is an untyped pointer to memory.  It’s
       traditionally char *argp (from the days before void * was valid C), and will be so named for this discussion.

       An ioctl() request has encoded in it whether the argument is an in parameter or out parameter, and the size of the
       argument  argp  in  bytes.   Macros  and  defines  used  in  specifying an ioctl() request are located in the file
       <sys/ioctl.h>.

RETURN VALUE
       Usually, on success zero is returned.  A few ioctl() requests use the return value  as  an  output  parameter  and
       return a non-negative value on success.  On error, -1 is returned, and errno is set appropriately.

ERRORS
       EBADF  d is not a valid descriptor.

       EFAULT argp references an inaccessible memory area.

       EINVAL Request or argp is not valid.

       ENOTTY d is not associated with a character special device.

       ENOTTY The specified request does not apply to the kind of object that the descriptor d references.

CONFORMING TO
       No  single standard.  Arguments, returns, and semantics of ioctl() vary according to the device driver in question
       (the call is used as a catch-all for  operations  that  don’t  cleanly  fit  the  Unix  stream  I/O  model).   See
       ioctl_list(2) for a list of many of the known ioctl() calls.  The ioctl() function call appeared in Version 7 AT&T
       Unix.

NOTES
       In order to use this call, one needs an open file descriptor.  Often the open(2) call has unwanted  side  effects,
       that can be avoided under Linux by giving it the O_NONBLOCK flag.

SEE ALSO
       execve(2), fcntl(2), ioctl_list(2), open(2), sd(4), tty(4)

COLOPHON
       This  page  is part of release 3.15 of the Linux man-pages project.  A description of the project, and information
       about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                   2000-09-21                                               IOCTL(2)
##############################
##############################
